Cloudflare Adapters

Relevant source files

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

• README.md
• AGENTS.md
• test/lib/adapters/cloudflare/cache.test.ts
• test/lib/adapters/cloudflare/database.test.ts
• test/lib/adapters/cloudflare/environment.test.ts

Cloudflare Adapters serve as the platform-specific implementation layer within the FOSSBilling API architecture. The project is designed to be platform-agnostic, separating core application logic (located in src/services/) from the underlying runtime environment. The platform layer, defined in src/lib, establishes interfaces for essential services like caching, database access, and environment variable management.

These adapters implement those interfaces specifically for the Cloudflare Workers runtime, utilizing native Cloudflare features such as KV (Key-Value) storage and D1 SQL databases. This architectural split allows developers to swap the platform layer—for instance, using Node.js reference implementations during testing—without modifying the service-level code.

Sources: README.md, AGENTS.md

Architecture and Platform Interfacing

The architecture follows a clear separation of concerns where feature logic remains runtime-agnostic. The "Platform Layer" defines the contracts, while "Adapters" provide the concrete execution.

Adapter Components Overview

Component	Implementation Class	Cloudflare Technology	Purpose
Cache	CloudflareKVAdapter	Cloudflare KV	Caching GitHub API responses and statistics.
Database	CloudflareD1Adapter	Cloudflare D1	Storing system-wide alerts and extensions data.
Environment	CloudflareEnvironmentAdapter	Worker Bindings	Accessing secrets like GITHUB_TOKEN.

Sources: README.md, AGENTS.md

Data Flow Diagram

The following diagram illustrates how a request flows through the runtime-agnostic service logic to the platform-specific Cloudflare adapters.

Cache Adapter (CloudflareKVAdapter)

The CloudflareKVAdapter facilitates persistent storage of transient data using Cloudflare Workers KV. It is primarily used to cache GitHub API responses to prevent rate-limiting and to store aggregated statistics.

Key Functionality

• Standard Operations: Implements get, put, and delete methods.
• TTL Support: Supports expirationTtl (seconds) and expiration (unix timestamp) options during the put operation.
• Persistence: Data is shared across worker instances globally via the CACHE_KV and AUTH_KV namespaces.

Sources: test/lib/adapters/cloudflare/cache.test.ts:1-100, README.md

Sequence: Cache Write Operation

This diagram shows how the adapter interacts with the native Cloudflare KV namespace.

Database Adapter (CloudflareD1Adapter)

The CloudflareD1Adapter provides a wrapper around Cloudflare's D1 SQL database. It allows the API to perform structured queries for services like Central Alerts and Extension listings.

Implementation Details

• Prepared Statements: Uses adapter.prepare(sql) to create statements, supporting standard SQL syntax.
• Binding: Supports parameter binding via the .bind(...params) method to prevent SQL injection.
• Execution Modes:
  • .all(): Returns all rows matching the query.
  • .first(): Returns only the first row or a specific field.
  • .run(): Executes statements that don't return rows (e.g., INSERT, UPDATE) and returns metadata like last_row_id.
• Batching: Supports executing multiple statements in a single transaction via .batch([stmt1, stmt2]).

Sources: test/lib/adapters/cloudflare/database.test.ts:25-140, README.md

Environment Adapter (CloudflareEnvironmentAdapter)

The environment adapter provides a safe way to access configuration and secrets within the Worker runtime. It wraps the env object provided by the Cloudflare Workers global scope.

Logic and Validation

The adapter enforces type safety for environment variables. It ensures that only valid string values are returned, preventing runtime errors if a binding is an unexpected type (like an object or number).

Method	Behavior
get(key)	Returns the value if it exists and is a string; otherwise returns undefined.
has(key)	Returns true only if the key exists AND the value is a string.

Sources: test/lib/adapters/cloudflare/environment.test.ts:1-80

Infrastructure Bindings

The adapters rely on specific bindings defined in the project's configuration (wrangler.jsonc).

• DB_CENTRAL_ALERTS: A D1 database binding used for storing alert messages.
• CACHE_KV: A KV namespace for caching GitHub data with a 24-hour TTL.
• AUTH_KV: A KV namespace used to store the UPDATE_TOKEN for administrative tasks.

Sources: README.md, AGENTS.md

Summary

Cloudflare Adapters are the critical link between the FOSSBilling API's business logic and the Cloudflare infrastructure. By implementing standardized interfaces for KV, D1, and Environment variables, these adapters ensure that the core application remains testable and portable while fully utilizing the performance and scalability of Cloudflare's edge network.