@synnaxlabs/client 0.40.0 → 0.41.0

package/src/framer/streamer.spec.ts

@@ -27,7 +27,6 @@ describe("Streamer", () => {
   test("happy path", async () => {
     const ch = await newChannel();
     const streamer = await client.openStreamer(ch.key);
-    await new Promise((resolve) => setTimeout(resolve, 100));
     const writer = await client.openWriter({
       start: TimeStamp.now(),
       channels: ch.key,
@@ -56,7 +55,6 @@ describe("Streamer", () => {
       channels: ch.key,
       downsampleFactor: 1,
     });
-    await new Promise((resolve) => setTimeout(resolve, 100));
     const writer = await client.openWriter({
       start: TimeStamp.now(),
       channels: ch.key,
@@ -75,7 +73,6 @@ describe("Streamer", () => {
       channels: ch.key,
       downsampleFactor: 2,
     });
-    await new Promise((resolve) => setTimeout(resolve, 100));
     const writer = await client.openWriter({
       start: TimeStamp.now(),
       channels: ch.key,
@@ -94,7 +91,6 @@ describe("Streamer", () => {
       channels: ch.key,
       downsampleFactor: 10,
     });
-    await new Promise((resolve) => setTimeout(resolve, 100));
     const writer = await client.openWriter({
       start: TimeStamp.now(),
       channels: ch.key,
@@ -145,9 +141,6 @@ describe("Streamer - Calculated Channels", () => {
     // Set up streamer to listen for calculated results
     const streamer = await client.openStreamer(calcChannel.key);
 
-    // Give streamer time to initialize
-    await new Promise((resolve) => setTimeout(resolve, 100));
-
     // Write test data
     const startTime = TimeStamp.now();
     const writer = await client.openWriter({
@@ -200,7 +193,6 @@ describe("Streamer - Calculated Channels", () => {
     });
 
     const streamer = await client.openStreamer(calcChannel.key);
-    await new Promise((resolve) => setTimeout(resolve, 100));
 
     const startTime = TimeStamp.now();
     const writer = await client.openWriter({
@@ -254,7 +246,6 @@ describe("Streamer - Calculated Channels", () => {
     });
 
     const streamer = await client.openStreamer(calcChannel.key);
-    await new Promise((resolve) => setTimeout(resolve, 100));
 
     const startTime = TimeStamp.now();
     const writer = await client.openWriter({

package/src/hardware/device/client.ts

@@ -12,7 +12,7 @@ import { toArray, type UnknownRecord } from "@synnaxlabs/x";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { z } from "zod";
 
-import { type framer } from "@/framer";
+import { framer } from "@/framer";
 import {
   type Device,
   deviceZ,
@@ -21,7 +21,10 @@ import {
   type New,
   newZ,
   ONTOLOGY_TYPE,
+  type State,
+  stateZ,
 } from "@/hardware/device/payload";
+import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
 import { ontology } from "@/ontology";
 import { signals } from "@/signals";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
@@ -29,6 +32,7 @@ import { nullableArrayZ } from "@/util/zod";
 
 const SET_CHANNEL_NAME = "sy_device_set";
 const DELETE_CHANNEL_NAME = "sy_device_delete";
+const STATE_CHANNEL_NAME = "sy_device_state";
 
 const RETRIEVE_ENDPOINT = "/hardware/device/retrieve";
 const CREATE_ENDPOINT = "/hardware/device/create";
@@ -43,19 +47,26 @@ const deleteReqZ = z.object({ keys: keyZ.array() });
 const deleteResZ = z.object({});
 
 const retrieveReqZ = z.object({
-  search: z.string().optional(),
-  limit: z.number().optional(),
-  offset: z.number().optional(),
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
   makes: z.string().array().optional(),
+  models: z.string().array().optional(),
+  locations: z.string().array().optional(),
+  racks: rackKeyZ.array().optional(),
+  search: z.string().optional(),
+  limit: z.number().optional(),
+  offset: z.number().optional(),
   ignoreNotFound: z.boolean().optional(),
+  includeState: z.boolean().optional(),
 });
 
 interface RetrieveRequest extends z.input<typeof retrieveReqZ> {}
 
 export interface RetrieveOptions
-  extends Pick<RetrieveRequest, "limit" | "offset" | "makes" | "ignoreNotFound"> {}
+  extends Pick<
+    RetrieveRequest,
+    "limit" | "offset" | "makes" | "ignoreNotFound" | "includeState"
+  > {}
 
 interface PageOptions extends Pick<RetrieveOptions, "makes"> {}
 
@@ -75,26 +86,33 @@ export class Client implements AsyncTermSearcher<string, Key, Device> {
     Properties extends UnknownRecord = UnknownRecord,
     Make extends string = string,
     Model extends string = string,
-  >(key: string, options?: RetrieveOptions): Promise<Device<Properties, Make, Model>>;
+    StateDetails extends {} = UnknownRecord,
+  >(
+    key: string,
+    options?: RetrieveOptions,
+  ): Promise<Device<Properties, Make, Model, StateDetails>>;
 
   async retrieve<
     Properties extends UnknownRecord = UnknownRecord,
     Make extends string = string,
     Model extends string = string,
+    StateDetails extends {} = UnknownRecord,
   >(
     keys: string[],
     options?: RetrieveOptions,
-  ): Promise<Array<Device<Properties, Make, Model>>>;
+  ): Promise<Array<Device<Properties, Make, Model, StateDetails>>>;
 
   async retrieve<
     Properties extends UnknownRecord = UnknownRecord,
     Make extends string = string,
     Model extends string = string,
+    StateDetails extends {} = UnknownRecord,
   >(
     keys: string | string[],
     options?: RetrieveOptions,
   ): Promise<
-    Device<Properties, Make, Model> | Array<Device<Properties, Make, Model>> | null
+    | Device<Properties, Make, Model, StateDetails>
+    | Array<Device<Properties, Make, Model, StateDetails>>
   > {
     const isSingle = !Array.isArray(keys);
     const res = await sendRequired(
@@ -106,8 +124,8 @@ export class Client implements AsyncTermSearcher<string, Key, Device> {
     );
     checkForMultipleOrNoResults("Device", keys, res.devices, isSingle);
     return isSingle
-      ? (res.devices[0] as Device<Properties, Make, Model>)
-      : (res.devices as Array<Device<Properties, Make, Model>>);
+      ? (res.devices[0] as Device<Properties, Make, Model, StateDetails>)
+      : (res.devices as Array<Device<Properties, Make, Model, StateDetails>>);
   }
 
   async search(term: string, options?: RetrieveOptions): Promise<Device[]> {
@@ -183,6 +201,20 @@ export class Client implements AsyncTermSearcher<string, Key, Device> {
     );
   }
 
+  async openStateObserver<Details extends {} = UnknownRecord>(): Promise<
+    framer.ObservableStreamer<State<Details>[]>
+  > {
+    return new framer.ObservableStreamer<State<Details>[]>(
+      await this.frameClient.openStreamer(STATE_CHANNEL_NAME),
+      (frame) => {
+        const s = frame.get(STATE_CHANNEL_NAME);
+        if (s.length === 0) return [null, false];
+        const states = s.parseJSON(stateZ);
+        return [states as State<Details>[], true];
+      },
+    );
+  }
+
   newSearcherWithOptions(
     options: RetrieveOptions,
   ): AsyncTermSearcher<string, Key, Device> {

package/src/hardware/device/device.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 { id } from "@synnaxlabs/x";
+import { id, type UnknownRecord } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
 
 import { NotFoundError } from "@/errors";
@@ -108,5 +108,113 @@ describe("Device", async () => {
         }),
       ).rejects.toThrow(NotFoundError);
     });
+
+    describe("state", () => {
+      it("should not include state by default", async () => {
+        const d = await client.hardware.devices.create({
+          key: "SN_STATE_TEST1",
+          rack: testRack.key,
+          location: "Dev1",
+          name: "state_test1",
+          make: "ni",
+          model: "dog",
+          properties: { cat: "dog" },
+        });
+
+        const retrieved = await client.hardware.devices.retrieve(d.key);
+        expect(retrieved.state?.key).toHaveLength(0);
+      });
+
+      it("should include state when includeState is true", async () => {
+        const d = await client.hardware.devices.create({
+          key: "SN_STATE_TEST2",
+          rack: testRack.key,
+          location: "Dev1",
+          name: "state_test2",
+          make: "ni",
+          model: "dog",
+          properties: { cat: "dog" },
+        });
+
+        const retrieved = await client.hardware.devices.retrieve(d.key, {
+          includeState: true,
+        });
+        expect(retrieved.state).toBeDefined();
+        if (retrieved.state) {
+          expect(retrieved.state.variant).toBeDefined();
+          expect(retrieved.state.key).toBeDefined();
+          expect(retrieved.state.details).toBeDefined();
+        }
+      });
+
+      it("should include state for multiple devices", async () => {
+        const d1 = await client.hardware.devices.create({
+          key: "SN_STATE_TEST3",
+          rack: testRack.key,
+          location: "Dev1",
+          name: "state_test3",
+          make: "ni",
+          model: "dog",
+          properties: { cat: "dog" },
+        });
+
+        const d2 = await client.hardware.devices.create({
+          key: "SN_STATE_TEST4",
+          rack: testRack.key,
+          location: "Dev2",
+          name: "state_test4",
+          make: "ni",
+          model: "dog",
+          properties: { cat: "dog" },
+        });
+
+        const retrieved = await client.hardware.devices.retrieve([d1.key, d2.key], {
+          includeState: true,
+        });
+        expect(retrieved).toHaveLength(2);
+        retrieved.forEach((device) => {
+          expect(device.state).toBeDefined();
+          if (device.state) {
+            expect(device.state.variant).toBeDefined();
+            expect(device.state.key).toBeDefined();
+            expect(device.state.details).toBeDefined();
+          }
+        });
+      });
+
+      it("should handle state with type-safe details", async () => {
+        interface DeviceStateDetails {
+          status: string;
+          temperature: number;
+        }
+
+        const key = id.create();
+        await client.hardware.devices.create({
+          key,
+          rack: testRack.key,
+          location: "Dev1",
+          name: "state_test5",
+          make: "ni",
+          model: "dog",
+          properties: { cat: "dog" },
+        });
+
+        await expect
+          .poll(async () => {
+            const retrieved = await client.hardware.devices.retrieve<
+              UnknownRecord,
+              string,
+              string,
+              DeviceStateDetails
+            >(key, { includeState: true });
+            return (
+              retrieved.state !== undefined &&
+              retrieved.state.variant === "info" &&
+              retrieved.state.key === key
+            );
+          })
+          .toBeTruthy();
+      });
+    });
   });
 });

package/src/hardware/device/payload.ts

@@ -16,6 +16,17 @@ import { decodeJSONString } from "@/util/decodeJSONString";
 export const keyZ = z.string();
 export type Key = z.infer<typeof keyZ>;
 
+export const stateZ = z.object({
+  key: keyZ,
+  variant: z.string(),
+  details: z.record(z.unknown()).or(z.string().transform(decodeJSONString)),
+});
+
+export interface State<Details extends {} = UnknownRecord>
+  extends Omit<z.infer<typeof stateZ>, "details"> {
+  details: Details;
+}
+
 export const deviceZ = z.object({
   key: keyZ,
   rack: rackKeyZ,
@@ -25,16 +36,19 @@ export const deviceZ = z.object({
   location: z.string(),
   configured: z.boolean().optional(),
   properties: z.record(z.unknown()).or(z.string().transform(decodeJSONString)),
+  state: stateZ.optional(),
 });
 
 export interface Device<
   Properties extends UnknownRecord = UnknownRecord,
   Make extends string = string,
   Model extends string = string,
-> extends Omit<z.output<typeof deviceZ>, "properties"> {
+  StateDetails extends {} = UnknownRecord,
+> extends Omit<z.output<typeof deviceZ>, "properties" | "state"> {
   properties: Properties;
   make: Make;
   model: Model;
+  state?: State<StateDetails>;
 }
 
 export const newZ = deviceZ.extend({

package/src/hardware/rack/client.ts

@@ -13,6 +13,7 @@ import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
+import { framer } from "@/framer";
 import {
   type Key,
   keyZ,
@@ -21,6 +22,8 @@ import {
   ONTOLOGY_TYPE,
   type Payload,
   rackZ,
+  type State,
+  stateZ,
 } from "@/hardware/rack/payload";
 import { type task } from "@/hardware/task";
 import { ontology } from "@/ontology";
@@ -31,12 +34,17 @@ const RETRIEVE_ENDPOINT = "/hardware/rack/retrieve";
 const CREATE_ENDPOINT = "/hardware/rack/create";
 const DELETE_ENDPOINT = "/hardware/rack/delete";
 
+const STATE_CHANNEL_NAME = "sy_rack_state";
+
 const retrieveReqZ = z.object({
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
   search: z.string().optional(),
-  offset: z.number().optional(),
+  embedded: z.boolean().optional(),
+  hostIsNode: z.boolean().optional(),
   limit: z.number().optional(),
+  offset: z.number().optional(),
+  includeState: z.boolean().optional(),
 });
 
 const retrieveResZ = z.object({ racks: nullableArrayZ(rackZ) });
@@ -49,14 +57,24 @@ const deleteReqZ = z.object({ keys: keyZ.array() });
 
 const deleteResZ = z.object({});
 
+export interface RetrieveOptions {
+  includeState?: boolean;
+}
+
 export class Client implements AsyncTermSearcher<string, Key, Payload> {
   readonly type = ONTOLOGY_TYPE;
   private readonly client: UnaryClient;
   private readonly tasks: task.Client;
+  private readonly frameClient: framer.Client;
 
-  constructor(client: UnaryClient, taskClient: task.Client) {
+  constructor(
+    client: UnaryClient,
+    taskClient: task.Client,
+    frameClient: framer.Client,
+  ) {
     this.client = client;
     this.tasks = taskClient;
+    this.frameClient = frameClient;
   }
 
   async delete(keys: Key | Key[]): Promise<void> {
@@ -107,9 +125,12 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     return this.sugar(res.racks);
   }
 
-  async retrieve(key: string | Key): Promise<Rack>;
-  async retrieve(keys: Key[]): Promise<Rack[]>;
-  async retrieve(racks: string | Key | Key[]): Promise<Rack | Rack[]> {
+  async retrieve(key: string | Key, options?: RetrieveOptions): Promise<Rack>;
+  async retrieve(keys: Key[], options?: RetrieveOptions): Promise<Rack[]>;
+  async retrieve(
+    racks: string | Key | Key[],
+    options?: RetrieveOptions,
+  ): Promise<Rack | Rack[]> {
     const { variant, normalized, single } = analyzeParams(racks, {
       string: "names",
       number: "keys",
@@ -117,7 +138,10 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     const res = await sendRequired<typeof retrieveReqZ, typeof retrieveResZ>(
       this.client,
       RETRIEVE_ENDPOINT,
-      { [variant]: normalized },
+      {
+        [variant]: normalized,
+        includeState: options?.includeState,
+      },
       retrieveReqZ,
       retrieveResZ,
     );
@@ -126,20 +150,36 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     return single ? sugared[0] : sugared;
   }
 
+  async openStateObserver(): Promise<framer.ObservableStreamer<State[]>> {
+    return new framer.ObservableStreamer<State[]>(
+      await this.frameClient.openStreamer(STATE_CHANNEL_NAME),
+      (fr) => {
+        const data = fr.get(STATE_CHANNEL_NAME);
+        if (data.length === 0) return [[], false];
+        const states = data.parseJSON(stateZ);
+        return [states, true];
+      },
+    );
+  }
+
   private sugar(payloads: Payload[]): Rack[] {
-    return payloads.map(({ key, name }) => new Rack(key, name, this.tasks));
+    return payloads.map(
+      ({ key, name, state }) => new Rack(key, name, this.tasks, state),
+    );
   }
 }
 
 export class Rack {
   key: Key;
   name: string;
+  state?: State;
   private readonly tasks: task.Client;
 
-  constructor(key: Key, name: string, taskClient: task.Client) {
+  constructor(key: Key, name: string, taskClient: task.Client, state?: State) {
     this.key = key;
     this.name = name;
     this.tasks = taskClient;
+    this.state = state;
   }
 
   async listTasks(): Promise<task.Task[]> {

package/src/hardware/rack/payload.ts

@@ -8,12 +8,27 @@
 // included in the file licenses/APL.txt.
 
 import { zod } from "@synnaxlabs/x";
+import { TimeStamp } from "@synnaxlabs/x/telem";
 import { z } from "zod";
 
 export const keyZ = zod.uint32;
 export type Key = z.infer<typeof keyZ>;
 
-export const rackZ = z.object({ key: keyZ, name: z.string() });
+export const stateZ = z.object({
+  key: keyZ,
+  variant: z.string(),
+  message: z.string(),
+  lastReceived: TimeStamp.z.optional(),
+});
+
+export interface State extends z.infer<typeof stateZ> {}
+
+export const rackZ = z.object({
+  key: keyZ,
+  name: z.string(),
+  state: stateZ.optional(),
+});
+
 export interface Payload extends z.infer<typeof rackZ> {}
 
 export const newZ = rackZ.partial({ key: true });

package/src/hardware/rack/rack.spec.ts

@@ -7,6 +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 { TimeStamp } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
 import { ZodError } from "zod";
 
@@ -66,4 +67,39 @@ describe("Rack", () => {
       ).rejects.toThrow(NotFoundError);
     });
   });
+  describe("state", () => {
+    it("should include state when includeState is true", async () => {
+      const r = await client.hardware.racks.create({ name: "test" });
+      await expect
+        .poll(async () => {
+          const retrieved = await client.hardware.racks.retrieve(r.key, {
+            includeState: true,
+          });
+          return (
+            retrieved.state !== undefined &&
+            retrieved.state.lastReceived instanceof TimeStamp &&
+            retrieved.state.key === r.key
+          );
+        })
+        .toBeTruthy();
+    });
+    it("should include state for multiple racks", async () => {
+      const r1 = await client.hardware.racks.create({ name: "test1" });
+      const r2 = await client.hardware.racks.create({ name: "test2" });
+
+      await expect
+        .poll(async () => {
+          const retrieved = await client.hardware.racks.retrieve([r1.key, r2.key], {
+            includeState: true,
+          });
+          return retrieved.every(
+            (rack) =>
+              rack.state !== undefined &&
+              rack.state.lastReceived instanceof TimeStamp &&
+              rack.state.key === rack.key,
+          );
+        })
+        .toBeTruthy();
+    });
+  });
 });

package/src/hardware/task/task.spec.ts

@@ -100,11 +100,14 @@ describe("Task", async () => {
         };
         expect(await w.write("sy_task_state", [state])).toBeTruthy();
         await w.close();
-        const retrieved = await client.hardware.tasks.retrieve(t.key, {
-          includeState: true,
-        });
-        expect(retrieved.state).not.toBeNull();
-        expect(retrieved.state?.variant).toBe(state.variant);
+        await expect
+          .poll(async () => {
+            const retrieved = await client.hardware.tasks.retrieve(t.key, {
+              includeState: true,
+            });
+            return retrieved.state?.variant === state.variant;
+          })
+          .toBeTruthy();
       });
     });
   });

package/src/ranger/client.ts

@@ -17,7 +17,7 @@ import { z } from "zod";
 import { type channel } from "@/channel";
 import { MultipleFoundError, NotFoundError, QueryError } from "@/errors";
 import { type framer } from "@/framer";
-import { type label } from "@/label";
+import { label } from "@/label";
 import { ontology } from "@/ontology";
 import { type Alias, Aliaser } from "@/ranger/alias";
 import { KV } from "@/ranger/kv";
@@ -195,6 +195,7 @@ const retrieveReqZ = z.object({
   overlapsWith: TimeRange.z.optional(),
   limit: z.number().int().optional(),
   offset: z.number().int().optional(),
+  hasLabels: label.keyZ.array().optional(),
 });
 
 export interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
@@ -321,7 +322,7 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
       "sy_range_delete",
       (variant, data) => {
         if (variant === "delete")
-          return data.toStrings().map((k) => ({ variant, key: k, value: undefined }));
+          return data.toUUIDs().map((k) => ({ variant, key: k, value: undefined }));
         const sugared = this.sugarMany(data.parseJSON(payloadZ));
         return sugared.map((r) => ({ variant, key: r.key, value: r }));
       },