@synnaxlabs/client 0.48.0 → 0.49.0

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(),
@@ -68,12 +77,13 @@ export interface Payload extends z.infer<typeof payloadZ> {}
 
 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(),
 });
@@ -89,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,16 +16,15 @@ 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";
@@ -38,7 +37,7 @@ export const synnaxParamsZ = 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(),
 });
@@ -59,7 +58,7 @@ export default class Synnax extends framer.Client {
   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;
@@ -110,19 +111,15 @@ export default class Synnax extends framer.Client {
       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.params = parsedParams;
-    this.auth = auth_;
     this.transport = transport;
     this.channels = new channel.Client(this, chRetriever, transport.unary, chCreator);
     this.connectivity = new connection.Checker(
@@ -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);
   }
 

package/src/device/access.spec.ts

@@ -0,0 +1,159 @@
+// 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 { id } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import { device } from "@/device";
+import { AuthError, NotFoundError } from "@/errors";
+import { createTestClientWithPolicy } from "@/testutil/access";
+import { createTestClient } from "@/testutil/client";
+
+const client = createTestClient();
+
+describe("device", () => {
+  describe("access control", () => {
+    it("should deny access when no retrieve policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [],
+        actions: [],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomDevice = await client.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+      await expect(
+        userClient.devices.retrieve({ key: randomDevice.key }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to retrieve devices with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: ["retrieve"],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomDevice = await client.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+      const retrieved = await userClient.devices.retrieve({
+        key: randomDevice.key,
+      });
+      expect(retrieved.key).toBe(randomDevice.key);
+      expect(retrieved.name).toBe(randomDevice.name);
+    });
+
+    it("should allow the caller to create devices with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: ["create"],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      await userClient.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+    });
+
+    it("should deny access when no create policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: [],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      await expect(
+        userClient.devices.create({
+          key: id.create(),
+          rack: rack.key,
+          location: "Dev1",
+          name: "test",
+          make: "ni",
+          model: "test",
+          properties: {},
+        }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to delete devices with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: ["delete", "retrieve"],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomDevice = await client.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+      await userClient.devices.delete(randomDevice.key);
+      await expect(
+        userClient.devices.retrieve({ key: randomDevice.key }),
+      ).rejects.toThrow(NotFoundError);
+    });
+
+    it("should deny access when no delete policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [device.ontologyID("")],
+        actions: [],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomDevice = await client.devices.create({
+        key: id.create(),
+        rack: rack.key,
+        location: "Dev1",
+        name: "test",
+        make: "ni",
+        model: "test",
+        properties: {},
+      });
+      await expect(userClient.devices.delete(randomDevice.key)).rejects.toThrow(
+        AuthError,
+      );
+    });
+  });
+});

package/src/{hardware/device → device}/client.ts

@@ -11,25 +11,13 @@ import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { array, type record } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import {
-  type Device,
-  deviceZ,
-  type Key,
-  keyZ,
-  type New,
-  newZ,
-} from "@/hardware/device/payload";
-import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
-import { type ontology } from "@/ontology";
+import { type Device, deviceZ, type Key, keyZ, type New, newZ } from "@/device/payload";
+import { ontology } from "@/ontology";
+import { keyZ as rackKeyZ } from "@/rack/payload";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
 export const SET_CHANNEL_NAME = "sy_device_set";
 export const DELETE_CHANNEL_NAME = "sy_device_delete";
-export const STATUS_CHANNEL_NAME = "sy_device_status";
-
-const RETRIEVE_ENDPOINT = "/hardware/device/retrieve";
-const CREATE_ENDPOINT = "/hardware/device/create";
-const DELETE_ENDPOINT = "/hardware/device/delete";
 
 const createReqZ = z.object({ devices: newZ.array() });
 const createResZ = z.object({ devices: deviceZ.array() });
@@ -45,8 +33,8 @@ const retrieveRequestZ = z.object({
   locations: z.string().array().optional(),
   racks: rackKeyZ.array().optional(),
   searchTerm: z.string().optional(),
-  limit: z.number().optional(),
-  offset: z.number().optional(),
+  limit: z.int().optional(),
+  offset: z.int().optional(),
   includeStatus: z.boolean().optional(),
 });
 const retrieveResZ = z.object({ devices: array.nullableZ(deviceZ) });
@@ -97,7 +85,7 @@ export class Client {
     const isSingle = typeof args === "object" && "key" in args;
     const res = await sendRequired(
       this.client,
-      RETRIEVE_ENDPOINT,
+      "/device/retrieve",
       args,
       retrieveArgsZ,
       retrieveResZ,
@@ -127,7 +115,7 @@ export class Client {
     const isSingle = !Array.isArray(devices);
     const res = await sendRequired(
       this.client,
-      CREATE_ENDPOINT,
+      "/device/create",
       { devices: array.toArray(devices) },
       createReqZ,
       createResZ,
@@ -139,7 +127,7 @@ export class Client {
   async delete(keys: Key | Key[]): Promise<void> {
     await sendRequired(
       this.client,
-      DELETE_ENDPOINT,
+      "/device/delete",
       { keys: array.toArray(keys) },
       deleteReqZ,
       deleteResZ,
@@ -147,4 +135,7 @@ export class Client {
   }
 }
 
-export const ontologyID = (key: Key): ontology.ID => ({ type: "device", key });
+export const ontologyID = ontology.createIDFactory<Key>("device");
+export const TYPE_ONTOLOGY_ID = ontologyID("");
+
+export const statusKey = (key: Key): string => ontology.idToString(ontologyID(key));