@smthrs/sync 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/SyncAuth.js

@@ -0,0 +1,119 @@
+/**
+ * The sync read path's connection authentication: implementations of the
+ * `SyncRpcs.SyncAuth` RPC middleware.
+ *
+ * A connection presents a {@link WorkspaceShare.WorkspaceCapability} in the
+ * {@link capabilityHeader} request header. {@link layer} verifies it against
+ * the workspace's {@link WorkspaceShare.WorkspaceShare} authority and runs
+ * the handler as the workspace principal. A request with no header runs as
+ * the anonymous principal — branch share capabilities carried in request
+ * payloads still authorize branch reads — and the server refuses anonymous
+ * access to every non-branch run. A request whose header is present but
+ * malformed, forged, expired, or signed by an unknown key is refused
+ * outright: presence of a credential is a claim, and a false claim is never
+ * downgraded to anonymity.
+ *
+ * There is deliberately no trusted pass-through implementation here: the only
+ * sanctioned bypass is an in-process caller providing `SyncPrincipal` itself,
+ * never a transport.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import * as Layer from "effect/Layer";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Headers from "effect/unstable/http/Headers";
+import * as RpcMiddleware from "effect/unstable/rpc/RpcMiddleware";
+import { causeText } from "./internal/CauseText.js";
+import * as shareSigner from "./internal/ShareSigner.js";
+import { SyncError } from "./SyncError.js";
+import * as SyncPrincipal from "./SyncPrincipal.js";
+import { SyncAuth } from "./SyncRpcs.js";
+import * as WorkspaceShare from "./WorkspaceShare.js";
+/**
+ * The request header a connection presents its workspace capability in.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const capabilityHeader = "flows-sync-workspace";
+const denied = shareSigner.unauthorized;
+/**
+ * Renders a workspace capability as its header value: unpadded base64url of
+ * the schema-encoded capability JSON.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export const encodeCapability = (capability) => {
+    const encoded = Schema.encodeUnknownResult(WorkspaceShare.WorkspaceCapability)(capability);
+    return Result.isFailure(encoded)
+        ? Effect.fail(new SyncError({
+            code: "invalid_request",
+            message: "The workspace capability does not encode",
+            // The rendering, never the parse failure itself: a schema issue
+            // carries the value it rejected, and the value here is a credential.
+            cause: causeText(encoded.failure)
+        }))
+        : Effect.succeed(Encoding.encodeBase64Url(JSON.stringify(encoded.success)));
+};
+/**
+ * Decodes a capability header value. Every malformation folds to the same
+ * `unauthorized` refusal so the header is not a parsing oracle.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export const decodeCapability = (value) => {
+    const text = Encoding.decodeBase64UrlString(value);
+    if (Result.isFailure(text)) {
+        return Effect.fail(denied("The workspace capability header is not a capability"));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text.success);
+    }
+    catch {
+        return Effect.fail(denied("The workspace capability header is not a capability"));
+    }
+    const decoded = Schema.decodeUnknownResult(WorkspaceShare.WorkspaceCapability)(parsed);
+    return Result.isFailure(decoded)
+        ? Effect.fail(denied("The workspace capability header is not a capability"))
+        : Effect.succeed(decoded.success);
+};
+/**
+ * Provides the workspace-capability authentication middleware: no header
+ * runs the handler as anonymous, a verified header runs it as the workspace
+ * principal, and anything else refuses the request. Verification faults
+ * (Web Crypto failing) propagate as their own error rather than as a
+ * refusal.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.effect(SyncAuth, Effect.gen(function* () {
+    const share = yield* WorkspaceShare.WorkspaceShare;
+    const middleware = (effect, options) => {
+        const header = Headers.get(options.headers, capabilityHeader);
+        if (header._tag === "None") {
+            return Effect.provideService(effect, SyncPrincipal.SyncPrincipal, SyncPrincipal.anonymous);
+        }
+        return decodeCapability(header.value).pipe(Effect.flatMap((capability) => share.verify(capability, { access: "read" })), Effect.flatMap((claims) => Effect.provideService(effect, SyncPrincipal.SyncPrincipal, 
+        // The signed expiry travels WITH the identity. A handler that
+        // opens a stream authorizes once; reducing the verified claims to
+        // a capability id here left the stream with nothing to expire on.
+        SyncPrincipal.workspace(claims.capabilityId, claims.expiresAtMs))));
+    };
+    return middleware;
+}));
+/**
+ * Stamps every outgoing request from a generated RPC client with the given
+ * workspace capability.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerClient = (capability) => RpcMiddleware.layerClient(SyncAuth, Effect.map(encodeCapability(capability), (header) => ({ next, request }) => next({ ...request, headers: Headers.set(request.headers, capabilityHeader, header) })));
+//# sourceMappingURL=SyncAuth.js.map

package/dist/esm/SyncAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncAuth.js","sourceRoot":"","sources":["../../src/SyncAuth.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The sync read path's connection authentication: implementations of the\n * `SyncRpcs.SyncAuth` RPC middleware.\n *\n * A connection presents a {@link WorkspaceShare.WorkspaceCapability} in the\n * {@link capabilityHeader} request header. {@link layer} verifies it against\n * the workspace's {@link WorkspaceShare.WorkspaceShare} authority and runs\n * the handler as the workspace principal. A request with no header runs as\n * the anonymous principal — branch share capabilities carried in request\n * payloads still authorize branch reads — and the server refuses anonymous\n * access to every non-branch run. A request whose header is present but\n * malformed, forged, expired, or signed by an unknown key is refused\n * outright: presence of a credential is a claim, and a false claim is never\n * downgraded to anonymity.\n *\n * There is deliberately no trusted pass-through implementation here: the only\n * sanctioned bypass is an in-process caller providing `SyncPrincipal` itself,\n * never a transport.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Encoding from \"effect/Encoding\"\nimport * as Layer from \"effect/Layer\"\nimport * as Result from \"effect/Result\"\nimport * as Schema from \"effect/Schema\"\nimport * as Headers from \"effect/unstable/http/Headers\"\nimport * as RpcMiddleware from \"effect/unstable/rpc/RpcMiddleware\"\nimport { causeText } from \"./internal/CauseText.ts\"\nimport * as shareSigner from \"./internal/ShareSigner.ts\"\nimport { SyncError } from \"./SyncError.ts\"\nimport * as SyncPrincipal from \"./SyncPrincipal.ts\"\nimport { SyncAuth } from \"./SyncRpcs.ts\"\nimport * as WorkspaceShare from \"./WorkspaceShare.ts\"\n\n/**\n * The request header a connection presents its workspace capability in.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const capabilityHeader = \"flows-sync-workspace\"\n\nconst denied = shareSigner.unauthorized\n\n/**\n * Renders a workspace capability as its header value: unpadded base64url of\n * the schema-encoded capability JSON.\n *\n * @category encoding\n * @since 0.1.0\n */\nexport const encodeCapability = (\n  capability: WorkspaceShare.WorkspaceCapability\n): Effect.Effect<string, SyncError> => {\n  const encoded = Schema.encodeUnknownResult(WorkspaceShare.WorkspaceCapability)(capability)\n  return Result.isFailure(encoded)\n    ? Effect.fail(\n      new SyncError({\n        code: \"invalid_request\",\n        message: \"The workspace capability does not encode\",\n        // The rendering, never the parse failure itself: a schema issue\n        // carries the value it rejected, and the value here is a credential.\n        cause: causeText(encoded.failure)\n      })\n    )\n    : Effect.succeed(Encoding.encodeBase64Url(JSON.stringify(encoded.success)))\n}\n\n/**\n * Decodes a capability header value. Every malformation folds to the same\n * `unauthorized` refusal so the header is not a parsing oracle.\n *\n * @category encoding\n * @since 0.1.0\n */\nexport const decodeCapability = (value: string): Effect.Effect<WorkspaceShare.WorkspaceCapability, SyncError> => {\n  const text = Encoding.decodeBase64UrlString(value)\n  if (Result.isFailure(text)) {\n    return Effect.fail(denied(\"The workspace capability header is not a capability\"))\n  }\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(text.success)\n  } catch {\n    return Effect.fail(denied(\"The workspace capability header is not a capability\"))\n  }\n  const decoded = Schema.decodeUnknownResult(WorkspaceShare.WorkspaceCapability)(parsed)\n  return Result.isFailure(decoded)\n    ? Effect.fail(denied(\"The workspace capability header is not a capability\"))\n    : Effect.succeed(decoded.success)\n}\n\n/**\n * Provides the workspace-capability authentication middleware: no header\n * runs the handler as anonymous, a verified header runs it as the workspace\n * principal, and anything else refuses the request. Verification faults\n * (Web Crypto failing) propagate as their own error rather than as a\n * refusal.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<SyncAuth, never, WorkspaceShare.WorkspaceShare> = Layer.effect(\n  SyncAuth,\n  Effect.gen(function*() {\n    const share = yield* WorkspaceShare.WorkspaceShare\n    const middleware: RpcMiddleware.RpcMiddleware<never, SyncError, never> = (effect, options) => {\n      const header = Headers.get(options.headers, capabilityHeader)\n      if (header._tag === \"None\") {\n        return Effect.provideService(effect, SyncPrincipal.SyncPrincipal, SyncPrincipal.anonymous)\n      }\n      return decodeCapability(header.value).pipe(\n        Effect.flatMap((capability) => share.verify(capability, { access: \"read\" })),\n        Effect.flatMap((claims) =>\n          Effect.provideService(\n            effect,\n            SyncPrincipal.SyncPrincipal,\n            // The signed expiry travels WITH the identity. A handler that\n            // opens a stream authorizes once; reducing the verified claims to\n            // a capability id here left the stream with nothing to expire on.\n            SyncPrincipal.workspace(claims.capabilityId, claims.expiresAtMs)\n          )\n        )\n      )\n    }\n    return middleware\n  })\n)\n\n/**\n * Stamps every outgoing request from a generated RPC client with the given\n * workspace capability.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerClient = (\n  capability: WorkspaceShare.WorkspaceCapability\n): Layer.Layer<RpcMiddleware.ForClient<SyncAuth>, SyncError> =>\n  RpcMiddleware.layerClient(\n    SyncAuth,\n    Effect.map(encodeCapability(capability), (header) => ({ next, request }) =>\n      next({ ...request, headers: Headers.set(request.headers, capabilityHeader, header) }))\n  )\n"]}

package/dist/esm/SyncClient.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Browser-safe client for replaying and following journal entries.
+ *
+ * @since 0.1.0
+ */
+import type * as JournalEvent from "@smthrs/journal/JournalEvent";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import * as RpcClientError from "effect/unstable/rpc/RpcClientError";
+import type * as RpcGroup from "effect/unstable/rpc/RpcGroup";
+import type { ShareCapability } from "./BranchProtocol.ts";
+import { SyncError, SyncGapError } from "./SyncError.ts";
+import { type Progress, type Resync, RunCursor, type Scope, type Snapshot, type SnapshotRequest, type WorkspaceCursor } from "./SyncProtocol.ts";
+import { SyncRpcs } from "./SyncRpcs.ts";
+/**
+ * Frames one subscription round may carry before the follow replenishes it.
+ *
+ * A subscription's `credit` is a hard frame limit the server enforces with
+ * `Stream.take`, so the number the client sends is the size of its window, not
+ * a hint. At `credit: 1` the window closed after every single entry and the
+ * follow resubscribed: following a run that emits a hundred entries cost a
+ * hundred subscribe round trips, each of them a fresh cursor snapshot and a
+ * fresh server-side fan-out. Replenishing 256 frames at a time makes the
+ * round-trip cost proportional to the window rather than to the traffic, and
+ * keeps it bounded — an unbounded window would hand the server one
+ * never-closing subscription per follower.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultCredit = 256;
+/**
+ * Entries one catch-up page asks for.
+ *
+ * Bootstrap is the replay half of replay-then-follow, so the page size is the
+ * memory one catch-up costs and the granularity at which its cursor advances.
+ * It matches {@link defaultCredit} and stays under
+ * `SyncProtocol.maxReadLimit`, which is the ceiling the server enforces.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultBootstrapLimit = 256;
+/**
+ * The policy one sync client runs every operation under.
+ *
+ * Both fields are validated by {@link makeWith} and {@link layerWith}, so a
+ * value that is not a positive safe integer fails the constructor rather than
+ * disabling the bound it configures.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Options {
+    /**
+     * Largest summed encoded-entry size one frame or bootstrap page may carry,
+     * in bytes. Defaults to {@link defaultMaxFrameBytes}.
+     */
+    readonly maxFrameBytes?: number | undefined;
+    /**
+     * Entries one catch-up page asks for. Defaults to
+     * {@link defaultBootstrapLimit}, and may not exceed
+     * `SyncProtocol.maxReadLimit`.
+     */
+    readonly bootstrapLimit?: number | undefined;
+}
+/**
+ * Input accepted by a sync subscription.
+ *
+ * `capability` authorizes branch reads: following a shared branch's run
+ * requires a capability that verifies for that branch on the server.
+ *
+ * `EApply` and `EResync` are the consumer's own failure types for `apply` and
+ * `onResync`. The subscription fails with them unchanged, so an application
+ * failure is never dressed as a transport or protocol {@link SyncError}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SubscribeOptions<EApply = never, EResync = never> {
+    readonly scope: Scope;
+    /**
+     * Where this subscription starts, per run. The effective position is the
+     * LATER of this and the client's matching progress map (applied when an
+     * apply callback is present, delivered otherwise), so a caller
+     * ahead of the shared view keeps its place and a caller behind it is
+     * fast-forwarded. Rebuild from an earlier position with a fresh client.
+     */
+    readonly cursors: WorkspaceCursor;
+    readonly capability?: ShareCapability;
+    /**
+     * Frames one subscription round may carry before the follow replenishes the
+     * window. Defaults to {@link defaultCredit}, and must be a positive integer
+     * no greater than `SyncProtocol.maxSubscribeCredit`.
+     */
+    readonly credit?: number | undefined;
+    /**
+     * Applies one entry, and DEFINES what this subscription's cursor means.
+     *
+     * Without it the cursor advances as each entry is handed to the consumer,
+     * so a consumer whose own application then fails has a cursor naming an
+     * entry it never materialized. With it the cursor advances only after this
+     * effect succeeds, and records it in `Progress.applied`. A failure here
+     * fails the subscription with the entry unacknowledged, so the
+     * next applying subscription delivers it again; the effect must
+     * therefore be idempotent, because a redelivery is exactly what a retry is.
+     */
+    readonly apply?: ((entry: JournalEvent.Entry) => Effect.Effect<void, EApply>) | undefined;
+    /**
+     * Restores state when the server refuses a cursor below a compaction floor.
+     * Return the exact run and sequence actually restored, after applying it.
+     *
+     * The entries under the floor are deleted. Fetch an explicitly public
+     * projection through `snapshot` or an authorized local source; a
+     * projection has a real hole to fill. The returned sequence must cover the
+     * requested floor; a newer snapshot resumes at its own sequence, not the
+     * older floor. Missing handlers, failures, interruption, and invalid receipts
+     * leave the cursor unmoved. There is no implicit skip of deleted history.
+     *
+     * Durable consumers must commit their restored state and durable cursor in
+     * their own transaction and seed a fresh client from that cursor on restart.
+     * This client's cursor is in memory, not an atomic cross-store transaction.
+     * Recovery must be idempotent, including when a newer compaction requires
+     * another restoration before the suffix can be read.
+     */
+    readonly onResync?: ((resync: Resync) => Effect.Effect<RunCursor, EResync>) | undefined;
+}
+/**
+ * Replicated journal subscription operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    /** Fetches a public snapshot without applying state or advancing a cursor. */
+    readonly snapshot: (request: SnapshotRequest) => Effect.Effect<Snapshot, SyncError>;
+    /** Replays then follows `options.scope`, also failing with the callbacks' own errors. */
+    readonly subscribe: <EApply = never, EResync = never>(options: SubscribeOptions<EApply, EResync>) => Stream.Stream<JournalEvent.Entry, SyncError | SyncGapError | EApply | EResync>;
+    /**
+     * Delivery and application positions. `delivered` is a transport bookmark
+     * only; `applied` is what the `apply` and `onResync` callbacks acknowledged.
+     */
+    readonly progress: Effect.Effect<Progress>;
+}
+declare const SyncClient_base: Context.ServiceClass<SyncClient, "@smthrs/sync/SyncClient", Service>;
+/**
+ * The browser-safe journal replication client.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export declare class SyncClient extends SyncClient_base {
+}
+/**
+ * The client tag's former name, kept for one release.
+ *
+ * @deprecated Use {@link SyncClient}.
+ * @category services
+ * @since 0.1.0
+ */
+export declare const Sync: typeof SyncClient;
+/**
+ * The client tag's former name, kept for one release.
+ *
+ * @deprecated Use {@link SyncClient}.
+ * @category services
+ * @since 0.1.0
+ */
+export type Sync = SyncClient;
+/**
+ * Constructs a closed sync stub, optionally overriding individual operations.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides a closed sync stub.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<SyncClient>;
+type Client = RpcClient.RpcClient<RpcGroup.Rpcs<typeof SyncRpcs>, RpcClientError.RpcClientError>;
+/**
+ * Projects a Sync RPC client into the local replication service.
+ *
+ * Delivered and applied cursors are separate per-service `Ref` maps: concurrent
+ * subscriptions for one materialization share them, and each commit advances
+ * its matching map monotonically. A
+ * cursor advances in the same stream pull that admits each entry to the
+ * consumer, or — when the caller supplies `SubscribeOptions.apply` — only
+ * after that callback has applied the entry. Interrupted partial pages
+ * therefore retain the last admitted entry rather than incorrectly
+ * acknowledging the server's whole page.
+ *
+ * A frame or bootstrap page whose encoded entries exceed `maxFrameBytes` is
+ * refused with `frame_too_large`. Out-of-scope entries, repeated or reordered
+ * sequences, and missing response generations fail with `protocol_violation`
+ * before delivery. Each entry-bearing run in a Read page must have exactly one
+ * explicit generation cursor, and every entry must be above the requested
+ * cursor. Live frames instead drop already-covered entries and deliver only
+ * the suffix above the cursor. An incomplete bootstrap page with no entries
+ * or a completed subscription window with no frames fails with
+ * `protocol_violation` instead of reopening immediately.
+ *
+ * A live follow that loses its transport reconnects under
+ * {@link reconnectPolicy}, resuming from the acknowledged cursors; the failure
+ * cause is logged before the retry folds it. The follow spends a credit window
+ * of {@link defaultCredit} frames per subscription round and replenishes it by
+ * resubscribing from the cursors it has acknowledged. Already-covered entries
+ * are not delivered again; the round-trip cost scales with credit windows.
+ *
+ * A `compacted` refusal fails closed unless `SubscribeOptions.onResync`
+ * restores the missing prefix and returns its exact cursor. Snapshot fetching
+ * never applies state or advances cursors. Only a validated receipt for the requested run at or
+ * above its compaction floor advances the cursor before reading the suffix.
+ *
+ * A subscription's effective cursor per run is the LATER of the caller's and
+ * the matching progress map: a caller that restored its own progress is never
+ * regressed, and a caller asking for history this client already acknowledged
+ * is fast-forwarded. Rebuild a projection from an earlier position with a
+ * fresh client, whose acknowledged map is empty.
+ *
+ * This constructor carries the default policy, which is valid by
+ * construction and so cannot fail. {@link makeWith} takes an explicit
+ * {@link Options} and validates it.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: ({ client }: {
+    readonly client: Client;
+}) => Effect.Effect<Service>;
+/**
+ * Constructs the sync client under an explicit policy.
+ *
+ * Every option is validated here, once, so a client either exists under a
+ * policy it can serve or never exists at all. Validating on each `subscribe`
+ * and each `snapshot` instead accepted a `maxFrameBytes` of `NaN` at
+ * construction and then refused every operation under it, which reported a
+ * composition's mistake as a run-time failure of the follow. This mirrors
+ * `SyncServer.makeLiveWith` and `BranchCommands.makeLiveWith`.
+ *
+ * `SubscribeOptions.credit` is a REQUEST count rather than a client policy, so
+ * it is still checked where the request is built.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const makeWith: ({ bootstrapLimit, client, maxFrameBytes }: Options & {
+    readonly client: Client;
+}) => Effect.Effect<Service, SyncError>;
+/**
+ * Provides the sync client from the active RPC protocol.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<SyncClient, never, RpcClient.Protocol>;
+/**
+ * Provides the sync client under an explicit policy. Fails with
+ * `invalid_request` when an option is not a positive safe integer, so a bad
+ * policy fails the composition rather than every operation under it.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerWith: (options: Options) => Layer.Layer<SyncClient, SyncError, RpcClient.Protocol>;
+export {};
+//# sourceMappingURL=SyncClient.d.ts.map

package/dist/esm/SyncClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncClient.d.ts","sourceRoot":"","sources":["../../src/SyncClient.ts"],"names":[],"mappings":"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"}