Central Alerts API Endpoints

Relevant source files

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

• src/services/central-alerts/v1/interfaces.ts
• src/services/central-alerts/v1/db/init.sql
• src/services/central-alerts/v1/README.md
• README.md
• test/services/central-alerts/v1/database.test.ts
• test/services/central-alerts/v1/index.test.ts

The Central Alerts API is a dedicated service within the FOSSBilling API Worker designed to broadcast critical notifications to FOSSBilling installations. This system allows project administrators to target specific version ranges of the software with security hotfixes, update notices, or general project announcements.

The service acts as a middleman between the FOSSBilling central authority and distributed instances, ensuring that administrators receive timely information directly within their application panels. It relies on a Cloudflare D1 database for persistent storage of alert data and uses structured version comparisons to determine alert relevance.

Sources: README.md:12-14, src/services/central-alerts/v1/README.md:1-5

Service Architecture

The Central Alerts service is built using the Hono framework and is deployed as part of a platform-agnostic worker. It primarily interacts with a Cloudflare D1 database binding named DB_CENTRAL_ALERTS.

Data Flow Overview

The following diagram illustrates how a client instance retrieves alerts from the API.

API Endpoints

List Active Alerts

GET /central-alerts/v1/list

This is the primary public endpoint for fetching active system alerts. It returns a collection of alerts that may include metadata such as severity levels, target version ranges, and call-to-action buttons.

Request Details:

• Method: GET
• Authentication: None (Public)
• Path: /central-alerts/v1/list

Success Response (200 OK):
The response returns a result object containing an array of alerts.

Field	Type	Description
id	string	Unique identifier for the alert.
title	string	Short summary of the alert.
message	string	Detailed description of the notification.
type	string	Severity level: success, info, warning, or danger.
dismissible	boolean	Whether the user can close the alert in their panel.
min_fossbilling_version	string	Minimum software version affected (Semantic Version).
max_fossbilling_version	string	Maximum software version affected (Semantic Version).
include_preview_branch	boolean	Whether the alert applies to preview/beta releases.
buttons	array	(Optional) List of interactive links/actions.
datetime	string	ISO 8601 timestamp of when the alert was issued.

Sources: src/services/central-alerts/v1/README.md:7-40, src/services/central-alerts/v1/interfaces.ts:1-15

Data Model and Schema

The service utilizes a relational schema in SQLite (via D1) to manage alert entries. Buttons are stored as a JSON string within the database and parsed into objects during API delivery.

Database Schema

CREATE TABLE IF NOT EXISTS central_alerts (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    message TEXT NOT NULL,
    type TEXT NOT NULL CHECK (type IN ('success', 'info', 'warning', 'danger')),
    dismissible BOOLEAN NOT NULL DEFAULT false,
    min_fossbilling_version TEXT NOT NULL,
    max_fossbilling_version TEXT NOT NULL,
    include_preview_branch BOOLEAN NOT NULL DEFAULT false,
    buttons JSON DEFAULT '[]',
    datetime TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Sources: src/services/central-alerts/v1/db/init.sql:4-17

Entity Relationship Diagram

The following diagram shows the structure of the central_alerts entity and its attributes.

Logic and Validation

Version Filtering

Alerts are designed to be targeted. The min_fossbilling_version and max_fossbilling_version fields are used by the consuming FOSSBilling instance or the API (depending on implementation) to filter notifications. For example, a "danger" alert might be targeted specifically at versions between 0.0.0 and 0.5.2 to warn about a critical SQL injection vulnerability.

Sources: src/services/central-alerts/v1/db/init.sql:24-27, test/services/central-alerts/v1/index.test.ts:55-58

Error Handling

The API includes middleware and standard error structures to prevent leaking database details. If the database connection fails or a query is invalid, the API returns a 500 Internal Server Error with a sanitized message.

Error Response Format:

{
  "result": null,
  "error": {
    "message": "Unable to load central alerts",
    "code": "DATABASE_ERROR"
  }
}

Sources: test/services/central-alerts/v1/index.test.ts:145-160, src/services/central-alerts/v1/README.md:42-49

Conclusion

The Central Alerts API provides a critical communication channel for the FOSSBilling ecosystem. By utilizing a structured D1 database and targeting specific software versions, it ensures that security-sensitive information and project updates reach the relevant administrators efficiently while maintaining a lightweight, platform-agnostic architecture.