@synnaxlabs/client 0.27.0 → 0.29.0

package/package.json

@@ -1,10 +1,7 @@
 {
   "name": "@synnaxlabs/client",
-  "private": false,
-  "version": "0.27.0",
-  "type": "module",
-  "description": "The Client Library for Synnax",
-  "repository": "https://github.com/synnaxlabs/synnax/tree/main/client/ts",
+  "version": "0.29.0",
+  "description": "The Synnax Client Library",
   "keywords": [
     "synnax",
     "grpc",
@@ -15,29 +12,40 @@
     "telemetry",
     "control systems"
   ],
+  "homepage": "https://github.com/synnaxlabs/synnax/tree/main/client/ts",
+  "bugs": {
+    "url": "https://github.com/synnaxlabs/synnax/issues"
+  },
+  "license": "BUSL-1.1",
+  "main": "dist/client.cjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/synnaxlabs/synnax.git",
+    "directory": "client/ts"
+  },
   "dependencies": {
     "async-mutex": "^0.5.0",
     "zod": "3.23.8",
-    "@synnaxlabs/freighter": "0.27.0",
-    "@synnaxlabs/x": "0.27.0"
+    "@synnaxlabs/freighter": "0.29.0",
+    "@synnaxlabs/x": "0.29.0"
   },
   "devDependencies": {
-    "@types/node": "^22.2.0",
-    "@vitest/coverage-v8": "^2.0.5",
-    "eslint": "^9.9.0",
-    "typescript": "^5.5.4",
-    "vite": "5.4.0",
-    "vitest": "^2.0.5",
+    "@types/node": "^22.5.4",
+    "@vitest/coverage-v8": "^2.1.0",
+    "eslint": "^9.10.0",
+    "typescript": "^5.6.2",
+    "vite": "5.4.4",
+    "vitest": "^2.1.0",
     "@synnaxlabs/tsconfig": "0.0.2",
     "@synnaxlabs/vite-plugin": "0.0.1",
     "eslint-config-synnaxlabs": "0.0.1"
   },
   "peerDependencies": {
-    "zod": "^3.23.8"
+    "zod": "3.23.8"
   },
-  "main": "dist/client.cjs",
-  "module": "dist/client.js",
+  "type": "module",
   "types": "dist/index.d.ts",
