@synnaxlabs/client 0.47.0 → 0.49.0

package/src/framer/streamer.spec.ts

@@ -8,8 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { EOF, Unreachable } from "@synnaxlabs/freighter";
-import { id, sleep } from "@synnaxlabs/x";
-import { DataType, Series, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
+import { DataType, id, Rate, Series, sleep, TimeSpan, TimeStamp } from "@synnaxlabs/x";
 import { describe, expect, it, test, vi } from "vitest";
 
 import { type channel } from "@/channel";
@@ -114,11 +113,98 @@ describe("Streamer", () => {
       });
     });
 
+    describe("throttling", () => {
+      test("throttle at 60Hz", async () => {
+        const ch = await newVirtualChannel(client);
+        const streamer = await client.openStreamer({
+          channels: ch.key,
+          throttleRate: 60,
+        });
+        const writer = await client.openWriter({
+          start: TimeStamp.now(),
+          channels: ch.key,
+        });
+        try {
+          const startTime = Date.now();
+          // Write data rapidly
+          for (let i = 0; i < 10; i++) {
+            await writer.write(ch.key, new Float64Array([i]));
+            await sleep.sleep(TimeSpan.milliseconds(5));
+          }
+
+          // Read frames - should be throttled
+          const receivedFrames: Frame[] = [];
+          const timeout = Date.now() + 500;
+          while (Date.now() < timeout)
+            try {
+              const frame = await Promise.race([
+                streamer.read(),
+                sleep.sleep(TimeSpan.milliseconds(100)).then(() => null),
+              ]);
+              if (frame) receivedFrames.push(frame);
+              else break;
+            } catch {
+              break;
+            }
+
+          expect(receivedFrames.length).toBeGreaterThan(0);
+          const elapsed = Date.now() - startTime;
+          // Should take at least the throttle period
+          expect(elapsed).toBeGreaterThanOrEqual(16); // ~1/60Hz
+        } finally {
+          await writer.close();
+          streamer.close();
+        }
+      });
+
+      test("no throttling with rate of 0", async () => {
+        const ch = await newVirtualChannel(client);
+        const streamer = await client.openStreamer({
+          channels: ch.key,
+          throttleRate: 0,
+        });
+        const writer = await client.openWriter({
+          start: TimeStamp.now(),
+          channels: ch.key,
+        });
+        try {
+          await writer.write(ch.key, new Float64Array([1, 2, 3]));
+          const d = await streamer.read();
+          expect(Array.from(d.get(ch.key))).toEqual([1, 2, 3]);
+        } finally {
+          await writer.close();
+          streamer.close();
+        }
+      });
+
+      test("combine throttling and downsampling", async () => {
+        const ch = await newVirtualChannel(client);
+        const streamer = await client.openStreamer({
+          channels: ch.key,
+          downsampleFactor: 2,
+          throttleRate: 10,
+        });
+        const writer = await client.openWriter({
+          start: TimeStamp.now(),
+          channels: ch.key,
+        });
+        try {
+          await writer.write(ch.key, new Float64Array([1, 2, 3, 4, 5, 6]));
+          const d = await streamer.read();
+          // Should be downsampled to [1, 3, 5] and throttled
+          expect(Array.from(d.get(ch.key))).toEqual([1, 3, 5]);
+        } finally {
+          await writer.close();
+          streamer.close();
+        }
+      });
+    });
+
     describe("calculations", () => {
       test("basic calculated channel streaming", async () => {
         // Create a timestamp index channel
         const timeChannel = await client.channels.create({
-          name: "calc_test_time",
+          name: id.create(),
           isIndex: true,
           dataType: DataType.TIMESTAMP,
         });
@@ -139,7 +225,7 @@ describe("Streamer", () => {
 
         // Create calculated channel that adds the two source channels
         const calcChannel = await client.channels.create({
-          name: "test_calc",
+          name: id.create(),
           dataType: DataType.FLOAT64,
           virtual: true,
           expression: `return ${channelA.name} + ${channelB.name}`,
@@ -175,6 +261,7 @@ describe("Streamer", () => {
           streamer.close();
         }
       });
+
       test("calculated channel with constant", async () => {
         // Create an index channel for timestamps
         const timeChannel = await client.channels.create({
@@ -192,7 +279,7 @@ describe("Streamer", () => {
 
         // Create calculated channel that adds 5
         const calcChannel = await client.channels.create({
-          name: "calc_const_channel",
+          name: id.create(),
           dataType: DataType.FLOAT64,
           virtual: true,
           expression: `return ${baseChannel.name} + 5`,
@@ -231,23 +318,24 @@ describe("Streamer", () => {
       test("calculated channel with multiple operations", async () => {
         // Create timestamp channel
         const timeChannel = await client.channels.create({
-          name: "calc_multi_time",
+          name: id.create(),
           isIndex: true,
           dataType: DataType.TIMESTAMP,
         });
 
         // Create source channels
+        const names = [id.create(), id.create()];
         const [channelA, channelB] = await client.channels.create([
-          { name: "multi_test_a", dataType: DataType.FLOAT64, index: timeChannel.key },
-          { name: "multi_test_b", dataType: DataType.FLOAT64, index: timeChannel.key },
+          { name: names[0], dataType: DataType.FLOAT64, index: timeChannel.key },
+          { name: names[1], dataType: DataType.FLOAT64, index: timeChannel.key },
         ]);
 
         // Create calculated channel with multiple operations
         const calcChannel = await client.channels.create({
-          name: "multi_calc",
+          name: id.create(),
           dataType: DataType.FLOAT64,
           virtual: true,
-          expression: "return (multi_test_a * 2) + (multi_test_b / 2)",
+          expression: `return (${names[0]} * 2) + (${names[1]} / 2)`,
         });
 
         const streamer = await client.openStreamer(calcChannel.key);
@@ -274,6 +362,62 @@ describe("Streamer", () => {
           streamer.close();
         }
       });
+
+      describe("legacy calculations", async () => {
+        it("should correctly execute a calculation with a requires field", async () => {
+          const timeChannel = await client.channels.create({
+            name: id.create(),
+            isIndex: true,
+            dataType: DataType.TIMESTAMP,
+          });
+
+          const [channelA, channelB] = await client.channels.create([
+            {
+              name: id.create(),
+              dataType: DataType.FLOAT64,
+              index: timeChannel.key,
+            },
+            {
+              name: id.create(),
+              dataType: DataType.FLOAT64,
+              index: timeChannel.key,
+            },
+          ]);
+
+          const calcChannel = await client.channels.create({
+            name: id.create(),
+            dataType: DataType.FLOAT64,
+            virtual: true,
+            expression: `return ${channelA.name} + ${channelB.name}`,
+            requires: [channelA.key, channelB.key],
+          });
+
+          const streamer = await client.openStreamer(calcChannel.key);
+          await sleep.sleep(TimeSpan.milliseconds(10));
+
+          const startTime = TimeStamp.now();
+          const writer = await client.openWriter({
+            start: startTime,
+            channels: [timeChannel.key, channelA.key, channelB.key],
+          });
+
+          try {
+            await writer.write({
+              [timeChannel.key]: [startTime],
+              [channelA.key]: new Float64Array([2.5]),
+              [channelB.key]: new Float64Array([2.5]),
+            });
+
+            const frame = await streamer.read();
+
+            const calcData = Array.from(frame.get(calcChannel.key));
+            expect(calcData).toEqual([5.0]);
+          } finally {
+            await writer.close();
+            streamer.close();
+          }
+        });
+      });
     });
   });
 
@@ -341,6 +485,7 @@ describe("Streamer", () => {
       expect(openMock).toHaveBeenCalledWith({
         ...config,
         downsampleFactor: 1,
+        throttleRate: new Rate(0),
       });
       await hardened.update([1, 2, 3]);
       expect(streamer.updateMock).toHaveBeenCalledWith([1, 2, 3]);

package/src/framer/streamer.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { EOF, type Stream, type WebSocketClient } from "@synnaxlabs/freighter";
-import { breaker, observe, TimeSpan } from "@synnaxlabs/x";
+import { breaker, observe, Rate, TimeSpan } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { type channel } from "@/channel";
@@ -18,7 +18,11 @@ import { WSStreamerCodec } from "@/framer/codec";
 import { Frame, frameZ } from "@/framer/frame";
 import { StreamProxy } from "@/framer/streamProxy";
 
-const reqZ = z.object({ keys: z.number().array(), downsampleFactor: z.number() });
+const reqZ = z.object({
+  keys: z.number().array(),
+  downsampleFactor: z.int(),
+  throttleRate: Rate.z.optional(),
+});
 
 /**
  * Request interface for streaming frames from a Synnax cluster.
@@ -38,10 +42,12 @@ const intermediateStreamerConfigZ = z.object({
   /** The channels to stream data from. Can be channel keys, names, or payloads. */
   channels: paramsZ,
   /** Optional factor to downsample the data by. Defaults to 1 (no downsampling). */
-  downsampleFactor: z.number().optional().default(1),
-  /** useHighPerformanceCodec sets whether the writer will use the synnax frame
-  /* encoder as opposed to the standard JSON encoding mechanisms for frames. */
-  useHighPerformanceCodec: z.boolean().optional().default(true),
+  downsampleFactor: z.int().default(1),
+  /** Optional throttle rate in Hz to limit the rate of frames sent to the client. Defaults to 0 (no throttling). */
+  throttleRate: Rate.z.default(new Rate(0)),
+  /** useHighPerformanceCodec sets whether the writer will use the Synnax frame encoder
+   as opposed to the standard JSON encoding mechanisms for frames. */
+  useHighPerformanceCodec: z.boolean().default(true),
 });
 
 export const streamerConfigZ = intermediateStreamerConfigZ.or(
@@ -105,8 +111,17 @@ export const createStreamOpener =
     if (cfg.useHighPerformanceCodec)
       client = client.withCodec(new WSStreamerCodec(adapter.codec));
     const stream = await client.stream("/frame/stream", reqZ, resZ);
-    const streamer = new CoreStreamer(stream, adapter);
-    stream.send({ keys: adapter.keys, downsampleFactor: cfg.downsampleFactor ?? 1 });
+    const streamer = new CoreStreamer(
+      stream,
+      adapter,
+      cfg.downsampleFactor,
+      cfg.throttleRate,
+    );
+    stream.send({
+      keys: Array.from(adapter.keys),
+      downsampleFactor: cfg.downsampleFactor,
+      throttleRate: cfg.throttleRate,
+    });
     const [, err] = await stream.receive();
     if (err != null) throw err;
     return streamer;
@@ -129,15 +144,22 @@ class CoreStreamer implements Streamer {
   private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
   private readonly adapter: ReadAdapter;
   private readonly downsampleFactor: number;
+  private readonly throttleRate: Rate;
 
-  constructor(stream: Stream<typeof reqZ, typeof resZ>, adapter: ReadAdapter) {
+  constructor(
+    stream: Stream<typeof reqZ, typeof resZ>,
+    adapter: ReadAdapter,
+    downsampleFactor: number = 1,
+    throttleRate: Rate = new Rate(0),
+  ) {
     this.stream = new StreamProxy("Streamer", stream);
     this.adapter = adapter;
-    this.downsampleFactor = 1;
+    this.downsampleFactor = downsampleFactor;
+    this.throttleRate = throttleRate;
   }
 
   get keys(): channel.Key[] {
-    return this.adapter.keys;
+    return Array.from(this.adapter.keys);
   }
 
   async next(): Promise<IteratorResult<Frame, any>> {
@@ -158,8 +180,9 @@ class CoreStreamer implements Streamer {
     const hasChanged = await this.adapter.update(channels);
     if (!hasChanged) return;
     this.stream.send({
-      keys: this.adapter.keys,
+      keys: Array.from(this.adapter.keys),
       downsampleFactor: this.downsampleFactor,
+      throttleRate: this.throttleRate,
     });
   }
 

package/src/framer/writer.spec.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 { DataType, TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x";
+import { DataType, id, TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x";
 import { describe, expect, it, test } from "vitest";
 
 import { UnauthorizedError, ValidationError } from "@/errors";
@@ -42,8 +42,8 @@ describe("Writer", () => {
       const channels = await newIndexedPair(client);
       const writer = await client.openWriter({ start: TimeStamp.now(), channels });
       await expect(
-        writer.write("billy bob", randomSeries(10, DataType.FLOAT64)),
-      ).rejects.toThrow('Channel "billy bob" not found');
+        writer.write("nonexistent_channel", randomSeries(10, DataType.FLOAT64)),
+      ).rejects.toThrow('Channel "nonexistent_channel" not found');
       await writer.close();
     });
 
@@ -152,13 +152,13 @@ describe("Writer", () => {
 
     test("write with out of order timestamp", async () => {
       const indexCh = await client.channels.create({
-        name: "idx",
+        name: id.create(),
         dataType: DataType.TIMESTAMP,
         isIndex: true,
       });
 
       const dataCh = await client.channels.create({
-        name: "data",
+        name: id.create(),
         dataType: DataType.FLOAT64,
         index: indexCh.key,
       });

package/src/index.ts

@@ -8,13 +8,20 @@
 // included in the file licenses/APL.txt.
 
 export { access } from "@/access";
-export { policy } from "@/access/policy";
 export { arc } from "@/arc";
 export { channel } from "@/channel";
 export { Channel, isCalculated } from "@/channel/client";
-export { default as Synnax, type SynnaxProps, synnaxPropsZ } from "@/client";
+export {
+  checkConnection,
+  type CheckConnectionParams,
+  newConnectionChecker,
+  default as Synnax,
+  type SynnaxParams,
+  synnaxParamsZ,
+} from "@/client";
 export * from "@/connection";
 export { control } from "@/control";
+export { device } from "@/device";
 export {
   AuthError,
   ContiguityError,
@@ -28,16 +35,15 @@ export {
 } from "@/errors";
 export { framer } from "@/framer";
 export { Frame } from "@/framer/frame";
-export { hardware } from "@/hardware";
-export { device } from "@/hardware/device";
-export { rack } from "@/hardware/rack";
-export { task } from "@/hardware/task";
 export { label } from "@/label";
 export { ontology } from "@/ontology";
 export { group } from "@/ontology/group";
+export { rack } from "@/rack";
 export { ranger } from "@/ranger";
 export { status } from "@/status";
-export { createTestClient, TEST_CLIENT_PROPS } from "@/testutil/client";
+export { task } from "@/task";
+export { createTestClientWithPolicy } from "@/testutil/access";
+export { createTestClient, TEST_CLIENT_PARAMS } from "@/testutil/client";
 export { user } from "@/user";
 export { workspace } from "@/workspace";
 export { lineplot } from "@/workspace/lineplot";

package/src/label/access.spec.ts

@@ -0,0 +1,109 @@
+// 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 { describe, expect, it } from "vitest";
+
+import { AuthError, NotFoundError } from "@/errors";
+import { label } from "@/label";
+import { createTestClientWithPolicy } from "@/testutil/access";
+import { createTestClient } from "@/testutil/client";
+
+const client = createTestClient();
+
+describe("label", () => {
+  describe("access control", () => {
+    it("should deny access when no retrieve policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [],
+        actions: [],
+      });
+      const randomLabel = await client.labels.create({
+        name: "test",
+        color: "#E774D0",
+      });
+      await expect(
+        userClient.labels.retrieve({ key: randomLabel.key }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to retrieve labels with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [label.ontologyID("")],
+        actions: ["retrieve"],
+      });
+      const randomLabel = await client.labels.create({
+        name: "test",
+        color: "#E774D0",
+      });
+      const retrieved = await userClient.labels.retrieve({ key: randomLabel.key });
+      expect(retrieved.key).toBe(randomLabel.key);
+      expect(retrieved.name).toBe(randomLabel.name);
+      expect(retrieved.color).toBe(randomLabel.color);
+    });
+
+    it("should allow the caller to create labels with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [label.ontologyID("")],
+        actions: ["create"],
+      });
+      await userClient.labels.create({
+        name: "test",
+        color: "#E774D0",
+      });
+    });
+
+    it("should deny access when no create policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [label.ontologyID("")],
+        actions: [],
+      });
+      await expect(
+        userClient.labels.create({
+          name: "test",
+          color: "#E774D0",
+        }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to delete labels with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [label.ontologyID("")],
+        actions: ["delete"],
+      });
+      const randomLabel = await client.labels.create({
+        name: "test",
+        color: "#E774D0",
+      });
+      await userClient.labels.delete(randomLabel.key);
+      await expect(
+        userClient.labels.retrieve({ key: randomLabel.key }),
+      ).rejects.toThrow(NotFoundError);
+    });
+
+    it("should deny access when no delete policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [label.ontologyID("")],
+        actions: [],
+      });
+      const randomLabel = await client.labels.create({
+        name: "test",
+        color: "#E774D0",
+      });
+      await expect(userClient.labels.delete(randomLabel.key)).rejects.toThrow(
+        AuthError,
+      );
+    });
+  });
+});

package/src/label/client.ts

@@ -36,18 +36,13 @@ export interface SetOptions extends Pick<SetReq, "replace"> {}
 const removeReqZ = setReqZ.omit({ replace: true });
 const emptyResZ = z.object({});
 
-const CREATE_ENDPOINT = "/label/create";
-const DELETE_ENDPOINT = "/label/delete";
-const SET_ENDPOINT = "/label/set";
-const REMOVE_ENDPOINT = "/label/remove";
-const RETRIEVE_ENDPOINT = "/label/retrieve";
-
 const retrieveRequestZ = z.object({
   keys: keyZ.array().optional(),
+  names: z.string().array().optional(),
   for: ontology.idZ.optional(),
   searchTerm: z.string().optional(),
-  offset: z.number().optional(),
-  limit: z.number().optional(),
+  offset: z.int().optional(),
+  limit: z.int().optional(),
 });
 
 const singleRetrieveArgsZ = z
@@ -76,7 +71,7 @@ export class Client {
     const isSingle = "key" in args;
     const res = await sendRequired(
       this.client,
-      RETRIEVE_ENDPOINT,
+      "/label/retrieve",
       args,
       retrieveArgsZ,
       retrieveResponseZ,
@@ -88,7 +83,7 @@ export class Client {
   async label(id: ontology.ID, labels: Key[], opts: SetOptions = {}): Promise<void> {
     await sendRequired<typeof setReqZ, typeof emptyResZ>(
       this.client,
-      SET_ENDPOINT,
+      "/label/set",
       { id, labels, replace: opts.replace },
       setReqZ,
       emptyResZ,
@@ -98,7 +93,7 @@ export class Client {
   async remove(id: ontology.ID, labels: Key[]): Promise<void> {
     await sendRequired<typeof removeReqZ, typeof emptyResZ>(
       this.client,
-      REMOVE_ENDPOINT,
+      "/label/remove",
       { id, labels },
       removeReqZ,
       emptyResZ,
@@ -111,7 +106,7 @@ export class Client {
     const isMany = Array.isArray(labels);
     const res = await sendRequired<typeof createReqZ, typeof createResZ>(
       this.client,
-      CREATE_ENDPOINT,
+      "/label/create",
       { labels: array.toArray(labels) },
       createReqZ,
       createResZ,
@@ -122,7 +117,7 @@ export class Client {
   async delete(keys: Key | Key[]): Promise<void> {
     await sendRequired<typeof deleteReqZ, typeof emptyResZ>(
       this.client,
-      DELETE_ENDPOINT,
+      "/label/delete",
       { keys: array.toArray(keys) },
       deleteReqZ,
       emptyResZ,
@@ -130,4 +125,5 @@ export class Client {
   }
 }
 
-export const ontologyID = (key: Key): ontology.ID => ({ type: "label", key });
+export const ontologyID = ontology.createIDFactory<Key>("label");
+export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/ontology/client.ts

@@ -25,17 +25,15 @@ import {
 } from "@/ontology/payload";
 import { Writer } from "@/ontology/writer";
 
-const RETRIEVE_ENDPOINT = "/ontology/retrieve";
-
 const retrieveReqZ = z.object({
   ids: idZ.array().optional(),
   children: z.boolean().optional(),
   parents: z.boolean().optional(),
   excludeFieldData: z.boolean().optional(),
-  searchTerm: z.string().optional(),
-  limit: z.number().optional(),
-  offset: z.number().optional(),
   types: resourceTypeZ.array().optional(),
+  searchTerm: z.string().optional(),
+  limit: z.int().optional(),
+  offset: z.int().optional(),
 });
 export interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
 
@@ -174,7 +172,7 @@ export class Client {
   private async execRetrieve(request: RetrieveRequest): Promise<Resource[]> {
     const { resources } = await sendRequired(
       this.client,
-      RETRIEVE_ENDPOINT,
+      "/ontology/retrieve",
       request,
       retrieveReqZ,
       retrieveResZ,