Directory Plugin

The Directory plugin provides path-based routing and conditional plugin execution, allowing different plugin pipelines to handle different URL paths.

Overview

The Directory plugin acts as a sophisticated router that executes nested plugins only when requests match configured directory patterns. This enables you to create complex routing scenarios where different parts of your website have different functionality, security requirements, or processing pipelines.

Unlike simple URL matching, the Directory plugin creates isolated execution contexts for different paths, allowing you to compose complex plugin pipelines that only activate for specific sections of your site.

Key Features

Path-Based Routing: Execute plugins only for specific URL paths
Nested Plugin Support: Load and manage sub-plugins dynamically
Sequential Execution: Process nested plugins in order until one responds
Dynamic Loading: Load plugin libraries at runtime via FFI
Flexible Configuration: Support for complex routing scenarios
Response Phase Handling: Apply response transformations conditionally
Recursive Nesting: Nested plugins can have their own nested plugins

Configuration

To add the Directory plugin to your pipeline:

<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/DirectoryPlugin">
    <div class="plugin-config">
        <div class="config-property">
            <label class="property-label">library:</label>
            <span itemprop="library" class="property-value">file://./plugins/libdirectory.so</span>
        </div>
        <div class="config-property">
            <label class="property-label">directory:</label>
            <span itemprop="directory" class="property-value">/admin</span>
        </div>
        <div itemprop="nested_plugins" itemscope itemtype="https://rustybeam.net/schema/PluginConfig">
            <!-- Nested plugin configurations go here -->
        </div>
    </div>
</td>

Configuration Parameters

Parameter	Type	Required	Default	Description
`directory`	String	No	/	The path prefix to match (e.g., "/admin", "/api")
`nested_plugins`	JSON Array	No	[]	Array of plugin configurations to execute for matching paths

Important: The nested_plugins parameter expects a JSON array due to FFI limitations. The main server serializes the microdata plugin configurations to JSON before passing them to the directory plugin.

Path Matching Rules

The Directory plugin uses the following rules for path matching:

Exact match: /admin matches /admin
Prefix match: /admin matches /admin/users, /admin/settings
Trailing slashes ignored: /admin/ matches /admin
Case sensitive: /Admin does not match /admin
Root path: / matches all paths

Execution Flow

Request Phase:
- Check if request path matches configured directory
- If no match, pass through to next plugin in main pipeline
- If match, execute nested plugins sequentially
First Response Wins:
- Stop at first nested plugin that returns a response
- Remaining nested plugins are not called for request phase
Response Phase:
- All matching nested plugins process the response
- Each plugin can modify headers, transform content, etc.

Use Cases

Admin Interface Protection

<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/DirectoryPlugin">
    <span itemprop="directory">/admin</span>
    <div itemprop="nested_plugins">
        <!-- Basic Auth plugin -->
        <!-- Authorization plugin -->
        <!-- Admin file handler -->
    </div>
</td>

API Versioning

<!-- API v1 -->
<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/DirectoryPlugin">
    <span itemprop="directory">/api/v1</span>
    <div itemprop="nested_plugins">
        <!-- v1 API handler plugins -->
    </div>
</td>

<!-- API v2 -->
<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/DirectoryPlugin">
    <span itemprop="directory">/api/v2</span>
    <div itemprop="nested_plugins">
        <!-- v2 API handler plugins -->
    </div>
</td>

Static vs Dynamic Content

<!-- Static assets with compression -->
<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/DirectoryPlugin">
    <span itemprop="directory">/static</span>
    <div itemprop="nested_plugins">
        <!-- Compression plugin -->
        <!-- Cache control plugin -->
        <!-- File handler plugin -->
    </div>
</td>

Nested Plugin Configuration

Each nested plugin in the nested_plugins array requires:

library: Path to the plugin shared library (must use file:// URL)
config: Plugin-specific configuration as key-value pairs
nested_plugins: Additional nested plugins (recursive)

Example Nested Plugin JSON

[
    {
        "library": "file://./plugins/librusty_beam_basic_auth.so",
        "config": {
            "realm": "Admin Area",
            "authfile": "./admin-users.html"
        }
    },
    {
        "library": "file://./plugins/librusty_beam_file_handler.so",
        "config": {
            "root": "./admin-files"
        }
    }
]

Security Considerations

Library Loading: Only loads libraries from file:// URLs for security
Path Validation: Validates library paths to prevent directory traversal
No Process Isolation: Nested plugins run in the same process
Configuration Validation: Validates plugin configurations at load time
Error Handling: Failed plugins don't crash the directory plugin
Library Existence: Checks that library files exist before loading

Security Warning: The Directory plugin loads dynamic libraries at runtime. Ensure all plugin libraries are from trusted sources and have appropriate file permissions.

Performance Considerations

Lazy Loading: Plugins loaded once at startup, not per request
Fast Path Matching: O(1) string comparison for path checking
Memory Efficient: Plugins shared via Arc for multiple references
Sequential Processing: Nested plugins execute in order (not parallel)
Early Exit: Request processing stops at first responding plugin

Debugging

Enable verbose logging to see directory plugin behavior:

cargo run -- -v config/config.html

The plugin logs:

Path matching decisions
Nested plugin loading success/failure
Plugin execution order and responses
Library loading errors

Common Log Messages

[DirectoryPlugin] Path '/users' does not match directory '/admin'
[DirectoryPlugin] Path '/admin/users' matches directory '/admin', executing 3 nested plugins
[DirectoryPlugin] Nested plugin 'basic-auth' (index 0) handled request
[DirectoryPlugin] Failed to load nested plugin at index 2: file://./plugins/missing.so

Troubleshooting

Issue	Possible Cause	Solution
Nested plugins not executing	Path doesn't match directory pattern	Check path matching rules and trailing slashes
Plugin loading failures	Library file not found or invalid	Verify library paths and file permissions
Unexpected plugin execution order	Multiple directory plugins with overlapping paths	Order directory plugins from most to least specific
Response modifications not applied	Plugin only handles request phase	Ensure plugins implement handle_response method

Best Practices

Path Specificity: Place more specific paths before general ones
Plugin Order: Order nested plugins by dependency (auth before content)
Error Handling: Always have fallback handling for failed plugins
Testing: Test path matching with various URL patterns
Documentation: Document which plugins are active for each path