+  "module": "dist/client.js",
   "scripts": {
     "build": "tsc --noEmit && vite build",
     "watch": "tsc --noEmit && vite build --watch",

package/src/channel/client.ts

@@ -53,7 +53,8 @@ interface CreateOptions {
  * instantiated directly, but instead created via the `.channels.create` or retrieved
  * via the `.channels.retrieve` method on a Synnax client.
  *
- * Please refer to the [Synnax documentation](https://docs.synnaxlabs.com) for detailed
+ * Please refer to the [Synnax
+ * documentation](https://docs.synnaxlabs.com/reference/concepts/channels) for detailed
  * information on what channels are and how to use them.
  */
 export class Channel {
@@ -228,13 +229,14 @@ export class Client implements AsyncTermSearcher<string, Key, Channel> {
    * @param rate - The rate of the channel. This only applies to fixed rate channels.
    * @param dataType - The data type for the samples stored in the channel.
    * @param index - The key of the index channel that this channel should be associated
-   * with. An 'index' channel is a channel that stores timestamps for other channels. Refer
-   * to the Synnax documentation (https://docs.synnaxlabs.com) for more information. The
-   * index channel must have already been created. This field does not need to be specified
-   * if the channel is an index channel, or the channel is a fixed rate channel. If this
-   * value is specified, the 'rate' parameter will be ignored.
-   * @param isIndex - Set to true if the channel is an index channel, and false otherwise.
-   * Index channels must have a data type of `DataType.TIMESTAMP`.
+   * with. An 'index' channel is a channel that stores timestamps for other channels.
+   * Refer to the Synnax documentation
+   * (https://docs.synnaxlabs.com/reference/concepts/channels) for more information. The
+   * index channel must have already been created. This field does not need to be
+   * specified if the channel is an index channel, or the channel is a fixed rate
+   * channel. If this value is specified, the 'rate' parameter will be ignored.
+   * @param isIndex - Set to true if the channel is an index channel, and false
+   * otherwise. Index channels must have a data type of `DataType.TIMESTAMP`.
    * @returns the created channel. {@see Channel}
    * @throws {ValidationError} if any of the parameters for creating the channel are
    * invalid.

package/src/channel/retriever.ts

@@ -267,9 +267,9 @@ export class DebouncedBatchRetriever implements Retriever {
 
 export const retrieveRequired = async (
   r: Retriever,
-  params: Params,
+  channels: Params,
 ): Promise<Payload[]> => {
-  const { normalized } = analyzeChannelParams(params);
+  const { normalized } = analyzeChannelParams(channels);
   const results = await r.retrieve(normalized);
   const notFound: KeyOrName[] = [];
   normalized.forEach((v) => {

package/src/client.ts

@@ -79,6 +79,11 @@ export default class Synnax extends framer.Client {
   static readonly connectivity = connection.Checker;
   private readonly transport: Transport;
 
+  /**
+   * The version of the client.
+   */
+  readonly clientVersion: string = __VERSION__;
+
   /**
    * @param props.host - Hostname of a node in the cluster.
    * @param props.port - Port of the node in the cluster.
@@ -101,10 +106,7 @@ export default class Synnax extends framer.Client {
     transport.use(errorsMiddleware);
     let auth_: auth.Client | undefined;
     if (username != null && password != null) {
-      auth_ = new auth.Client(transport.unary, {
-        username,
-        password,
-      });
+      auth_ = new auth.Client(transport.unary, { username, password });
       transport.use(auth_.middleware());
     }
     const chRetriever = new channel.CacheRetriever(
@@ -120,6 +122,7 @@ export default class Synnax extends framer.Client {
     this.connectivity = new connection.Checker(
       transport.unary,
       connectivityPollFrequency,
+      this.clientVersion,
       props.name,
     );
     this.control = new control.Client(this);
@@ -138,7 +141,12 @@ export default class Synnax extends framer.Client {
     this.user = new user.Client(this.transport.unary);
     this.workspaces = new workspace.Client(this.transport.unary);
     const devices = new device.Client(this.transport.unary, this);
-    const tasks = new task.Client(this.transport.unary, this);
+    const tasks = new task.Client(
+      this.transport.unary,
+      this,
+      this.ontology,
+      this.ranges,
+    );
     const racks = new rack.Client(this.transport.unary, this, tasks);
     this.hardware = new hardware.Client(tasks, racks, devices);
   }

package/src/connection/checker.ts

@@ -8,6 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import type { UnaryClient } from "@synnaxlabs/freighter";
+import { migrate } from "@synnaxlabs/x";
 import { TimeSpan } from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
@@ -20,12 +21,16 @@ export const state = z.object({
   error: z.instanceof(Error).optional(),
   message: z.string().optional(),
   clusterKey: z.string(),
+  clientVersion: z.string(),
+  clientServerCompatible: z.boolean(),
+  nodeVersion: z.string().optional(),
 });
 
 export type State = z.infer<typeof state>;
 
 const responseZ = z.object({
   clusterKey: z.string(),
+  nodeVersion: z.string().optional(),
 });
 
 const DEFAULT: State = {
@@ -33,6 +38,19 @@ const DEFAULT: State = {
   status: "disconnected",
   error: undefined,
   message: "Disconnected",
+  clientServerCompatible: false,
+  clientVersion: __VERSION__,
+};
+
+const generateWarning = (
+  nodeVersion: string | null,
+  clientVersion: string,
+  clientIsNewer: boolean,
+): string => {
+  const toUpgrade = clientIsNewer ? "cluster" : "client";
+  return `Synnax cluster node version ${nodeVersion != null ? nodeVersion + " " : ""}is too ${clientIsNewer ? "old" : "new"} for client version ${clientVersion}.
+  This may cause compatibility issues. We recommend updating the ${toUpgrade}. For more information, see
+  https://docs.synnaxlabs.com/reference/typescript-client/troubleshooting#old-${toUpgrade}-version`;
 };
 
 /** Polls a synnax cluster for connectivity information. */
@@ -44,8 +62,10 @@ export class Checker {
   private readonly client: UnaryClient;
   private readonly name?: string;
   private interval?: NodeJS.Timeout;
+  private readonly clientVersion: string;
   private readonly onChangeHandlers: Array<(state: State) => void> = [];
   static readonly connectionStateZ = state;
+  private versionWarned = false;
 
   /**
    * @param client - The transport client to use for connectivity checks.
@@ -55,11 +75,13 @@ export class Checker {
   constructor(
     client: UnaryClient,
     pollFreq: TimeSpan = TimeSpan.seconds(30),
+    clientVersion: string,
     name?: string,
   ) {
     this._state = { ...DEFAULT };
     this.client = client;
     this.pollFrequency = pollFreq;
+    this.clientVersion = clientVersion;
     this.name = name;
     void this.check();
     this.startChecking();
@@ -77,11 +99,46 @@ export class Checker {
   async check(): Promise<State> {
     const prevStatus = this._state.status;
     try {
-      const [res, err] = await this.client.send(Checker.ENDPOINT, {}, z.object({}), responseZ);
+      const [res, err] = await this.client.send(
+        Checker.ENDPOINT,
+        {},
+        z.object({}),
+        responseZ,
+      );
       if (err != null) throw err;
+      const nodeVersion = res.nodeVersion;
+      const clientVersion = this.clientVersion;
+      const warned = this.versionWarned;
+      if (nodeVersion == null) {
+        this._state.clientServerCompatible = false;
+        if (!warned) {
+          console.warn(generateWarning(null, clientVersion, true));
+          this.versionWarned = true;
+        }
+      } else if (
+        !migrate.versionsEqual(clientVersion, nodeVersion, {
+          checkMajor: true,
+          checkMinor: true,
+          checkPatch: false,
+        })
+      ) {
+        this._state.clientServerCompatible = false;
+        if (!warned) {
+          console.warn(
+            generateWarning(
+              nodeVersion,
+              clientVersion,
+              migrate.semVerNewer(clientVersion, nodeVersion),
+            ),
+          );
+          this.versionWarned = true;
+        }
+      } else this._state.clientServerCompatible = true;
       this._state.status = "connected";
       this._state.message = `Connected to ${this.name ?? "cluster"}`;
       this._state.clusterKey = res.clusterKey;
+      this._state.nodeVersion = res.nodeVersion;
+      this._state.clientVersion = this.clientVersion;
     } catch (err) {
       this._state.status = "failed";
       this._state.error = err as Error;

package/src/connection/connection.spec.ts

@@ -9,6 +9,7 @@
 
 import { URL } from "@synnaxlabs/x/url";
 import { describe, expect, it } from "vitest";
+import { z } from "zod";
 
 import { auth } from "@/auth";
 import { Checker } from "@/connection/checker";
@@ -23,8 +24,47 @@ describe("connectivity", () => {
       password: "seldon",
     });
     transport.use(client.middleware());
-    const connectivity = new Checker(transport.unary);
-    await connectivity.check();
-    expect(connectivity.state.status).toEqual("connected");
+    const connectivity = new Checker(transport.unary, undefined, __VERSION__);
+    const state = await connectivity.check();
+    expect(state.status).toEqual("connected");
+    expect(z.string().uuid().safeParse(state.clusterKey).success).toBe(true);
+  });
+  describe("version compatibility", () => {
+    it("should pull the server and client versions", async () => {
+      const transport = new Transport(new URL({ host: HOST, port: PORT }));
+      const client = new auth.Client(transport.unary, {
+        username: "synnax",
+        password: "seldon",
+      });
+      transport.use(client.middleware());
+      const connectivity = new Checker(transport.unary, undefined, __VERSION__);
+      const state = await connectivity.check();
+      expect(state.clientServerCompatible).toBe(true);
+      expect(state.clientVersion).toBe(__VERSION__);
+    });
+    it("should adjust state if the server is too old", async () => {
+      const transport = new Transport(new URL({ host: HOST, port: PORT }));
+      const client = new auth.Client(transport.unary, {
+        username: "synnax",
+        password: "seldon",
+      });
+      transport.use(client.middleware());
+      const connectivity = new Checker(transport.unary, undefined, "50000.0.0");
+      const state = await connectivity.check();
+      expect(state.clientServerCompatible).toBe(false);
+      expect(state.clientVersion).toBe("50000.0.0");
+    });
+    it("should adjust state if the server is too new", async () => {
+      const transport = new Transport(new URL({ host: HOST, port: PORT }));
+      const client = new auth.Client(transport.unary, {
+        username: "synnax",
+        password: "seldon",
+      });
+      transport.use(client.middleware());
+      const connectivity = new Checker(transport.unary, undefined, "0.0.0");
+      const state = await connectivity.check();
+      expect(state.clientServerCompatible).toBe(false);
+      expect(state.clientVersion).toBe("0.0.0");
+    });
   });
 });

package/src/framer/client.ts

@@ -15,7 +15,6 @@ import {
   type MultiSeries,
   TimeRange,
   TimeSpan,
-  toArray,
 } from "@synnaxlabs/x";
 
 import { type Key, type KeyOrName, KeysOrNames, type Params } from "@/channel/payload";
@@ -170,8 +169,8 @@ export class Client {
     return fr;
   }
 
-  private async readFrame(tr: CrudeTimeRange, params: Params): Promise<Frame> {
-    const i = await this.openIterator(tr, params);
+  private async readFrame(tr: CrudeTimeRange, channels: Params): Promise<Frame> {
+    const i = await this.openIterator(tr, channels);
     const frame = new Frame();
     try {
       for await (const f of i) frame.push(f);

package/src/framer/streamer.spec.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { DataType, Rate, TimeStamp } from "@synnaxlabs/x/telem";
-import { describe, expect, it,test } from "vitest";
+import { describe, expect, it, test } from "vitest";
 
 import { type channel } from "@/channel";
 import { newClient } from "@/setupspecs";
@@ -42,12 +42,7 @@ describe("Streamer", () => {
   });
   test("open with config", async () => {
     const ch = await newChannel();
-    await expect(
-      client.openStreamer({
-        channels: ch.key,
-        from: TimeStamp.now(),
-      }),
-    ).resolves.not.toThrow();
+    await expect(client.openStreamer({ channels: ch.key })).resolves.not.toThrow();
   });
   it("should not throw an error when the streamer is opened with zero channels", async () => {
     await expect(client.openStreamer([])).resolves.not.toThrow();

package/src/framer/streamer.ts

@@ -9,7 +9,6 @@
 
 import { EOF, errorZ, type Stream, type StreamClient } from "@synnaxlabs/freighter";
 import { observe } from "@synnaxlabs/x";
-import { type CrudeTimeStamp, TimeStamp } from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
 import { type Key, type Params } from "@/channel/payload";
@@ -18,10 +17,7 @@ import { ReadFrameAdapter } from "@/framer/adapter";
 import { Frame, frameZ } from "@/framer/frame";
 import { StreamProxy } from "@/framer/streamProxy";
 
-const reqZ = z.object({
-  start: TimeStamp.z.optional(),
-  keys: z.number().array(),
-});
+const reqZ = z.object({ keys: z.number().array() });
 
 const resZ = z.object({
   frame: frameZ,
@@ -32,7 +28,6 @@ const ENDPOINT = "/frame/stream";
 
 export interface StreamerConfig {
   channels: Params;
-  from?: CrudeTimeStamp;
 }
 
 export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
@@ -54,12 +49,12 @@ export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
   static async _open(
     retriever: Retriever,
     client: StreamClient,
-    { channels, from }: StreamerConfig,
+    { channels }: StreamerConfig,
   ): Promise<Streamer> {
     const adapter = await ReadFrameAdapter.open(retriever, channels);
     const stream = await client.stream(ENDPOINT, reqZ, resZ);
     const streamer = new Streamer(stream, adapter);
-    stream.send({ start: new TimeStamp(from), keys: adapter.keys });
+    stream.send({ keys: adapter.keys });
     return streamer;
   }
 
@@ -77,8 +72,8 @@ export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
     return this.adapter.adapt(new Frame((await this.stream.receive()).frame));
   }
 
-  async update(params: Params): Promise<void> {
-    await this.adapter.update(params);
+  async update(channels: Params): Promise<void> {
+    await this.adapter.update(channels);
     this.stream.send({ keys: this.adapter.keys });
   }
 

package/src/hardware/rack/client.ts

@@ -127,9 +127,9 @@ export class Client implements AsyncTermSearcher<string, RackKey, Rack> {
   async retrieve(keys: number[] | RackKey[]): Promise<Rack[]>;
 
   async retrieve(
-    params: string | RackKey | string[] | RackKey[],
+    racks: string | RackKey | string[] | RackKey[],
   ): Promise<Rack | Rack[]> {
-    const { variant, normalized, single } = analyzeParams(params, {
+    const { variant, normalized, single } = analyzeParams(racks, {
       string: "names",
       number: "keys",
     });
@@ -141,7 +141,7 @@ export class Client implements AsyncTermSearcher<string, RackKey, Rack> {
       retrieveRackResZ,
     );
     const sugared = this.sugar(res.racks);
-    checkForMultipleOrNoResults("Rack", params, sugared, single);
+    checkForMultipleOrNoResults("Rack", racks, sugared, single);
     return single ? sugared[0] : sugared;
   }
 
@@ -186,4 +186,3 @@ export class Rack {
   }
 }
 export { rackKeyZ };
-

package/src/hardware/task/client.ts

@@ -18,7 +18,19 @@ import { z } from "zod";
 import { framer } from "@/framer";
 import { type Frame } from "@/framer/frame";
 import { rack } from "@/hardware/rack";
-import { NewTask, newTaskZ, Payload, State, StateObservable, stateZ, TaskKey, taskKeyZ, taskZ } from "@/hardware/task/payload";
+import {
+  NewTask,
+  newTaskZ,
+  Payload,
+  State,
+  StateObservable,
+  stateZ,
+  TaskKey,
+  taskKeyZ,
+  taskZ,
+} from "@/hardware/task/payload";
+import { ontology } from "@/ontology";
+import { ranger } from "@/ranger";
 import { signals } from "@/signals";
 import { analyzeParams, checkForMultipleOrNoResults } from "@/util/retrieve";
 import { nullableArrayZ } from "@/util/zod";
@@ -26,6 +38,8 @@ import { nullableArrayZ } from "@/util/zod";
 const TASK_STATE_CHANNEL = "sy_task_state";
 const TASK_CMD_CHANNEL = "sy_task_cmd";
 
+const TASK_NOT_CREATED = new Error("Task not created");
+
 export class Task<
   C extends UnknownRecord = UnknownRecord,
   D extends {} = UnknownRecord,
@@ -36,25 +50,34 @@ export class Task<
   readonly internal: boolean;
   readonly type: T;
   readonly config: C;
+  readonly snapshot: boolean;
   state?: State<D>;
-  private readonly frameClient: framer.Client;
+  private readonly frameClient: framer.Client | null;
+  private readonly ontologyClient: ontology.Client | null;
+  private readonly rangeClient: ranger.Client | null;
 
   constructor(
     key: TaskKey,
     name: string,
     type: T,
     config: C,
-    frameClient: framer.Client,
     internal: boolean = false,
+    snapshot: boolean = false,
     state?: State<D> | null,
+    frameClient: framer.Client | null = null,
+    ontologyClient: ontology.Client | null = null,
+    rangeClient: ranger.Client | null = null,
   ) {
     this.key = key;
     this.name = name;
     this.type = type;
     this.config = config;
     this.internal = internal;
+    this.snapshot = snapshot;
     if (state !== null) this.state = state;
     this.frameClient = frameClient;
+    this.ontologyClient = ontologyClient;
+    this.rangeClient = rangeClient;
   }
 
   get payload(): Payload<C, D> {
@@ -68,7 +91,12 @@ export class Task<
     };
   }
 
+  get ontologyID(): ontology.ID {
+    return new ontology.ID({ type: "task", key: this.key });
+  }
+
   async executeCommand(type: string, args?: UnknownRecord): Promise<string> {
+    if (this.frameClient == null) throw TASK_NOT_CREATED;
     const writer = await this.frameClient.openWriter(TASK_CMD_CHANNEL);
     const key = id.id();
     await writer.write(TASK_CMD_CHANNEL, [{ task: this.key, type, key, args }]);
@@ -81,6 +109,7 @@ export class Task<
     args: UnknownRecord,
     timeout: CrudeTimeSpan,
   ): Promise<State<D>> {
+    if (this.frameClient == null) throw TASK_NOT_CREATED;
     const streamer = await this.frameClient.openStreamer(TASK_STATE_CHANNEL);
     const cmdKey = await this.executeCommand(type, args);
     let res: State<D>;
@@ -105,6 +134,7 @@ export class Task<
   async openStateObserver<D extends UnknownRecord = UnknownRecord>(): Promise<
     StateObservable<D>
   > {
+    if (this.frameClient == null) throw TASK_NOT_CREATED;
     return new framer.ObservableStreamer<State<D>>(
       await this.frameClient.openStreamer(TASK_STATE_CHANNEL),
       (frame) => {
@@ -118,6 +148,14 @@ export class Task<
       },
     );
   }
+
+  async snapshottedTo(): Promise<ontology.Resource | null> {
+    if (this.ontologyClient == null || this.rangeClient == null) throw TASK_NOT_CREATED;
+    if (!this.snapshot) return null;
+    const parents = await this.ontologyClient.retrieveParents(this.ontologyID);
+    if (parents.length == 0) return null;
+    return parents[0];
+  }
 }
 
 const retrieveReqZ = z.object({
@@ -143,20 +181,36 @@ export type RetrieveOptions = Pick<
 const RETRIEVE_ENDPOINT = "/hardware/task/retrieve";
 const CREATE_ENDPOINT = "/hardware/task/create";
 const DELETE_ENDPOINT = "/hardware/task/delete";
+const COPY_ENDPOINT = "/hardware/task/copy";
 
 const createReqZ = z.object({ tasks: newTaskZ.array() });
 const createResZ = z.object({ tasks: taskZ.array() });
 const deleteReqZ = z.object({ keys: taskKeyZ.array() });
 const deleteResZ = z.object({});
+const copyReqZ = z.object({
+  key: taskKeyZ,
+  name: z.string(),
+  snapshot: z.boolean(),
+});
+const copyResZ = z.object({ task: taskZ });
 
 export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
   readonly type: string = "task";
   private readonly client: UnaryClient;
   private readonly frameClient: framer.Client;
+  private readonly ontologyClient: ontology.Client;
+  private readonly rangeClient: ranger.Client;
 
-  constructor(client: UnaryClient, frameClient: framer.Client) {
+  constructor(
+    client: UnaryClient,
+    frameClient: framer.Client,
+    ontologyClient: ontology.Client,
+    rangeClient: ranger.Client,
+  ) {
     this.client = client;
     this.frameClient = frameClient;
+    this.ontologyClient = ontologyClient;
+    this.rangeClient = rangeClient;
   }
 
   async create<
@@ -251,6 +305,17 @@ export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
     return single && variant !== "rack" ? sugared[0] : sugared;
   }
 
+  async copy(key: string, name: string, snapshot: boolean): Promise<Task> {
+    const res = await sendRequired(
+      this.client,
+      COPY_ENDPOINT,
+      { key, name, snapshot },
+      copyReqZ,
+      copyResZ,
+    );
+    return this.sugar([res.task])[0];
+  }
+
   async retrieveByName(name: string, rack?: number): Promise<Task> {
     const tasks = await this.execRetrieve({ names: [name], rack });
     checkForMultipleOrNoResults("Task", name, tasks, true);
@@ -270,8 +335,19 @@ export class Client implements AsyncTermSearcher<string, TaskKey, Payload> {
 
   private sugar(payloads: Payload[]): Task[] {
     return payloads.map(
-      ({ key, name, type, config, state, internal }) =>
-        new Task(key, name, type, config, this.frameClient, internal, state),
+      ({ key, name, type, config, state, internal, snapshot }) =>
+        new Task(
+          key,
+          name,
+          type,
+          config,
+          internal,
+          snapshot,
+          state,
+          this.frameClient,
+          this.ontologyClient,
+          this.rangeClient,
+        ),
     );
   }