Cloudflare Worker API
Relevant source files
The following files were used as context for generating this wiki page:
The Cloudflare Worker API manages the live auction state, processes advertiser payments, and serves interactive artwork for The Driving Fly project. It operates as a serverless backend using Cloudflare Workers, a SQLite-backed Durable Object for state persistence, and R2 buckets for immutable asset storage.
The API coordinates between the Next.js frontend, Stripe Checkout for financial transactions, and Cloudflare Email Service for outbid notifications.
Sources: apps/website/README.md:5-15, apps/website/worker-configuration.d.ts:4-12
System Architecture
The API uses a centralized Durable Object named AUCTION to maintain the authoritative state of the auction in a SQLite database. This ensures consistency for bid publication, history tracking, and livery revisions.
The diagram shows the flow of requests from the client through the Worker API to persistent storage and external services.
Sources: apps/website/README.md:76-85, apps/website/worker-configuration.d.ts:11
API Endpoints
The Worker exposes several RESTful endpoints and a WebSocket interface to manage the lifecycle of an advertisement.
Core Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/auction | GET | Returns a snapshot of the current auction, including placements and history. |
/api/artwork | POST | Uploads PNG artwork/logos. Returns a temporary token. |
/api/checkout | POST | Creates a Stripe Checkout session for a specific slot. |
/api/checkout/confirm | POST | Verifies the status of a specific checkout session. |
/api/stripe/webhook | POST | Receives signed payment events from Stripe. |
/api/live | GET | Initiates a WebSocket connection for real-time livery updates. |
Sources: apps/website/tests/auction.test.ts:145-165, apps/website/README.md:120-130
Artwork and Assets
Artwork is uploaded to R2 storage but remains private until a verified purchase occurs. Once published, the Worker serves artwork via GET /api/artwork/{token}.png with immutable cache headers.
Sources: apps/website/tests/auction.test.ts:250-265, apps/website/README.md:143-150
Auction Logic and Persistence
The Auction Durable Object manages the synchronous SQL transactions required for the bidding process. It enforces the rule that a new bid must be at least US $1 higher than the current confirmed bid.
Transaction Flow
When a payment is confirmed via a Stripe webhook, the system performs the following steps:
- Validates the session amount and metadata.
- Compares the bid against the latest winner within a SQL transaction.
- Commits the replacement, updates the history, and increments the livery revision.
- Triggers an outbid notification to the previous owner.
- Broadcasts the new snapshot over hibernating WebSockets.
The sequence diagram illustrates the atomic process of ad publication following a successful payment.
Sources: apps/website/README.md:95-105, apps/website/tests/auction.test.ts:320-335
Configuration and Environment
The API relies on specific bindings and secrets configured in the Cloudflare environment.
| Binding | Type | Description |
|---|---|---|
AUCTION | DurableObjectNamespace | Interface to the SQLite-backed auction state. |
ARTWORK | R2Bucket | Storage for uploaded ad textures and logos. |
STRIPE_API_KEY | Secret | Restricted API key for communicating with Stripe. |
STRIPE_WEBHOOK_SECRET | Secret | Secret for validating Stripe-Signature headers. |
EMAIL | SendEmail | Binding for Cloudflare Email Service. |
Sources: apps/website/worker-configuration.d.ts:4-12, apps/website/README.md:65-75
Development and Testing
The project uses opennextjs-cloudflare to bridge Next.js with the Worker environment. Integration tests utilize miniflare to simulate the Cloudflare runtime, including SQLite and R2 bindings.
Build Scripts
npm run build:worker: Compiles the project usingopennextjs-cloudflare.npm run cf:types: Generates TypeScript definitions for Cloudflare bindings.npm run test: Executes the vitest suite, covering forged signatures and auction rules.
Sources: apps/website/package.json:6-15, apps/website/tests/auction.test.ts:110-120
The Cloudflare Worker API provides a robust, real-time backend for the auction, ensuring that ad placements are handled with transactional integrity while maintaining a high-performance interactive experience for users.