@synnaxlabs/client 0.47.0 → 0.49.0

package/src/channel/payload.spec.ts

@@ -0,0 +1,171 @@
+// Copyright 2025 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 { DataType } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import { escapeInvalidName, nameZ, newZ } from "@/channel/payload";
+
+describe("nameZ", () => {
+  describe("valid names", () => {
+    const validNames = [
+      ["temperature", "lowercase letters"],
+      ["Pressure", "capitalized word"],
+      ["sensor1", "letters followed by digit"],
+      ["sensor_temp", "letters with underscore"],
+      ["temp123", "letters followed by digits"],
+      ["Sensor_temp", "capitalized with underscore"],
+      ["temp123_sensor_temp", "complex valid name"],
+      ["_private", "underscore prefix"],
+      ["__double", "double underscore prefix"],
+      ["a", "single letter"],
+      ["A", "single capital letter"],
+      ["_", "single underscore"],
+      ["_1", "underscore followed by digit"],
+    ];
+    validNames.forEach(([name, description]) => {
+      it(`should accept ${name} (${description})`, () => {
+        const result = nameZ.safeParse(name);
+        expect(result.success).toBe(true);
+      });
+    });
+  });
+
+  describe("invalid names", () => {
+    it("should reject empty string", () => {
+      const result = nameZ.safeParse("");
+      expect(result.success).toBe(false);
+      expect(result.error?.issues[0].message).toContain("Name must not be empty");
+    });
+
+    it("should reject name starting with digit", () => {
+      const result = nameZ.safeParse("1sensor");
+      expect(result.success).toBe(false);
+      // Regex validation covers both "cannot start with digit" and "invalid characters"
+      expect(result.error?.issues[0].message).toContain(
+        "can only contain letters, digits, and underscores",
+      );
+    });
+
+    it("should reject name with spaces", () => {
+      const result = nameZ.safeParse("my channel");
+      expect(result.success).toBe(false);
+      expect(result.error?.issues[0].message).toContain(
+        "can only contain letters, digits, and underscores",
+      );
+    });
+
+    it("should reject name with special characters", () => {
+      const result = nameZ.safeParse("sensor!");
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject name with hyphens", () => {
+      const result = nameZ.safeParse("sensor-temp");
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject name with dots", () => {
+      const result = nameZ.safeParse("sensor.temp");
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject name with parentheses", () => {
+      const result = nameZ.safeParse("sensor(1)");
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject name with brackets", () => {
+      const result = nameZ.safeParse("sensor[0]");
+      expect(result.success).toBe(false);
+    });
+  });
+});
+
+describe("newZ", () => {
+  const validNewChannel = {
+    name: "temperature_sensor",
+    dataType: DataType.FLOAT32,
+    virtual: true,
+  };
+
+  describe("name validation", () => {
+    it("should accept valid channel names", () => {
+      const result = newZ.safeParse(validNewChannel);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject empty name", () => {
+      const result = newZ.safeParse({ ...validNewChannel, name: "" });
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject name starting with digit", () => {
+      const result = newZ.safeParse({ ...validNewChannel, name: "1sensor" });
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject name with spaces", () => {
+      const result = newZ.safeParse({ ...validNewChannel, name: "my channel" });
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject name with special characters", () => {
+      const result = newZ.safeParse({ ...validNewChannel, name: "sensor-temp" });
+      expect(result.success).toBe(false);
+    });
+
+    it("should accept name with underscores", () => {
+      const result = newZ.safeParse({
+        ...validNewChannel,
+        name: "sensor_temp_123",
+      });
+      expect(result.success).toBe(true);
+    });
+
+    it("should accept name starting with underscore", () => {
+      const result = newZ.safeParse({ ...validNewChannel, name: "_private_sensor" });
+      expect(result.success).toBe(true);
+    });
+  });
+});
+describe("escapeInvalidName", () => {
+  it("should escape invalid name", () => {
+    const result = escapeInvalidName("sensor-temp");
+    expect(result).toBe("sensor_temp");
+  });
+  it("should escape name starting with digit", () => {
+    const result = escapeInvalidName("1sensor");
+    expect(result).toBe("_1sensor");
+  });
+  it("should escape name with spaces", () => {
+    const result = escapeInvalidName("my channel");
+    expect(result).toBe("my_channel");
+  });
+  it("should escape name with special characters", () => {
+    const result = escapeInvalidName("sensor!");
+    expect(result).toBe("sensor_");
+  });
+  it("should escape name with hyphens", () => {
+    const result = escapeInvalidName("sensor-temp");
+    expect(result).toBe("sensor_temp");
+  });
+  it("should escape name with dots", () => {
+    const result = escapeInvalidName("sensor.temp");
+    expect(result).toBe("sensor_temp");
+  });
+  it("should allow an empty string by default", () => {
+    const result = escapeInvalidName("");
+    expect(result).toBe("");
+  });
+  it("should change empty string to underscore when changeEmptyToUnderscore is true", () => {
+    const result = escapeInvalidName("", true);
+    expect(result).toBe("_");
+  });
+});

