@synnaxlabs/client 0.57.1 → 0.57.3

package/src/ranger/client.ts

@@ -288,6 +288,21 @@ const retrieveMultiParamsZ = retrieveRequestZ
 
 const retrieveResZ = z.object({ ranges: payloadZ.array().default(() => []) });
 
+/** Request addressing a page of a range's children, in relationship-key order. */
+export type ChildrenRequest = {
+  key: Key;
+  limit?: number;
+  offset?: number;
+};
+
+/** Params addressing a range's children. A bare key addresses all of them. */
+export type ChildrenParams = Key | ChildrenRequest;
+
+const CHILDREN_SERVER_FIELDS = ["limit", "offset"] as const;
+
+const normalizeChildren = (params: ChildrenParams): ChildrenRequest =>
+  typeof params === "string" ? { key: params } : params;
+
 /** The base flags applied to every composed range fetch. */
 const BASE_REQUEST: Partial<RetrieveRequest> = {
   includeLabels: true,
@@ -340,16 +355,13 @@ const watchRelationships = <Q extends query.Params>(
     affectedRangeKeys(relOfEvent(event)),
   );
 
-const rangesWithLabel = (
-  relationships: query.Table<string, ontology.Relationship>,
-  key: label.Key,
-): Key[] | null => {
-  const keys = relationships
-    .get(
+const rangesWithLabel = (cache: ontology.Cache, key: label.Key): Key[] | null => {
+  const keys = cache
+    .relationshipsTo(label.ontologyID(key))
+    .filter(
       (r) =>
         r.type === label.LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE &&
-        r.from.type === "range" &&
-        r.to.key === key,
+        r.from.type === "range",
     )
     .map((r) => r.from.key);
   return keys.length === 0 ? null : keys;
@@ -358,10 +370,10 @@ const rangesWithLabel = (
 /** Projects label content changes onto the ranges they label. */
 const watchLabels = <Q extends query.Params>(
   labels: query.Table<label.Key, label.Label>,
-  relationships: query.Table<string, ontology.Relationship>,
+  cache: ontology.Cache,
 ): query.Watch<Q, Key> =>
   query.watch<Q, Key, label.Key, label.Label>(labels, (event) =>
-    rangesWithLabel(relationships, event.key),
+    rangesWithLabel(cache, event.key),
   );
 
 /** Config for {@link Client}. */
@@ -389,7 +401,7 @@ export class Client extends query.Retriever<
   /** The range alias table; injected into sibling clients at wiring. */
   readonly aliases: query.Table<string, alias.Alias>;
   /** Cached queries for the children of a range, keyed by the parent's key. */
-  readonly children: query.Retrieves<Key, Range[]>;
+  readonly children: query.Retrieves<ChildrenParams, Range[]>;
   /**
    * Cached queries for the closest range parent of a resource, keyed by the
    * child's ontology ID.
@@ -422,7 +434,9 @@ export class Client extends query.Retriever<
         query.deriveWatch(relationships, (event) =>
           affectedRangeKeys(relOfEvent(event)),
         ),
-        query.deriveWatch(labels, (event) => rangesWithLabel(relationships, event.key)),
+        query.deriveWatch(labels, (event) =>
+          rangesWithLabel(ontologyClient.cache, event.key),
+        ),
       ],
     });
     const single = cache.queries<Key | Name, Range, Key, Range>({
@@ -443,7 +457,7 @@ export class Client extends query.Retriever<
         matches: (r, query) => this.requestMatches(r, query),
         watch: [
           watchRelationships<RetrieveRequest>(relationships),
-          watchLabels<RetrieveRequest>(labels, relationships),
+          watchLabels<RetrieveRequest>(labels, ontologyClient.cache),
         ],
       },
       compose: (r) => this.composeOne(r),
@@ -454,17 +468,27 @@ export class Client extends query.Retriever<
     this.store = ranges;
     this.kvPairs = kvPairs;
     this.aliases = aliases;
-    this.children = cache.queries<Key, Range[], Key, Range>({
+    const children = cache.queries<ChildrenRequest, Range[], Key, Range>({
       name: "child ranges",
       table: composed,
       fetch: async (query) => (await this.fetchChildren(query)).map((r) => r.key),
       compose: (records) => records,
       matches: (r, query) => {
         const parent = this.cfg.ontology.cache.parentID(ontologyID(r.key));
-        return parent != null && ontology.idsEqual(parent, ontologyID(query));
+        return parent != null && ontology.idsEqual(parent, ontologyID(query.key));
       },
-      watch: [watchRelationships<Key>(this.cfg.ontology.cache.relationships)],
+      serverFields: CHILDREN_SERVER_FIELDS,
+      watch: [
+        watchRelationships<ChildrenRequest>(this.cfg.ontology.cache.relationships),
+      ],
     });
+    this.children = {
+      retrieve: async (params, options) =>
+        await children.retrieve(normalizeChildren(params), options),
+      onChange: (params, handler) =>
+        children.onChange(normalizeChildren(params), handler),
+      getCached: (params) => children.getCached(normalizeChildren(params)),
+    };
     this.parent = cache.queries<ontology.ID, Range | null, Key, Range>({
       name: "parent range",
       table: composed,
@@ -597,7 +621,7 @@ export class Client extends query.Retriever<
   private composeOne(cached: Range): Range {
     const id = ontologyID(cached.key);
     const labels = label.cachedLabelsOf(
-      this.cfg.ontology.cache.relationships,
+      this.cfg.ontology.cache,
       this.cfg.labels.store,
       id,
     );
@@ -642,6 +666,17 @@ export class Client extends query.Retriever<
     }
   }
 
+  /** Writes a fetch response as one batch per table, so each table flushes once. */
+  private writeThroughMany(ranges: Range[]): void {
+    this.store.batch(() =>
+      this.cfg.labels.store.batch(() =>
+        this.cfg.ontology.cache.relationships.batch(() =>
+          ranges.forEach((r) => this.writeThrough(r)),
+        ),
+      ),
+    );
+  }
+
   /**
    * Fetches the given keys with labels and parents included, writing them and
    * their relationships through. Powers the table's fetch primitive.
@@ -652,15 +687,19 @@ export class Client extends query.Retriever<
       keys,
       ignoreNotFoundError: true,
     });
-    ranges.forEach((r) => this.writeThrough(r));
+    this.writeThroughMany(ranges);
     return ranges;
   }
 
   private async fetchSingle(query: Key | Name): Promise<Range> {
     const cached = this.store.get(query);
     if (cached != null) return this.composeOne(cached);
-    const req = keyZ.safeParse(query).success ? { keys: [query] } : { names: [query] };
-    const ranges = await this.execRetrieve({ ...BASE_REQUEST, ...req });
+    if (keyZ.safeParse(query).success) {
+      const ranges = await this.store.retrieve([query]);
+      checkForMultipleOrNoResults("Range", query, ranges, true);
+      return this.composeOne(ranges[0]);
+    }
+    const ranges = await this.execRetrieve({ ...BASE_REQUEST, names: [query] });
     checkForMultipleOrNoResults("Range", query, ranges, true);
     this.writeThrough(ranges[0]);
     return ranges[0];
@@ -686,7 +725,7 @@ export class Client extends query.Retriever<
   private async fetchRequest(query: RetrieveRequest): Promise<Range[]> {
     if (isKeysOnly(query)) return await this.store.retrieve(query.keys);
     const ranges = await this.execRetrieve({ ...BASE_REQUEST, ...query });
-    ranges.forEach((r) => this.writeThrough(r));
+    this.writeThroughMany(ranges);
     return ranges;
   }
 
@@ -701,7 +740,7 @@ export class Client extends query.Retriever<
       return false;
     if (primitive.isNonZero(req.hasLabels)) {
       const labels = label.cachedLabelsOf(
-        this.cfg.ontology.cache.relationships,
+        this.cfg.ontology.cache,
         this.cfg.labels.store,
         ontologyID(r.key),
       );
@@ -711,10 +750,12 @@ export class Client extends query.Retriever<
     return true;
   }
 
-  private async fetchChildren(query: Key): Promise<Range[]> {
+  private async fetchChildren(query: ChildrenRequest): Promise<Range[]> {
     const resources = await this.cfg.ontology.children.retrieve({
-      ids: ontologyID(query),
+      ids: ontologyID(query.key),
       types: ["range"],
+      limit: query.limit,
+      offset: query.offset,
     });
     if (resources.length === 0) return [];
     return await this.store.retrieve(resources.map(({ id: { key } }) => key));

package/src/status/client.ts

@@ -99,7 +99,7 @@ export class Client extends query.Retriever<
           value: (changed, prev) => {
             const next = { ...prev, ...changed };
             const id = ontologyID(changed.key);
-            next.labels = label.cachedLabelsOf(relationships, labels.store, id);
+            next.labels = label.cachedLabelsOf(ontologyClient.cache, labels.store, id);
             return next;
           },
         }),
@@ -278,7 +278,7 @@ export class Client extends query.Retriever<
   /** Rebuilds a cached status with its cached labels attached. */
   private compose(cached: Status): Status {
     const labels = label.cachedLabelsOf(
-      this.cfg.ontology.cache.relationships,
+      this.cfg.ontology.cache,
       this.cfg.labels.store,
       ontologyID(cached.key),
     );
@@ -307,14 +307,19 @@ export class Client extends query.Retriever<
   /** Fetches statuses and writes their included labels through the caches. */
   private async fetchThrough(req: RetrieveRequest): Promise<Status[]> {
     const statuses = await this.execRetrieve({ ...BASE_REQUEST, ...req });
-    statuses.forEach((s) => this.writeThrough(s));
+    // One batch per table, so each table flushes once for the whole response.
+    this.store.batch(() =>
+      this.cfg.labels.store.batch(() =>
+        this.cfg.ontology.cache.relationships.batch(() =>
+          statuses.forEach((s) => this.writeThrough(s)),
+        ),
+      ),
+    );
     return statuses;
   }
 
   private async fetchSingle(key: Key): Promise<Status> {
-    const cached = this.store.get(key);
-    if (cached != null) return cached;
-    const statuses = await this.fetchThrough({ keys: [key] });
+    const statuses = await this.store.retrieve([key]);
     checkForMultipleOrNoResults("Status", key, statuses, true);
     return statuses[0];
   }
@@ -362,13 +367,12 @@ export class Client extends query.Retriever<
 
   /** Returns the keys of cached statuses labeled by the given label. */
   private statusesLabeledBy(labelKey: label.Key): Key[] {
-    return this.cfg.ontology.cache.relationships
-      .get(
+    return this.cfg.ontology.cache
+      .relationshipsTo(label.ontologyID(labelKey))
+      .filter(
         (r) =>
           r.type === label.LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE &&
-          r.from.type === "status" &&
-          r.to.type === "label" &&
-          r.to.key === labelKey,
+          r.from.type === "status",
       )
       .map((r) => r.from.key);
   }

package/src/status/status.ts

@@ -192,6 +192,20 @@ export const removeVariants = (
   return remove === variant ? undefined : variant;
 };
 
+/** Rank of each variant by severity, most severe lowest. */
+const SEVERITY: Record<Variant, number> = {
+  error: 0,
+  warning: 1,
+  loading: 2,
+  success: 3,
+  info: 4,
+  disabled: 5,
+};
+
+/** @returns true when a is more severe than b. */
+export const moreSevere = (a: Variant, b: Variant): boolean =>
+  SEVERITY[a] < SEVERITY[b];
+
 /** Options for {@link toString}. */
 export interface ToStringOptions {
   includeTimestamp?: boolean;

package/src/task/client.ts

@@ -91,6 +91,12 @@ const COMMAND_DEADLINE = TimeSpan.seconds(10);
 
 const STATUS_NAME = "Task Status";
 
+/**
+ * The task status schema without a details-data schema. Hoisted because statusZ()
+ * builds a fresh schema per call, which costs far more than the parse itself.
+ */
+export const defaultStatusZ = statusZ();
+
 const retrieveSnapshottedTo = async (taskKey: Key, ontologyClient: ontology.Client) => {
   const parents = await ontologyClient.parents.retrieve({ ids: ontologyID(taskKey) });
   if (parents.length === 0) return null;
@@ -415,10 +421,14 @@ export class Client extends query.Retriever<
   /** The task record table; injected into sibling clients at wiring. */
   readonly store: query.Table<Key, Omit<Task, "status">>;
   private readonly cfg: ClientConfig;
+  private readonly statusesByTask: query.LookupIndex<status.Key, status.Status>;
   private readonly commandDeadlines = new Map<Key, ReturnType<typeof setTimeout>>();
 
   constructor(cfg: ClientConfig) {
     const { cache, statusStore } = cfg;
+    const statusesByTask = statusStore.index(
+      new query.LookupIndex<status.Key, status.Status>(statusTaskKey),
+    );
     const store = cache.createTable<Key, Omit<Task, "status">>({
       name: "tasks",
       equal: (a, b) => deep.equal(a.payload, b.payload),
@@ -458,7 +468,9 @@ export class Client extends query.Retriever<
           commands.forEach((changed) => {
             if (!LOADING_COMMANDS.includes(changed.type)) return;
             const key = statusKey(changed.task);
-            if (statusStore.get(key) == null) return;
+            // Commands reach every client, so one for a task this client neither
+            // tracks nor holds a status for is dropped.
+            if (store.get(changed.task) == null && statusStore.get(key) == null) return;
             const optimistic = this.optimisticStatus(changed);
             statusStore.set(key, optimistic);
             if (optimistic.variant === "loading")
@@ -471,7 +483,7 @@ export class Client extends query.Retriever<
       source: store,
       compose: (record) => this.compose(record),
       equal: (a, b) => deep.equal(a.payload, b.payload),
-      watch: [query.deriveWatch(statusStore, (event) => affectedTaskKeys(event))],
+      watch: [query.deriveWatch(statusStore, (event) => affectedKeys(event))],
     });
     const single = cache.queries<SingleRequest, Task, Key, Task>({
       name: "task",
@@ -489,13 +501,14 @@ export class Client extends query.Retriever<
         schema: retrieveMultiParamsZ,
         fetch: async (req) => await this.fetchThrough(req),
         matches: (t, req) => requestFilter(req)(t),
-        watch: [query.watch(statusStore, (event) => affectedTaskKeys(event))],
+        watch: [query.watch(statusStore, (event) => affectedKeys(event))],
       },
       compose: (record) => this.compose(record),
       single: { schema: singleQueryZ, space: single },
     });
     this.cfg = cfg;
     this.store = store;
+    this.statusesByTask = statusesByTask;
   }
 
   async create(task: New): Promise<Task>;
@@ -719,20 +732,25 @@ export class Client extends query.Retriever<
     );
   }
 
-  // A task's status may live under the "task:<key>" row or under any status
-  // whose details reference the task; the freshest wins. Rows are parsed
-  // because the status table holds every domain's statuses generically.
+  // A task's status may live under the "task:<key>" row or under any status whose
+  // details reference the task; the freshest wins, ties going to the more severe. Rows
+  // are parsed because the status table holds every domain's statuses generically.
   private latestStatusOf(key: Key): Status | undefined {
-    const taskKey = statusKey(key);
-    const candidates = this.cfg.statusStore
-      .get((s) => s.key === taskKey || status.detailsOf(s)?.task === key)
-      .map((s) => statusZ().safeParse(s))
+    const direct = this.cfg.statusStore.get(statusKey(key));
+    const rows = this.statusesByTask.get(key);
+    // A task status names its task in details too, so the index usually holds it.
+    if (direct != null && !rows.includes(direct)) rows.push(direct);
+    const candidates = rows
+      .map((s) => defaultStatusZ.safeParse(s))
       .filter((p) => p.success)
       .map((p) => p.data);
     if (candidates.length === 0) return undefined;
-    return candidates.reduce((latest, s) =>
-      new TimeStamp(s.time).afterEq(new TimeStamp(latest.time)) ? s : latest,
-    );
+    return candidates.reduce((latest, s) => {
+      const time = new TimeStamp(s.time);
+      const latestTime = new TimeStamp(latest.time);
+      if (!time.equals(latestTime)) return time.after(latestTime) ? s : latest;
+      return status.moreSevere(s.variant, latest.variant) ? s : latest;
+    });
   }
 
   /** Writes a fetched task and its included status. */
@@ -759,6 +777,12 @@ export class Client extends query.Retriever<
     // no status or the status may not have synced. Only both count as a hit.
     if (cached != null && this.cfg.statusStore.has(statusKey(cached.key)))
       return this.compose(cached);
+    if (primitive.isNonZero(q.keys)) {
+      // The refresh covers a cached task whose status has not synced.
+      const tasks = await this.store.retrieve(q.keys, { refresh: true });
+      checkForMultipleOrNoResults("Task", q, tasks, true);
+      return this.compose(tasks[0]);
+    }
     const tasks = await this.execRetrieve({ ...q, includeStatus: true });
     checkForMultipleOrNoResults("Task", q, tasks, true);
     this.writeThrough(tasks[0]);
@@ -866,17 +890,28 @@ export class Client extends query.Retriever<
 /** @returns the key of the status that reports on the given task. */
 export const statusKey = (key: Key): string => ontology.idToString(ontologyID(key));
 
-const taskStatusZ = z.object({ details: z.object({ task: keyZ }) });
+/**
+ * @returns the key of the task the status reports on, or null when it names none.
+ * Guarded before the key parse: most statuses in the table belong to other domains,
+ * and a failed zod parse costs orders of magnitude more than the miss is worth.
+ */
+const statusTaskKey = (s: status.Status): Key | null => {
+  const task = status.detailsOf(s)?.task;
+  if (typeof task !== "string") return null;
+  return keyZ.safeParse(task).success ? task : null;
+};
 
-// Task statuses may arrive under any status key; the referenced task lives in
-// the details, with the "task:<key>" status key as a fallback.
-const affectedTaskKeys = (
+/**
+ * @returns the keys of the tasks a status change affects, or null when none. A status
+ * names its task in `details.task`, with the "task:<key>" status key as a fallback.
+ */
+export const affectedKeys = (
   event: query.TableEvent<status.Key, status.Status>,
 ): Key[] | null => {
   const keys: Key[] = [];
   if (event.variant === "set") {
-    const parsed = taskStatusZ.safeParse(event.value);
-    if (parsed.success) keys.push(parsed.data.details.task);
+    const task = statusTaskKey(event.value);
+    if (task != null) keys.push(task);
   }
   const [type, key] = event.key.split(":");
   if (type === "task" && primitive.isNonZero(key) && !keys.includes(key))

package/src/testutil/client.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { TimeSpan } from "@synnaxlabs/x";
-import { afterAll } from "vitest";
+import { afterAll, vi } from "vitest";
 
 import Synnax, { type SynnaxParams } from "@/client";
 
@@ -50,3 +50,7 @@ export const createTestClient = (params?: Partial<SynnaxParams>): Synnax => {
   openClients.push(client);
   return client;
 };
+
+/** Spies on the client's unary send so specs can count requests on the wire. */
+export const spyOnSend = (client: Synnax, field: "transport" = "transport") =>
+  vi.spyOn(client[field].unary, "send");

package/src/testutil/proxy.ts

@@ -35,12 +35,27 @@ export interface SeverableProxy {
   port: number;
   /** Drops every live connection and refuses new ones, as if the cluster died. */
   sever: () => Promise<void>;
+  /**
+   * Silently kills every live WebSocket connection, modeling a half-open socket (NAT
+   * timeout, VPN drop, laptop sleep): the cluster side is destroyed while the client
+   * side is held open with its writes discarded, so no close or reset ever reaches the
+   * client. New connections still forward. Returns how many connections were
+   * blackholed.
+   */
+  blackholeStreams: () => number;
   /** Accepts connections again on the same port. */
   restore: () => Promise<void>;
   /** Shuts the proxy down for good. */
   close: () => Promise<void>;
 }
 
+interface ProxiedPair {
+  downstream: Socket;
+  upstream: Socket;
+  /** Whether a WebSocket upgrade was observed on this connection. */
+  ws: boolean;
+}
+
 /**
  * Creates a TCP proxy in front of the live test cluster so specs can simulate
  * cluster downtime without touching the cluster itself. Connect a client to
@@ -50,7 +65,10 @@ export const createSeverableProxy = async (
   target: SeverableProxyTarget = {},
 ): Promise<SeverableProxy> => {
   const { host, port } = { ...DEFAULT_TARGET, ...target };
-  const sockets = new Set<Socket>();
+  const pairs = new Set<ProxiedPair>();
+  // Client-side sockets of blackholed connections: held open, silent, until the proxy
+  // is severed or closed.
+  const zombies = new Set<Socket>();
   let severed = false;
   const server = createServer((downstream) => {
     // A connection the kernel accepted before the sever is still delivered after it,
@@ -60,10 +78,16 @@ export const createSeverableProxy = async (
       return;
     }
     const upstream = connect(port, host);
-    sockets.add(downstream).add(upstream);
+    const pair: ProxiedPair = { downstream, upstream, ws: false };
+    pairs.add(pair);
+    // The upgrade can arrive on any request of a pooled keep-alive connection, not just
+    // the first, so every chunk is sniffed until one is seen.
+    downstream.on("data", (chunk: Buffer) => {
+      if (!pair.ws && /upgrade:\s*websocket/i.test(chunk.toString("latin1")))
+        pair.ws = true;
+    });
     const destroy = (): void => {
-      sockets.delete(downstream);
-      sockets.delete(upstream);
+      pairs.delete(pair);
       downstream.destroy();
       upstream.destroy();
     };
@@ -90,13 +114,42 @@ export const createSeverableProxy = async (
   const sever = async (): Promise<void> => {
     severed = true;
     const closed = new Promise<void>((resolve) => server.close(() => resolve()));
-    sockets.forEach((socket) => socket.destroy());
-    sockets.clear();
+    pairs.forEach(({ downstream, upstream }) => {
+      downstream.destroy();
+      upstream.destroy();
+    });
+    pairs.clear();
+    zombies.forEach((socket) => socket.destroy());
+    zombies.clear();
     await closed;
   };
+  const blackholeStreams = (): number => {
+    let count = 0;
+    for (const pair of [...pairs]) {
+      if (!pair.ws) continue;
+      count += 1;
+      const { downstream, upstream } = pair;
+      downstream.unpipe(upstream);
+      upstream.unpipe(downstream);
+      for (const socket of [downstream, upstream]) {
+        socket.removeAllListeners("close");
+        socket.removeAllListeners("error");
+        socket.on("error", () => {});
+      }
+      // Discard anything the client still writes so backpressure cannot close the
+      // socket on the proxy's behalf.
+      downstream.on("data", () => {});
+      downstream.resume();
+      upstream.destroy();
+      pairs.delete(pair);
+      zombies.add(downstream);
+    }
+    return count;
+  };
   return {
     port: boundPort,
     sever,
+    blackholeStreams,
     restore: async () => {
       severed = false;
       await listen(boundPort);