The Admin UI

Relevant source files

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

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

The Admin UI is a self-contained web interface for managing the gr8hopper redirect service. It provides administrators with a simple, mobile-optimized panel to create, edit, and delete redirect routes, configure global settings, and perform maintenance tasks like importing/exporting configurations and purging the CDN cache. The entire UI is embedded within the application, requiring no separate hosting or dependencies.

Access to the Admin UI and its corresponding API is protected by HTTP Basic Authentication. The interface is served from a customizable path, which defaults to /admin. All interactions with the server are handled through a set of RESTful API endpoints, which manipulate the route and settings data stored in either Cloudflare KV or a local JSON file, depending on the deployment environment.

Sources: README.md, src/admin-html.ts, src/handlers/admin.ts

Architecture

The Admin UI follows a simple client-server architecture where the "client" is a single-page application (SPA) embedded directly into the server.

• Frontend: A single HTML file containing vanilla JavaScript and CSS. It is generated by the getAdminHtml function in src/admin-html.ts and served directly by the Hono web server. This approach ensures the application is fully self-contained.
• Backend: A set of API endpoints built with Hono, defined in src/handlers/admin.ts. These endpoints handle all business logic for managing routes and settings.
• Authentication: A middleware layer (basicAuth) protects all admin-related routes. This is configured in the main entry points (src/index.ts for Cloudflare Workers and src/server.ts for Node.js).
• Storage: The admin handler interacts with a storage adapter (StorageAdapter) to persist data, abstracting away the difference between Cloudflare KV and a JSON file.

Sources: src/admin-html.ts:5, src/handlers/admin.ts:19, src/index.ts:13, src/server.ts:130

The following diagram illustrates the request flow for an admin user interacting with the UI.

Authentication

All endpoints under the admin path (default /admin) are protected by HTTP Basic Authentication. The application will not start if the required ADMIN_USERNAME and ADMIN_PASSWORD environment variables are not set. For security, the username 'admin' is explicitly rejected.

The authentication middleware is applied in the main application entry points, ensuring no unauthenticated access to the admin API or UI is possible.

• Cloudflare Workers: basicAuth is applied in src/index.ts.
• Node.js/VPS: basicAuth is applied in src/server.ts.

Sources: src/server.ts:80-106, src/index.ts:36-47, SECURITY.md:14-16

The authentication flow is visualized below.

UI Components

The Admin UI is constructed from several key components, all rendered from src/admin-html.ts.

Component	Description	Source
Header	Displays the application name, version, and a "Log out" button.	src/admin-html.ts:1210-1222
Settings Section	An expandable panel to configure global settings like route_param, cache_ttl, and fallback_url.	src/admin-html.ts:1225-1279
Routes List	The main area, which lists all redirects. Each entry has an on/off toggle, route ID, destination template, and buttons to edit or delete.	src/admin-html.ts:1282-1318
Modals	Used for creating/editing routes, confirming bulk imports, and confirming CDN cache purges to prevent accidental actions.	src/admin-html.ts:1329-1481
Toast Notifications	Provides non-blocking feedback for actions like saving a route or a failed import.	src/admin-html.ts:1199-1202, 1484-1514
Import/Export Buttons	Allow administrators to download the entire configuration as a JSON file or upload one to replace the existing setup.	src/admin-html.ts:1286-1299
Cache Purge Button	Appears if Cloudflare credentials are configured, allowing a full CDN cache purge.	src/admin-html.ts:1262-1276

Sources: src/admin-html.ts

API Endpoints

The Admin UI communicates with the backend via a RESTful API. All endpoints are prefixed with the admin path (e.g., /admin).

Method	Endpoint	Description
GET	/routes	Lists all redirect routes.
POST	/routes	Creates a new redirect route.
GET	/routes/:id or /routes/*	Retrieves a single route. The wildcard * supports IDs with slashes.
PATCH	/routes/:id or /routes/*	Updates an existing route (partial updates supported).
DELETE	/routes/:id or /routes/*	Deletes a route.
GET	/settings	Retrieves the global settings.
PUT	/settings	Updates the global settings.
GET	/export	Exports all routes and settings as a single JSON file.
POST	/import	Imports a JSON file, replacing all existing routes and settings.
GET	/purge-cache/status	Checks if CDN cache purging is configured and available.
POST	/purge-cache	Triggers a purge of the entire Cloudflare CDN cache.

Sources: src/handlers/admin.ts:77-336, README.md

Route Management Flow

Creating or updating a route involves validation and interaction with the storage adapter.

Import/Export

The import/export feature allows for easy backup, restoration, and bulk management of routes.

Export

A GET request to /export retrieves all routes and settings from storage and formats them into a specific JSON structure for download.

Sources: src/handlers/admin.ts:251-275

Import

The import process is more complex, involving validation, a full replacement of data, and a rollback mechanism in case of failure.

1. A POST request is sent to /import with a JSON file.
2. The server validates the structure of the routes and settings objects.
3. Each route within the file is individually validated for ID format and configuration.
4. The server backs up the current routes and settings in memory.
5. All existing routes are deleted, and the new routes are written to storage in a bulk operation.
6. If settings are included, they are updated.
7. If any step fails, the server attempts to restore the backup.

Sources: src/handlers/admin.ts:278-336

The following diagram illustrates the import sequence.

CDN Cache Purging

This feature is exclusive to Cloudflare Worker deployments and provides a button in the UI to purge the CDN cache.

• Availability: The UI first calls GET /purge-cache/status. The backend checks for the presence of CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID environment variables to determine if the feature is available.
• Execution: If the user confirms the action, the browser sends a POST /purge-cache request. The backend then makes a signed API request to the Cloudflare API to purge everything for the configured zone ID.

Sources: src/handlers/admin.ts:429-467, src/admin-html.ts:1873-1883

Conclusion

The Admin UI is a crucial component of gr8hopper, providing a complete and user-friendly solution for managing redirects. Its design as an embedded, self-contained SPA simplifies deployment and maintenance, while the robust backend API offers powerful features like bulk import/export and CDN cache control. The clear separation between the UI, API logic, and storage adapters makes the system modular and easy to extend.