Versions Service
Relevant source files
The following files were used as context for generating this wiki page:
The Versions Service acts as the central source of truth for FOSSBilling update information. It is responsible for fetching release metadata from the official GitHub repository, processing it into a standardized format, and providing it to FOSSBilling instances to determine if updates are necessary.
The service is built using the Hono framework and is designed to be runtime-agnostic, though it primarily targets Cloudflare Workers. It utilizes aggressive caching via Cloudflare KV to remain performant and avoid exceeding GitHub API rate limits.
Sources: README.md:12-14, src/services/versions/v1/README.md:3-5
Architecture and Data Flow
The service follows a layered architecture where the API interface (Hono) delegates logic to utility functions that interact with external providers (GitHub) and local storage (KV Cache).
Core Components
- API Router: Defines the RESTful endpoints for external consumption.
- Cache Layer: Uses Cloudflare KV to store release data for 24 hours (
max-age: 86400). - GitHub Provider: Interfaces with GitHub via REST (for releases) and GraphQL (for batch processing file contents).
- Update Logic: A protected endpoint that force-refreshes the cache.
Sources: src/services/versions/v1/index.ts:31-50, src/services/versions/v1/README.md:3-8
Release Data Retrieval Flow
The service prioritizes cached data. If the cache is empty or a force-update is requested, it initiates a fresh fetch from GitHub.
API Endpoints
All endpoints are prefixed with /versions/v1.
| Endpoint | Method | Description |
|---|---|---|
/ | GET | Returns a map of all available releases, sorted by semantic version. |
/:version | GET | Returns details for a specific version. Supports latest as an alias. |
/count | GET | Returns the total number of available releases. |
/build_changelog/:current | GET | Generates a consolidated changelog of all releases newer than :current. |
/update | GET | Triggers a cache refresh. Requires Bearer Authentication. |
Sources: src/services/versions/v1/README.md:10-58, src/services/versions/v1/index.ts:133-248
Data Models
The ReleaseDetails object represents the standardized metadata for a single FOSSBilling version.
| Field | Type | Description |
|---|---|---|
version | string | The semantic version tag (e.g., "0.6.0"). |
released_on | string | ISO 8601 timestamp of the release. |
minimum_php_version | string | Minimum PHP version required (extracted from composer.json). |
download_url | string | Direct link to the FOSSBilling.zip asset. |
size_bytes | number | Size of the download asset in bytes. |
is_prerelease | boolean | Indicates if the release is marked as a pre-release on GitHub. |
github_release_id | number | The internal ID from GitHub. |
changelog | string | The release notes/body text. |
Sources: src/services/versions/v1/index.ts:326-335, src/services/versions/v1/README.md:18-28
Implementation Details
GitHub Integration
The service uses a hybrid approach to fetch data efficiently:
- REST API: Fetches the list of the last 100 releases from
GET /repos/FOSSBilling/FOSSBilling/releases. - GraphQL API: For any release not already in the cache, the service uses a single GraphQL query to batch-fetch the
composer.jsonfile content. This avoids the "N+1" problem of making a separate REST call for every single release to determine PHP requirements.
Sources: src/services/versions/v1/index.ts:275-312, src/services/versions/v1/index.ts:466-498
Authentication and Security
The /update endpoint is protected by a Bearer token stored in the AUTH_KV namespace under the key UPDATE_TOKEN. The service implements an internal cache for this token (UPDATE_TOKEN_CACHE_TTL_MS = 60000) to reduce KV read operations.
Error Handling and Resilience
The service implements a "graceful degradation" strategy. If the GitHub API is unavailable (e.g., due to rate limits or downtime), the service will attempt to serve "stale" data from the cache. In such cases, the JSON response includes a stale: true flag.
If both the GitHub API and the cache are unavailable, the service returns a 503 Service Unavailable status with a standardized error envelope including http_status and error_code from the upstream failure.
Sources: src/services/versions/v1/index.ts:114-123, test/services/versions/v1/errors.test.ts:114-142
Middleware
The Versions Service utilizes several Hono middlewares to ensure consistency and performance:
- CORS: Allows cross-origin requests from any origin (
*). - Trailing Slash: Redirects requests ending in
/to the non-trailing version (e.g.,/versions/v1/to/versions/v1). - ETag: Generates ETag headers for cacheable responses to support
304 Not Modifiedstatus codes. - Pretty JSON: Automatically formats JSON responses for better readability.
Sources: test/services/versions/v1/middleware.test.ts:44-125, src/services/versions/v1/index.ts:43-50
Summary
The Versions Service provides a robust, cached interface for FOSSBilling update metadata. By combining REST and GraphQL APIs with Cloudflare KV storage, it delivers high-performance version checks while maintaining resilience against upstream API failures.