Configuration

Understanding and configuring your Noorle plugin.

Overview

Plugin configuration is handled through noorle.yaml, which is completely optional. Plugins work perfectly without it, using sensible defaults.

When You Need Configuration

You only need noorle.yaml when you want to:

Request network access to specific hosts
Access environment variables
Set resource limits
Provide metadata for documentation

Configuration File Structure

yaml

# noorle.yaml
schema_version: "1.0"  # Required when file exists

metadata:              # Optional section
  name: my-plugin
  description: "What this plugin does"
  author: "Your Name <[email protected]>"
  homepage: "https://github.com/you/my-plugin"
  license: "MIT"
  tags:
    - category
    - functionality

permissions:           # Optional section
  network:
    allow:
      - host: "api.example.com"
  environment:
    allow:
      - API_KEY
  storage:
    allow:
      - uri: "fs://input/**"
        access: [read]
      - uri: "fs://working/**"
        access: [read, write]
  resources:
    limits:
      memory: "256Mi"
      timeout: "60s"

Configuration Sections

Schema Version

Required when noorle.yaml exists:

yaml

schema_version: "1.0"

This ensures compatibility as the configuration format evolves.

Metadata (Optional)

Provides information about your plugin:

yaml

metadata:
  name: weather-plugin       # Defaults to folder name
  description: "Fetches current weather data"
  author: "Jane Doe <[email protected]>"
  homepage: "https://github.com/janedoe/weather-plugin"
  license: "MIT"             # SPDX identifier
  tags:
    - weather
    - api
    - utility

Defaults:

name: Folder name
Other fields: Empty if not specified

Permissions

Network Access

Control which hosts your plugin can connect to:

yaml

permissions:
  network:
    allow:
      - host: "api.openweather.org"    # Specific host
      - host: "*.weather.com"          # Wildcard subdomain
      - host: "*"                       # All hosts (use sparingly!)

Default: No network access

Examples:

yaml

# Single API
permissions:
  network:
    allow:
      - host: "api.github.com"

# Multiple APIs
permissions:
  network:
    allow:
      - host: "api.openai.com"
      - host: "api.anthropic.com"

# Development (allow all)
permissions:
  network:
    allow:
      - host: "*"

Environment Variables

Specify which environment variables your plugin can access:

yaml

permissions:
  environment:
    allow:
      - API_KEY
      - DEBUG_MODE
      - SERVICE_URL

Default: No environment access

Usage in code:

Python:

python

from wit_world.imports import environment

env_vars = environment.get_environment()
for name, value in env_vars:
    if name == "API_KEY":
        api_key = value

TypeScript:

typescript

import { environment } from './wasi';

const env = environment.getEnvironment();
const apiKey = env.get('API_KEY');

Storage Access

Control storage permissions with URI-based access:

yaml

permissions:
  storage:
    allow:
      - uri: "fs://input/**"
        access: [read]
      - uri: "fs://working/**"
        access: [read, write]
      - uri: "fs://output/**"
        access: [read, write]

Default: No storage access

Important: Only directories listed in storage.allow will be preopened and accessible to the WASM component. For example, with the above configuration, only /input, /working, and /output will be accessible.

Limitation: Subdirectory patterns are not supported. You can only specify top-level directories like fs://input/**. Patterns like fs://input/abcd/** will not work.

Note: Most plugins don't need storage access.

Resource Limits

Configure memory and timeout limits:

yaml

permissions:
  resources:
    limits:
      memory: "256Mi"    # 128Mi default, 512Mi max
      timeout: "60s"     # 30s default, 120s max

Configurable Limits:

Memory: 128MB (default), up to 512MB (maximum)
Timeout: 30 seconds (default), up to 120 seconds (maximum)

Platform-Enforced (Not Configurable):

CPU Time: Max 100ms per request (enforced by platform)

Note: Memory and timeout can be configured in noorle.yaml within the platform maximums. CPU time is enforced by the platform and cannot be modified. See Usage Limits for complete details.

Environment Files (.env)

For local development and deployment:

Local Development

Create .env for local testing:

bash

# .env
API_KEY=your-api-key-here
DEBUG_MODE=true
SERVICE_URL=https://api.example.com

Note: Don't commit .env to version control!

Deployment

Set environment variables during deployment:

bash

# Deploy with environment file
noorle plugin deploy --env-file .env.production

# Or set individually
noorle plugin deploy --env API_KEY=prod-key --env DEBUG_MODE=false

Platform Environment

Environment variables can be managed in the Noorle console:

Go to your plugin settings
Add environment variables
They're automatically available to your plugin

Configuration Examples

Minimal Plugin

No configuration needed! The plugin works with defaults.

API Client Plugin

yaml

schema_version: "1.0"

permissions:
  network:
    allow:
      - host: "api.example.com"
  environment:
    allow:
      - API_KEY
      - API_SECRET

Data Processing Plugin

yaml

schema_version: "1.0"

metadata:
  name: data-processor
  description: "Processes and transforms data"

permissions:
  resources:
    limits:
      memory: "512Mi"  # Needs more memory for large datasets

Development Plugin

yaml

schema_version: "1.0"

metadata:
  name: dev-plugin
  tags:
    - development
    - testing

permissions:
  network:
    allow:
      - host: "*"  # Allow all during development
  environment:
    allow:
      - DEBUG
      - LOG_LEVEL

Best Practices

