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

244 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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