@synnaxlabs/client 0.26.7 → 0.28.0

package/src/access/access.spec.ts

@@ -23,7 +23,7 @@ const client = newClient();
 
 describe("Policy", () => {
   describe("create", () => {
-    test("create one", async () => {
+    test.skip("create one", async () => {
       const policy = await client.access.create({
         subjects: [{ type: UserOntologyType, key: "1" }],
         objects: [
@@ -40,7 +40,7 @@ describe("Policy", () => {
       ]);
       expect(policy.actions).toEqual(["update"]);
     });
-    test("create many", async () => {
+    test.skip("create many", async () => {
       const policies = await client.access.create([
         {
           subjects: [{ type: UserOntologyType, key: "10" }],
@@ -62,11 +62,11 @@ describe("Policy", () => {
           actions: ["update"],
         },
       ]);
-      expect(policies.length).toEqual(2);
+      expect(policies.length).toEqual(3);
       expect(policies[0].subjects[0].key).toEqual("10");
       expect(policies[1].subjects[1].key).toEqual("21");
     });
-    test("create instances of policies", async () => {
+    test.skip("create instances of policies", async () => {
       const policy = {
         key: undefined,
         subjects: [
@@ -85,7 +85,7 @@ describe("Policy", () => {
       expect(p.key).not.toEqual(policy.key);
     });
   });
-  test("retrieve by subject", async () => {
+  test.skip("retrieve by subject", async () => {
     const key1 = id.id();
     const policies = [
       {
@@ -120,13 +120,13 @@ describe("Policy", () => {
     expect(p).toHaveLength(2);
     expect([p[0].actions, p[1].actions].sort()).toEqual([["delete"], ["update"]]);
   });
-  test("retrieve by subject - not found", async () => {
+  test.skip("retrieve by subject - not found", async () => {
     const res = await client.access.retrieve({ type: UserOntologyType, key: "999" });
     expect(res).toHaveLength(0);
   });
 
   describe("delete", async () => {
-    test("delete one", async () => {
+    test.skip("delete one", async () => {
       const id1 = id.id();
       const id2 = id.id();
       const id3 = id.id();
@@ -163,7 +163,7 @@ describe("Policy", () => {
       expect(res).toHaveLength(1);
       expect(res[0].actions).toEqual(["delete"]);
     });
-    test("delete many", async () => {
+    test.skip("delete many", async () => {
       const id1 = id.id();
       const id2 = id.id();
       const id3 = id.id();
@@ -203,7 +203,7 @@ describe("Policy", () => {
     });
   });
   describe("registration", async () => {
-    test("register a user", async () => {
+    test.skip("register a user", async () => {
       const username = id.id();
       await client.user.register(username, "pwd1");
       new Synnax({
@@ -213,14 +213,14 @@ describe("Policy", () => {
         password: "pwd1",
       });
     });
-    test("duplicate username", async () => {
+    test.skip("duplicate username", async () => {
       const username = id.id();
       await client.user.register(username, "pwd1");
       await expect(client.user.register(username, "pwd1")).rejects.toThrow(AuthError);
     });
   });
   describe("privilege", async () => {
-    test("new user", async () => {
+    test.skip("new user", async () => {
       const username = id.id();
       const user2 = await client.user.register(username, "pwd1");
       expect(user2).toBeDefined();

package/src/channel/batchRetriever.spec.ts

@@ -55,6 +55,7 @@ describe("channelRetriever", () => {
         rate: Rate.hz(1),
         leaseholder: 1,
         index: 0,
+        virtual: false,
       }));
     });
     const retriever = new DebouncedBatchRetriever(base, 10);
@@ -81,6 +82,7 @@ describe("channelRetriever", () => {
         rate: Rate.hz(1),
         leaseholder: 1,
         index: 0,
+        virtual: false,
       }));
     });
     const retriever = new DebouncedBatchRetriever(base, 10);

package/src/channel/channel.spec.ts

@@ -30,6 +30,7 @@ describe("Channel", () => {
       expect(channel.rate).toEqual(Rate.hz(1));
       expect(channel.dataType).toEqual(DataType.FLOAT32);
     });
+
     test("create index and indexed pair", async () => {
       const one = await client.channels.create({
         name: "Time",
@@ -44,6 +45,7 @@ describe("Channel", () => {
       });
       expect(two.key).not.toEqual(0);
     });
+
     test("create many", async () => {
       const channels = await client.channels.create([
         {
@@ -63,6 +65,7 @@ describe("Channel", () => {
       expect(channels[0].name).toEqual("test1");
       expect(channels[1].name).toEqual("test2");
     });
+
     test("create instances of channels", async () => {
       const timeIndexChannel = await client.channels.create({
         name: "time",
@@ -89,6 +92,20 @@ describe("Channel", () => {
       });
       await client.channels.create([sensorOne, sensorTwo, sensorThree]);
     });
+
+    describe("virtual", () => {
+      it("should create a virtual channel", async () => {
+        const channel = await client.channels.create({
+          name: "test",
+          dataType: DataType.JSON,
+          virtual: true,
+        });
+        expect(channel.virtual).toEqual(true);
+        const retrieved = await client.channels.retrieve(channel.key);
+        expect(retrieved.virtual).toBeTruthy();
+      });
+    });
+
     describe("retrieveIfNameExists", () => {
       it("should retrieve the existing channel when it exists", async () => {
         const name = `test-${Math.random()}-${TimeStamp.now().valueOf()}`;
@@ -159,38 +176,41 @@ describe("Channel", () => {
       });
     });
   });
-  test("retrieve by key", async () => {
-    const channel = await client.channels.create({
-      name: "test",
-      leaseholder: 1,
-      rate: Rate.hz(1),
-      dataType: DataType.FLOAT32,
+
+  describe("retrieve", () => {
+    test("retrieve by key", async () => {
+      const channel = await client.channels.create({
+        name: "test",
+        leaseholder: 1,
+        rate: Rate.hz(1),
+        dataType: DataType.FLOAT32,
+      });
+      const retrieved = await client.channels.retrieve(channel.key);
+      expect(retrieved.name).toEqual("test");
+      expect(retrieved.leaseholder).toEqual(1);
+      expect(retrieved.rate).toEqual(Rate.hz(1));
+      expect(retrieved.dataType).toEqual(DataType.FLOAT32);
+    });
+    test("retrieve by key - not found", async () => {
+      await expect(
+        async () => await client.channels.retrieve("1-1000"),
+      ).rejects.toThrow(QueryError);
+    });
+    test("retrieve by name", async () => {
+      const retrieved = await client.channels.retrieve(["test"]);
+      expect(retrieved.length).toBeGreaterThan(0);
+      retrieved.forEach((ch) => expect(ch.name).toEqual("test"));
+    });
+    test("retrieve by key - not found", async () => {
+      await expect(
+        async () => await client.channels.retrieve("1-1000"),
+      ).rejects.toThrow(NotFoundError);
+    });
+    test("retrieve by name", async () => {
+      const retrieved = await client.channels.retrieve(["test"]);
+      expect(retrieved.length).toBeGreaterThan(0);
+      retrieved.forEach((ch) => expect(ch.name).toEqual("test"));
     });
-    const retrieved = await client.channels.retrieve(channel.key);
-    expect(retrieved.name).toEqual("test");
-    expect(retrieved.leaseholder).toEqual(1);
-    expect(retrieved.rate).toEqual(Rate.hz(1));
-    expect(retrieved.dataType).toEqual(DataType.FLOAT32);
-  });
-  test("retrieve by key - not found", async () => {
-    await expect(async () => await client.channels.retrieve("1-1000")).rejects.toThrow(
-      QueryError,
-    );
-  });
-  test("retrieve by name", async () => {
-    const retrieved = await client.channels.retrieve(["test"]);
-    expect(retrieved.length).toBeGreaterThan(0);
-    retrieved.forEach((ch) => expect(ch.name).toEqual("test"));
-  });
-  test("retrieve by key - not found", async () => {
-    await expect(async () => await client.channels.retrieve("1-1000")).rejects.toThrow(
-      NotFoundError,
-    );
-  });
-  test("retrieve by name", async () => {
-    const retrieved = await client.channels.retrieve(["test"]);
-    expect(retrieved.length).toBeGreaterThan(0);
-    retrieved.forEach((ch) => expect(ch.name).toEqual("test"));
   });
 
   describe("delete", async () => {

package/src/channel/client.ts

@@ -101,6 +101,11 @@ export class Channel {
    * should not be relied upon in the current version of Synnax.
    */
   readonly alias: string | undefined;
+  /**
+   * Whether the channel is virtual. Virtual channels do not store any data in the
+   * database, but can still be used for streaming purposes.
+   */
+  readonly virtual: boolean;
 
   constructor({
     dataType,
@@ -111,6 +116,7 @@ export class Channel {
     isIndex = false,
     index = 0,
     internal = false,
+    virtual = false,
     frameClient,
     alias,
   }: NewPayload & {
@@ -126,6 +132,7 @@ export class Channel {
     this.isIndex = isIndex;
     this.internal = internal;
     this.alias = alias;
+    this.virtual = virtual;
     this._frameClient = frameClient ?? null;
   }
 

package/src/channel/payload.ts

@@ -30,6 +30,7 @@ export const payload = z.object({
   index: z.number(),
   isIndex: z.boolean(),
   internal: z.boolean(),
+  virtual: z.boolean(),
   alias: z.string().optional(),
 });
 

package/src/client.ts

@@ -44,8 +44,8 @@ export const synnaxPropsZ = z.object({
         required_error: "Port is required",
       }),
     ),
-  username: z.string().optional(),
-  password: z.string().optional(),
+  username: z.string().min(1, "Username is required"),
+  password: z.string().min(1, "Password is required"),
   connectivityPollFrequency: TimeSpan.z.default(TimeSpan.seconds(30)),
   secure: z.boolean().optional().default(false),
   name: z.string().optional(),
@@ -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,24 +122,31 @@ 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);
     this.ontology = new ontology.Client(transport.unary, this);
     const rangeWriter = new ranger.Writer(this.transport.unary);
-    this.labels = new label.Client(this.transport.unary, this);
+    this.labels = new label.Client(this.transport.unary, this, this.ontology);
     this.ranges = new ranger.Client(
       this,
       rangeWriter,
       this.transport.unary,
       chRetriever,
       this.labels,
+      this.ontology,
     );
     this.access = new access.Client(this.transport.unary);
     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/control/client.ts

@@ -1,3 +1,12 @@
+// Copyright 2024 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 { StateTracker } from "@/control/state";
 import { framer } from "@/framer";
 

package/src/errors.spec.ts

@@ -1,3 +1,12 @@
+// Copyright 2024 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 { MatchableErrorType } from "@synnaxlabs/freighter/src/errors";
 import { describe, expect, test } from "vitest";
 

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";

package/src/framer/frame.spec.ts

@@ -156,7 +156,7 @@ describe("framer.Frame", () => {
   });
 
   describe("weaklyAligned", () => {
-    it("should return true if all keys have the same timerange", () => {
+    it("should return true if all keys have the same time range", () => {
       const f = new framer.Frame(
         new Map([
           [
@@ -182,7 +182,7 @@ describe("framer.Frame", () => {
       expect(f.isWeaklyAligned).toEqual(true);
     });
 
-    it("should return false if any key has a different timerange", () => {
+    it("should return false if any key has a different time range", () => {
       const f = new framer.Frame(
         new Map([
           [