Template Placeholders

Relevant source files

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

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

Template placeholders are a core feature of gr8hopper, enabling dynamic and flexible URL redirection. They allow you to define a destination URL template that gets populated with values extracted from the incoming request URL. This is particularly useful for complex, parameter-driven routing scenarios where you need to redirect users to many different destinations based on dynamic data, without creating a unique redirect rule for each case.

The system supports extracting parameters from both query strings and URL paths (using pattern routes), and provides a special reserved placeholder for tracking purposes. This dynamic substitution is handled by the redirect handler, which constructs the final destination URL before issuing a 301 redirect.

Sources: README.md:16-22, src/handlers/redirect.ts

Placeholder Substitution Flow

When a request is received, gr8hopper identifies the matching route and extracts parameters from the request URL. These parameters are then used to substitute the corresponding placeholders in the route's destination template. If a placeholder in the template does not have a corresponding parameter in the request, it is left as-is in the final URL, which helps in identifying configuration errors.

Sources: README.md:111-112

The following diagram illustrates the high-level substitution process:

Sources: README.md:73-90, README.md:111-112

Placeholder Types

gr8hopper supports several types of placeholders, sourced from different parts of the incoming URL.

Query Parameter Placeholders

The most common type of placeholder is derived from query string parameters. Any query parameter in the source URL can be used as a placeholder in the destination template.

Placeholder	Source	Example Request
{anyParam}	URL query parameter ?anyParam=value	/?r=my-route&id=123

Example:

• Route ID: product-page
• Destination Template: https://example.com/products/{id}?ref={route}
• Request URL: https://your-domain.com/?r=product-page&id=abc-987
• Resulting Redirect: https://example.com/products/abc-987?ref=product-page

This is demonstrated in the admin panel's help text to guide users.

Sources: README.md:106-113, src/admin-html.ts:1470-1478

Path Parameter Placeholders (Pattern Routes)

For more advanced routing, gr8hopper supports "Pattern Routes" where the route ID itself is a pattern that can capture segments of the URL path. These captured segments become available as placeholders.

Syntax	Description	Example Pattern	Matches Path
{param}	Required path parameter.	shop/{category}	/shop/shoes
:param	Shorthand for a required path parameter.	shop/:category	/shop/shoes
{param?}	Optional path parameter.	blog/{year?}/{slug}	/blog/2024/post and /blog/post
{param=default}	Optional path parameter with a default value.	docs/{lang=en}/{topic}	/docs/api (lang='en')
*	Wildcard for exactly one path segment.	files/*/details	/files/image.jpg/details
**	Globstar for zero or more path segments.	assets/**	/assets/css/style.css

If multiple wildcards of the same type are used, they are indexed (e.g., *, *1, *2).

Sources: README.md:115-139

Reserved Placeholders

gr8hopper includes a set of reserved placeholders that are automatically populated.

Placeholder	Source	Description
{route}	The ID of the matched route.	Automatically URL-encoded. Useful for tracking which route was triggered.

A user-defined parameter named route (e.g., from a query string ?route=...) will be overwritten by this reserved placeholder.

Sources: README.md:108, README.md:154-155

Validation and Security

To ensure security and stability, placeholders and the patterns they are defined in are subject to strict validation.

Route ID and Pattern Validation

The validateRouteIdPattern function ensures that route IDs containing placeholders are well-formed. The validation checks include:

• Balanced {} braces.
• No nested braces.
• Non-empty parameter names inside {...} and :....
• Parameter names do not contain invalid characters like ?, =, {, }, or whitespace.

This validation is performed in src/utils/validation.ts before a route is saved.

Sources: src/utils/validation.ts:38-81, src/utils/validation.ts:192-200

The following diagram shows the validation flow for a route ID pattern:

Sources: src/utils/validation.ts:38-81

Destination URL Security

The destination template URL, which contains the placeholders, is also validated to prevent security vulnerabilities:

• Scheme Validation: Only http: and https: protocols are allowed. Dangerous schemes like javascript:, data:, and file: are blocked by isValidUrlScheme.
• Sanitization: The sanitizeUrl function removes control characters (e.g., newlines, null bytes) to prevent HTTP Header Injection attacks.
• Length Limit: URLs are limited to a maximum of 2048 characters to prevent abuse.

These security measures ensure that even if an attacker could manipulate a placeholder's value, they cannot construct a malicious redirect URL.

Sources: SECURITY.md:49-52, src/utils/validation.ts:13-17, src/utils/validation.ts:88-128

Summary

Template placeholders are the mechanism that gives gr8hopper its power for dynamic routing. By combining placeholders sourced from query strings and URL paths with a simple substitution engine, it allows for the management of complex redirect logic from a centralized and easy-to-understand interface. The system is fortified with robust validation and sanitization to ensure that this flexibility does not compromise security.

Sources: README.md:16-22, SECURITY.md:49-52