Home

Relevant source files

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

• README.md
• package.json
• src/index.ts
• src/server.ts
• src/admin-html.ts
• CONTRIBUTING.md
• SECURITY.md

gr8hopper is a lightweight, performance-first URL redirect service designed to handle complex, parameter-driven routing logic. It provides a simple admin UI to manage redirect routes and can be deployed to high-performance edge environments like Cloudflare Workers or self-hosted on any VPS using Node.js, Bun, or Docker. The core strength of gr8hopper is centralizing dynamic redirect logic, allowing for clean source data in CRMs or contact lists while the service handles the complex routing.

Built on the Hono web framework, gr8hopper has a minimal footprint and is optimized for speed, primarily through an aggressive caching strategy. While powerful enough for advanced scenarios, its simplicity also makes it an excellent general-purpose redirector.

Sources: README.md:7-21, package.json:10-11

Core Features

Feature	Description
Admin UI	A self-contained, responsive web interface for adding, editing, deleting, and managing redirect routes and global settings. Sources: README.md:23, src/admin-html.ts
Parameter Rewriting	Dynamically substitutes placeholders in the destination URL (e.g., {param}) with values from the source URL's query parameters or path segments. Sources: README.md:24
Pattern Routes	Supports advanced route matching using wildcards (*, **), named parameters (:param, {param}), and query string patterns. Sources: README.md:106-112
Edge Efficiency	Designed for edge deployment on Cloudflare Workers, leveraging aggressive 301 caching to serve subsequent requests directly from the CDN edge, minimizing code execution. Sources: README.md:25, README.md:214-216
Standalone Deployment	Can be deployed as a self-contained service on a VPS via Node.js, Bun, or a provided Docker image. Sources: README.md:26, src/server.ts
Minimal Footprint	Built on the zero-dependency, lightweight Hono web framework, ensuring fast startup and low resource usage. Sources: README.md:27

Architecture Overview

gr8hopper is built with a flexible architecture that supports two primary deployment targets: serverless (Cloudflare Workers) and traditional servers (VPS/Docker). This is achieved through separate entry points that share common handlers, storage adapters, and middleware.

Sources: CONTRIBUTING.md:32-40, README.md:281-298

This diagram illustrates the high-level project structure.

Deployment Environments

Cloudflare Workers

This is the recommended environment for production due to its performance and scalability.

• Entry Point: src/index.ts
• Storage: Uses Cloudflare KV via the KVAdapter. Route and settings data is stored in a globally distributed key-value store.
• Initialization: Handlers and configuration are initialized on the first request to a worker instance (cold start) and then cached for subsequent requests to improve performance.
• Security: Admin credentials and Cloudflare API tokens are managed securely using Wrangler secrets.

Sources: src/index.ts:13-48, README.md:329-332

The following diagram shows the request flow for a Cloudflare Worker deployment.

VPS (Node.js/Docker)

This environment is for self-hosting the service on a virtual private server.

• Entry Point: src/server.ts
• Storage: Uses a local JSON file (routes.json by default) via the JsonFileAdapter. The location is configurable with the CONFIG_FILE environment variable.
• Server: Uses @hono/node-server to run the Hono application.
• Security: Admin credentials must be provided via ADMIN_USERNAME and ADMIN_PASSWORD environment variables. The application will exit on startup if they are not set. The username 'admin' is explicitly rejected for security.

Sources: src/server.ts:1-150, README.md:371-379

Redirect Logic

The core function of gr8hopper is to process an incoming request, find a matching route, and issue a 301 redirect to a dynamically constructed destination URL.

This diagram shows the redirect decision flow.

Template Placeholders

The destination URL template can contain placeholders in the format {param} which are replaced by values from the incoming request.

Placeholder	Source	Example
{route}	The ID of the matched route (URL-encoded).	partner-a
{anyParam}	A URL query parameter from the source request.	?anyParam=value
{*}	A wildcard path segment from a pattern route.	/files/image.jpg -> {*: 'image.jpg'}

Missing placeholders are intentionally left as-is in the final URL to make configuration errors visible.

