Redirect Management Plugin

Manage URL redirects with exact, wildcard, and regex matching. Includes CSV bulk import/export, analytics tracking, and optional Cloudflare Bulk Redirects integration.

Overview

The Redirect Management plugin handles URL redirects at the application level with sub-millisecond lookups via an LRU cache. It supports multiple matching strategies and integrates with Cloudflare's edge network for maximum performance.

Setup

The Redirect Management plugin is a core plugin. Activate it in the admin panel:

1. Navigate to Admin → Plugins
2. Find Redirect Management
3. Click Activate

The plugin creates two database tables: redirects and redirect_analytics.

Access the admin UI at Admin → Redirects in the sidebar.

Creating Redirects

Match Types

Status Codes

Redirect Options

Each redirect supports Cloudflare-aligned options:

Admin Form

Create redirects via the admin UI at /admin/redirects/new:

1. Enter Source URL (e.g., /old-page)
2. Enter Destination URL (e.g., /new-page or https://example.com)
3. Select Status Code and Match Type
4. Toggle options as needed
5. Click Create Redirect

The plugin validates for circular redirects and duplicate sources before saving.

CSV Import & Export

Exporting

Click Export CSV on the redirects list page. The export respects any active filters. CSV columns:

id, source_url, destination_url, match_type, status_code, active,
preserve_query_string, include_subdomains, subpath_matching,
preserve_path_suffix, created_at, updated_at

Importing

Click Import CSV and upload a CSV file (max 10MB). Required columns: source_url and destination_url.

Duplicate Handling Strategies:

Validation checks:

• URL format validation (must start with /, http://, or https://)
• Status code validation (301, 302, 307, 308, 410)
• Intra-file duplicate detection
• Database duplicate detection
• Circular redirect chain detection

If errors are found, the system returns an error CSV with line numbers and error messages for each invalid row.

source_url,destination_url,match_type,status_code,active
/old-blog,/blog,exact,301,true
/legacy/*,/new/*,wildcard,301,true
/temp-page,/landing,exact,302,true

Cloudflare Integration

Sync eligible redirects to Cloudflare Bulk Redirects for edge-level processing, eliminating the need to hit your Workers for common redirects.

Requirements

Set these environment variables:

CLOUDFLARE_API_TOKEN=your_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id

The API token needs Account Filter Lists Edit and Account Rulesets Edit permissions.

Eligibility

A redirect is synced to Cloudflare only if:

• Match type is Exact or Wildcard (not Regex)
• Status code is 301, 302, 307, or 308 (not 410)
• Redirect is active

Sync Modes

Auto-sync on create: Enable autoOffloadEnabled in plugin settings. Eligible redirects are automatically synced to Cloudflare after creation.

Manual sync: Click Sync to Cloudflare in the admin UI to sync all eligible redirects. This clears existing Cloudflare items and replaces them with the current set.

Real-time sync: Individual redirects are synced to Cloudflare after create/update operations (non-blocking).

Cloudflare Resources

The plugin creates and manages:

• A redirect list named sonicjs-redirects
• A ruleset named SonicJS Bulk Redirects in the http_request_redirect phase

API Reference

REST API

All API routes are mounted at /api/redirects and support Bearer token authentication via the REDIRECTS_API_KEY environment variable.

Query parameters: isActive, statusCode, matchType, search, limit (default 50), offset

curl -X POST http://localhost:8787/api/redirects \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "/old-page",
    "destination": "/new-page",
    "matchType": 0,
    "statusCode": 301,
    "preserveQueryString": false
  }'

Admin Routes

Configuration

Plugin Settings

Environment Variables

Middleware

The redirect middleware processes incoming requests with sub-millisecond lookups:

1. Normalizes the URL (lowercase, strips trailing slash)
2. Checks the LRU cache (capacity: 1000 entries)
3. Falls back to database on cache miss
4. Records hit analytics asynchronously
5. Executes the redirect

The cache is automatically invalidated on create, update, and delete operations.

Next Steps