Central Alerts Service

Relevant source files

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

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

The Central Alerts Service is a core component of the FOSSBilling API Worker designed to broadcast critical notifications to FOSSBilling installations. It enables project maintainers to push targeted messages, such as security hotfixes, update notices, or general announcements, to specific ranges of FOSSBilling versions.

Sources: README.md:9-11, src/services/central-alerts/v1/README.md:5-7

Architecture and Data Flow

The service is built on the Hono framework and follows a decoupled architecture that separates routing logic from database operations. It interacts with a Cloudflare D1 database (aliased as DB_CENTRAL_ALERTS) to retrieve stored alert records. The data flow begins with a client request to the /list endpoint, which triggers the CentralAlertsDatabase class to query and process alert data before returning a standardized JSON response.

Sources: README.md:5-7, src/services/central-alerts/v1/index.ts:14-17, src/services/central-alerts/v1/README.md:2, src/services/central-alerts/v1/database.ts:6-8

Request Sequence

The following diagram illustrates the lifecycle of a request to retrieve active alerts.

Data Model

The service utilizes a specific schema within the Cloudflare D1 database to store alert metadata. This includes version constraints (minimum and maximum supported versions) and UI-related properties like alert types and interactive buttons.

Database Schema

The central_alerts table is defined with the following structure:

Field	Type	Constraints	Description
id	TEXT	PRIMARY KEY	Unique identifier for the alert.
title	TEXT	NOT NULL	The headline of the notification.
message	TEXT	NOT NULL	The body content of the alert.
type	TEXT	CHECK (success, info, warning, danger)	Visual category of the alert.
dismissible	BOOLEAN	DEFAULT false	Whether the user can close the alert.
min_fossbilling_version	TEXT	NOT NULL	Lower bound of affected versions.
max_fossbilling_version	TEXT	NOT NULL	Upper bound of affected versions.
include_preview_branch	BOOLEAN	DEFAULT false	Include pre-release versions.
buttons	JSON	DEFAULT '[]'	Actionable links/buttons.
datetime	TEXT	NOT NULL	ISO 8601 timestamp for sorting.

Sources: src/services/central-alerts/v1/db/init.sql:4-18, src/services/central-alerts/v1/interfaces.ts:1-15

Alert Logic and Types

The service supports four primary alert types: success, info, warning, and danger. These types are often used by the client to determine the color and severity of the notification. Additionally, alerts can include a buttons array which contains objects with text, link, and an optional type.

Sources: src/services/central-alerts/v1/interfaces.ts:5-13, src/services/central-alerts/v1/README.md:52

API Implementation

Endpoints

Method	Path	Description	Access
GET	/central-alerts/v1/list	Returns all active alerts, sorted by datetime descending.	Public

Sources: src/services/central-alerts/v1/README.md:9-11, src/services/central-alerts/v1/index.ts:14

Logic and Error Handling

The implementation uses a CentralAlertsDatabase class to wrap database interactions. During retrieval, the service performs data sanitization, specifically:

1. Boolean Conversion: SQL integer values (0/1) for dismissible and include_preview_branch are converted to true JavaScript Booleans.
2. JSON Parsing: The buttons field, stored as a stringified JSON in SQL, is parsed into a structured object.
3. Global Sorting: Results are ordered by the datetime field in descending order to ensure the most recent alerts are processed first.

In the event of a database failure, the service logs the internal error and returns a generic 500 Internal Server Error with a standardized DATABASE_ERROR code to avoid exposing sensitive schema details.

Sources: src/services/central-alerts/v1/database.ts:24-53, src/services/central-alerts/v1/index.ts:22-35, test/services/central-alerts/v1/index.test.ts:133-145

Development and Testing

The service includes an initialization script for setting up the D1 database and is tested using Vitest. Tests verify that the /list endpoint returns the correct ISO 8601 datetime format, handles trailing slashes via 301 redirects, and maintains a consistent response structure.

Sources: package.json:11, test/services/central-alerts/v1/index.test.ts:18-20, test/services/central-alerts/v1/index.test.ts:108-115, test/services/central-alerts/v1/index.test.ts:145-155

Sample SQL Initialization

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
);

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

Summary

The Central Alerts Service provides a targeted communication channel between the FOSSBilling project and its distributed installations. By leveraging a structured D1 database and version-aware metadata, it ensures that critical information, particularly security advisories, reaches the specific user base affected, while maintaining high performance and platform independence through the Hono framework.