@synnaxlabs/client 0.56.2 → 0.57.1

package/src/query/write.ts

@@ -0,0 +1,42 @@
+// 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 { destructor } from "@synnaxlabs/x";
+
+export interface OptimisticParams<R> {
+  /**
+   * Rollbacks for the already-applied optimistic cache changes, run in
+   * reverse order when commit fails.
+   */
+  rollbacks: destructor.Destructor[];
+  /**
+   * Notified after the rollbacks are captured and before commit runs. Value-bearing
+   * writes close over their optimistic value: `() => opts.onOptimistic?.(value)`.
+   */
+  onOptimistic?: () => Promise<void> | void;
+  /** The network send. Its result is returned when it succeeds. */
+  commit: () => Promise<R>;
+}
+
+/**
+ * Runs an optimistic write. When commit or `onOptimistic` fails the rollbacks
+ * run and the error rethrows; on success the cache keeps the optimistic state.
+ */
+export const optimistic = async <R>({
+  rollbacks,
+  onOptimistic,
+  commit,
+}: OptimisticParams<R>): Promise<R> => {
+  const rollback = new destructor.Chain();
+  rollback.add(...rollbacks);
+  return await rollback.guard(async () => {
+    await onOptimistic?.();
+    return await commit();
+  });
+};

package/src/rack/client.ts

