Extensions Service
Relevant source files
The following files were used as context for generating this wiki page:
The Extensions Service is a core module within the FOSSBilling API Worker designed to manage and distribute information regarding third-party modules and themes (collectively referred to as extensions). It acts as a central repository, allowing FOSSBilling instances to query available extensions, retrieve specific metadata, and generate visual badges for status reporting.
Built on the Hono framework, the service is platform-agnostic but primarily utilizes Cloudflare's D1 for structured data storage. It integrates with the broader project architecture by leveraging shared platform interfaces and middleware for database access and request handling.
Sources: README.md, src/services/extensions/v1/index.ts:1-12, AGENTS.md
Architecture and Data Flow
The Extensions Service follows a standard controller-service-repository pattern. Routes are defined using Hono, logic for data retrieval is encapsulated within the ExtensionsDatabase class, and data is persisted in a Cloudflare D1 database instance named DB_EXTENSIONS.
System Flow
The following diagram illustrates the request flow from a client through the API layers to the database.
The service utilizes getPlatform(c) to resolve environment bindings, ensuring compatibility across different runtimes (Cloudflare vs Node).
Sources: src/services/extensions/v1/index.ts:15-25, test/services/extensions/v1/index.test.ts:80-140
API Endpoints
The service exposes several endpoints under the /extensions/v1 base path to facilitate extension discovery and metadata retrieval.
Endpoint Summary
| Endpoint | Method | Description |
|---|---|---|
/list | GET | Retrieves a list of all extensions, optionally filtered by type. |
/:id | GET | Returns detailed metadata for a specific extension by its ID. |
/:id/version | GET | Returns the latest version tag of the extension as plain text. |
/:id/badges/:type | GET | Generates an SVG badge for version, license, or compatibility. |
Sources: src/services/extensions/v1/index.ts:14-106, test/services/extensions/v1/index.test.ts:150-250
Extension Listing
The /list endpoint supports an optional type query parameter (e.g., mod or theme) to filter results. The service fetches all matching records and returns them as a JSON array.
Sources: src/services/extensions/v1/index.ts:14-25, test/services/extensions/v1/index.test.ts:162-171
Badge Generation
The service uses the badge-maker library to generate SVG badges dynamically. Supported badge types include:
- version: Displays the latest tag (e.g.,
v0.0.5). - min_fossbilling_version: Displays the minimum core version required.
- license: Displays the name of the extension's license.
Data Models
The service operates on extension objects stored in D1. These objects contain comprehensive metadata including author information, source repository details, and a history of releases.
Extension Schema
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier (e.g., "ExampleModule"). |
type | String | The category of extension (mod, theme). |
author | Object | Contains name, id, type, and url. |
releases | Array | List of objects containing tag, download_url, and min_fossbilling_version. |
license | Object | Contains name and optional URL. |
source | Object | Source control info (e.g., { "type": "github", "repo": "..." }). |
Sources: test/services/extensions/v1/index.test.ts:11-47, src/services/extensions/v1/index.ts:39-49
Implementation Details
Release Management
Releases are stored as a JSON string in the database and parsed into objects upon retrieval. The service includes utility functions to sort these releases in descending order based on their tags to ensure the "latest" version is accurately identified.
Sources: src/services/extensions/v1/index.ts:39-40, test/services/extensions/v1/index.test.ts:182-192
Error Handling
The service handles common error states, such as missing extensions or database failures:
- 404 Not Found: Returned when an extension ID does not match any database record (lookups are case-insensitive).
- 500 Internal Server Error: Returned if the database connection fails or required release data is missing.
Sources: src/services/extensions/v1/index.ts:74-82, test/services/extensions/v1/index.test.ts:212-220
Conclusion
The Extensions Service provides a vital link between extension developers and the FOSSBilling ecosystem. By centralizing metadata and providing standard API interfaces for versioning and badges, it ensures that FOSSBilling instances can maintain compatibility and security through up-to-date extension information.