Home
Relevant source files
The following files were used as context for generating this wiki page:
The FOSSBilling API Worker is a central hub service designed for FOSSBilling instances. Built on the Hono framework, it serves as the primary gateway for version management, system-wide alerts, and release statistics. The application is designed to be platform-agnostic, though it is primarily deployed to Cloudflare Workers using Wrangler.
The service architecture facilitates high-performance data retrieval by interfacing with the GitHub API, caching results for 24 hours to mitigate rate limiting, and providing structured JSON responses to client instances. It also includes a visual statistics dashboard for community monitoring of project health and release trends.
Sources: README.md:1-12, AGENTS.md:7-12
System Architecture
The project follows a modular, layer-based architecture that separates core business logic from platform-specific implementations.
- Application Logic: Located in
src/services/, including modules for versioning, alerts, and statistics. - Platform Layer: Defined in
src/lib/, providing interfaces for caching, databases, and environment variables. - Adapters: Contains concrete implementations for different runtimes, specifically
src/lib/adapters/cloudflare(using KV and D1) andsrc/lib/adapters/nodefor testing.
Sources: README.md:18-24, AGENTS.md:7-11
Data Flow Overview
The following diagram illustrates how a request for version data is handled by the worker, involving the Hono router, the internal service logic, and external dependencies like GitHub and Cloudflare KV.
The system prioritizes cached data to ensure fast response times for FOSSBilling instances.
Sources: src/services/versions/v1/index.ts:316-350, README.md:38-42
Core Services
Versions Service (/versions/v1)
This service acts as the source of truth for all FOSSBilling updates. It fetches metadata from GitHub releases, processes composer.json files to determine PHP requirements, and serves this data to instances for update checks.
| Endpoint | Method | Description |
|---|---|---|
/versions/v1 | GET | Lists all processed releases in descending semantic order. |
/versions/v1/:version | GET | Returns details for a specific version or the latest release. |
/versions/v1/build_changelog/:current | GET | Generates a consolidated changelog of all versions newer than the provided tag. |
/versions/v1/count | GET | Returns the total number of available releases. |
/versions/v1/update | GET | Triggers a cache refresh (requires Bearer authentication). |
Sources: README.md:28-36, src/services/versions/v1/README.md:11-66
Central Alerts Service (/central-alerts/v1)
Allows the FOSSBilling project to broadcast critical information, such as security hotfixes, directly to all installations. Data is stored in a Cloudflare D1 database.
| Feature | Description |
|---|---|
| Endpoint | GET /central-alerts/v1/list |
| Storage | Cloudflare D1 Database (DB_CENTRAL_ALERTS) |
| Content | JSON array of active alerts including message type, version constraints, and action buttons. |
Sources: README.md:38-42, README.md:50
Stats Service (/stats/v1)
Provides release statistics visualization. It offers both a raw data endpoint and a client-side rendered HTML dashboard.
Storage & Configuration
The worker utilizes Cloudflare-specific bindings for data persistence and authentication.
Storage Bindings
| Binding Name | Type | Purpose |
|---|---|---|
DB_CENTRAL_ALERTS | D1 | Stores system-wide alert messages. |
CACHE_KV | KV | Caches GitHub API responses and release statistics. |
AUTH_KV | KV | Stores the UPDATE_TOKEN for administrative tasks. |
Sources: README.md:48-52
Environment Variables
GITHUB_TOKEN: A Personal Access Token used to authenticate requests to the GitHub API, helping to avoid rate limits and access repository metadata.
Sources: README.md:56-57, src/services/versions/v1/index.ts:328-334
Development and Deployment
The project uses npm for task automation and wrangler for Cloudflare Workers interaction.
# Install dependencies
npm install
# Initialize local database
npm run init:db
# Start local development server
npm run dev
# Deploy to Cloudflare
npm run deploy
Sources: package.json:5-18, README.md:61-78
Testing
The codebase is tested using Vitest. The test suite includes:
- Integration Tests: Located in
test/integration/, testing the full app routing. - Service Tests: Colocated with service logic (e.g.,
test/services/versions/v1). - Runtime Tests: Can be run specifically for Node.js environments using
npm run test:node.
Sources: AGENTS.md:28-32, package.json:14-17
Summary
The FOSSBilling API Worker is a performance-optimized middleware that bridges the gap between the GitHub repository and active FOSSBilling installations. By leveraging Cloudflare's edge infrastructure and aggressive KV caching, it provides reliable versioning data, critical security alerts, and transparent project statistics.