10 KiB
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)
-
Debounce + coalesce bursts into one rebuild. A single admin action can call
scheduleStoreInitializationmany times (bulk product edits, tag reorders, store updates). Each call resetslastTriggerand 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 uploadsproducts.json,stores.json,stores/<id>.json,availability.json,slots.json,banners.json,essential-consts.json, then purges the CDN. -
Durable cross-request state.
pendingRegionsandallRegionsPendingmust 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. -
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.
-
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 clearingpendingRegions. -
Durable timers with retry.
state.storage.setAlarm()persists across restarts and retries on failure —setTimeout/ctx.waitUntilcannot.
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*Storewarm-ups (roles/constants/products/tags/slots/banners) are legacy — their Redis writes are commented out. The observable work is the cache-file generation increateAllCacheFiles.
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 (a0.1= 6 s value is commented in the source).- Alarm guard:
lastTrigger.isBefore(now − 30s). - Consequence:
products.json/stores.json/banners.json/essential-consts.jsonare eventual (typically ~30–60 s after the last write), whileslots.json/availability.jsonare 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) →
scheduleStoreInitializationlogs a warning and returns; writes still succeed but the cache never rebuilds. createAllCacheFilesis invoked fire-and-forget insideinitializeAllStores(catchlogs); 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 exposesPOST /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, butproducts.json/stores.jsonstill wait out the debounce. - Test-created data inflates rebuild cost;
bun run remove-test-datashrinks 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.