@thomasfosterau/legation-alchemy-cloudflare 0.0.0 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,329 @@
+import * as Effect from "effect/Effect";
+import { Authorization, Backend, Node, ProtocolError, Query, Transport } from "@thomasfosterau/legation";
+import { Cvr, FanoutBroker, FanoutTopics, HttpCache, InvalidationSink, Protocol } from "@thomasfosterau/legation/internal";
+import { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Duration from "effect/Duration";
+import * as Option from "effect/Option";
+import * as Workers from "@alchemy.run/cloudflare/Workers";
+import { DurableObjectStorage } from "@alchemy.run/cloudflare/Workers";
+import * as Clock from "effect/Clock";
+import * as HttpServerRequest from "effect/http/HttpServerRequest";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import * as Scope from "effect/Scope";
+import { QueryDatabaseClient } from "@alchemy.run/cloudflare/D1";
+import { SqlBackend } from "@thomasfosterau/legation/sql";
+import { HttpEffect } from "alchemy/Http";
+import { HttpServerError } from "effect/http/HttpServerError";
+declare namespace BindingTransport_d_exports {
+  export { InboundRequest, MakeOptions$2 as MakeOptions, ServiceBinding, make$6 as make };
+}
+/**
+ * The object of a Cloudflare service binding (`env.API`). Declared structurally
+ * so the transport needs no Workers types and a test can pass a plain
+ * fetch-alike.
+ */
+interface ServiceBinding {
+  readonly fetch: (request: Request) => Promise<Response>;
+}
+/**
+ * The inbound request being rendered — its cookie and origin are forwarded,
+ * and a relative {@link MakeOptions.path} resolves against its URL. A standard
+ * `Request` (SvelteKit's `event.request`) satisfies this structurally.
+ */
+interface InboundRequest {
+  readonly url: string;
+  readonly headers: {
+    readonly get: (name: string) => string | null;
+  };
+}
+/** Options for {@link make}. */
+interface MakeOptions$2 {
+  /** The service binding to the Worker running the sync server. */
+  readonly binding: ServiceBinding;
+  /** The inbound SSR request whose cookie and origin are forwarded. */
+  readonly request: InboundRequest;
+  /**
+   * The sync base the bound Worker serves. A path (default `/sync`) resolves
+   * against the inbound request's origin; an absolute URL overrides it.
+   */
+  readonly path?: string;
+  /** Extra headers attached to every call (e.g. an internal service token). */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Build the transport. Each call is one `binding.fetch` of a JSON POST —
+ * no network hop, no public route on the bound Worker.
+ */
+declare const make$6: (options: MakeOptions$2) => Transport.ClientTransport;
+declare namespace D1Executor_d_exports {
+  export { make$5 as make };
+}
+/**
+ * Build the executor over a bound D1 client. Needs the `RuntimeContext` of the
+ * Worker or Durable Object it runs in (the inner, per-instance phase of an
+ * Alchemy Durable Object has it).
+ */
+declare const make$5: (db: QueryDatabaseClient) => Effect.Effect<SqlBackend.SqlExecutor, never, RuntimeContext>;
+declare namespace DurableCvrStore_d_exports {
+  export { make$4 as make };
+}
+/** Build the store over the room's `state.storage`, in the room's runtime context. */
+declare const make$4: (storage: DurableObjectStorage) => Effect.Effect<Cvr.CvrStore, never, RuntimeContext>;
+declare namespace FanoutShard_d_exports {
+  export { ShardObject, leases, make$3 as make };
+}
+/** The shard's RPC surface, as the room-side broker calls it through a stub. */
+interface ShardObject {
+  /** Lease (or renew) `roomId` on this shard's topic for `ttlMillis`. */
+  readonly register: (roomId: string, ttlMillis: number) => Effect.Effect<void, never, RuntimeContext>;
+  /**
+   * A publish to this shard's topic: the rooms whose lease is still live, to be
+   * poked by the publisher. Expired leases are deleted as a side effect.
+   */
+  readonly publish: () => Effect.Effect<ReadonlyArray<string>, never, RuntimeContext>;
+}
+/** The lease operations, storage-backed (exported for direct testing). */
+declare const leases: {
+  register: (storage: Workers.DurableObjectStorage, roomId: string, ttlMillis: number, now: number) => Effect.Effect<void, never, RuntimeContext>;
+  /** The unexpired room ids, in listing order; expired entries are deleted as a side effect. */
+  live: (storage: Workers.DurableObjectStorage, now: number) => Effect.Effect<ReadonlyArray<string>, never, RuntimeContext>;
+};
+/**
+ * The shard's Durable Object implementation, for `LegationShard.make(...)`:
+ * its state is resolved at init, its leases read and written per call.
+ */
+declare const make$3: () => Effect.Effect<Effect.Effect<ShardObject>, never, Workers.DurableObjectState>;
+declare namespace DurableFanoutBroker_d_exports {
+  export { DurableBroker, MakeOptions$1 as MakeOptions, make$2 as make };
+}
+/** Options for {@link make}. */
+interface MakeOptions$1 {
+  /** The shard namespace (`yield* LegationShard` at the room's init). */
+  readonly shards: Workers.DurableObject<ShardObject>;
+  /**
+   * Poke one room with the topics of a publish that matched its leases. The
+   * room passes its own namespace's `poke` RPC (and delivers its own pokes
+   * locally).
+   */
+  readonly poke: (roomId: string, topics: ReadonlyArray<FanoutTopics.Topic>) => Effect.Effect<void, never, RuntimeContext>;
+  /**
+   * Bound on one shard or room call. A call that exceeds it is logged and
+   * dropped, so a hung shard cannot hold the publish that awaits it. Default 5
+   * seconds.
+   */
+  readonly timeout?: Duration.Input | undefined;
+}
+/** The broker plus the room's poke inlet (wire it to the room's `poke` RPC). */
+interface DurableBroker {
+  readonly broker: FanoutBroker.FanoutBroker;
+  /** Feed an inbound poke into the broker's subscribers. */
+  readonly notify: (topics: ReadonlyArray<FanoutTopics.Topic>) => Effect.Effect<void>;
+}
+/**
+ * Build the room's {@link DurableBroker} over the shard namespace; its poke feed
+ * lives as long as the scope. Needs the room's `RuntimeContext`, which it
+ * captures for its calls.
+ */
+declare const make$2: (options: MakeOptions$1) => Effect.Effect<DurableBroker, never, Scope.Scope | RuntimeContext>;
+declare namespace EdgeInvalidation_d_exports {
+  export { CachePurgeOptions, CachePurger, InvalidationTarget, KvNamespace, KvOptions, cachePurge, encode, forward, kv, kvKey, receive };
+}
+/** The part of a Workers KV namespace binding the KV sink uses. Structural, so a test can pass a fake. */
+interface KvNamespace {
+  readonly delete: (key: string) => Promise<void>;
+}
+/**
+ * The part of the Workers cache context the purge sink uses (`ctx.cache`).
+ * Structural, so a test can pass a fake.
+ */
+interface CachePurger {
+  readonly purge: (options: {
+    tags: Array<string>;
+  }) => Promise<{
+    readonly success: boolean;
+    readonly errors?: ReadonlyArray<unknown>;
+  }>;
+}
+/** The default KV key of a row: `{collection}:{id}`. */
+declare const kvKey: (collection: string, id: string) => string;
+/** Options for {@link kv}. */
+interface KvOptions {
+  /** The key a row is cached under; defaults to {@link kvKey}. */
+  readonly keyFor?: (collection: string, id: string) => string;
+  /** How many deletes run at once. Default 8. */
+  readonly concurrency?: number;
+}
+/**
+ * A sink that deletes each touched row's entry from a KV read-through cache.
+ * A failed delete is logged; the entry's TTL is the backstop.
+ */
+declare const kv: (namespace: KvNamespace, options?: KvOptions) => InvalidationSink.InvalidationSink;
+/** Options for {@link cachePurge}. */
+interface CachePurgeOptions extends HttpCache.EvictionTagOptions {
+  /**
+   * The most tags one `purge` call carries; more are split across calls.
+   * Default 30, a conservative bound; raise it if your plan allows more tags
+   * per purge.
+   */
+  readonly maxTagsPerPurge?: number;
+}
+/**
+ * A sink that purges the edge cache by tag: the coarse tag of every touched
+ * collection and the fine tag of every touched row (`HttpCache.evictionTags`).
+ * A purge that rejects, and one that resolves `{ success: false }`, is logged.
+ */
+declare const cachePurge: (cache: CachePurger, options?: CachePurgeOptions) => InvalidationSink.InvalidationSink;
+/**
+ * The Worker that holds the cache, as the committing Worker reaches it: an RPC
+ * method on the front door's `WorkerEntrypoint`, through a service binding.
+ * It takes {@link encode}'s payload and passes it to {@link receive}.
+ */
+interface InvalidationTarget {
+  readonly invalidate: (payload: string) => Promise<void>;
+}
+/** Encode what a write touched for {@link InvalidationTarget.invalidate}. */
+declare const encode: (touched: HttpCache.Touched) => string;
+/**
+ * A sink that forwards what a write touched to the Worker holding the cache.
+ * A failed call is logged.
+ */
+declare const forward: (target: InvalidationTarget) => InvalidationSink.InvalidationSink;
+/**
+ * The receiving end of {@link forward}: decode a payload and run `sink` on it.
+ * A payload that does not decode is logged and dropped. Call it from the RPC
+ * method the binding reaches.
+ */
+declare const receive: (sink: InvalidationSink.InvalidationSink) => (payload: string) => Effect.Effect<void>;
+declare namespace Room_d_exports {
+  export { RoomConfig, RoomObject, RoomServices, make$1 as make };
+}
+/** What the room's per-instance phase runs with: the object's state and runtime context. */
+type RoomServices = Workers.DurableObjectState | RuntimeContext;
+/** The room's surface: its HTTP routes, its poke RPC and its socket handlers. */
+interface RoomObject {
+  /** The room's HTTP routes ({@link routes}): push, pull, read and the poke socket. */
+  readonly fetch: HttpEffect<RoomServices>;
+  /**
+   * The RPC a publish calls when it matched this room's leases: the topics go
+   * to the room's bus, and every socket gets a contentless poke frame.
+   */
+  readonly poke: (topics: ReadonlyArray<string>) => Effect.Effect<void, never, RuntimeContext>;
+  /** The poke channel is one-way; inbound frames are ignored. */
+  readonly webSocketMessage: () => Effect.Effect<void>;
+  /** A closed poke socket needs no cleanup: the room keeps no per-socket state. */
+  readonly webSocketClose: () => Effect.Effect<void>;
+}
+/** Configuration for {@link make}: the node graph, the backend, the auth policy and the shards. */
+interface RoomConfig<R = never> {
+  readonly nodes: Node.NodeRegistry;
+  /**
+   * The authoritative storage contract (e.g. `SqlBackend` over
+   * `D1Executor.make(db)`), built in the room's per-instance phase.
+   */
+  readonly backend: Effect.Effect<Backend.Backend, never, RoomServices>;
+  /** Deny-by-default per-collection filters, built in the per-instance phase. */
+  readonly policy: Effect.Effect<Authorization.AuthPolicy, never, RoomServices>;
+  /** Resolve a client group to its identity (session binding). */
+  readonly identity?: Effect.Effect<Authorization.IdentityResolver, never, RoomServices> | undefined;
+  /** Named-query resolution (server-authoritative subsets). */
+  readonly queries?: Effect.Effect<Query.QueryResolver, never, RoomServices> | undefined;
+  /** The topic-shard namespace: the app's shard class (`LegationShard`), yielded at init. */
+  readonly shards: Effect.Effect<Workers.DurableObject<ShardObject>, never, R>;
+  /** Shard lease heartbeat (default 30 seconds; TTL is 3×). */
+  readonly heartbeat?: Duration.Input | undefined;
+  /**
+   * Bound on each shard or room call the room makes and each lease
+   * registration; a call that exceeds it is logged and dropped, so a hung
+   * shard cannot hold a push's publish open. Default 5 seconds.
+   */
+  readonly publishTimeout?: Duration.Input | undefined;
+  /**
+   * The clock the room's boot, heartbeat and request handling run on, as a test seam.
+   * Unset in production (the real clock); a test passes its `TestClock` so
+   * `publishTimeout` and the heartbeat move with virtual time.
+   */
+  readonly clock?: Clock.Clock | undefined;
+}
+/**
+ * The room's Durable Object implementation, for `LegationRoom.make(...)`. Init
+ * resolves the object's state, its own namespace (to poke sibling rooms) and
+ * the shard namespace; the per-instance phase builds the sync server.
+ */
+declare const make$1: <R>(config: RoomConfig<R>) => Effect.Effect<Effect.Effect<RoomObject, never, RoomServices>, never, Workers.DurableObjectState | Workers.DurableObjectScope | R>;
+declare namespace RoomProtocol_d_exports {
+  export { PokeFrame, Route, decodePullRequest, decodePushRequest, decodeReadRequest, pokeFrame, routeOf, routes };
+}
+type Decoder<A> = (input: unknown) => Effect.Effect<A, ProtocolError>;
+/**
+ * The room's HTTP routes. A room answers a route by the request path's last
+ * segment, so a request forwarded with its base path intact (`/sync/push`)
+ * reaches the same route as `/push`.
+ */
+declare const routes: {
+  readonly push: "/push";
+  readonly pull: "/pull";
+  readonly read: "/read";
+  /** WebSocket upgrade: the poke channel. */
+  readonly socket: "/socket";
+};
+/** One of the room's {@link routes}. */
+type Route = (typeof routes)[keyof typeof routes];
+/**
+ * The route a request path addresses: its last segment, when that names one of
+ * the {@link routes}.
+ */
+declare const routeOf: (pathname: string) => Route | undefined;
+/** The single frame a room socket ever sends. */
+interface PokeFrame {
+  readonly type: "poke";
+}
+/** The single poke frame a room socket sends, as a value to serialize. */
+declare const pokeFrame: PokeFrame;
+/** Re-exported request decoders — the room's HTTP bodies are the protocol's. */
+declare const decodePushRequest: Decoder<Protocol.PushRequest>;
+/** The protocol's pull-request decoder. */
+declare const decodePullRequest: Decoder<Protocol.PullRequest>;
+/** The protocol's read-request decoder. */
+declare const decodeReadRequest: Decoder<Protocol.ReadRequest>;
+declare namespace RoomTransport_d_exports {
+  export { MakeOptions, make };
+}
+/** Options for {@link make}. */
+interface MakeOptions {
+  /** The sync base URL, e.g. `https://app.example.com/sync`. */
+  readonly url: string;
+  /** Extra headers (e.g. the session token) attached to every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Socket reconnect backoff cap in milliseconds. Default 10_000. */
+  readonly maxReconnectDelayMillis?: number;
+}
+/**
+ * Build the transport. The poke socket dials lazily on first subscription
+ * and re-dials with linear backoff; each frame becomes one contentless
+ * poke.
+ */
+declare const make: (options: MakeOptions) => Transport.ClientTransport;
+declare namespace Worker_d_exports {
+  export { RouterConfig, routeSync };
+}
+/** Configuration for {@link routeSync}. */
+interface RouterConfig<R = never> {
+  /** The room namespace (`yield* LegationRoom` at the Worker's init). */
+  readonly rooms: Workers.DurableObject<RoomObject>;
+  /**
+   * Resolve the caller's room id — the per-user identity, typically from
+   * the verified session. `undefined` rejects the request with 401:
+   * anonymous callers never reach a room.
+   */
+  readonly roomIdOf: (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<string | undefined, never, R>;
+  /** The base path the sync routes hang off. Default `/sync`. */
+  readonly basePath?: string | undefined;
+}
+/**
+ * Route one request: `Option.none()` for a path outside the base, a 404 for an
+ * unknown route under it, a 401 for an anonymous caller, otherwise the room's
+ * own response.
+ */
+declare const routeSync: <R = never>(config: RouterConfig<R>) => Effect.Effect<Option.Option<HttpServerResponse.HttpServerResponse>, HttpServerError, HttpServerRequest.HttpServerRequest | R>;
+export { BindingTransport_d_exports as BindingTransport, D1Executor_d_exports as D1Executor, DurableCvrStore_d_exports as DurableCvrStore, DurableFanoutBroker_d_exports as DurableFanoutBroker, EdgeInvalidation_d_exports as EdgeInvalidation, FanoutShard_d_exports as FanoutShard, Room_d_exports as Room, RoomProtocol_d_exports as RoomProtocol, RoomTransport_d_exports as RoomTransport, Worker_d_exports as Worker };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":["MakeOptions","make","make","make","make","MakeOptions","FanoutShard.ShardObject","make","FanoutShard.ShardObject","make","Room.RoomObject"],"sources":["../src/BindingTransport.ts","../src/D1Executor.ts","../src/DurableCvrStore.ts","../src/FanoutShard.ts","../src/DurableFanoutBroker.ts","../src/EdgeInvalidation.ts","../src/Room.ts","../src/RoomProtocol.ts","../src/RoomTransport.ts","../src/Worker.ts"],"mappings":"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"}