Sources: README.md:96-104

Query Parameter Passthrough

If a route has passthrough: true, all query parameters from the source URL (e.g., UTM tags) are appended to the destination URL. This is an opt-in feature. Parameters already defined in the destination template take precedence.

Sources: README.md:162-171

Admin Panel

The admin panel is a single-page application embedded directly into the binary, accessible at the /admin path (or a custom path set by ADMIN_PATH). It provides full management of routes and settings.

Sources: src/admin-html.ts:1-6, README.md:195-202

API Endpoints

The admin panel communicates with the backend via a set of RESTful API endpoints. All admin endpoints are protected by HTTP Basic Authentication.

Sources: README.md:204-212, src/server.ts:129-131, src/index.ts:70-75

Method	Endpoint	Description
GET	/admin/routes	List all routes.
GET	/admin/routes/:id	Get a single route by its ID.
POST	/admin/routes	Create a new route.
PUT	/admin/routes/:id	Update an existing route.
DELETE	/admin/routes/:id	Delete a route.
GET	/admin/settings	Get global settings.
PUT	/admin/settings	Update global settings.
GET	/admin/export	Export all routes and settings as a JSON file.
POST	/admin/import	Import routes and settings from a JSON file, replacing all existing data.

Configuration

Environment Variables

The application is configured using environment variables, which differ slightly between deployment platforms.

Variable	Default	Platform	Description
PORT	3000	VPS	HTTP server port.
CONFIG_FILE	./routes.json	VPS	Path to the JSON file for storing routes.
ADMIN_USERNAME	(required)	Both	Admin panel username. Cannot be 'admin'.
ADMIN_PASSWORD	(required)	Both	Admin panel password.
ADMIN_PATH	admin	Both	URL path for the admin panel.
CLOUDFLARE_API_TOKEN	(optional)	CF Workers	API token for purging the Cloudflare cache.
CLOUDFLARE_ZONE_ID	(optional)	CF Workers	Zone ID for purging the Cloudflare cache.

Sources: README.md:186-193, src/server.ts:60-63, 110-117, src/index.ts:43-46

Route Schema

Each redirect is defined by a route object with the following structure.

Field	Type	Required	Description
id	string	Yes	The unique identifier for the route, which can be a simple string or a path pattern.
template	string	Yes	The target URL, which can include {param} placeholders.
active	boolean	Yes	Toggles whether the redirect is enabled or disabled.
passthrough	boolean	No	If true, appends query parameters from the source URL to the destination. Defaults to false.

Sources: README.md:88-94

Global Settings

These settings apply to the entire service and are managed in the admin panel.

Field	Type	Default	Description
fallback_url	string	/not-found	URL to redirect to when no matching route is found.
cache_ttl	number	604800	Browser cache duration in seconds (1 week).
route_param	string	r	The query parameter name used for simple route selection (e.g., ?r=my-route).

Sources: README.md:173-178

Security

Security is a critical aspect of gr8hopper.

• Authentication: The admin panel and its API are protected by HTTP Basic Authentication. ADMIN_USERNAME and ADMIN_PASSWORD are mandatory environment variables.
• Transport Security: Production deployments must use HTTPS to protect credentials in transit.
• Input Validation: Route IDs are sanitized, and destination URL templates are validated to block dangerous schemes like javascript:.
• Rate Limiting: It is recommended to configure rate limiting on the /admin path at the CDN or reverse proxy level to prevent brute-force attacks.

Sources: SECURITY.md:14-20, 48-53, README.md:465-489, src/server.ts:66-89

Development and Contribution

The project uses TypeScript and can be developed locally for either Cloudflare Workers or Node.js environments.

• Dependencies: Managed with npm. Key dependencies include hono and @hono/node-server.
• Local Development:
  • npm run dev: Starts a local development server for Cloudflare Workers using wrangler.
  • npm run dev:node: Starts a local development server for Node.js using tsx.
• Code Style: The project enforces a strict TypeScript configuration and consistent code style. JSDoc comments are used for public functions.

Sources: CONTRIBUTING.md:5-29, package.json:12-15