@synnaxlabs/client 0.56.2 → 0.57.1

package/src/connection/status.ts

@@ -0,0 +1,442 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import {
+  type CrudeTimeSpan,
+  deep,
+  type destructor,
+  id,
+  migrate,
+  observe,
+  TimeSpan,
+  TimeStamp,
+} from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { AuthError, DisconnectedError } from "@/errors";
+import { status } from "@/status";
+
+export const REASONS = ["unreachable", "auth", "incompatible"] as const;
+export const reasonZ = z.enum(REASONS);
+/** Why the connection is in the error variant. */
+export type Reason = z.infer<typeof reasonZ>;
+
+/** The fact vector beneath the connection's status variant. */
+export const statusDetailsZ = z.object({
+  error: z.instanceof(Error).optional(),
+  authenticated: z.boolean(),
+  streamLive: z.boolean(),
+  // The cluster refused the change stream. Unary calls the user is allowed to
+  // make still work; live updates do not arrive.
+  streamDenied: z.boolean(),
+  epoch: z.number(),
+  clusterKey: z.string(),
+  clientVersion: z.string(),
+  nodeVersion: z.string().optional(),
+  clientServerCompatible: z.boolean(),
+  clockSkew: TimeSpan.z,
+  clockSkewExceeded: z.boolean(),
+  retry: z.object({ attempt: z.number(), nextAt: TimeStamp.z }).nullable(),
+  // A check is in flight right now. A process fact, not a judgment: the
+  // variant holds its verdict while attempts run beneath it.
+  checking: z.boolean(),
+});
+export interface StatusDetails extends z.infer<typeof statusDetailsZ> {}
+
+/** Error-variant details: the same facts plus the reason the connection failed. */
+export const errorStatusDetailsZ = statusDetailsZ.extend({ reason: reasonZ });
+export interface ErrorStatusDetails extends z.infer<typeof errorStatusDetailsZ> {}
+
+export const nonErrorVariantZ = z.enum([
+  "success",
+  "info",
+  "warning",
+  "loading",
+  "disabled",
+]);
+
+/**
+ * The connection status: a standard status whose details carry the connection's
+ * facts. Renders anywhere a status does, with no translation. Discriminated on
+ * variant: `reason` exists only on the error member.
+ */
+export const statusZ = z.discriminatedUnion("variant", [
+  status.statusZ({ v: status.errorVariantZ, details: errorStatusDetailsZ }),
+  status.statusZ({ v: nonErrorVariantZ, details: statusDetailsZ }),
+]);
+export type ErrorStatus = status.Status<
+  typeof errorStatusDetailsZ,
+  typeof status.errorVariantZ
+>;
+export type NonErrorStatus = status.Status<
+  typeof statusDetailsZ,
+  typeof nonErrorVariantZ
+>;
+export type Status = ErrorStatus | NonErrorStatus;
+
+const DEFAULT_STATUS_DETAILS: StatusDetails = {
+  authenticated: false,
+  streamLive: false,
+  streamDenied: false,
+  epoch: 0,
+  clusterKey: "",
+  clientVersion: __VERSION__,
+  clientServerCompatible: false,
+  clockSkew: TimeSpan.ZERO,
+  clockSkewExceeded: false,
+  retry: null,
+  checking: false,
+};
+
+/** The status of a client that does not exist. */
+export const DEFAULT_STATUS: Status = {
+  key: "connection",
+  name: "Connection",
+  variant: "disabled",
+  message: "Disconnected",
+  description: "",
+  time: TimeStamp.ZERO,
+  details: DEFAULT_STATUS_DETAILS,
+};
+
+/** Consecutive check failures before escalating to error(unreachable). */
+export const DEFAULT_ESCALATE_AFTER = 4;
+
+export interface Config {
+  clientVersion: string;
+  /** Human-readable cluster name for status messages. */
+  name?: string;
+  escalateAfter: number;
+  clockSkewThreshold: TimeSpan;
+  /** Whether success requires a live change stream. */
+  requiresStream: boolean;
+}
+
+/**
+ * The consumer-facing view of a client's connection. Read {@link Handle.status}
+ * or subscribe via {@link Handle.onChange}; the client owns every transition.
+ */
+export interface Handle {
+  /** The current connection status. */
+  readonly status: Status;
+  /** Subscribes to status changes. Returns a destructor that unsubscribes. */
+  onChange: (callback: (status: Status) => void) => destructor.Destructor;
+  /**
+   * Resets the retry backoff and checks immediately. Auth and incompatibility
+   * errors are not cleared: those rest until the user supplies something new.
+   */
+  retryNow: () => void;
+}
+
+const isSettled = ({ variant }: Status): boolean =>
+  variant === "success" ||
+  variant === "warning" ||
+  variant === "error" ||
+  variant === "disabled";
+
+/**
+ * Resolves once the connection is usable: success, or warning when the cluster
+ * refuses live updates. Rejects with the stored failure when it settles on an
+ * error variant or is closed. The current status is evaluated first, so an
+ * already-connected handle resolves without waiting.
+ * @throws {Error} if the timeout elapses first.
+ */
+export const awaitConnected = async (
+  handle: Handle,
+  timeout?: CrudeTimeSpan,
+): Promise<Status> => {
+  const settled = await observe.until(handle, () => handle.status, isSettled, timeout);
+  if (settled.variant !== "success" && settled.variant !== "warning")
+    throw settled.details.error ?? new DisconnectedError(settled.message);
+  return settled;
+};
+
+/** The facts a single connectivity check yields. */
+export interface Info {
+  clusterKey: string;
+  nodeVersion: string;
+  /** Skew measured across the check's round trip. */
+  clockSkew: TimeSpan;
+}
+
+/**
+ * Everything that can move the connection status. The client is the only
+ * producer: check and retry events come from its own loop, the rest arrive as
+ * outside facts through its notify inbox.
+ */
+export type Event =
+  | { type: "check.started" }
+  | { type: "check.success"; info: Info }
+  | { type: "check.failure"; error: Error; attempt: number }
+  | { type: "stream.live" }
+  | { type: "stream.drop"; error?: Error }
+  | { type: "stream.denied"; error?: Error }
+  | { type: "auth.success" }
+  | { type: "auth.failure"; error: Error }
+  | { type: "epoch.advanced"; epoch: number }
+  | { type: "retry.scheduled"; attempt: number; nextAt: TimeStamp }
+  | { type: "retry.exhausted" }
+  | { type: "retry.requested" }
+  | { type: "credentials.replaced" }
+  | { type: "closed" };
+
+const CONNECTING = "Connecting";
+const RECONNECTING = "Reconnecting";
+const UNREACHABLE = "Cannot reach cluster";
+const STREAM_DENIED =
+  "Live updates are unavailable. This user cannot read the change channels.";
+
+const connectedMessage = ({ name }: Config): string =>
+  `Connected to ${name ?? "cluster"}`;
+
+/** The status a freshly constructed client starts in. */
+export const createInitialStatus = (config: Config): Status => ({
+  ...DEFAULT_STATUS,
+  key: id.create(),
+  name: config.name ?? DEFAULT_STATUS.name,
+  time: TimeStamp.now(),
+  variant: "loading",
+  message: `Connecting to ${config.name ?? "cluster"}`,
+  details: { ...DEFAULT_STATUS_DETAILS, clientVersion: config.clientVersion },
+});
+
+// Merges facts without touching variant or reason, so the union member holds.
+const update = <S extends Status>(prev: S, details: Partial<StatusDetails>): S => ({
+  ...prev,
+  details: { ...prev.details, ...details },
+});
+
+/** Moves to a non-error variant, structurally dropping any parked reason. */
+const enter = (
+  prev: Status,
+  variant: Exclude<status.Variant, "error">,
+  message: string,
+  details: Partial<StatusDetails> = {},
+  description: string = "",
+): NonErrorStatus => {
+  const { reason: _, ...merged }: StatusDetails & { reason?: Reason } = {
+    ...prev.details,
+    ...details,
+  };
+  return { ...prev, variant, message, description, details: merged };
+};
+
+const enterError = (
+  prev: Status,
+  message: string,
+  reason: Reason,
+  details: Partial<StatusDetails> = {},
+): ErrorStatus => ({
+  ...prev,
+  variant: "error",
+  message,
+  description: "",
+  details: { ...prev.details, ...details, reason },
+});
+
+const isCompatible = (nodeVersion: string, clientVersion: string): boolean =>
+  migrate.versionsEqual(clientVersion, nodeVersion, {
+    checkMajor: true,
+    checkMinor: true,
+    checkPatch: false,
+  });
+
+const checkFacts = (info: Info, config: Config): Partial<StatusDetails> => ({
+  clusterKey: info.clusterKey,
+  nodeVersion: info.nodeVersion,
+  // the check traverses the auth middleware, so a response is proof of auth
+  authenticated: true,
+  clockSkew: info.clockSkew,
+  clockSkewExceeded: info.clockSkew.abs().greaterThan(config.clockSkewThreshold),
+  clientServerCompatible: isCompatible(info.nodeVersion, config.clientVersion),
+});
+
+// Connected, with live updates refused. A settled outcome: only a policy
+// change lifts it, so the machine rests here instead of chasing the stream.
+const enterStreamDenied = (
+  prev: Status,
+  config: Config,
+  details: Partial<StatusDetails> = {},
+): Status =>
+  enter(
+    prev,
+    "warning",
+    connectedMessage(config),
+    {
+      ...details,
+      streamDenied: true,
+      streamLive: false,
+      error: undefined,
+      retry: null,
+    },
+    STREAM_DENIED,
+  );
+
+const reduceCheckSuccess = (prev: Status, info: Info, config: Config): Status => {
+  const { clusterKey } = prev.details;
+  if (clusterKey !== "" && info.clusterKey !== clusterKey)
+    return reduceClusterReplaced(prev, info, config);
+  const facts = checkFacts(info, config);
+  // reachable but the stream is still dark: the client re-demands it and we
+  // stay degraded until it reports live. A parked unreachable error must
+  // lift out of error: the short circuit it drives would starve the very
+  // stream reopen this state waits on.
+  if (config.requiresStream && !prev.details.streamLive) {
+    if (prev.details.streamDenied) return enterStreamDenied(prev, config, facts);
+    if (prev.variant === "error" && prev.details.reason === "unreachable")
+      return enter(prev, "loading", RECONNECTING, {
+        ...facts,
+        error: undefined,
+        retry: null,
+      });
+    return update(prev, facts);
+  }
+  if (prev.variant === "success") return update(prev, { ...facts, retry: null });
+  return enter(prev, "success", connectedMessage(config), {
+    ...facts,
+    error: undefined,
+    retry: null,
+  });
+};
+
+// The cluster answering the check is not the one previously contacted.
+// Everything learned from the old cluster is void, so the machine returns to
+// first contact: loading at epoch 0 with a dark stream.
+const reduceClusterReplaced = (prev: Status, info: Info, config: Config): Status =>
+  enter(prev, "loading", `Connecting to ${config.name ?? "cluster"}`, {
+    ...checkFacts(info, config),
+    streamLive: false,
+    streamDenied: false,
+    epoch: 0,
+    error: undefined,
+    retry: null,
+  });
+
+const reduceAuthFailure = (prev: Status, error: Error): Status =>
+  enterError(prev, error.message, "auth", {
+    error,
+    authenticated: false,
+    retry: null,
+  });
+
+const reduceCheckFailure = (
+  prev: Status,
+  error: Error,
+  attempt: number,
+  config: Config,
+): Status => {
+  if (AuthError.matches(error)) return reduceAuthFailure(prev, error);
+  const escalating = prev.variant === "loading";
+  if (escalating && attempt >= config.escalateAfter)
+    return enterError(prev, error.message ?? UNREACHABLE, "unreachable", { error });
+  if (prev.variant === "success")
+    return enter(prev, "loading", RECONNECTING, { error });
+  return update(prev, { error });
+};
+
+const reduceStreamLive = (prev: Status, config: Config): Status => {
+  const parked = prev.variant === "error" && prev.details.reason !== "unreachable";
+  if (parked) return update(prev, { streamLive: true, streamDenied: false });
+  return enter(prev, "success", connectedMessage(config), {
+    streamLive: true,
+    streamDenied: false,
+    error: undefined,
+    retry: null,
+  });
+};
+
+const reduceStreamDrop = (prev: Status, error?: Error): Status => {
+  if (prev.variant !== "success") return update(prev, { streamLive: false });
+  return enter(prev, "loading", RECONNECTING, { streamLive: false, error });
+};
+
+const reduceRetryExhausted = (prev: Status): Status => {
+  if (prev.variant !== "loading") return update(prev, { retry: null });
+  return enterError(prev, prev.details.error?.message ?? UNREACHABLE, "unreachable", {
+    retry: null,
+  });
+};
+
+/**
+ * Folds an event into the connection status. Pure: every transition in the
+ * lifecycle lives here and nowhere else. `disabled` is terminal.
+ */
+export const reduce = (prev: Status, event: Event, config: Config): Status => {
+  if (prev.variant === "disabled") return prev;
+  switch (event.type) {
+    case "check.started":
+      return update(prev, { checking: true });
+    case "check.success":
+      return update(reduceCheckSuccess(prev, event.info, config), { checking: false });
+    case "check.failure":
+      return update(reduceCheckFailure(prev, event.error, event.attempt, config), {
+        checking: false,
+      });
+    case "stream.live":
+      return reduceStreamLive(prev, config);
+    case "stream.drop":
+      return reduceStreamDrop(prev, event.error);
+    case "stream.denied":
+      return enterStreamDenied(prev, config);
+    case "auth.success":
+      return update(prev, { authenticated: true });
+    case "auth.failure":
+      return reduceAuthFailure(prev, event.error);
+    case "epoch.advanced":
+      return update(prev, { epoch: event.epoch });
+    case "retry.scheduled":
+      return update(prev, { retry: { attempt: event.attempt, nextAt: event.nextAt } });
+    case "retry.exhausted":
+      return reduceRetryExhausted(prev);
+    case "retry.requested":
+      // deliberately does not clear auth or incompatibility: those rest until
+      // the user supplies something new
+      if (prev.variant !== "error" || prev.details.reason !== "unreachable")
+        return prev;
+      return enter(prev, "loading", CONNECTING);
+    case "credentials.replaced":
+      // the new user may hold the permissions the old one lacked
+      return enter(prev, "loading", CONNECTING, {
+        error: undefined,
+        streamDenied: false,
+      });
+    case "closed":
+      return enter(prev, "disabled", "Closed", {
+        streamLive: false,
+        retry: null,
+        checking: false,
+      });
+  }
+};
+
+// Fields that legitimately churn without meaning anything: the stamp moves on
+// every advance and raw skew jitters on every successful check. Everything
+// else is material, so new fields notify by default.
+const comparable = ({ time: _, ...rest }: Status): unknown => ({
+  ...rest,
+  details: { ...rest.details, clockSkew: undefined },
+});
+
+/** Whether the change is worth notifying observers about. */
+export const materialChange = (prev: Status, next: Status): boolean =>
+  !deep.equal(comparable(prev), comparable(next));
+
+/**
+ * Folds the event and stamps the status time when the result is worth publishing.
+ * @returns the next status and whether observers should be notified.
+ */
+export const advance = (
+  prev: Status,
+  event: Event,
+  config: Config,
+): [Status, boolean] => {
+  const next = reduce(prev, event, config);
+  if (!materialChange(prev, next)) return [next, false];
+  return [{ ...next, time: TimeStamp.now() }, true];
+};