1. Minimal Permissions

Only request what you need:

yaml

# Good: Specific hosts
permissions:
  network:
    allow:
      - host: "api.openweather.org"

# Bad: Overly broad
permissions:
  network:
    allow:
      - host: "*"

2. Document Environment Variables

Add comments explaining each variable:

yaml

permissions:
  environment:
    allow:
      - API_KEY         # OpenWeather API key
      - CACHE_TTL       # Cache duration in seconds
      - DEBUG_MODE      # Enable verbose logging

3. Use Meaningful Tags

Help users discover your plugin:

yaml

metadata:
  tags:
    - weather         # Functionality
    - api-client      # Type
    - real-time       # Characteristic

4. Version Your Configuration

Track configuration changes:

yaml

# Version 1.0 - Initial release
# Version 1.1 - Added caching support
# Version 1.2 - Added multiple API support
schema_version: "1.0"

Configuration Validation

Using the CLI

Validate your configuration:

bash

noorle plugin validate noorle.yaml

Output:

✓ Configuration valid
  - Network: api.example.com
  - Environment: API_KEY, DEBUG_MODE
  - Memory: 256Mi

Common Validation Errors

Missing schema version:

yaml

# Error: schema_version is required
metadata:
  name: my-plugin

Invalid host pattern:

yaml

permissions:
  network:
    allow:
      - host: "https://api.example.com"  # Don't include protocol!

Invalid resource units:

yaml

permissions:
  resources:
    limits:
      memory: "256"  # Missing unit (Mi, Gi)

Runtime Behavior

Permission Denials

When a plugin tries to access something not permitted:

python

# Without network permission
response = fetch("https://api.example.com")
# Error: Network access to api.example.com denied

# Without environment permission
api_key = os.environ.get("API_KEY")
# Returns: None (silent failure)

Default Behaviors

Without configuration:

Network: All requests fail
Environment: No variables accessible
Storage: No access
Resources: Platform defaults apply

Migration Guide

From No Config to Config

Start without noorle.yaml
Add configuration as needed:

yaml

# Start simple
schema_version: "1.0"

# Add permissions as you need them
permissions:
  network:
    allow:
      - host: "api.example.com"

Adding New Permissions

When your plugin evolves:

yaml

# Version 1: Basic API
permissions:
  network:
    allow:
      - host: "api.v1.example.com"

# Version 2: Add new API
permissions:
  network:
    allow:
      - host: "api.v1.example.com"
      - host: "api.v2.example.com"  # Added

Troubleshooting

Plugin Can't Access API

Check:

Host is in permissions.network.allow
No typos in hostname
Don't include protocol (http://)
Use wildcards correctly (*.example.com)

Environment Variables Not Working

Check:

Variable is in permissions.environment.allow
Variable is set in deployment environment
Name matches exactly (case-sensitive)

Resource Limits Hit

Signs:

Plugin crashes or restarts
"Out of memory" errors
Slow performance

Solution:

yaml

permissions:
  resources:
    limits:
      memory: "512Mi"  # Increase from default

Security Considerations

Principle of Least Privilege

Only request necessary permissions
Be specific with hostnames
Limit environment variable access
Set appropriate resource limits

Sensitive Data

Never hardcode secrets in configuration
Use environment variables for sensitive data
Don't commit .env files with real credentials
Rotate credentials regularly

Next Steps

Quick Start - Build your first plugin
WebAssembly - Understanding the technology
Language Guides - Language-specific configuration

Configuration ​

Overview ​

When You Need Configuration ​

Configuration File Structure ​

Configuration Sections ​

Schema Version ​

Metadata (Optional) ​

Permissions ​

Network Access ​

Environment Variables ​

Storage Access ​

Resource Limits ​

Environment Files (.env) ​

Local Development ​

Deployment ​

Platform Environment ​

Configuration Examples ​

Minimal Plugin ​

API Client Plugin ​

Data Processing Plugin ​

Development Plugin ​

Best Practices ​

1. Minimal Permissions ​

2. Document Environment Variables ​

3. Use Meaningful Tags ​

4. Version Your Configuration ​

Configuration Validation ​

Using the CLI ​

Common Validation Errors ​

Runtime Behavior ​

Permission Denials ​

Default Behaviors ​

Migration Guide ​

From No Config to Config ​

Adding New Permissions ​

Troubleshooting ​

Plugin Can't Access API ​

Environment Variables Not Working ​

Resource Limits Hit ​

Security Considerations ​

Principle of Least Privilege ​

Sensitive Data ​

Next Steps ​

Configuration

Overview

When You Need Configuration

Configuration File Structure

Configuration Sections

Schema Version

Metadata (Optional)

Permissions

Network Access

Environment Variables

Storage Access

Resource Limits

Environment Files (.env)

Local Development

Deployment

Platform Environment

Configuration Examples

Minimal Plugin

API Client Plugin

Data Processing Plugin

Development Plugin

Best Practices

1. Minimal Permissions

2. Document Environment Variables

3. Use Meaningful Tags

4. Version Your Configuration

Configuration Validation

Using the CLI

Common Validation Errors

Runtime Behavior

Permission Denials

Default Behaviors

Migration Guide

From No Config to Config

Adding New Permissions

Troubleshooting

Plugin Can't Access API

Environment Variables Not Working

Resource Limits Hit

Security Considerations

Principle of Least Privilege

Sensitive Data

Next Steps