@thomasfosterau/legation-alchemy-cloudflare 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,172 @@
+# @thomasfosterau/legation-alchemy-cloudflare
+
+## 0.1.0
+
+### Minor Changes
+
+- 604ffd3: New package `@thomasfosterau/legation-alchemy-cloudflare` (ADR-0034): the reference deployment of ADR-0022's topology on Cloudflare, built on the Effect-native services of Alchemy's Cloudflare provider. It replaces `@thomasfosterau/legation-cloudflare`, which was never published.
+
+  - `Room.make(config)` is the per-user room's Alchemy Durable Object implementation: the sync server over stateless HTTP push/pull/read, CVRs in the object's storage (`DurableCvrStore`), a `FanoutBus` over the topic shards, and hibernatable sockets (`Cloudflare.upgrade`) that carry only contentless pokes. `backend`, `policy`, `identity` and `queries` are effects built in the object's per-instance phase; `shards` is the app's shard class. Every shard call, room poke and lease registration is bounded by `publishTimeout`.
+  - `FanoutShard.make()` is the topic shard's implementation, with a typed RPC surface (`register`, `publish`): a shard answers its leased rooms and the publishing room pokes each once, over the `poke` RPC, with every topic it matched.
+  - The app declares the classes (`class LegationRoom extends Cloudflare.DurableObject<LegationRoom, Room.RoomObject>()("LegationRoom") {}`) and binds the implementations (`LegationRoom.make(Room.make(...))`, `LegationShard.make(FanoutShard.make())`).
+  - `Worker.routeSync` routes an Alchemy Worker's `/sync` requests to the caller's room through the namespace's stub, answering `Option.none()` outside the base path. A room answers a route by the path's last segment.
+  - `D1Executor.make(db)` is `SqlBackend`'s executor over `Cloudflare.D1.QueryDatabase`'s client; D1 has no interactive transactions, so it reports `transactional: false` and does not meet Backend guarantee 1 (#342, #353).
+  - `RoomTransport`, `BindingTransport` and `EdgeInvalidation` are unchanged from the package this one replaces.
+
+  Peers: `alchemy` and `@alchemy.run/cloudflare` at exactly 2.0.0-beta.85, and `effect ^4.1.0`, which Alchemy requires. `@cloudflare/workers-types` is not a peer.
+
+### Patch Changes
+
+- Updated dependencies [2a1f63c]
+- Updated dependencies [ef59fa7]
+- Updated dependencies [56a2e51]
+- Updated dependencies [d09dc65]
+- Updated dependencies [db2366a]
+- Updated dependencies [97db489]
+- Updated dependencies [cc67999]
+- Updated dependencies [a94df19]
+- Updated dependencies [d76b04d]
+- Updated dependencies [6f53fb1]
+- Updated dependencies [d675d2e]
+- Updated dependencies [1743c2b]
+- Updated dependencies [1c56914]
+- Updated dependencies [615e792]
+- Updated dependencies [c8d9afc]
+- Updated dependencies [4709f41]
+- Updated dependencies [f0348b4]
+- Updated dependencies [3e29e1b]
+- Updated dependencies [a053736]
+- Updated dependencies [8a8adfc]
+- Updated dependencies [8995115]
+- Updated dependencies [8995115]
+- Updated dependencies [87fa7a5]
+- Updated dependencies [822001c]
+- Updated dependencies [4c59860]
+- Updated dependencies [961e604]
+- Updated dependencies [5937efe]
+- Updated dependencies [08ac9cd]
+- Updated dependencies [1fc3725]
+- Updated dependencies [8995115]
+- Updated dependencies [8a8adfc]
+- Updated dependencies [025fabb]
+- Updated dependencies [0b8fccb]
+- Updated dependencies [e7369e1]
+- Updated dependencies [8995115]
+- Updated dependencies [c856d66]
+- Updated dependencies [01a8c64]
+- Updated dependencies [3362c37]
+- Updated dependencies [62dcb1c]
+- Updated dependencies [be4be06]
+- Updated dependencies [ae18cb3]
+- Updated dependencies [be0a44d]
+- Updated dependencies [cc2f5b7]
+- Updated dependencies [e818dc4]
+- Updated dependencies [d1b01a4]
+- Updated dependencies [5496ddf]
+- Updated dependencies [19eb4b0]
+- Updated dependencies [a874acb]
+- Updated dependencies [c5d3484]
+- Updated dependencies [38c3147]
+- Updated dependencies [e9363c0]
+- Updated dependencies [fed4634]
+- Updated dependencies [fcc52eb]
+- Updated dependencies [454e75c]
+- Updated dependencies [2003cd6]
+- Updated dependencies [52c614f]
+- Updated dependencies [94d6327]
+- Updated dependencies [91f07db]
+- Updated dependencies [6e9e119]
+- Updated dependencies [6c2c802]
+- Updated dependencies [ebcc6aa]
+- Updated dependencies [a1b95d4]
+- Updated dependencies [c105fbf]
+- Updated dependencies [e1a028a]
+- Updated dependencies [dfb8759]
+- Updated dependencies [9260efb]
+- Updated dependencies [0644af5]
+- Updated dependencies [4b05d55]
+- Updated dependencies
+- Updated dependencies [82911cc]
+- Updated dependencies [9c9f2b0]
+- Updated dependencies [7b21d11]
+- Updated dependencies [6f54de8]
+- Updated dependencies [ab1fb4e]
+- Updated dependencies [792d8f5]
+- Updated dependencies [a3b2ee4]
+- Updated dependencies [eb9555a]
+- Updated dependencies [c0ab703]
+- Updated dependencies [8c65627]
+- Updated dependencies [26ad3f3]
+- Updated dependencies [d7cafd2]
+- Updated dependencies [cb0a33d]
+- Updated dependencies [912d95d]
+- Updated dependencies [7290d2b]
+- Updated dependencies [41c33e3]
+- Updated dependencies [a77261c]
+- Updated dependencies [c47786c]
+- Updated dependencies [501b12c]
+- Updated dependencies [7f1efac]
+- Updated dependencies [a04918b]
+- Updated dependencies [cf0b26c]
+- Updated dependencies [ddb1fda]
+- Updated dependencies [f54f568]
+- Updated dependencies [fc880dc]
+- Updated dependencies [9cbd160]
+- Updated dependencies [0bebedf]
+- Updated dependencies [bc4c599]
+- Updated dependencies [20a6e18]
+- Updated dependencies [b4d2b80]
+- Updated dependencies [2201b4c]
+- Updated dependencies [0cdefe7]
+- Updated dependencies [66f3b5b]
+- Updated dependencies [7e11e61]
+- Updated dependencies [6175e38]
+- Updated dependencies [caf4761]
+- Updated dependencies [821b10d]
+- Updated dependencies [9e74a83]
+- Updated dependencies [49fd066]
+- Updated dependencies [06405ed]
+- Updated dependencies [e7f4871]
+- Updated dependencies [916d91b]
+- Updated dependencies [47f4e15]
+- Updated dependencies [f829146]
+- Updated dependencies [13658a7]
+- Updated dependencies [31cfb2c]
+- Updated dependencies [a1cea1c]
+- Updated dependencies [7e94abc]
+- Updated dependencies [4fbd0b7]
+- Updated dependencies [9d2f21b]
+- Updated dependencies [3016170]
+- Updated dependencies [f4a1a60]
+- Updated dependencies [507ccb1]
+- Updated dependencies [c671ccf]
+- Updated dependencies [16889f0]
+- Updated dependencies [fb2a992]
+- Updated dependencies [22f320d]
+- Updated dependencies [652ae7b]
+- Updated dependencies [83bcf76]
+- Updated dependencies [20e57d3]
+- Updated dependencies [f010749]
+- Updated dependencies [8d02113]
+- Updated dependencies [bf9054d]
+- Updated dependencies [e40c73a]
+- Updated dependencies [ca38874]
+- Updated dependencies [27e1040]
+- Updated dependencies [e68eb3e]
+- Updated dependencies [985c4d5]
+- Updated dependencies [3be5abc]
+- Updated dependencies [97db489]
+- Updated dependencies [4a23603]
+- Updated dependencies [f441941]
+- Updated dependencies [a01f43b]
+- Updated dependencies [9a6426b]
+- Updated dependencies [97cc5f9]
+- Updated dependencies [fc880dc]
+- Updated dependencies [e34bc24]
+- Updated dependencies [0470e1c]
+- Updated dependencies [439f449]
+- Updated dependencies [3a88118]
+- Updated dependencies [1b8b120]
+- Updated dependencies [cf48723]
+- Updated dependencies [b4489c5]
+  - @thomasfosterau/legation@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+# @thomasfosterau/legation-alchemy-cloudflare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The reference deployment of the [`@thomasfosterau/legation`](../effect) sync engine on
+Cloudflare — per-user Durable Object rooms, topic-sharded fan-out, and a D1
+backend — following ADR-0022 (topology) and ADR-0023 (topic-derived fan-out),
+built on the Effect-native services of [Alchemy](https://alchemy.run)'s
+Cloudflare provider, `@alchemy.run/cloudflare` (ADR-0034). The Durable Objects
+are Alchemy Durable Objects, their state, storage and sockets are the provider's
+`Cloudflare.DurableObjectState`, and the D1 executor runs through its
+`Cloudflare.D1.QueryDatabase` client.
+
+- **`Room`** — the per-user Durable Object (`LegationRoom.make(Room.make(...))`).
+  It runs the sync `Server` for one user: push/pull/read over stateless HTTP
+  (each request wakes the object, is answered, and lets it hibernate), CVRs in
+  the object's transactional storage (`DurableCvrStore`, co-located with the
+  user), a `FanoutBus` over the topic shards, and hibernatable WebSockets
+  (`Cloudflare.upgrade`) that carry only contentless poke frames — so hibernated
+  sockets cost nothing between writes. Each shard call, room poke and lease
+  registration is bounded by `publishTimeout` (default 5 seconds): a hung shard
+  is dropped with its poke, so it cannot hold a push open, and a lost poke only
+  delays the next pull.
+- **`FanoutShard`** — one Durable Object per topic (`getByName(topic)` is the
+  shard function), with a typed RPC surface (`register`, `publish`). Rooms lease
+  their topics on a heartbeat; a publish answers every live room, and the
+  publishing room pokes them (one `poke` RPC per room, carrying every topic it
+  matched). Expired leases age out lazily, so a crashed room needs no
+  distributed cleanup.
+- **`Worker` (`routeSync`)** — the stateless entry, for an Alchemy Worker's
+  `fetch`. It claims only the sync base path (default `/sync`), resolves the
+  caller's identity to their room, forwards the request to the room's stub
+  (WebSocket upgrades included), and answers `Option.none()` for everything
+  else, so it composes inside any existing handler.
+- **`D1Executor`** — a `SqlBackend` executor over the `QueryDatabaseClient` of
+  `Cloudflare.D1.QueryDatabase`. D1 has no interactive transactions, so a
+  mutation's writes and its mutation-id bump commit separately, and D1 isolates
+  no handler's reads from another client group's writes: SqlBackend on D1 does
+  not meet Backend guarantee 1 (#342, #353). For apps that need it, use Durable
+  Object storage or Postgres via Hyperdrive; on D1, prefer single-statement,
+  idempotent handlers.
+- **`RoomTransport`** — the browser-side `ClientTransport`: push/pull/read as
+  HTTP POSTs plus one reconnecting poke socket. Sync stays correct over HTTP
+  alone — a dead socket only delays pokes, and the pull interval is the safety
+  net.
+- **`BindingTransport`** — the same protocol over a **service binding**
+  (`env.API.fetch`), for the two-Worker shape where the Worker rendering the
+  page is not the Worker holding the backend. It forwards the inbound cookie
+  and origin, so the bound Worker resolves the same caller — and therefore the
+  same room — that the browser will reach on its own first pull.
+
+## Install
+
+```sh
+npm install @thomasfosterau/legation-alchemy-cloudflare @thomasfosterau/legation effect \
+  alchemy@2.0.0-beta.85 @alchemy.run/cloudflare@2.0.0-beta.85
+npm install --save-dev @cloudflare/workers-types
+```
+
+`alchemy` and `@alchemy.run/cloudflare` are peers at exactly 2.0.0-beta.85 (each
+`@alchemy.run/*` release pins `alchemy` exactly). `@cloudflare/workers-types` is
+not a peer of this package: the provider's own declarations import it, so a
+Worker project type-checks with it installed.
+
+## Usage
+
+The app declares its two Durable Object classes and binds this package's
+implementations to them; the Worker hosting them provides both layers.
+
+```ts
+// sync.ts
+import * as Cloudflare from "@alchemy.run/cloudflare";
+import * as Effect from "effect/Effect";
+import { Authorization } from "@thomasfosterau/legation";
+import { SqlBackend } from "@thomasfosterau/legation/sql";
+import { D1Executor, FanoutShard, Room } from "@thomasfosterau/legation-alchemy-cloudflare";
+
+export class LegationShard extends Cloudflare.DurableObject<
+  LegationShard,
+  FanoutShard.ShardObject
+>()("LegationShard") {}
+
+export class LegationRoom extends Cloudflare.DurableObject<LegationRoom, Room.RoomObject>()(
+  "LegationRoom"
+) {}
+
+export const LegationShardLive = LegationShard.make(FanoutShard.make());
+
+export const LegationRoomLive = LegationRoom.make(
+  Effect.gen(function* () {
+    // Bindings resolve at init; the room builds its server per instance.
+    const db = yield* Cloudflare.D1.QueryDatabase(AppDatabase);
+    return yield* Room.make({
+      nodes,
+      backend: Effect.map(D1Executor.make(db), (executor) => SqlBackend.make({ executor, nodes })),
+      policy: Effect.succeed(Authorization.policy({/* … */})),
+      shards: LegationShard,
+    });
+  })
+);
+```
+
+```ts
+// worker.ts — the Worker that hosts both classes and routes /sync to the rooms
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { Worker } from "@thomasfosterau/legation-alchemy-cloudflare";
+
+export default Api.make(
+  Effect.gen(function* () {
+    const rooms = yield* LegationRoom;
+    return {
+      fetch: Effect.gen(function* () {
+        const routed = yield* Worker.routeSync({ rooms, roomIdOf: resolveSession });
+        return Option.isSome(routed) ? routed.value : yield* app;
+      }),
+    };
+  }).pipe(Effect.provide(Layer.mergeAll(LegationRoomLive, LegationShardLive)))
+);
+```
+
+`Room.make`'s `backend`, `policy`, `identity` and `queries` are effects run in
+the room's per-instance phase, where the object's state and Alchemy's
+`RuntimeContext` are available, so a backend over D1 (or any other binding)
+is built there. A request reaches the room with its base path intact, and the
+room answers by the path's last segment (`/sync/push` is the `push` route).
+
+## What Alchemy does not cover
+
+- **Interactive transactions on D1.** The provider's client has `batch()`
+  (statements in one implicit transaction) but nothing interactive, so the
+  executor reports `transactional: false`, as before.
+- **Aborting a shard or room call.** Alchemy's RPC stubs take no abort signal.
+  A call past `publishTimeout` is abandoned, not aborted: the room stops
+  waiting for it and workerd cancels it with the event that made it.
+- **The `/socket` upgrade in tests.** `Cloudflare.upgrade` needs workerd's
+  `WebSocketPair` and a 101 response, which Node lacks; the tests accept a fake
+  socket directly.
+
+## Effect version
+
+Peers `effect ^4.1.0`, the floor Alchemy requires (`alchemy` and
+`@alchemy.run/cloudflare` 2.0.0-beta.85 peer `effect ^4.1.0`). Tested against
+`4.1.2` (the version CI pins) and `4.1.0` (the floor; CI runs this package's
+tests against it on every PR); install one copy of `effect` in your app
+(ADR-0003). The rest of legation peers `effect ^4.0.0`.
+
+## SSR from a separate Worker
+
+A binding-only API Worker (`workersDev: false`, no custom domain) is reachable
+only through the front door's service binding, so an SSR render cannot hold the
+sync server in-process. `Hydration.snapshot` takes a `ClientTransport`; give it
+a `BindingTransport` and the render pulls over the binding:
+
+```ts
+// +page.server.ts — the effect an Effect-based `load` runs
+import { BindingTransport } from "@thomasfosterau/legation-alchemy-cloudflare";
+import { loadSnapshot } from "@thomasfosterau/legation-svelte/kit";
+
+const pageSnapshot = ({ cookies, request, platform }) =>
+  loadSnapshot(cookies, {
+    nodes,
+    reads: [{ collection: "products" }],
+    transport: BindingTransport.make({
+      binding: platform.env.API,
+      request, // the document request: its cookie and origin are forwarded
+    }),
+  });
+```
+
+The render happens under the _browser's_ client group id, so the snapshot's
+pull cookie continues that group's CVR conversation and the browser's first
+pull is a delta rather than a reset. That only holds while the hop preserves
+the caller's identity — drop the cookie and the snapshot still carries the
+right rows while its cookie belongs to another room's CVR, which is a silent
+reset on every first paint. `binding-snapshot.test.ts` pins both sides of that.
+
+## Evicting server-side caches on a write
+
+`EdgeInvalidation` turns the hints a committed write publishes into evictions
+of the caches an app keeps on Cloudflare (#206): `kv` deletes the
+`{collection}:{id}` entry of every touched row from a KV read-through cache, and
+`cachePurge` purges the Workers cache by tag, with the same tag spelling the
+browser's Cache API invalidation uses (`collection:{name}`,
+`collection:{name}:{id}`, from `HttpCache` in `@thomasfosterau/legation/internal`).
+The eviction is no longer an obligation of each mutation: it subscribes to the
+bus (`InvalidationSink.run`).
+
+**The cache lives in a different Worker than the write.** `cache.purge({ tags })`
+purges only the calling Worker's cache. In the usual shape the front door (the
+SvelteKit Worker serving every page) holds the cache, while writes land in the
+API Worker behind its service binding. So the API Worker forwards what each
+write touched, and the front door runs the sinks:
+
+```ts
+// API Worker, where the server and its bus run (a Durable Object room, say)
+yield * InvalidationSink.run(EdgeInvalidation.forward(env.FRONT_DOOR));
+
+// Front door Worker: an RPC entrypoint, reachable only through the binding
+export class Invalidation extends WorkerEntrypoint<Env> {
+  invalidate(payload: string): Promise<void> {
+    const sink = InvalidationSink.all([
+      EdgeInvalidation.kv(this.env.RESOURCES),
+      EdgeInvalidation.cachePurge(this.ctx.cache),
+    ]);
+    return Effect.runPromise(EdgeInvalidation.receive(sink)(payload));
+  }
+}
+```
+
+Expose the receiving end as an RPC method, not as a route on the front door's
+`fetch`: a `fetch` route is reachable from the internet, and anyone could then
+purge the cache.
+
+Every eviction is fire-and-forget. A failed KV delete, a failed forward, and a
+purge that rejects or resolves `{ success: false }` (which is how `cache.purge`
+reports a Cloudflare-side failure, so a `catch` alone misses it) are logged;
+none of them fails or delays the write, which committed before its hint was
+published. The cache's TTL is the backstop for a lost eviction. A large write is
+purged in calls of at most `maxTagsPerPurge` tags (default 30).
+
+## License
+
+MIT