package/src/control/client.ts

@@ -7,23 +7,95 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { StateTracker } from "@/control/state";
-import { framer } from "@/framer";
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import { z } from "zod";
 
-export const CONTROL_STATE_CHANNEL_NAME = "sy_node_1_control";
+import { type channel } from "@/channel";
+import { keyZ } from "@/channel/types.gen";
+import { type KeyedState, keyedStateZ, updateZ } from "@/control/state";
+import { query } from "@/query";
 
-export class Client {
-  private readonly framer: framer.Client;
+/** The free virtual channel carrying control updates for the entire cluster. */
+const CHANNEL_NAME = "sy_control";
 
-  constructor(framer: framer.Client) {
-    this.framer = framer;
+const RETRIEVE_ENDPOINT = "/control/retrieve";
+
+const retrieveRequestZ = z.object({ keys: keyZ.array().optional() });
+const retrieveMultiParamsZ = retrieveRequestZ.or(query.keyListZ(keyZ));
+const retrieveResZ = z.object({ states: keyedStateZ.array().default(() => []) });
+
+export type RetrieveMultipleParams = z.input<typeof retrieveRequestZ>;
+
+interface RetrieveRequest extends z.infer<typeof retrieveRequestZ> {}
+
+export interface ClientConfig {
+  unary: UnaryClient;
+  cache: query.Cache;
+}
+
+/**
+ * Reads the control state of channels across the cluster. A channel is in the table
+ * exactly while a subject holds it, so absence is the uncontrolled state: a release
+ * deletes the entry instead of storing a sentinel.
+ */
+export class Client extends query.Retriever<
+  typeof retrieveMultiParamsZ,
+  channel.Key,
+  KeyedState
+> {
+  readonly type: string = "control";
+  /** The control state table, keyed by the channel under control. */
+  readonly store: query.Table<channel.Key, KeyedState>;
+  private readonly cfg: ClientConfig;
+
+  constructor(cfg: ClientConfig) {
+    const store = cfg.cache.createTable<channel.Key, KeyedState>({
+      name: "control",
+      fetch: async (keys) => await this.execRetrieve({ keys }),
+      listen: [transferListener()],
+    });
+    super(cfg.cache, {
+      name: "control",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) => await this.execRetrieve(req),
+        matches: (state, req) => req.keys == null || req.keys.includes(state.key),
+      },
+    });
+    this.cfg = cfg;
+    this.store = store;
   }
 
-  async openStateTracker(): Promise<StateTracker> {
-    const stream = await framer.HardenedStreamer.open(
-      async (p) => await this.framer.openStreamer(p),
-      CONTROL_STATE_CHANNEL_NAME,
+  private async execRetrieve(req: RetrieveRequest): Promise<KeyedState[]> {
+    // An empty key set reads the whole cluster, so it must not reach the Core here.
+    if (req.keys != null && req.keys.length === 0) return [];
+    const { states } = await this.cfg.unary.send(
+      RETRIEVE_ENDPOINT,
+      { keys: req.keys ?? [] },
+      retrieveRequestZ,
+      retrieveResZ,
     );
-    return new StateTracker(stream);
+    return states;
   }
 }
+
+/**
+ * Mirrors the cluster's control transfers into the table: the `to` end of a transfer
+ * sets the channel's holder, and a transfer without one deletes the entry.
+ */
+const transferListener = (): query.ListenerSpec<channel.Key, KeyedState> => ({
+  bind: (table): query.Listener<typeof updateZ> => ({
+    channel: CHANNEL_NAME,
+    schema: updateZ,
+    onChange: (updates) =>
+      table.batch(() =>
+        updates
+          .flatMap((u) => u.transfers)
+          .forEach(({ from, to }) => {
+            if (to == null) table.delete(from.resource);
+            else table.set({ key: to.resource, ...to });
+          }),
+      ),
+  }),
+});

package/src/control/state.ts

@@ -7,21 +7,35 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { binary, control, type observe } from "@synnaxlabs/x";
+import { control } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { type channel } from "@/channel";
 import { keyZ } from "@/channel/types.gen";
-import { framer } from "@/framer";
 
+/** How strongly a writer claims a channel. The highest authority holds control. */
 export type Authority = control.Authority;
+/** The highest authority. A writer holding it cannot be displaced. */
 export const ABSOLUTE_AUTHORITY = control.ABSOLUTE_AUTHORITY;
+/** The lowest authority. Any other writer displaces it. */
 export const ZERO_AUTHORITY = control.ZERO_AUTHORITY;
+/** Control of one channel moving between writers, or being released. */
 export type Transfer = control.Transfer<typeof channel.keyZ>;
+/** Who holds control of a channel, and at what authority. */
 export interface State extends control.State<typeof channel.keyZ> {}
+/** A named party that can hold control. */
 export interface Subject extends control.Subject {}
+/** Zod schema for {@link State}. */
 export const stateZ = control.stateZ(z.number());
 
+/**
+ * A control state stored under the channel it controls, which is how the client caches
+ * it.
+ */
+export const keyedStateZ = stateZ.transform((s) => ({ key: s.resource, ...s }));
+export interface KeyedState extends z.infer<typeof keyedStateZ> {}
+
+/** Renders a {@link Transfer} as readable text, for logs and status messages. */
 export const transferString = (t: Transfer): string => {
   const fromResource = t.from?.resource;
   const toResource = t.to?.resource;
@@ -35,41 +49,8 @@ export const transferString = (t: Transfer): string => {
   } (${t.to.authority.toString()})`;
 };
 
-const updateZ = z.object({
+export const updateZ = z.object({
   transfers: z.array(control.transferZ(keyZ)),
 });
 
 export interface Update extends z.infer<typeof updateZ> {}
-
-export class StateTracker
-  extends framer.ObservableStreamer<Transfer[]>
-  implements observe.ObservableAsyncCloseable<Transfer[]>
-{
-  readonly states: Map<channel.Key, State>;
-  private readonly codec: binary.JSONCodec;
-
-  constructor(streamer: framer.Streamer) {
-    super(streamer, (frame) => {
-      const raw = Array.from(frame.series[0].as("string"));
-      const updates: Update[] = raw.map((r) => this.codec.decodeString(r, updateZ));
-      updates.forEach((u) => this.merge(u));
-      return [updates.flatMap((u) => u.transfers), true];
-    });
-    this.states = new Map();
-    this.codec = new binary.JSONCodec();
-  }
-
-  subjects(): Subject[] {
-    const subjects = new Map<string, Subject>();
-    this.states.forEach((s) => subjects.set(s.subject.key, s.subject));
-    return Array.from(subjects.values());
-  }
-
-  private merge(update: Update): void {
-    update.transfers.forEach((t) => {
-      if (t.from == null && t.to == null) console.warn("Invalid transfer: ", t);
-      if (t.to == null) this.states.delete(t.from.resource);
-      else this.states.set(t.to.resource, t.to);
-    });
-  }
-}