@@ -8,10 +8,11 @@
 // included in the file licenses/APL.txt.
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
-import { array } from "@synnaxlabs/x";
+import { array, deep, primitive } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ontology } from "@/ontology";
+import { query } from "@/query";
 import {
   type Key,
   keyZ,
@@ -21,7 +22,9 @@ import {
   type Payload,
   payloadZ,
   type Status,
+  statusZ,
 } from "@/rack/types.gen";
+import { type status } from "@/status";
 import { type task } from "@/task";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
@@ -39,10 +42,11 @@ const retrieveReqZ = z.object({
   offset: z.int().optional(),
   includeStatus: z.boolean().optional(),
 });
-const retrieveResZ = z.object({ racks: array.nullishToEmpty(payloadZ) });
+const retrieveMultiParamsZ = retrieveReqZ.or(query.keyListZ(keyZ));
+const retrieveResZ = z.object({ racks: payloadZ.array().default(() => []) });
 export const rackZ = payloadZ;
 
-const singleRetrieveArgsZ = z.union([
+const singleRetrieveParamsZ = z.union([
   z
     .object({
       key: keyZ,
@@ -56,15 +60,20 @@ const singleRetrieveArgsZ = z.union([
     })
     .transform(({ name, includeStatus }) => ({ names: [name], includeStatus })),
 ]);
-export type RetrieveSingleParams = z.input<typeof singleRetrieveArgsZ>;
+export type RetrieveSingleParams = z.input<typeof singleRetrieveParamsZ>;
 
-const multiRetrieveArgsZ = retrieveReqZ;
+const multiRetrieveParamsZ = retrieveReqZ;
 
-export type RetrieveMultipleParams = z.input<typeof multiRetrieveArgsZ>;
+export type RetrieveMultipleParams = z.input<typeof multiRetrieveParamsZ>;
 
-const retrieveArgsZ = z.union([singleRetrieveArgsZ, multiRetrieveArgsZ]);
+const retrieveParamsZ = z.union([singleRetrieveParamsZ, multiRetrieveParamsZ]);
 
-export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
+export type RetrieveParams = z.input<typeof retrieveParamsZ>;
+
+interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
+
+type SingleQuery =
+  { key: Key; includeStatus?: boolean } | { name: string; includeStatus?: boolean };
 
 const createReqZ = z.object({ racks: newZ.array() });
 const createResZ = z.object({ racks: payloadZ.array() });
@@ -72,53 +81,178 @@ const createResZ = z.object({ racks: payloadZ.array() });
 const deleteReqZ = z.object({ keys: keyZ.array() });
 const deleteResZ = z.object({});
 
-export class Client {
-  private readonly client: UnaryClient;
-  private readonly tasks: task.Client;
+/** Query fields only the server can evaluate. */
+const SERVER_FIELDS = ["searchTerm", "limit", "offset", "hostIsNode"] as const;
 
-  constructor(client: UnaryClient, taskClient: task.Client) {
-    this.client = client;
-    this.tasks = taskClient;
+/** Drops includeStatus when unset so equivalent queries hash identically. */
+const normalizeSingle = (params: RetrieveSingleParams): SingleQuery => {
+  const base = "key" in params ? { key: params.key } : { name: params.name };
+  return params.includeStatus === true ? { ...base, includeStatus: true } : base;
+};
+
+const singleQueryZ = z
+  .union([
+    z.strictObject({ key: keyZ, includeStatus: z.boolean().optional() }),
+    z.strictObject({ name: z.string(), includeStatus: z.boolean().optional() }),
+    keyZ.transform((key) => ({ key })),
+  ])
+  .transform(normalizeSingle);
+
+/** The table never holds statuses; the status table is their single home. */
+const stripStatus = ({ status: _, ...rack }: Payload): Omit<Payload, "status"> => rack;
+
+/**
+ * Client-side matching for a request: key and name sets and payload-held
+ * flags. Server-computed shapes (search, pagination, host resolution) never
+ * reach this filter; they refetch instead.
+ */
+const requestFilter = (
+  req: RetrieveRequest,
+): ((r: Omit<Payload, "status">) => boolean) => {
+  const keySet = primitive.isNonZero(req.keys) ? new Set(req.keys) : undefined;
+  const nameSet = primitive.isNonZero(req.names) ? new Set(req.names) : undefined;
+  return (r) => {
+    if (keySet != null && !keySet.has(r.key)) return false;
+    if (nameSet != null && !nameSet.has(r.name)) return false;
+    if (req.integration != null && !r.integrations.includes(req.integration))
+      return false;
+    if (req.embedded != null && r.embedded !== req.embedded) return false;
+    return true;
+  };
+};
+
+// Rack statuses live in the status table under the "rack:<key>" status key.
+const affectedRackKeys = (
+  event: query.TableEvent<status.Key, status.Status>,
+): Key[] | null => {
+  const [type, key] = event.key.split(":");
+  if (type !== "rack") return null;
+  const parsed = keyZ.safeParse(Number(key));
+  return parsed.success ? [parsed.data] : null;
+};
+
+export interface ClientConfig {
+  unary: UnaryClient;
+  tasks: task.Client;
+  cache: query.Cache;
+  statusStore: query.Table<status.Key, status.Status>;
+  ontology: ontology.Client;
+}
+
+export class Client extends query.Retriever<
+  typeof retrieveMultiParamsZ,
+  Key,
+  Omit<Payload, "status">,
+  Rack,
+  RetrieveSingleParams,
+  SingleQuery
+> {
+  private readonly cfg: ClientConfig;
+  private readonly store: query.Table<Key, Omit<Payload, "status">>;
+
+  constructor(cfg: ClientConfig) {
+    const { cache, statusStore } = cfg;
+    const store = cache.createTable<Key, Omit<Payload, "status">>({
+      name: "racks",
+      fetch: async (keys) => (await this.fetchThrough({ keys })).map(stripStatus),
+      listen: [
+        query.createSetListener(SET_CHANNEL_NAME, payloadZ, {
+          value: ({ status: _, ...rack }) => rack,
+        }),
+        query.createDeleteListener(DELETE_CHANNEL_NAME, keyZ),
+      ],
+    });
+    // Composed rows always carry status; includeStatus only gates fetch flags.
+    const composed = cache.derive<Key, Omit<Payload, "status">, Rack>({
+      name: "rack.composed",
+      source: store,
+      compose: (record) => this.compose(record, true),
+      equal: (a, b) => deep.equal(a.payload, b.payload),
+      watch: [query.deriveWatch(statusStore, (event) => affectedRackKeys(event))],
+    });
+    const single = cache.queries<SingleQuery, Rack, Key, Rack>({
+      name: "rack",
+      table: composed,
+      fetch: async (q) => [(await this.fetchSingle(q)).key],
+      compose: (records) => records[0],
+      keyOf: (q) => ("key" in q ? q.key : null),
+      matches: (r, q) => ("key" in q ? r.key === q.key : r.name === q.name),
+      single: true,
+    });
+    super(cache, {
+      name: "rack",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) => (await this.fetchThrough(req)).map(stripStatus),
+        matches: (r, req) => requestFilter(req)(r),
+        serverFields: SERVER_FIELDS,
+        watch: [
+          query.watch(statusStore, (event, q: RetrieveRequest) => {
+            if (q.includeStatus !== true) return null;
+            return affectedRackKeys(event);
+          }),
+        ],
+      },
+      compose: (record, q) =>
+        this.compose(record, (q as { includeStatus?: boolean }).includeStatus === true),
+      single: { schema: singleQueryZ, space: single },
+    });
+    this.cfg = cfg;
+    this.store = store;
   }
 
-  async delete(keys: Key | Key[]): Promise<void> {
-    await this.client.send(
-      "/rack/delete",
-      { keys: array.toArray(keys) },
-      deleteReqZ,
-      deleteResZ,
-    );
+  async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
+    const keysArr = array.toArray(keys);
+    const drop = () => [
+      this.cfg.ontology.cache.deleteResources(ontologyID(keysArr)),
+      this.store.delete(keysArr),
+    ];
+    await query.optimistic({
+      rollbacks: drop(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/rack/delete",
+          { keys: keysArr },
+          deleteReqZ,
+          deleteResZ,
+        ),
+    });
+    drop();
+  }
+
+  async rename(key: Key, name: string, opts: query.WriteOptions = {}): Promise<void> {
+    const rename = () => [
+      query.partialUpdate(this.store, key, { name }),
+      this.cfg.ontology.cache.renameResource(ontologyID(key), name),
+    ];
+    await query.optimistic({
+      rollbacks: rename(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () => {
+        const r = await this.retrieve(key);
+        await this.create({ ...r.payload, name });
+      },
+    });
+    rename();
   }
 
   async create(rack: New): Promise<Rack>;
   async create(racks: New[]): Promise<Rack[]>;
   async create(rack: New | New[]): Promise<Rack | Rack[]> {
     const isSingle = !Array.isArray(rack);
-    const res = await this.client.send(
+    const res = await this.cfg.unary.send(
       "/rack/create",
       { racks: array.toArray(rack) },
       createReqZ,
       createResZ,
     );
+    this.store.set(res.racks.map(stripStatus));
     const sugared = this.sugar(res.racks);
     return isSingle ? sugared[0] : sugared;
   }
 
-  async retrieve(args: RetrieveSingleParams): Promise<Rack>;
-  async retrieve(args: RetrieveMultipleParams): Promise<Rack[]>;
-  async retrieve(args: RetrieveArgs): Promise<Rack | Rack[]> {
-    const isSingle = "key" in args || "name" in args;
-    const res = await this.client.send(
-      "/rack/retrieve",
-      args,
-      retrieveArgsZ,
-      retrieveResZ,
-    );
-    const sugared = this.sugar(res.racks);
-    checkForMultipleOrNoResults("Rack", args, sugared, isSingle);
-    return isSingle ? sugared[0] : sugared;
-  }
-
   sugar(payload: Payload): Rack;
   sugar(payloads: Payload[]): Rack[];
   sugar(payloads: Payload | Payload[]): Rack | Rack[] {
@@ -126,18 +260,72 @@ export class Client {
     const sugared = array
       .toArray(payloads)
       .map(
-        ({ key, name, status, integrations }) =>
-          new Rack(key, name, this.tasks, status, integrations),
+        ({ key, name, status, integrations, embedded }) =>
+          new Rack(key, name, this.cfg.tasks, status, integrations, embedded),
       );
     return isSingle ? sugared[0] : sugared;
   }
+
+  /** Rebuilds a cached rack, attaching its cached status when requested. */
+  private compose(cached: Omit<Payload, "status">, includeStatus: boolean): Rack {
+    if (!includeStatus) return this.sugar(cached);
+    const st = this.statusOf(cached.key);
+    if (st == null) return this.sugar(cached);
+    return this.sugar({ ...cached, status: st });
+  }
+
+  // Only the "rack:<key>" row is the rack's status. Task statuses name their rack in
+  // their details, and matching on that would let them take the rack's status over.
+  private statusOf(key: Key): Status | undefined {
+    const parsed = statusZ.safeParse(this.cfg.statusStore.get(statusKey(key)));
+    return parsed.success ? parsed.data : undefined;
+  }
+
+  /** Writes fetched racks and their included statuses. */
+  private writeThrough(racks: Payload[]): void {
+    this.store.set(racks.map(stripStatus));
+    racks.forEach(({ status: st }) => {
+      if (st != null) this.cfg.statusStore.set(st);
+    });
+  }
+
+  private async execRetrieve(params: RetrieveParams): Promise<Payload[]> {
+    const res = await this.cfg.unary.send(
+      "/rack/retrieve",
+      params,
+      retrieveParamsZ,
+      retrieveResZ,
+    );
+    return res.racks;
+  }
+
+  /** Fetches racks and writes their included statuses through the caches. */
+  private async fetchThrough(req: RetrieveRequest): Promise<Payload[]> {
+    const racks = await this.execRetrieve(req);
+    this.writeThrough(racks);
+    return racks;
+  }
+
+  private async fetchSingle(q: SingleQuery): Promise<Rack> {
+    // Names are not unique, so only key queries can be served from the table.
+    // A status-bearing hit needs both the record and its status cached.
+    if ("key" in q && q.includeStatus !== true) {
+      const cached = this.store.get(q.key);
+      if (cached != null) return this.sugar(cached);
+    }
+    const racks = await this.execRetrieve(q);
+    checkForMultipleOrNoResults("Rack", q, racks, true);
+    this.writeThrough(racks);
+    return this.sugar(racks[0]);
+  }
 }
 
 export class Rack {
   key: Key;
   name: string;
   status?: Status;
-  integrations?: string[];
+  integrations: string[];
+  embedded: boolean;
   private readonly tasks: task.Client;
 
   constructor(
@@ -145,13 +333,15 @@ export class Rack {
     name: string,
     taskClient: task.Client,
     status?: Status,
-    integrations?: string[],
+    integrations: string[] = [],
+    embedded: boolean = false,
   ) {
     this.key = key;
     this.name = name;
     this.tasks = taskClient;
     this.status = status;
     this.integrations = integrations;
+    this.embedded = embedded;
   }
 
   async listTasks(): Promise<task.Task[]> {
@@ -168,10 +358,7 @@ export class Rack {
     task: task.New<Schemas>,
     schemas?: Schemas,
   ): Promise<task.Task<Schemas>> {
-    task.key = (
-      (BigInt(this.key) << 32n) +
-      (BigInt(task.key ?? 0) & 0xffffffffn)
-    ).toString();
+    task.rack = this.key;
     return await this.tasks.create(task, schemas as Required<Schemas>);
   }
 
@@ -185,6 +372,7 @@ export class Rack {
       name: this.name,
       status: this.status,
       integrations: this.integrations,
+      embedded: this.embedded,
     };
   }
 }

package/src/rack/types.gen.ts

@@ -9,10 +9,10 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { status, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ontology } from "@/ontology";
+import { status } from "@/status";
 
 export const keyZ = z.uint32();
 export type Key = z.infer<typeof keyZ>;
@@ -29,33 +29,32 @@ export type Status = z.infer<typeof statusZ>;
 
 /**
  * Payload is a collection container for hardware devices and tasks running on a
- * specific cluster node. Racks serve as the integration point between the
- * Synnax server and physical hardware via the Driver system.
+ * specific Core. Racks are the integration point between the Core and physical hardware
+ * through the Driver.
  */
 export const payloadZ = z.object({
   /** key is the composite identifier for this rack. */
-  key: keyZ,
+  key: keyZ.refine((v) => v !== 0, "key is required"),
   /** name is a human-readable name for the rack. */
-  name: z.string().min(1, "Name is required"),
-  /** taskCounter is an internal counter used for generating unique local task keys. */
-  taskCounter: z.uint32().optional(),
+  name: z.string().min(1, "name is required"),
   /** embedded is true if this rack is embedded within the Synnax server process. */
-  embedded: z.boolean().optional(),
+  embedded: z.boolean().default(false),
   /** status is the current operational status of the rack. */
   status: statusZ.optional(),
   /**
-   * integrations is the list of hardware integrations this rack supports (e.g., "ni", "opc",
-   * "labjack"). An empty or nil list means the rack supports no integrations.
+   * integrations is the list of hardware integrations this rack supports (e.g., "ni",
+   * "opc", "labjack"). An empty or nil list means the rack supports no integrations.
    */
-  integrations: zod.nullToUndefined(z.string().array()),
+  integrations: z
+    .string()
+    .array()
+    .default(() => []),
 });
 export interface Payload extends z.infer<typeof payloadZ> {}
 
-export const newZ = payloadZ
-  .omit({ taskCounter: true, embedded: true, key: true })
-  .extend({
-    key: z.uint32().default(0),
-  });
+export const newZ = payloadZ.omit({ embedded: true, key: true }).extend({
+  key: keyZ.refine((v) => v !== 0, "key is required").default(0),
+});
 export interface New extends z.input<typeof newZ> {}
 
 export const ontologyID = ontology.createIDFactory<Key>("rack");

package/src/range/alias/types.gen.ts

@@ -15,9 +15,8 @@ import { channel } from "@/channel";
 import { ranger } from "@/ranger";
 
 /**
- * Alias associates a human-readable string alias with a channel within the
- * context of a specific range. Enables semantic naming of channels that varies by
- * range context.
+ * Alias associates a human-readable string alias with a channel within the context of a
+ * specific range. Enables semantic naming of channels that varies by range context.
  */
 export const aliasZ = z.object({
   /** range is the unique identifier of the range containing this alias. */