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

package/dist/esm/SyncServer.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The workspace-side implementation of the sync read path.
+ *
+ * @since 0.1.0
+ */
+import { Journal } from "@smthrs/journal";
+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 type * as Rpc from "effect/unstable/rpc/Rpc";
+import type * as RpcGroup from "effect/unstable/rpc/RpcGroup";
+import * as RunCatalog from "./RunCatalog.ts";
+import { SyncError } from "./SyncError.ts";
+import * as SyncProtocol from "./SyncProtocol.ts";
+import { SyncRpcs } from "./SyncRpcs.ts";
+/**
+ * Sync read-path operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly snapshot: (request: SyncProtocol.SnapshotRequest) => Effect.Effect<SyncProtocol.Snapshot, SyncError>;
+    readonly read: (request: SyncProtocol.ReadRequest) => Effect.Effect<SyncProtocol.ServerReadResponse, SyncError>;
+    readonly subscribe: (request: SyncProtocol.SubscribeRequest) => Stream.Stream<SyncProtocol.ServerFrame, SyncError>;
+}
+declare const SyncServer_base: Context.ServiceClass<SyncServer, "@smthrs/sync/SyncServer", Service>;
+/**
+ * The workspace sync server.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class SyncServer extends SyncServer_base {
+}
+declare const SnapshotSource_base: Context.ServiceClass<SnapshotSource, "@smthrs/sync/SnapshotSource", {
+    readonly read: (request: SyncProtocol.SnapshotRequest) => Effect.Effect<SyncProtocol.Snapshot, SyncError>;
+}>;
+/**
+ * Explicit host opt-in for public projection snapshots. Never bind this to raw
+ * Journal.latestCheckpoint: executable checkpoints are intentionally unredacted.
+ * Providers must select the requested lineage/projection/version, retain a
+ * snapshot covering compaction, and return a complete state through its sequence.
+ * Run/branch read authorization occurs before this callback. Its output must be
+ * safe for every reader authorized for that run; narrower data needs a separate
+ * authorization boundary. Missing providers fail closed.
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export declare class SnapshotSource extends SnapshotSource_base {
+}
+/**
+ * Constructs a closed sync server stub.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides a closed sync server stub.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<SyncServer>;
+/**
+ * Largest number of journal reads one workspace subscription keeps open at
+ * once.
+ *
+ * A workspace subscription serves every run it covers, and every open read is
+ * a cursor plus a page buffer. Without a bound the cost of one follower is the
+ * size of the workspace: a thousand-run workspace opened a thousand journal
+ * streams the moment a subscription started, whether or not the follower ever
+ * read from them, and a follower that stalled held all of them. Sixty-four
+ * bounds what one follower costs without bounding what it sees: the workspace
+ * tail visits every covered run each round, so a run past the bound waits for
+ * a slot for the length of one round rather than being starved.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultConcurrency = 64;
+/**
+ * How long a workspace subscription waits before re-reading the runs it
+ * covers, when nothing announces a change, in milliseconds.
+ *
+ * A workspace tail is a fan-in over many runs, and the runs another engine
+ * process owns reach this process only through the database. rc.0 has no
+ * cross-process wake, so the interval is the whole of the freshness policy for
+ * them: a follower sees an entry within one interval of it being durable. A
+ * second matches the rest of the rc.0 posture — the heartbeat sweep, the
+ * cancel poll, and {@link RunCatalog.defaultPollIntervalMs}.
+ *
+ * It is not what an in-process append waits for. An entry this process commits
+ * is published on `Journal.changes`, and a workspace subscription that covers
+ * its run wakes the round on it, so a follower beside the writer sees it at
+ * once rather than at the next tick. A run-scoped subscription is likewise
+ * unaffected: it follows one journal stream directly and keeps that stream's
+ * wake.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultTailIntervalMs = 1000;
+/**
+ * Read-path policy.
+ *
+ * The default caps the encoded entries of one read page or one subscription
+ * frame at 2 MiB, and the run streams one subscription holds open at
+ * {@link defaultConcurrency}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    /**
+     * Largest summed encoded-entry size one read page or subscription frame may
+     * carry, in bytes. Defaults to {@link SyncProtocol.defaultMaxFrameBytes}.
+     */
+    readonly maxFrameBytes?: number | undefined;
+    /**
+     * Largest number of journal reads one workspace subscription keeps open at
+     * once. Defaults to {@link defaultConcurrency}.
+     */
+    readonly concurrency?: number | undefined;
+    /**
+     * How long a workspace subscription waits before re-reading every run it
+     * covers, when nothing wakes it — no journal entry committed in this
+     * process, no catalog announcement — in milliseconds, and the longest a
+     * stream of local wakes may defer that catalog-wide round. Defaults to
+     * {@link defaultTailIntervalMs}.
+     */
+    readonly tailIntervalMs?: number | undefined;
+}
+/**
+ * Constructs the workspace sync server with default policy.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeLive: Effect.Effect<Service, never, Journal.Journal | RunCatalog.RunCatalog>;
+/**
+ * Constructs the workspace sync server over a journal and a run catalog, under
+ * an explicit policy.
+ *
+ * Every option is validated as a positive safe integer at construction, so a
+ * policy fails loudly instead of quietly not existing: the TypeScript type
+ * says `number`, and `maxFrameBytes: NaN` made every `bytes > maxFrameBytes`
+ * comparison false, which disabled the ceiling it configured.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeLiveWith: (options?: Options) => Effect.Effect<Service, SyncError, Journal.Journal | RunCatalog.RunCatalog>;
+/**
+ * Provides the workspace sync server.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<SyncServer, never, Journal.Journal | RunCatalog.RunCatalog>;
+/**
+ * Provides the workspace sync server under an explicit policy. Fails with
+ * `invalid_request` when an option is not a positive safe integer.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerWith: (options: Options) => Layer.Layer<SyncServer, SyncError, Journal.Journal | RunCatalog.RunCatalog>;
+/**
+ * Provides the sync RPC handlers over the sync server: a thin, honest
+ * projection of {@link Service} onto the wire, mirroring
+ * `BranchServer.layerHandlers`. Serving these handlers requires an
+ * implementation of the group's `SyncAuth` middleware — `SyncAuth.layer` is
+ * the production one — and without a middleware-installed principal every
+ * request runs as anonymous and non-branch reads are refused.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerHandlers: Layer.Layer<Rpc.ToHandler<RpcGroup.Rpcs<typeof SyncRpcs>>, never, SyncServer>;
+export {};
+//# sourceMappingURL=SyncServer.d.ts.map

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

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