Express Server Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Express server in TrackerBot serves as a public bug and data intake portal. It is one of two primary services running side-by-side in the project, providing web-based forms that forward user submissions directly to GitHub as repository issues. This service allows the community to report website bugs or data inaccuracies (such as quest or item stats) without requiring direct access to the GitHub repositories.
The server is built using Express 5 and utilizes a modular architecture where static assets are served from a dedicated directory, while API endpoints handle logic for validation, rate limiting, and GitHub integration via Axios.
Sources: webserver.js:1-12, AGENTS.md:7-10, README.md:14-23, package.json:23-24
System Architecture
The web server operates as a stateless intermediary between the client-side HTML forms and the GitHub API. It handles environment validation at startup to ensure necessary tokens and repository paths are available.
The diagram shows the request flow from the client through security middleware to the final GitHub API integration.
Sources: webserver.js:17-40, webserver.js:89-106, AGENTS.md:12-25
Environment and Security Configuration
The server requires specific environment variables to function, particularly for GitHub authentication and repository routing. Security is enforced through multiple layers, including rate limiting and origin allow-listing.
- Trust Proxy: The server is configured to
trust proxy, which is critical for accurate rate limiting when deployed behind reverse proxies like Nginx or Cloudflare. - Origin Allowlist: A configurable
ALLOWED_ORIGINSset prevents unauthorized domains from submitting data to the API endpoints. - Rate Limiting: Separate instances of
express-rate-limitare applied to the/dataand/issueroutes to provide independent per-IP quotas (5 requests per minute).
Sources: webserver.js:21-34, webserver.js:46-49, webserver.js:64-87
| Variable | Description | Source |
|---|---|---|
GITHUB_TOKEN | Personal Access Token with issue write permissions. | webserver.js:23 |
REPO_DEV | Repository path for website/app bug reports. | webserver.js:52 |
REPO_DATA_REPORT | Repository path for game data/overlay reports. | webserver.js:51 |
ALLOWED_ORIGINS | Comma-separated list of permitted request origins. | webserver.js:77 |
PORT | The port on which the Express server listens (default 3000). | webserver.js:43 |
Request Handling and Validation
The server implements strict validation and sanitization for all incoming reports to prevent API abuse and maintain data quality in the GitHub repositories.
Honeypot and Sanitization
To mitigate automated spam, the server uses a "honeypot" field named company. If this hidden field contains any data, the request is silently ignored (returning a success response to the bot but taking no action). Real data is then truncated to defined maximum lengths before processing.
Sources: webserver.js:57-62, webserver.js:100-112
Data Models and Caps
Input fields are subject to length restrictions to ensure compatibility with GitHub's issue limits and to prevent payload injection.
| Field | Max Length | Description |
|---|---|---|
title | 200 characters | The short summary of the issue. |
discord | 64 characters | User's Discord handle for follow-up. |
category | 64 characters | The area of impact (e.g., Maps, Quests). |
reference | 500 characters | Optional links to screenshots or sources. |
description | 8000 characters | Detailed explanation of the issue. |
Sources: webserver.js:57-61, webserver.js:104-112
API Endpoints
The server exposes two main POST endpoints for report submission and one GET endpoint for health monitoring.
POST /data
Handles game data reports (e.g., incorrect item stats). Submissions are routed to the REPO_DATA_REPORT repository. The issue body is formatted to include the Discord handle, category, and reference link before the description.
Sources: webserver.js:116-152, web/data/index.html:36-61
POST /issue
Handles website/development bug reports. Submissions are routed to the REPO_DEV repository. It requires a title, Discord handle, and description.
Sources: webserver.js:157-185, web/issue/index.html:33-47
This diagram illustrates the sequence of operations performed during a report submission.
Sources: webserver.js:116-185, web/data/index.html:106-120
Static File Serving
The server serves static HTML, CSS, and asset files from the /web directory using express.static. This includes the main portal and specific forms for different report types.
- /index.html: The central portal providing links to specific report forms.
- /issue/index.html: The form for website-specific bugs.
- /data/index.html: The form for data-specific reports, supporting URL parameters for pre-filling fields.
- /styles.css: Global styles for the web portal.
Sources: webserver.js:96, web/index.html, web/issue/index.html, web/data/index.html
Error Handling and Logging
The server includes a specialized logSanitizedError function. This is a critical security measure that prevents the full Axios error object—which contains sensitive environment variables like the GITHUB_TOKEN in request headers—from being written to the logs.
function logSanitizedError(route, err) {
const status = err.response?.status ?? "no-response";
const message = err.message ?? "unknown error";
console.error(`[${route}] GitHub API error: status=${status} message=${message}`);
}
Sources: webserver.js:187-196
Summary
The Express Server Configuration in TrackerBot provides a secure and robust bridge between public users and GitHub's issue tracking system. Through the use of environment validation, rate limiting, honeypots, and sanitized logging, the system ensures that community feedback is collected efficiently while protecting the project's internal credentials and preventing API abuse.