Stats API Endpoints

Relevant source files

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

• src/services/stats/v1/index.ts
• src/services/stats/v1/interfaces.ts
• test/services/stats/v1/index.test.ts
• AGENTS.md
• test/integration/app.test.ts

The Stats API provides release statistics visualization and data aggregation for FOSSBilling versions. It serves both a client-side rendered HTML dashboard and a JSON data endpoint that processes historical release data into actionable metrics. The service is built using the Hono framework and integrates with the project's centralized caching and versioning services.

The system aggregates metrics such as release sizes, PHP version requirements, and release frequency. It utilizes a 24-hour cache TTL to ensure performance while maintaining relatively up-to-date information derived from GitHub release data.

Sources: AGENTS.md:63-71, src/services/stats/v1/index.ts:1-24

Service Architecture

The Stats service is implemented as a Hono module that leverages middleware for CORS, ETag generation, and caching. It follows a runtime-agnostic design, allowing it to run on platforms like Cloudflare Workers or Node.js.

Data Flow and Processing

The service retrieves raw release information from the Versions Service and transforms it into structured statistics. The data is cached in a KV store under the key fossbilling-stats-data to minimize repetitive aggregation logic and external API calls.

The diagram shows the request flow for statistics data, highlighting the interaction between the Stats service, the Versions service, and the KV cache.
Sources: src/services/stats/v1/index.ts:133-155, test/services/stats/v1/index.test.ts:98-115

API Endpoints

Statistics Dashboard

• Endpoint: GET /stats/v1/
• Description: Returns a self-contained HTML page that uses Chart.js to visualize the data fetched from the /data endpoint.

Statistics Data

• Endpoint: GET /stats/v1/data
• Description: Returns the raw aggregated metrics used for visualizations.

Field	Type	Description
releaseSizes	Array<ReleaseSizeData>	List of versions with their size in MB and release date.
phpVersions	Array<PhpVersionData>	List of versions with their minimum PHP requirements.
patchesPerRelease	Array<PatchPerReleaseData>	Count of patches (e.g., 0.6.x) per version line.
releasesPerYear	Array<ReleasesPerYearData>	Frequency of releases grouped by calendar year.

Sources: src/services/stats/v1/index.ts:172-180, src/services/stats/v1/interfaces.ts:1-30

Data Aggregation Logic

The service performs several transformation steps to prepare data for charts:

Version Line Parsing

Individual semantic versions are grouped into "version lines" (e.g., 0.5.1 and 0.5.2 both belong to 0.5.x). This is achieved by splitting the version string and appending .x to the major and minor segments.
Sources: src/services/stats/v1/index.ts:74-80

Metric Calculation

• Release Size: Converted from bytes to MB and rounded to two decimal places.
• PHP Versions: Extracted from the minimum_php_version field provided by the Versions service.
• Sorting: Versions are sorted using semantic version comparison via the semver library to ensure chronological accuracy in line graphs, while years are sorted lexicographically.

function aggregateStats(releases: Releases): StatsData {
  const versions = Object.keys(releases).sort(semverCompare);

  const releaseSizes = versions.map((version) => ({
    version,
    size_mb:
      Math.round((releases[version].size_bytes / 1024 / 1024) * 100) / 100,
    released_on: releases[version].released_on
  }));
  // ... additional aggregation logic
}

Sources: src/services/stats/v1/index.ts:82-131

Caching Strategy

The Stats API implements a multi-layer caching strategy:

1. Application Cache (KV): The aggregated JSON object is stored in KV with a TTL of 86,400 seconds (24 hours).
2. HTTP Cache: The Hono cache middleware is used to set Cache-Control headers, allowing edge caching.
3. ETag Middleware: Provides web-standard validation to prevent re-downloading unchanged data.

Configuration	Value	Source
Cache Key	fossbilling-stats-data	src/services/stats/v1/index.ts:14
Cache TTL	86,400 seconds	src/services/stats/v1/index.ts:17
Cache Name	stats-api-v1	src/services/stats/v1/index.ts:15

Sources: src/services/stats/v1/index.ts:14-42, test/integration/app.test.ts:258-265

Error Handling

If the Versions service fails to provide data and no cached stats are available, the API returns a 503 Service Unavailable response. If cached data is available but the fresh fetch fails, the service returns the cached data with a stale: true flag in the response metadata.

The sequence diagram illustrates the fallback logic when external dependencies or cache misses occur.
Sources: src/services/stats/v1/index.ts:57-72, test/services/stats/v1/index.test.ts:117-142

Summary

The Stats API Endpoints provide a comprehensive view of FOSSBilling's project evolution through automated data aggregation. By integrating with the project's versioning backend and utilizing persistent KV caching, the service offers high-performance visualizations and data access while remaining resilient to upstream API limitations or failures.