DirectoryPlugin Schema

Schema definition for the Directory Plugin, which provides path-based plugin routing with nested plugin execution.

Schema Information

Property Value
Schema URL https://rustybeam.net/schema/DirectoryPlugin
Parent Schema https://rustybeam.net/schema/Plugin
Description Path-based conditional plugin executor with nested plugin support

Properties

Property Type Cardinality Description
directory https://rustybeam.net/schema/Text 0..1 The directory path to match (e.g., /admin, /api). Defaults to / if not specified. Matches exact path and all subpaths. Can also accept file:// URLs where the last path segment becomes the directory.
nested_plugins https://rustybeam.net/schema/Text 0..1 JSON configuration for nested plugins that execute only for matching paths. Contains an array of plugin configurations with library paths and properties.
Implementation Note
The Directory Plugin is a compiled .so library located at file://./plugins/libdirectory.so. Due to FFI boundary limitations, nested plugin configurations are passed as JSON strings in the nested_plugins property.

Usage Examples

Basic Directory Plugin Configuration

<tr itemscope itemtype="https://rustybeam.net/schema/DirectoryPlugin">
    <span itemprop="library">file://./plugins/libdirectory.so</span>
    <span itemprop="directory">/admin</span>
    <span itemprop="nested_plugins">[
        {
            "library": "file://./plugins/librusty_beam_basic_auth.so",
            "config": {
                "realm": "Admin Area"
            }
        },
        {
            "library": "file://./plugins/librusty_beam_file_handler.so",
            "config": {}
        }
    ]</span>
</tr>

API Versioning Example

<tr itemscope itemtype="https://rustybeam.net/schema/DirectoryPlugin">
    <span itemprop="library">file://./plugins/libdirectory.so</span>
    <span itemprop="directory">/api/v1</span>
    <span itemprop="nested_plugins">[
        {
            "library": "file://./plugins/librusty_beam_rate_limit.so",
            "config": {
                "requests_per_minute": "60"
            }
        },
        {
            "library": "file://./plugins/librusty_beam_cors.so",
            "config": {
                "allowed_origins": "https://app-v1.example.com"
            }
        }
    ]</span>
</tr>
Path Matching Behavior
The directory property matches exact paths and all subpaths. For example, /admin matches /admin, /admin/, /admin/users, etc. Paths are case-sensitive and trailing slashes are normalized. If the directory property contains a file:// URL, the last path segment is extracted as the directory.

Schema Inheritance

This schema inherits from the base Plugin schema, which provides:

JSON Schema for nested_plugins

The nested_plugins property expects a JSON array with the following structure:

[
    {
        "library": "string (required) - Plugin library path",
        "config": {
            "key": "value - Plugin-specific configuration properties"
        },
        "nested_plugins": [
            // Recursive nested plugins (for plugins that support nesting)
        ]
    }
]

Validation Rules

Implementation Notes

See Also