Contribution Guidelines

Relevant source files

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

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

Thank you for considering contributing to gr8hopper, a lightweight, performance-first URL redirect service. This document provides a comprehensive guide for making contributions, from setting up your development environment to submitting pull requests. The project is designed for deployment on Cloudflare Workers or any VPS (via Node.js/Bun/Docker) and is built on the Hono web framework.

Before starting, it's recommended to check existing issues and pull requests to prevent duplicate work. For significant changes, please open an issue first to discuss the proposed approach.

Sources: CONTRIBUTING.md:3-4, CONTRIBUTING.md:20-22, README.md:7

Development Setup

To begin development, you need to set up the project locally. This involves forking and cloning the repository, installing dependencies, and running the local development server.

Sources: CONTRIBUTING.md:5-9

Initial Setup

1. Fork and Clone: Fork the gr8hopper repository on GitHub and clone it to your local machine.
2. Install Dependencies: Navigate to the project directory and install the required npm packages.

   npm install
   

Sources: CONTRIBUTING.md:6-7, package.json:12

Running Locally

The project supports two primary development environments: Node.js for general VPS-style development and Cloudflare Workers for edge-specific development.

The following diagram illustrates the local development server options.

The available npm scripts for development are listed below:

Script	Description
npm run dev	Starts the local development server for Cloudflare Workers using wrangler dev.
npm run dev:node	Starts the local development server for Node.js using tsx watch src/server.ts for hot reloading.
npm run build	Compiles the TypeScript source code into JavaScript in the dist/ directory.
npx tsc --noEmit	Runs type checking without generating output files.

Sources: CONTRIBUTING.md:8, CONTRIBUTING.md:26, package.json:13-16

Code Style and Conventions

To maintain code quality and consistency, please adhere to the following guidelines.

General Style

• The project uses TypeScript with strict mode enabled.
• Use meaningful and descriptive names for variables and functions.
• Add JSDoc comments for all public functions to explain their purpose, parameters, and return values.
• Keep functions small, focused, and responsible for a single task.

Sources: CONTRIBUTING.md:11-15

Commit Messages

Commit messages should be clear, descriptive, and follow a conventional format. This helps in understanding the history of changes and automating changelog generation.

Prefix	Description
feat	A new feature
fix	A bug fix
docs	Documentation only changes
refactor	A code change that neither fixes a bug nor adds a feature

Example:

feat: add support for regex-based route matching

Sources: CONTRIBUTING.md:30-36

Development Workflow

The standard workflow for making changes ensures that contributions are easy to review and integrate.

This flowchart shows the recommended development process from branch creation to pull request.

Pull Request Requirements

Before submitting a Pull Request, please ensure the following:

1. Documentation: Update any relevant documentation if your changes affect user-facing features or configuration.
2. Type Checking: Ensure the TypeScript code compiles without any errors (npx tsc --noEmit).
3. Testing: Test your changes on both Node.js and Cloudflare Workers platforms if possible to ensure compatibility.
4. Description: Provide a clear description of what your PR does and why the change is being made.

Sources: CONTRIBUTING.md:38-41

Project Structure

The project is organized into several key directories within the src/ folder, separating concerns like request handling, data storage, and middleware.

src/
├── index.ts           # CF Workers entry - routes requests
├── server.ts          # Node.js entry - HTTP server setup
├── types.ts           # Shared TypeScript interfaces
├── admin-html.ts      # Admin UI (embedded HTML and JS)
├── handlers/          # Request handlers (redirect, admin)
├── storage/           # Storage adapters (KV, JSON file)
├── middleware/        # Auth and other middleware
└── utils/             # Shared utilities (validation, sanitization)

Sources: CONTRIBUTING.md:43-50, README.md:231-247

Adding Features

The project is designed to be extensible. The most common contributions involve adding new storage adapters or middleware.

New Storage Adapter

To add support for a new data storage backend (e.g., a database), you must implement the StorageAdapter interface.

1. Create a new file in src/storage/ that implements the StorageAdapter interface (defined conceptually in src/storage/adapter.ts).
2. Add the new adapter to the storage selection logic in the entry points (src/index.ts for Cloudflare Workers and src/server.ts for Node.js).

The following class diagram shows the structure of storage adapters.

New Middleware

Middleware functions follow the Hono middleware conventions.

1. Create the middleware function in a new file under src/middleware/.
2. Apply the middleware to the appropriate routes in src/index.ts or src/server.ts. For example, the basic authentication middleware is applied to all admin routes.

Sources: CONTRIBUTING.md:57-60, src/server.ts:130-133, src/index.ts:74-81

Security Considerations

Security is critical for a service that handles URL redirection. All contributions must adhere to the project's security policies.

• Authentication: Admin endpoints are protected by HTTP Basic Auth. Do not weaken these protections.
• Input Validation: All user-provided input, especially route IDs and template URLs, must be validated and sanitized. The src/utils/validation.ts file contains functions like validateRouteIdPattern and isValidUrlScheme for this purpose. Dangerous URL schemes (javascript:, data:, etc.) are explicitly blocked.
• Open Redirects: Be mindful that the core function of the app is to perform redirects. Any vulnerability that allows an attacker to create or modify routes can lead to phishing.
• XSS Protection: The admin panel uses safe DOM methods (textContent, createElement) to render dynamic content and prevent Cross-Site Scripting (XSS). Avoid using innerHTML with user-controllable data.
• Vulnerability Reporting: If you discover a security vulnerability, do not open a public issue. Email the maintainers directly as outlined in SECURITY.md.

Sources: SECURITY.md:10-14, SECURITY.md:25-29, SECURITY.md:39-44, src/utils/validation.ts:11-15, src/admin-html.ts:1418-1420