Route Configuration Schema

Relevant source files

The following files were used as context for generating this wiki page:

• src/types.ts
• src/utils/validation.ts
• README.md
• src/handlers/admin.ts
• src/admin-html.ts
• SECURITY.md
• src/index.ts

The gr8hopper configuration defines how incoming requests are redirected. It is composed of two main parts: a collection of individual Route definitions and a set of GlobalSettings. This schema is designed to be flexible, supporting both simple key-value redirects and complex, parameter-driven routing patterns.

The entire configuration can be managed via the Admin UI and its backing API. For VPS deployments, it is stored in a JSON file, while Cloudflare Workers deployments use Cloudflare KV for storage. The schema is validated upon creation or modification to ensure integrity and security.

Sources: src/types.ts, README.md, src/index.ts:18-25

Core Data Structures

The configuration is primarily defined by two TypeScript interfaces: RouteConfig for individual redirects and GlobalSettings for service-wide behavior.

This diagram illustrates the main configuration interfaces and their relationships. StoredRoute extends RouteConfig with an id, and ConfigFile aggregates all routes and settings for JSON-based storage.

Sources: src/types.ts:1-31

Route Configuration (RouteConfig)

Each route is an object that maps a unique id (the route key or path pattern) to a RouteConfig object.

Field	Type	Required	Description
template	string	Yes	The target URL, which can include {param} placeholders for dynamic substitution.
active	boolean	Yes	A flag to enable or disable the redirect for this route.
passthrough	boolean	No	If true, appends query parameters from the source URL to the destination URL. Defaults to false.

Sources: src/types.ts:4-10, README.md:112-116

Route ID / Path

The id of a route serves as its unique identifier and can be either a simple string or a complex pattern for matching request paths and queries.

• Simple Routes: Identified by a simple string (e.g., my-route). These are matched using the route_param query parameter (e.g., /?r=my-route).
• Pattern Routes: Use special tokens to match against the request's path and query string, allowing for more dynamic routing.

The following tokens are supported in route ID patterns:

Token	Description	Example
:param	A required path parameter.	shop/:category/:id
{param}	A required path parameter (alternative syntax).	shop/{category}/{id}
{param?}	An optional path parameter.	blog/{year?}/{slug}
{param=default}	An optional path parameter with a default value.	docs/{version=v1}/{page}
*	A wildcard that matches exactly one path segment.	*/details/*
**	A globstar that matches zero or more path segments.	files/**
?key={value}	Matches a query parameter with a placeholder value.	product/{id}?lang={lang}
?key=value	Matches a query parameter with a literal value.	product/{id}?lang=en
?*	Matches any query parameters.	product/{id}?*

Matching Behavior:

• Path matching is case-insensitive.
• Query parameter names are case-sensitive.
• Captured parameter values preserve their original casing.

Sources: README.md:124-168, src/utils/validation.ts:33-68, src/admin-html.ts:1532-1535

Destination Template (template)

The template field is the destination URL. It supports placeholders that are dynamically replaced with values from the incoming request.

Placeholder	Source	Example
{route}	The route's ID (URL-encoded). This is a reserved, automatic placeholder.	partner-a
{anyParam}	A value from a URL query parameter (?anyParam=value) or a captured path parameter from a pattern route.	12345 from ?id=12345

Validation:
To prevent security vulnerabilities, template URLs are strictly validated:

1. Control characters are stripped via sanitizeUrl.
2. The URL scheme must be http: or https:. Dangerous schemes like javascript: and data: are blocked.
3. The total URL length cannot exceed 2048 characters.

Sources: README.md:118-122, src/utils/validation.ts:10-20, 93-125, SECURITY.md:60-61

Query Parameter Passthrough (passthrough)

When passthrough is set to true, any query parameters from the source request URL are appended to the destination URL. This is useful for preserving tracking tags like UTM parameters.

Behavior:

• Precedence: Placeholders defined in the destination template take precedence. Source query parameters are only appended if their key does not already exist in the destination URL.
• Exclusions: The route_param (e.g., r) and any parameters captured by the route ID pattern are automatically excluded from the passthrough.

Sources: README.md:170-195, src/types.ts:9

Global Settings (GlobalSettings)

These settings apply to the entire redirect service and are configured in the Admin UI.

Field	Type	Default	Description
fallback_url	string	/not-found	URL to redirect to when a requested route is not found. Must be an absolute URL to perform an external redirect.
cache_ttl	number	604800	The max-age for the Cache-Control header, in seconds (default is 1 week).
route_param	string	r	The name of the URL query parameter used to select a simple route.

Sources: src/types.ts:15-21, README.md:197-201

Configuration Validation

All route and settings configurations are validated before being saved. This process is handled by functions in src/utils/validation.ts and enforced by the admin API handlers.

The following flowchart shows the validation process when a new route is created or updated.

This flow ensures that only well-formed and secure configurations are persisted. Key functions include validateRouteIdPattern, validateRouteConfig, and validateSettings.

Sources: src/handlers/admin.ts:100-123, src/utils/validation.ts:33-68, 321-355, 401-441

Storage and Management

The route configuration is managed via a set of RESTful API endpoints and stored using a StorageAdapter.

API Management

The admin API provides endpoints to perform CRUD operations on routes and settings. The following diagram shows the sequence for creating a new route.

This sequence demonstrates how the Admin UI interacts with the API to create a new route, including the validation and storage steps.

Sources: src/handlers/admin.ts:100-123, src/admin-html.ts:1696-1736

Storage Format (ConfigFile)

For file-based storage (used in VPS/Docker deployments), the entire configuration is stored in a single JSON file. The structure of this file is defined by the ConfigFile interface.

// From: src/types.ts
export interface ConfigFile {
  routes: Record<string, RouteConfig>
  settings: GlobalSettings
}

The routes key is an object where each key is a route ID and the value is its corresponding RouteConfig.

Sources: src/types.ts:33-37, README.md:300-318

Conclusion

The gr8hopper route configuration schema provides a powerful and flexible system for managing URL redirects. It balances simplicity for basic use cases with advanced pattern-matching capabilities for complex routing logic. Through strict validation and a clear data model, it ensures that redirects are both efficient and secure. The entire schema is accessible and manageable through a clean Admin UI and a well-defined API.