# Durable Objects in the backend What we use Cloudflare Durable Objects for, why, and how the cache pipeline works. --- ## TL;DR There is exactly **one** Durable Object class in this backend: **`CacheCreator`**. - Bound as **`CACHE_CREATOR`**, a single named instance (`idFromName('store-init')`). - Its job: **debounce, coalesce, and serialise cache-file rebuilds**, and remember which regions still need rebuilding across requests. - Mutations call `scheduleStoreInitialization(regionId?)`, which pings the DO. The DO records the request and sets a **30-second alarm**. When the writes go quiet, the alarm fires and rebuilds the affected region(s) — or every region for a global change. It is **not** used for notifications or orders (those use Cloudflare Queues), and it does not serve reads. --- ## Where it lives | Piece | File | | --- | --- | | DO class | `src/jobs/cache-creator.ts` | | Export + binding wiring | `worker.ts` (`export { CacheCreator }`), `wrangler.dev.toml` / `wrangler.prod.toml` (`[durable_objects]`, `[[migrations]]`) | | Scheduler helper | `src/stores/store-initializer.ts` → `scheduleStoreInitialization()` | | Work performed on alarm | `src/stores/store-initializer.ts` → `initializeAllStores()` → `src/lib/cloud_cache.ts` → `createAllCacheFiles()` | Local state lives under `.wrangler/state/v3/do/freshyo-backend-dev-CacheCreator/`. ```toml # wrangler.dev.toml [durable_objects] bindings = [ { name = "CACHE_CREATOR", class_name = "CacheCreator" }, ] [[migrations]] tag = "cache-creator-v1" new_classes = ["CacheCreator"] ``` --- ## Why a Durable Object (the problems it solves) 1. **Debounce + coalesce bursts into one rebuild.** A single admin action can call `scheduleStoreInitialization` many times (bulk product edits, tag reorders, store updates). Each call resets `lastTrigger` and the alarm, so a burst becomes **one** rebuild ~30 s after the last write instead of N full rebuilds. A rebuild is expensive: per region it reads all products/tags/slots/banners/stores and uploads `products.json`, `stores.json`, `stores/.json`, `availability.json`, `slots.json`, `banners.json`, `essential-consts.json`, then purges the CDN. 2. **Durable cross-request state.** `pendingRegions` and `allRegionsPending` must outlive the HTTP request that triggered them. Worker module memory is not durable and a fire-and-forget promise can be cancelled when the response ends. DO storage is durable and the instance is single-threaded, so this state is safe. 3. **Single-writer serialisation.** All scheduling funnels through one instance, so two concurrent admin writes cannot run overlapping rebuilds that race the region version counters or interleave S3 uploads. 4. **Global vs regional routing (never narrowed).** A **global** change (global product/store edit) must rebuild **every** region. A later **regional** write in the same debounce window must not narrow that run. The DO encodes this with `allRegionsPending` (wins) and by clearing `pendingRegions`. 5. **Durable timers with retry.** `state.storage.setAlarm()` persists across restarts and retries on failure — `setTimeout` / `ctx.waitUntil` cannot. --- ## DO storage model | Key | Type | Meaning | | --- | --- | --- | | `lastTrigger` | number (ms) | When `schedule()` was last called. Drives the debounce guard. | | `pendingRegions` | `number[]` | Regions queued by regional requests. | | `allRegionsPending` | boolean | A global request was made; overrides `pendingRegions`. | `POST /clear` deletes all of the above (ops/debug). --- ## The DO's own HTTP surface The DO is reached only through its stub (`stub.fetch(...)`), never by clients. | Method + path | Effect | | --- | --- | | `POST /schedule?regionId=` | Queue that region, set/reset the alarm. | | `POST /schedule` (no `regionId`) | Queue **all** regions (`allRegionsPending`). | | `POST /clear` | `storage.deleteAll()` — ops/debug. | | anything else | `200 "CacheCreator ready"`. | --- ## Lifecycle ``` mutation (admin/superadmin) └─ scheduleStoreInitialization(regionId?) └─ env.CACHE_CREATOR.get(idFromName('store-init')).fetch('/schedule?regionId=…') └─ CacheCreator.schedule(regionId?) ├─ storage.put('lastTrigger', now) ├─ regional → append to pendingRegions (unless allRegionsPending) ├─ global → allRegionsPending = true, clear pendingRegions └─ storage.setAlarm(now + 30s) ← resets on every call (debounce) … writes go quiet for 30 s … CacheCreator.alarm() ├─ guard: lastTrigger older than (now − 30s)? ├─ drain + clear pendingRegions / allRegionsPending ├─ allRegionsPending OR pendingRegions empty → initializeAllStores() (all regions) └─ else → initializeAllStores(regionId) (each queued) initializeAllStores(regionId?) └─ createAllCacheFiles(regionId?) ├─ incrementRegionCacheVersion / slots / availability counters (D1) ├─ build + upload the region's cache files to S3 ├─ purge the CDN for those URLs └─ refreshGenKvForRegion(regionId) (KV mirror used by common.essentialConsts) ``` > Note: the `initialize*Store` warm-ups (roles/constants/products/tags/slots/banners) are > legacy — their Redis writes are commented out. The observable work is the cache-file > generation in `createAllCacheFiles`. --- ## Who schedules | Router / procedure | Scope | | --- | --- | | `admin.product.*` (create/update/delete/tag/group/prices/stock) | staff region | | `admin.store.*` (create/update/delete) | staff region | | `admin.banner.*` (create/update/delete) | staff region | | `admin.region.updateRegionConstants` | region (only cache-affecting keys, e.g. `tagsOrder`) | | `superadmin.globalProducts.*`, `superadmin.products.elevate` | **all regions** | | `superadmin.globalStores.*`, `superadmin.stores.elevate` | **all regions** | | `superadmin.regions.updateRegionConstants` | region | Exception: **`superadmin.regions.create`** generates the new region's cache files **inline** (`await createRegionCacheFiles(region.id)`), not through the DO — a brand-new region has no existing cache to debounce. --- ## Guarantees - At most one rebuild per quiet window per region (coalescing). - A global request is never narrowed by a concurrent regional request. - Pending state survives worker restarts; the alarm is retried. - Writes never fail because of the cache: if the binding is missing or scheduling throws, the mutation still succeeds (the error is logged). ## Non-goals - Not a job queue (notifications/orders use `NOTIF_QUEUE` / `ORDER_*_QUEUE`). - Not a read cache (it produces immutable, versioned files served by the CDN). - Does not make reads fresh — the rebuild is **eventual by design**. --- ## Timing - `ALARM_DELAY_MINUTES = 0.5` → **30 s** (a `0.1` = 6 s value is commented in the source). - Alarm guard: `lastTrigger.isBefore(now − 30s)`. - Consequence: `products.json` / `stores.json` / `banners.json` / `essential-consts.json` are **eventual** (typically ~30–60 s after the last write), while `slots.json` / `availability.json` are written **synchronously** inside their mutation and are immediate. --- ## Failure modes & known issues - **Debounce boundary race** — the guard compares against exactly 30 s, so an alarm that fires a hair early can be skipped, leaving the change unbuilt until the next write. - **Large rebuilds can OOM the local `workerd`** (V8 heap limit) when the DB has many stores/regions; a global write rebuilds every region. - **Missing binding** (local dev without the DO) → `scheduleStoreInitialization` logs a warning and returns; writes still succeed but the cache never rebuilds. - `createAllCacheFiles` is invoked fire-and-forget inside `initializeAllStores` (`catch` logs); a failure there does not fail the alarm. - The alarm processes queued regions **sequentially**, so a backlog is serialised. --- ## Operations - **Inspect/clear local DO state**: the instance lives under `.wrangler/state/v3/do/…/CacheCreator/`; the DO exposes `POST /clear`. - **Force a rebuild locally**: perform any write that calls `scheduleStoreInitialization` (e.g. create a throwaway product/tag), then wait ~30 s. - **Deploying**: a new DO class/migration requires a `[[migrations]]` tag change. - **Logs** to look for: `from the fetch method of durable object`, `from the shceduler`, `Starting creation of cache files for region …`, `Cache files created successfully for region …`. --- ## Alternatives considered | Option | Why not | | --- | --- | | **Cloudflare Queues** (used for notifications/orders) | No coalescing/dedupe by key, no single-writer; you'd still need durable "pending regions" state. | | **Cron Triggers** | Minute granularity, no per-write debounce, cannot target only changed regions. | | **`ctx.waitUntil` in the request** | Bounded lifetime, no retry, and bursts still trigger N rebuilds. | | **Rebuild synchronously in the mutation** | Admin writes block for seconds; burst cost multiplies; more likely to hit CPU/subrequest limits. | | **KV-based debounce** | Eventually consistent, no atomic lock → concurrent writers race. | The DO earns its place specifically for **debounce + cross-request state + single-writer routing**, which is what a cache-invalidation coordinator needs. --- ## Testing implications The API suite (`tests/`) treats this pipeline as **eventual**: - Cache rows poll the versioned files; the ~30 s debounce dominates their runtime. - Shared test intervals live in `tests/constants.ts` (`SIXTY_SECONDS_MS`, `THIRTY_SECONDS_MS`). Locally, synchronous paths (`slots`, `availability`, D1 version reads) settle in ~1–2 s, but `products.json` / `stores.json` still wait out the debounce. - Test-created data inflates rebuild cost; `bun run remove-test-data` shrinks the DB so rebuilds stay light. --- ## Related files - `src/jobs/cache-creator.ts` — the DO. - `src/stores/store-initializer.ts` — `scheduleStoreInitialization`, `initializeAllStores`. - `src/lib/cloud_cache.ts` — `createRegionCacheFiles`, `createAllCacheFiles`, version counters, S3 upload, CDN purge, KV mirror refresh. - `src/lib/gen-store.ts` — KV mirror read (`readEssentialConstsFromKv`). - `worker.ts`, `wrangler.dev.toml`, `wrangler.prod.toml` — binding + migration.