FileHandlerPlugin Schema

The FileHandlerPlugin schema defines the configuration for static file serving in Rusty Beam. This is a core handler plugin that serves files from the filesystem, handles MIME types, and provides basic file operations like GET, PUT, and DELETE.

Schema Definition

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

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

Properties

Inheritance: This schema inherits properties from HandlerPlugin (config_file, rulesfile) and Plugin (library, plugin). No additional properties are required for basic file serving.

Property	Type	Cardinality	Description	Source
`library`	URL	1	Plugin library path	Plugin
`config_file`	Text	0..1	Optional configuration file for custom MIME types or file serving rules	HandlerPlugin

Configuration Example

Basic File Handler

<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/FileHandlerPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_file_handler.so</span>
</td>

With Custom Configuration

<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/FileHandlerPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_file_handler.so</span>
    <span itemprop="config_file">config/mime-types.html</span>
</td>

Supported Operations

HTTP Methods: The file handler supports multiple HTTP methods for different file operations:

Method	Operation	Description	Authorization
`GET`	Read File	Serves file content with appropriate MIME type	Typically public
`HEAD`	File Info	Returns headers without body (file size, type, etc.)	Same as GET
`PUT`	Upload/Update	Creates or updates file content	Requires authorization
`DELETE`	Remove File	Deletes file from filesystem	Requires authorization

File Serving Features

MIME Type Detection: Automatic content-type based on file extension
Range Requests: Supports HTTP Range headers for partial content
ETags: Provides entity tags for caching
Last-Modified: Includes modification timestamps
Directory Security: Prevents path traversal attacks
Index Files: Serves index.html for directory requests

Security Features

Built-in Security:

Path Canonicalization: All file paths are canonicalized to prevent directory traversal
Root Containment: Files are served only from within the configured server root
Authorization Integration: Respects authorization rules for file access
Method Restrictions: PUT/DELETE operations can be restricted by authorization

Pipeline Placement

Recommended Order: The file handler should typically be placed near the end of the plugin pipeline, after authentication, authorization, and selector processing, but before access logging.

Integration Examples

With Authorization

Control which users can access files using authorization rules:

<!-- Allow everyone to read assets -->
<tr itemscope itemtype="https://rustybeam.net/schema/AuthorizationRule">
    <td><span itemprop="username">*</span></td>
    <td><span itemprop="path">/assets/*</span></td>
    <td><span itemprop="method">GET</span></td>
    <td><span itemprop="action">allow</span></td>
</tr>

<!-- Restrict file uploads to admins -->
<tr itemscope itemtype="https://rustybeam.net/schema/AuthorizationRule">
    <td><span itemprop="role">administrators</span></td>
    <td><span itemprop="path">/uploads/*</span></td>
    <td><span itemprop="method">PUT</span></td>
    <td><span itemprop="action">allow</span></td>
</tr>

With Selector Handler

The file handler works seamlessly with the selector handler for HTML manipulation. The selector handler processes CSS selector requests, and if no selectors are found, the file handler serves the complete file.

Common MIME Types

Extension	MIME Type	Description
.html	text/html	HTML documents
.css	text/css	Stylesheets
.js	application/javascript	JavaScript files
.json	application/json	JSON data
.png	image/png	PNG images
.jpg	image/jpeg	JPEG images
.svg	image/svg+xml	SVG images
.pdf	application/pdf	PDF documents