freshyo/apps/backend/docs/durable-objects.md
2026-10-20 00:31:05 +05:30

10 KiB
Raw Blame History

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/.

# 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/<id>.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=<id> 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.

  • 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.