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

package/src/SyncError.ts

@@ -0,0 +1,147 @@
+/**
+ * Stable, schema-backed failures for the sync boundary.
+ *
+ * @since 0.1.0
+ */
+
+import * as JournalEvent from "@smthrs/journal/JournalEvent"
+import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
+import { Resync } from "./SyncProtocol.ts"
+
+/** The literals behind {@link ErrorCode}, also read by {@link SyncError.is}. */
+const errorCodes = [
+  "invalid_request",
+  "unsupported",
+  "unauthorized",
+  "not_found",
+  "backpressure",
+  "frame_too_large",
+  "decode_failed",
+  "transport_failed",
+  "protocol_violation",
+  "lineage_changed",
+  "compacted",
+  "closed",
+  "unknown"
+] as const
+
+/**
+ * Stable error codes returned by sync operations.
+ *
+ * `unsupported` reports an unavailable host operation or presence transport
+ * (since 1.0.0). It never implies an empty roster.
+ *
+ * `compacted` reports that the request's cursor for one run starts below that
+ * run's compaction floor, so the entries it asks for have been deleted. It is
+ * its own code rather than an `unknown` because it is RECOVERABLE and nothing
+ * else here is: the accompanying {@link SyncError.resync} names the checkpoint
+ * to resume from, and a follower that applies it converges. Folding it into
+ * `unknown` cost the checkpoint, and with it every path back.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const ErrorCode = Schema.Literals(errorCodes).annotate({ identifier: "@smthrs/sync/ErrorCode" })
+
+const codes: ReadonlySet<string> = new Set(errorCodes)
+
+/**
+ * Stable error code returned by a sync operation.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ErrorCode = typeof ErrorCode.Type
+
+const Rewind = Schema.Struct({
+  runId: JournalEvent.RunId,
+  generation: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  afterSeq: Schema.Int.check(Schema.isGreaterThanOrEqualTo(-1))
+})
+
+/**
+ * Error raised by sync validation, transport, framing, or subscription work.
+ *
+ * `resync` is set only on `compacted`, and names the run and the checkpoint
+ * sequence a follower resumes from. It is optional so every other code keeps
+ * the shape it already had on the wire.
+ *
+ * `rewind` is set on server-side `lineage_changed` refusals and names the
+ * current generation and archive boundary. The caller rebuilds its projection
+ * from retained history and creates a fresh client; the client never retries this failure.
+ *
+ * `cause` is a bounded STRING, not the host object that failed. This error is
+ * the declared error schema of every RPC in both groups, so whatever it
+ * carries reaches a remote follower that may hold nothing but a branch share
+ * link. A `Schema.Unknown` cause published the host's own failure verbatim —
+ * a driver message with SQL text, a rejected credential — counted against no
+ * size ceiling, and had no defined wire form for a class instance or a cyclic
+ * value. `internal/CauseText` is the one renderer that fills it.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class SyncError extends Schema.TaggedError<SyncError>()("@smthrs/sync/SyncError", {
+  code: ErrorCode,
+  message: Schema.String,
+  cause: Schema.optional(Schema.String),
+  resync: Schema.optional(Resync),
+  rewind: Schema.optional(Rewind)
+}) {
+  /**
+   * Returns `true` when a value carries this error's shape: the tag, a `code`
+   * this package declares, a string `message`, and a `resync` only alongside
+   * `compacted`.
+   *
+   * It is a STRUCTURAL check, not a class check, deliberately. Everything that
+   * reaches it on a shipped path has crossed a boundary that rebuilds the
+   * value — the RPC client's schema-decoded error channel, or a browser
+   * `postMessage` that keeps the fields and drops the prototype — and a check
+   * that demanded the prototype would refuse an error the package itself sent.
+   * What it does not verify is that the value was produced by this package: a
+   * value constructed in-process with the right fields passes.
+   *
+   * It is TOTAL. The value is `unknown`, so ANY property read on it may be a
+   * throwing getter — the tag included, which is the first one read and was
+   * the one read outside the protection — and this guard decides whether a
+   * follow reconnects and whether a cursor moves past a compaction floor: a
+   * question about a value's shape must answer, never raise.
+   *
+   * @since 0.1.0
+   */
+  static readonly is = (value: unknown): value is SyncError => {
+    try {
+      if (!Predicate.isTagged(value, "@smthrs/sync/SyncError")) return false
+      const candidate = value as {
+        readonly code?: unknown
+        readonly message?: unknown
+        readonly resync?: unknown
+        readonly rewind?: unknown
+      }
+      if (typeof candidate.message !== "string") return false
+      if (typeof candidate.code !== "string" || !codes.has(candidate.code)) return false
+      if (
+        candidate.rewind !== undefined &&
+        (candidate.code !== "lineage_changed" || !Schema.is(Rewind)(candidate.rewind))
+      ) return false
+      if (candidate.resync === undefined) return true
+      return candidate.code === "compacted" && Schema.is(Resync)(candidate.resync)
+    } catch {
+      return false
+    }
+  }
+}
+
+/**
+ * Terminal error raised when a server frame starts beyond the client's
+ * covered cursor.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class SyncGapError extends Schema.TaggedError<SyncGapError>()("@smthrs/sync/SyncGapError", {
+  runId: JournalEvent.RunId,
+  expectedFrom: JournalEvent.Seq,
+  receivedFrom: JournalEvent.Seq
+}) {}

package/src/SyncPrincipal.ts

@@ -0,0 +1,115 @@
+/**
+ * The authenticated identity of one sync request.
+ *
+ * The principal is a `Context.Reference` whose default is
+ * {@link anonymous}, which is what makes the read path fail closed: code
+ * that never authenticates runs as anonymous, and the server refuses
+ * anonymous access to every non-branch run. The only ways to become the
+ * workspace principal are a workspace capability verified by
+ * `SyncAuth.layer` at the RPC boundary, or an in-process caller that
+ * provides the reference itself — which is the sanctioned path for code
+ * already holding the journal, and never for a transport.
+ *
+ * @since 0.1.0
+ */
+
+import * as Context from "effect/Context"
+import * as Layer from "effect/Layer"
+
+/**
+ * A request that presented no credential. It may still read branch runs
+ * through per-request branch share capabilities.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Anonymous {
+  readonly _tag: "Anonymous"
+}
+
+/**
+ * A request authenticated for the workspace's non-branch runs.
+ * `capabilityId` names the credential for auditing; in-process callers name
+ * themselves.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Workspace {
+  readonly _tag: "Workspace"
+  readonly capabilityId: string
+  /**
+   * When the credential that established this principal stops authorizing,
+   * in epoch milliseconds, or `Infinity` for an in-process owner that
+   * presented no credential at all.
+   *
+   * A signed expiry is this package's ONLY revocation mechanism, and an open
+   * subscription is not a sequence of requests: it is authorized once, at
+   * open, and then streams. Without the expiry on the identity itself,
+   * nothing downstream could tell a live subscription to stop, so a holder of
+   * an expired capability kept reading for as long as it declined to
+   * disconnect.
+   */
+  readonly expiresAtMs: number
+}
+
+/**
+ * Any authenticated identity a sync request can carry.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Principal = Anonymous | Workspace
+
+/**
+ * The unauthenticated principal.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const anonymous: Principal = { _tag: "Anonymous" }
+
+/**
+ * Constructs the workspace principal for a named credential.
+ *
+ * `expiresAtMs` defaults to `Infinity`, which is the honest answer for an
+ * in-process owner that already holds the journal: it presented no credential,
+ * so no credential can expire under it.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const workspace = (
+  capabilityId: string,
+  expiresAtMs: number = Number.POSITIVE_INFINITY
+): Principal => ({ _tag: "Workspace", capabilityId, expiresAtMs })
+
+/**
+ * Returns `true` when a principal may read non-branch runs.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export const isWorkspace = (principal: Principal): principal is Workspace => principal._tag === "Workspace"
+
+/**
+ * The current request's principal, defaulting to {@link anonymous}.
+ *
+ * @category references
+ * @since 0.1.0
+ */
+export const SyncPrincipal: Context.Reference<Principal> = Context.Reference<Principal>(
+  "@smthrs/sync/SyncPrincipal",
+  { defaultValue: () => anonymous }
+)
+
+/**
+ * Provides the workspace principal directly, bypassing credential
+ * verification. For in-process callers that already own the journal — a
+ * transport boundary must authenticate through `SyncAuth.layer` instead.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerWorkspace = (capabilityId: string): Layer.Layer<never> =>
+  Layer.succeed(SyncPrincipal, workspace(capabilityId))