ConfigReloadPlugin Schema

The ConfigReloadPlugin schema defines the configuration for the configuration reload plugin in Rusty Beam. This plugin enables hot reloading of server configuration without restarting the server by handling PATCH requests to the configuration file.

Hot Reload Feature: This plugin allows administrators to reload server configuration by sending a PATCH request with no body to the configuration file endpoint. The server will receive a SIGHUP signal and reload its configuration without dropping connections.

Schema Definition

Schema URL: https://rustybeam.net/schema/ConfigReloadPlugin

Parent Schema: https://rustybeam.net/schema/UtilityPlugin

Properties

Inheritance: This schema inherits properties from UtilityPlugin and Plugin (library, name).
Property Type Cardinality Description
name https://rustybeam.net/schema/Text 0..1 Plugin instance name for identification. Defaults to "config-reload" if not specified.

Configuration Example

<!-- Configuration reload plugin (minimal configuration) -->
<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/ConfigReloadPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_config_reload.so</span>
</td>

How It Works

The ConfigReloadPlugin intercepts PATCH requests to the configuration file and provides hot reload functionality:

  1. Detection: Monitors PATCH requests to the actual configuration file path
  2. Empty Body Check: If the PATCH request has no body (Content-Length: 0), it triggers a reload
  3. SIGHUP Signal: Sends SIGHUP to the server process to reload configuration
  4. Response: Returns HTTP 202 Accepted with confirmation message

API Endpoints

Configuration Reload

Method: PATCH
Path: /config/ (or path to your configuration file)
Headers: Content-Length: 0
Body: Empty

Response:

OPTIONS Support

The plugin also responds to OPTIONS requests on the configuration file to advertise PATCH support:

OPTIONS /config/
Allow: GET, PUT, DELETE, OPTIONS, PATCH, HEAD, POST
Accept-Ranges: selector

Plugin Pipeline Placement

Pipeline Position: This plugin should be placed early in the pipeline, typically after authentication/authorization plugins but before file handler plugins. This ensures that reload requests are intercepted before being processed as regular file requests.

Examples

Manual Reload via curl

# Trigger configuration reload
curl -X PATCH -H "Content-Length: 0" http://localhost:3000/config/

# Response: "Configuration reload initiated"

JavaScript Reload

// Trigger server reload from web interface
async function reloadServer() {
    try {
        const response = await fetch('/config/', {
            method: 'PATCH',
            headers: {
                'Content-Length': '0'
            }
        });
        
        if (response.ok) {
            console.log('Server configuration reload initiated');
        } else {
            throw new Error(`Reload failed: ${response.status}`);
        }
    } catch (error) {
        console.error('Error reloading server:', error);
    }
}

Integration with Other Plugins

With Authorization Plugin

When used with authorization plugins, ensure that configuration reload endpoints are properly protected. Only administrators should be able to trigger server reloads.

With File Handler Plugin

This plugin should be placed before file handler plugins in the pipeline to intercept PATCH requests before they're processed as file modifications.

Security Considerations

Security Best Practices:

Troubleshooting

Issue Possible Cause Solution
PATCH returns 404 Plugin not in pipeline or wrong path Verify plugin is configured and path matches config file
Reload not working SIGHUP signal not reaching process Check process permissions and signal handling
500 Internal Server Error Failed to send SIGHUP signal Check server logs and process permissions

Debug Logging

To debug configuration reload issues, run the server in verbose mode:

cargo run -- -v config/config.html

See Also