244 lines
10 KiB
Markdown
244 lines
10 KiB
Markdown
# 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/<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.
|
||
|
||
---
|
||
|
||
## 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.
|