RedirectPlugin Schema

Schema definition for the Redirect Plugin, which provides URL redirection with pattern matching and both request and response redirects.

Schema Information

Property	Value
Schema URL	`https://rustybeam.net/schema/RedirectPlugin`
Parent Schema	https://rustybeam.net/schema/HandlerPlugin
Description	URL redirection with regex pattern matching for both request and response redirects

Properties

Property	Type	Cardinality	Description
rulesfile	https://rustybeam.net/schema/URL	0..1	Path to HTML file containing RedirectRule microdata. Supports file:// URLs. Contains redirect rules for pattern matching and URL rewriting.
name	https://rustybeam.net/schema/Text	0..1	Plugin instance name for logging and identification. Defaults to "redirect" if not specified.

Usage Examples

Basic Redirect Configuration

<tr itemscope itemtype="https://rustybeam.net/schema/RedirectPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_redirect.so</span>
    <span itemprop="rulesfile">file://./config/redirects.html</span>
</tr>

Named Redirect Instance

<tr itemscope itemtype="https://rustybeam.net/schema/RedirectPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_redirect.so</span>
    <span itemprop="rulesfile">file://./examples/guestbook/config/server-config.html</span>
    <span itemprop="name">main_redirects</span>
</tr>

Redirect Rules File Format

The rules file referenced by rulesfile should contain RedirectRule microdata:

Request Redirects (Traditional)

<!-- Simple path redirect -->
<div itemscope itemtype="https://rustybeam.net/schema/RedirectRule">
    <span itemprop="from">/old-path</span>
    <span itemprop="to">/new-path</span>
    <span itemprop="status">301</span>
</div>

<!-- Regex pattern with capture groups -->
<div itemscope itemtype="https://rustybeam.net/schema/RedirectRule">
    <span itemprop="from">^/blog/(\d{4})/(\d{2})/(.+)$</span>
    <span itemprop="to">/posts/$1-$2-$3</span>
    <span itemprop="status">301</span>
    <span itemprop="https_only">true</span>
</div>

Response Redirects (Error Handling)

<!-- Redirect on 403 Forbidden -->
<div itemscope itemtype="https://rustybeam.net/schema/RedirectRule">
    <span itemprop="from">^/auth/.*$</span>
    <span itemprop="to">/</span>
    <span itemprop="status">302</span>
    <span itemprop="on">403</span>
</div>

<!-- Handle multiple error codes -->
<div itemscope itemtype="https://rustybeam.net/schema/RedirectRule">
    <span itemprop="from">^/api/.*$</span>
    <span itemprop="to">/error?code=$code</span>
    <span itemprop="status">302</span>
    <span itemprop="on">403</span>
    <span itemprop="on">500</span>
</div>

Redirect Types
The Redirect Plugin supports two types of redirects:

Request Redirects: Traditional redirects that match incoming request URLs (no on property)
Response Redirects: Redirects triggered by HTTP response codes (has on property)

Schema Inheritance

This schema inherits from the HandlerPlugin schema, which provides:

config_file - Configuration file path
rulesfile - Rules file path (used by RedirectPlugin)

And ultimately from the base Plugin schema, which provides:

library - Plugin library path
plugin - Base plugin reference property

Advanced Redirect Patterns

HTTPS Enforcement

<div itemscope itemtype="https://rustybeam.net/schema/RedirectRule">
    <span itemprop="from">.*</span>
    <span itemprop="to">https://$host$uri</span>
    <span itemprop="status">301</span>
    <span itemprop="https_only">false</span>
</div>

Domain Canonicalization

<div itemscope itemtype="https://rustybeam.net/schema/RedirectRule">
    <span itemprop="from">^/(.*)$</span>
    <span itemprop="to">https://www.example.com/$1</span>
    <span itemprop="status">301</span>
    <span itemprop="host_pattern">^(?!www\\.).*example\\.com$</span>
</div>

Validation Rules

The rulesfile property should be a valid file path or file:// URL
Rules file must contain valid RedirectRule microdata
The referenced rules file must be readable by the server
Redirect patterns support full regex syntax with capture groups
The name property should be unique if multiple redirect plugins are used
Status codes must be valid HTTP redirect codes (301, 302, 303, 307, 308)

Plugin Pipeline Placement
The Redirect Plugin should be placed early in the plugin pipeline for request redirects, but after authentication plugins for response redirects. Response redirects process errors from other plugins like authorization failures.

Supported Redirect Features

Regex Pattern Matching: Full regex support with capture groups ($1, $2, etc.)
Variable Substitution: Use $host, $uri, $code in destination URLs
HTTPS Enforcement: Automatic HTTP to HTTPS redirects
Host-Based Rules: Different redirects for different domains
Response Code Triggers: Redirect based on HTTP response codes
Multiple Status Codes: Single rule can handle multiple error codes
Conditional Matching: Rules with additional conditions (HTTPS, host patterns)

Integration with Other Plugins

Authorization Plugin: Handle 403 errors with response redirects
Basic Auth Plugin: Redirect unauthenticated users to login pages
File Handler Plugin: Handle 404 errors with friendly redirects
Security Headers Plugin: Work together for HTTPS enforcement
Rate Limit Plugin: Redirect rate-limited users to information pages