@synnaxlabs/client 0.48.0 → 0.49.0

package/src/framer/frame.spec.ts

@@ -544,6 +544,137 @@ describe("framer.Frame", () => {
     });
   });
 
+  describe("forEachUnique", () => {
+    it("should iterate over all unique columns in the frame", () => {
+      const f = new framer.Frame(
+        new Map([
+          [
+            12,
+            [
+              new Series({
+                data: new Float32Array([1, 2, 3]),
+                timeRange: new TimeRange(1, 2),
+              }),
+            ],
+          ],
+          [
+            13,
+            [
+              new Series({
+                data: new Float32Array([4, 5, 6]),
+                timeRange: new TimeRange(4, 6),
+              }),
+            ],
+          ],
+          [
+            14,
+            [
+              new Series({
+                data: new Float32Array([7, 8, 9]),
+                timeRange: new TimeRange(7, 9),
+              }),
+            ],
+          ],
+        ]),
+      );
+      f.push(
+        12,
+        new Series({
+          data: new Float32Array([10, 11, 12]),
+          timeRange: new TimeRange(10, 12),
+        }),
+      );
+      f.push(
+        13,
+        new Series({
+          data: new Float32Array([13, 14, 15]),
+          timeRange: new TimeRange(13, 15),
+        }),
+      );
+      f.push(
+        14,
+        new Series({
+          data: new Float32Array([7, 8, 9]),
+          timeRange: new TimeRange(7, 9),
+        }),
+      );
+      const firstValues = new Set<number>();
+      f.forEachUnique((_, ms) => {
+        firstValues.add(ms.at(0) as number);
+      });
+      expect(firstValues).toEqual(new Set([1, 4, 7]));
+    });
+    it("should get all data from the frame", () => {
+      const f = new framer.Frame(
+        new Map([
+          [
+            12,
+            [
+              new Series({
+                data: new Float32Array([1, 2, 3]),
+                timeRange: new TimeRange(1, 2),
+              }),
+            ],
+          ],
+        ]),
+      );
+      f.push(
+        12,
+        new Series({
+          data: new Float32Array([10, 11, 12]),
+          timeRange: new TimeRange(10, 12),
+        }),
+      );
+      f.push(
+        13,
+        new Series({
+          data: new Float32Array([13, 14, 15]),
+          timeRange: new TimeRange(13, 15),
+        }),
+      );
+      const data: number[] = [];
+      f.forEachUnique((key, ms) => {
+        if (key !== 12) return;
+        for (let i = 0; i < ms.length; i++) data.push(ms.at(i, true) as number);
+      });
+      expect(data).toEqual([1, 2, 3, 10, 11, 12]);
+    });
+    it("should allow use of an index parameter", () => {
+      const f = new framer.Frame(
+        new Map([
+          [
+            12,
+            [
+              new Series({
+                data: new Float32Array([1, 2, 3]),
+                timeRange: new TimeRange(1, 2),
+              }),
+            ],
+          ],
+        ]),
+      );
+      f.push(
+        12,
+        new Series({
+          data: new Float32Array([10, 11, 12]),
+          timeRange: new TimeRange(10, 12),
+        }),
+      );
+      f.push(
+        13,
+        new Series({
+          data: new Float32Array([13, 14, 15]),
+          timeRange: new TimeRange(13, 15),
+        }),
+      );
+      let currentIndex = 0;
+      f.forEachUnique((_, __, i) => {
+        expect(i).toEqual(currentIndex);
+        currentIndex++;
+      });
+      expect(currentIndex).toEqual(2);
+    });
+  });
   describe("mapFilter", () => {
     it("should filter out items based on the keep boolean", () => {
       const f = new framer.Frame(

package/src/framer/frame.ts

@@ -386,6 +386,14 @@ export class Frame {
     });
   }
 
+  /**
+   * Iterates over all unique columns in the frame.
+   * @param fn a function that takes a channel key, multi-series, and index.
+   */
+  forEachUnique(fn: (k: channel.KeyOrName, ms: MultiSeries, i: number) => void): void {
+    this.uniqueColumns.forEach((k, i) => fn(k, this.get(k), i));
+  }
+
   at(index: number, required: true): Record<channel.KeyOrName, TelemValue>;
 
   at(
@@ -457,11 +465,11 @@ export class Frame {
 export const frameZ = z.object({
   keys: z.union([
     z.null().transform<number[]>(() => []),
-    z.number().array().optional().default([]),
+    z.number().array().default([]),
   ]),
   series: z.union([
     z.null().transform<z.infer<typeof Series.crudeZ>[]>(() => []),
-    Series.crudeZ.array().optional().default([]),
+    Series.crudeZ.array().default([]),
   ]),
 });
 

package/src/framer/iterator.ts

@@ -196,9 +196,9 @@ export class Iterator {
   }
 
   /**
-   * @returns true if the iterator value contains a valid segment, and fale otherwise.
-   * valid most commonly returns false when the iterator is exhausted or has
-   * accumulated an error.
+   * @returns true if the iterator value contains a valid segment, and false otherwise.
+   * valid most commonly returns false when the iterator is exhausted or has accumulated
+   * an error.
    */
   async valid(): Promise<boolean> {
     return await this.execute({ command: Command.Valid });

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}`,
@@ -193,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`,
@@ -232,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);
@@ -279,7 +366,7 @@ describe("Streamer", () => {
       describe("legacy calculations", async () => {
         it("should correctly execute a calculation with a requires field", async () => {
           const timeChannel = await client.channels.create({
-            name: "calc_test_time",
+            name: id.create(),
             isIndex: true,
             dataType: DataType.TIMESTAMP,
           });
@@ -298,7 +385,7 @@ describe("Streamer", () => {
           ]);
 
           const calcChannel = await client.channels.create({
-            name: "test_calc",
+            name: id.create(),
             dataType: DataType.FLOAT64,
             virtual: true,
             expression: `return ${channelA.name} + ${channelB.name}`,
@@ -398,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,10 +111,16 @@ 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);
+    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;
@@ -132,11 +144,18 @@ 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[] {
@@ -163,6 +182,7 @@ class CoreStreamer implements Streamer {
     this.stream.send({
       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,7 +8,6 @@
 // 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";
@@ -22,6 +21,7 @@ export {
 } from "@/client";
 export * from "@/connection";
 export { control } from "@/control";
+export { device } from "@/device";
 export {
   AuthError,
   ContiguityError,
@@ -35,15 +35,14 @@ 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 { task } from "@/task";
+export { createTestClientWithPolicy } from "@/testutil/access";
 export { createTestClient, TEST_CLIENT_PARAMS } from "@/testutil/client";
 export { user } from "@/user";
 export { workspace } from "@/workspace";

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,
+      );
+    });
+  });
+});