package/src/channel/payload.ts

@@ -18,6 +18,8 @@ import {
 } from "@synnaxlabs/x";
 import { z } from "zod";
 
+import { ontology } from "@/ontology";
+
 const errorMessage = "Channel key must be a valid uint32.";
 export const keyZ = z.uint32().or(
   z
@@ -28,7 +30,14 @@ export const keyZ = z.uint32().or(
 );
 export type Key = z.infer<typeof keyZ>;
 export type Keys = Key[];
-export const nameZ = z.string();
+const VALID_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+export const nameZ = z
+  .string()
+  .min(1, "Name must not be empty")
+  .regex(
+    VALID_NAME_PATTERN,
+    "Name can only contain letters, digits, and underscores, and cannot start with a digit",
+  );
 export type Name = z.infer<typeof nameZ>;
 export type Names = Name[];
 export type KeyOrName = Key | Name;
@@ -50,10 +59,10 @@ export type Operation = z.infer<typeof operationZ>;
 export const statusZ = status.statusZ();
 export type Status = z.infer<typeof statusZ>;
 export const payloadZ = z.object({
-  name: nameZ,
+  name: z.string(),
   key: keyZ,
   dataType: DataType.z,
-  leaseholder: z.number(),
+  leaseholder: zod.uint12,
   index: keyZ,
   isIndex: z.boolean(),
   internal: z.boolean(),
@@ -66,15 +75,17 @@ export const payloadZ = z.object({
 });
 export interface Payload extends z.infer<typeof payloadZ> {}
 
-export const newZ = payloadZ.omit({ requires: true }).extend({
+export const newZ = payloadZ.extend({
   key: keyZ.optional(),
-  leaseholder: z.number().optional(),
+  name: nameZ,
+  leaseholder: zod.uint12.optional(),
   index: keyZ.optional(),
   isIndex: z.boolean().optional(),
-  internal: z.boolean().optional().default(false),
-  virtual: z.boolean().optional().default(false),
-  expression: z.string().optional().default(""),
+  internal: z.boolean().default(false),
+  virtual: z.boolean().default(false),
+  expression: z.string().default(""),
   operations: array.nullableZ(operationZ).optional(),
+  requires: array.nullableZ(keyZ).optional(),
 });
 
 export interface New
@@ -88,3 +99,21 @@ export const paramsZ = z.union([
   zod.toArray(payloadZ).transform((p) => p.map((c) => c.key)),
 ]);
 export type Params = Key | Name | Keys | Names | Payload | Payload[];
+
+export const ontologyID = ontology.createIDFactory<Key>("channel");
+export const TYPE_ONTOLOGY_ID = ontologyID(0);
+
+const CHAR_REGEX = /[a-zA-Z0-9_]/;
+
+export const escapeInvalidName = (name: string, changeEmptyToUnderscore = false) => {
+  if (name === "") return changeEmptyToUnderscore ? "_" : "";
+  if (name.match(VALID_NAME_PATTERN)) return name;
+  // if it doesn't match, convert non-alphanumeric characters to underscores and prepend
+  // an underscore if the first character is a digit
+  let result = "";
+  for (const char of name)
+    if (char.match(CHAR_REGEX)) result += char;
+    else result += "_";
+  if (result[0].match(/^\d/)) result = `_${result}`;
+  return result;
+};

package/src/channel/retriever.ts

@@ -7,8 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type UnaryClient } from "@synnaxlabs/freighter";
-import { array, DataType, debounce } from "@synnaxlabs/x";
+import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { array, DataType, debounce, zod } from "@synnaxlabs/x";
 import { Mutex } from "async-mutex";
 import { z } from "zod";
 
@@ -25,25 +25,25 @@ import {
   payloadZ,
 } from "@/channel/payload";
 import { QueryError } from "@/errors";
+import { keyZ as rangeKeyZ } from "@/ranger/payload";
 import {
   analyzeParams as analyzeParameters,
   type ParamAnalysisResult,
 } from "@/util/retrieve";
 
 const reqZ = z.object({
-  leaseholder: z.number().optional(),
+  nodeKey: zod.uint12.optional(),
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
   searchTerm: z.string().optional(),
-  rangeKey: z.string().optional(),
-  limit: z.number().optional(),
-  offset: z.number().optional(),
+  rangeKey: rangeKeyZ.optional(),
+  limit: z.int().optional(),
+  offset: z.int().optional(),
   dataTypes: DataType.z.array().optional(),
   notDataTypes: DataType.z.array().optional(),
   virtual: z.boolean().optional(),
   isIndex: z.boolean().optional(),
   internal: z.boolean().optional(),
-  calculated: z.boolean().optional(),
   legacyCalculated: z.boolean().optional(),
 });
 export interface RetrieveRequest extends z.input<typeof reqZ> {}
@@ -72,7 +72,6 @@ export interface Retriever {
 }
 
 export class ClusterRetriever implements Retriever {
-  private static readonly ENDPOINT = "/channel/retrieve";
   private readonly client: UnaryClient;
 
   constructor(client: UnaryClient) {
@@ -95,13 +94,13 @@ export class ClusterRetriever implements Retriever {
   }
 
   private async execute(request: RetrieveRequest): Promise<Payload[]> {
-    const [res, err] = await this.client.send(
-      ClusterRetriever.ENDPOINT,
+    const res = await sendRequired(
+      this.client,
+      "/channel/retrieve",
       request,
       reqZ,
       resZ,
     );
-    if (err != null) throw err;
     return res.channels;
   }
 }

package/src/channel/writer.ts

@@ -34,10 +34,6 @@ const deleteResZ = z.object({});
 const renameReqZ = z.object({ keys: keyZ.array(), names: nameZ.array() });
 const renameResZ = z.object({});
 
-const CREATE_ENDPOINT = "/channel/create";
-const DELETE_ENDPOINT = "/channel/delete";
-const RENAME_ENDPOINT = "/channel/rename";
-
 export interface DeleteProps extends z.input<typeof deleteReqZ> {}
 export interface RenameProps extends z.input<typeof renameReqZ> {}
 
@@ -56,7 +52,7 @@ export class Writer {
       typeof createResZ
     >(
       this.client,
-      CREATE_ENDPOINT,
+      "/channel/create",
       {
         channels: channels.map((c) => ({
           ...c,
@@ -74,7 +70,7 @@ export class Writer {
     const keys = keyZ.array().parse(props.keys ?? []);
     await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
       this.client,
-      DELETE_ENDPOINT,
+      "/channel/delete",
       props,
       deleteReqZ,
       deleteResZ,
@@ -86,7 +82,7 @@ export class Writer {
   async rename(keys: Key[], names: string[]): Promise<void> {
     await sendRequired<typeof renameReqZ, typeof renameResZ>(
       this.client,
-      RENAME_ENDPOINT,
+      "/channel/rename",
       { keys, names },
       renameReqZ,
       renameResZ,

package/src/client.ts

@@ -16,21 +16,20 @@ import { auth } from "@/auth";
 import { channel } from "@/channel";
 import { connection } from "@/connection";
 import { control } from "@/control";
+import { device } from "@/device";
 import { errorsMiddleware } from "@/errors";
 import { framer } from "@/framer";
-import { hardware } from "@/hardware";
-import { device } from "@/hardware/device";
-import { rack } from "@/hardware/rack";
-import { task } from "@/hardware/task";
 import { label } from "@/label";
 import { ontology } from "@/ontology";
+import { rack } from "@/rack";
 import { ranger } from "@/ranger";
 import { status } from "@/status";
+import { task } from "@/task";
 import { Transport } from "@/transport";
 import { user } from "@/user";
 import { workspace } from "@/workspace";
 
-export const synnaxPropsZ = z.object({
+export const synnaxParamsZ = z.object({
   host: z.string({ error: "Host is required" }).min(1, "Host is required"),
   port: z
     .number({ error: "Port is required" })
@@ -38,13 +37,13 @@ export const synnaxPropsZ = z.object({
   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),
+  secure: z.boolean().default(false),
   name: z.string().optional(),
   retry: breaker.breakerConfigZ.optional(),
 });
 
-export interface SynnaxProps extends z.input<typeof synnaxPropsZ> {}
-export interface ParsedSynnaxProps extends z.infer<typeof synnaxPropsZ> {}
+export interface SynnaxParams extends z.input<typeof synnaxParamsZ> {}
+export interface ParsedSynnaxParams extends z.infer<typeof synnaxParamsZ> {}
 
 /**
  * Client to perform operations against a Synnax cluster.
@@ -56,10 +55,10 @@ export interface ParsedSynnaxProps extends z.infer<typeof synnaxPropsZ> {}
  */
 export default class Synnax extends framer.Client {
   readonly createdAt: TimeStamp;
-  readonly props: ParsedSynnaxProps;
+  readonly params: ParsedSynnaxParams;
   readonly ranges: ranger.Client;
   readonly channels: channel.Client;
-  readonly auth: auth.Client | undefined;
+  readonly auth: auth.Client;
   readonly users: user.Client;
   readonly access: access.Client;
   readonly connectivity: connection.Checker;
@@ -67,7 +66,9 @@ export default class Synnax extends framer.Client {
   readonly workspaces: workspace.Client;
   readonly labels: label.Client;
   readonly statuses: status.Client;
-  readonly hardware: hardware.Client;
+  readonly tasks: task.Client;
+  readonly racks: rack.Client;
+  readonly devices: device.Client;
   readonly control: control.Client;
   readonly arcs: arc.Client;
   static readonly connectivity = connection.Checker;
@@ -93,8 +94,8 @@ export default class Synnax extends framer.Client {
    * A Synnax client must be closed when it is no longer needed. This will stop
    * the client from polling the cluster for connectivity information.
    */
-  constructor(props_: SynnaxProps) {
-    const props = synnaxPropsZ.parse(props_);
+  constructor(params: SynnaxParams) {
+    const parsedParams = synnaxParamsZ.parse(params);
     const {
       host,
       port,
@@ -103,33 +104,29 @@ export default class Synnax extends framer.Client {
       connectivityPollFrequency,
       secure,
       retry: breaker,
-    } = props;
+    } = parsedParams;
     const transport = new Transport(
       new URL({ host, port: Number(port) }),
       breaker,
       secure,
     );
     transport.use(errorsMiddleware);
-    let auth_: auth.Client | undefined;
-    if (username != null && password != null) {
-      auth_ = new auth.Client(transport.unary, { username, password });
-      transport.use(auth_.middleware());
-    }
     const chRetriever = new channel.CacheRetriever(
       new channel.ClusterRetriever(transport.unary),
     );
-    const chCreator = new channel.Writer(transport.unary, chRetriever);
     super(transport.stream, transport.unary, chRetriever);
+    this.auth = new auth.Client(transport.unary, { username, password });
+    transport.use(this.auth.middleware());
+    const chCreator = new channel.Writer(transport.unary, chRetriever);
     this.createdAt = TimeStamp.now();
-    this.props = props;
-    this.auth = auth_;
+    this.params = parsedParams;
     this.transport = transport;
     this.channels = new channel.Client(this, chRetriever, transport.unary, chCreator);
     this.connectivity = new connection.Checker(
       transport.unary,
       connectivityPollFrequency,
       this.clientVersion,
-      props.name,
+      parsedParams.name,
     );
     this.control = new control.Client(this);
     this.ontology = new ontology.Client(transport.unary, this);
@@ -147,15 +144,14 @@ export default class Synnax extends framer.Client {
     this.access = new access.Client(this.transport.unary);
     this.users = new user.Client(this.transport.unary);
     this.workspaces = new workspace.Client(this.transport.unary);
-    const devices = new device.Client(this.transport.unary);
-    const tasks = new task.Client(
+    this.tasks = new task.Client(
       this.transport.unary,
       this,
       this.ontology,
       this.ranges,
     );
-    const racks = new rack.Client(this.transport.unary, tasks);
-    this.hardware = new hardware.Client(tasks, racks, devices);
+    this.racks = new rack.Client(this.transport.unary, this.tasks);
+    this.devices = new device.Client(this.transport.unary);
     this.arcs = new arc.Client(this.transport.unary, this.transport.stream);
   }
 
@@ -164,6 +160,20 @@ export default class Synnax extends framer.Client {
   }
 
   close(): void {
-    this.connectivity.stopChecking();
+    this.connectivity.stop();
   }
 }
+
+export interface CheckConnectionParams
+  extends Pick<SynnaxParams, "host" | "port" | "secure" | "retry" | "name"> {}
+
+export const checkConnection = async (params: CheckConnectionParams) =>
+  await newConnectionChecker(params).check();
+
+export const newConnectionChecker = (params: CheckConnectionParams) => {
+  const { host, port, secure, name, retry } = params;
+  const retryConfig = breaker.breakerConfigZ.optional().parse(retry);
+  const url = new URL({ host, port: Number(port) });
+  const transport = new Transport(url, retryConfig, secure);
+  return new connection.Checker(transport.unary, undefined, __VERSION__, name);
+};

package/src/connection/checker.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import type { UnaryClient } from "@synnaxlabs/freighter";
+import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { migrate, TimeSpan } from "@synnaxlabs/x";
 import { z } from "zod";
 
@@ -29,6 +29,7 @@ const responseZ = z.object({
   clusterKey: z.string(),
   nodeVersion: z.string().optional(),
 });
+const requestZ = z.void();
 
 const DEFAULT: State = {
   clusterKey: "",
@@ -52,7 +53,6 @@ const createWarning = (
 
 /** Polls a synnax cluster for connectivity information. */
 export class Checker {
-  private static readonly ENDPOINT = "/connectivity/check";
   static readonly DEFAULT: State = DEFAULT;
   private readonly _state: State;
   private readonly pollFrequency = TimeSpan.seconds(30);
@@ -81,11 +81,11 @@ export class Checker {
     this.clientVersion = clientVersion;
     this.name = name;
     void this.check();
-    this.startChecking();
+    this.start();
   }
 
   /** Stops the connectivity client from polling the cluster for connectivity */
-  stopChecking(): void {
+  stop(): void {
     if (this.interval != null) clearInterval(this.interval);
   }
 
@@ -96,13 +96,13 @@ export class Checker {
   async check(): Promise<State> {
     const prevStatus = this._state.status;
     try {
-      const [res, err] = await this.client.send(
-        Checker.ENDPOINT,
-        {},
-        z.object({}),
+      const res = await sendRequired(
+        this.client,
+        "/connectivity/check",
+        undefined,
+        requestZ,
         responseZ,
       );
-      if (err != null) throw err;
       const nodeVersion = res.nodeVersion;
       const clientVersion = this.clientVersion;
       const warned = this.versionWarned;
@@ -156,7 +156,7 @@ export class Checker {
     this.onChangeHandlers.push(callback);
   }
 
-  private startChecking(): void {
+  private start(): void {
     this.interval = setInterval(() => {
       void this.check();
     }, this.pollFrequency.milliseconds);

package/src/connection/connection.spec.ts

@@ -13,18 +13,18 @@ import { z } from "zod";
 
 import { auth } from "@/auth";
 import { connection } from "@/connection";
-import { TEST_CLIENT_PROPS } from "@/testutil/client";
+import { TEST_CLIENT_PARAMS } from "@/testutil/client";
 import { Transport } from "@/transport";
 
 describe("connectivity", () => {
   it("should connect to the server", async () => {
     const transport = new Transport(
       new URL({
-        host: TEST_CLIENT_PROPS.host,
-        port: Number(TEST_CLIENT_PROPS.port),
+        host: TEST_CLIENT_PARAMS.host,
+        port: Number(TEST_CLIENT_PARAMS.port),
       }),
     );
-    const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+    const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
     transport.use(client.middleware());
     const connectivity = new connection.Checker(
       transport.unary,
@@ -39,11 +39,11 @@ describe("connectivity", () => {
     it("should pull the server and client versions", async () => {
       const transport = new Transport(
         new URL({
-          host: TEST_CLIENT_PROPS.host,
-          port: Number(TEST_CLIENT_PROPS.port),
+          host: TEST_CLIENT_PARAMS.host,
+          port: Number(TEST_CLIENT_PARAMS.port),
         }),
       );
-      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(
         transport.unary,
@@ -57,11 +57,11 @@ describe("connectivity", () => {
     it("should adjust state if the server is too old", async () => {
       const transport = new Transport(
         new URL({
-          host: TEST_CLIENT_PROPS.host,
-          port: Number(TEST_CLIENT_PROPS.port),
+          host: TEST_CLIENT_PARAMS.host,
+          port: Number(TEST_CLIENT_PARAMS.port),
         }),
       );
-      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(
         transport.unary,
@@ -75,11 +75,11 @@ describe("connectivity", () => {
     it("should adjust state if the server is too new", async () => {
       const transport = new Transport(
         new URL({
-          host: TEST_CLIENT_PROPS.host,
-          port: Number(TEST_CLIENT_PROPS.port),
+          host: TEST_CLIENT_PARAMS.host,
+          port: Number(TEST_CLIENT_PARAMS.port),
         }),
       );
-      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(transport.unary, undefined, "0.0.0");
       const state = await connectivity.check();