@synnaxlabs/client 0.40.0 → 0.42.0

package/src/framer/writer.ts

@@ -7,13 +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 {
-  decodeError,
-  errorZ,
-  type Stream,
-  type StreamClient,
-} from "@synnaxlabs/freighter";
-import { control } from "@synnaxlabs/x";
+import { EOF, type Stream, type WebSocketClient } from "@synnaxlabs/freighter";
+import { control, errors } from "@synnaxlabs/x";
 import {
   type CrudeSeries,
   type CrudeTimeStamp,
@@ -24,16 +19,16 @@ import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
 import { channel } from "@/channel";
+import { SynnaxError } from "@/errors";
 import { WriteAdapter } from "@/framer/adapter";
+import { WSWriterCodec } from "@/framer/codec";
 import { type Crude, frameZ } from "@/framer/frame";
-import { StreamProxy } from "@/framer/streamProxy";
 
-enum Command {
+export enum WriterCommand {
   Open = 0,
   Write = 1,
   Commit = 2,
-  Error = 3,
-  SetAuthority = 4,
+  SetAuthority = 3,
 }
 
 export enum WriterMode {
@@ -60,12 +55,18 @@ const constructWriterMode = (mode: CrudeWriterMode): WriterMode => {
 
 export const ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT: TimeSpan = new TimeSpan(-1);
 
+export class WriterClosedError extends SynnaxError.sub("writer_closed") {
+  constructor() {
+    super("WriterClosed");
+  }
+}
+
 const netConfigZ = z.object({
   start: TimeStamp.z.optional(),
   controlSubject: control.subjectZ.optional(),
   keys: channel.keyZ.array().optional(),
-  authorities: control.Authority.z.array().optional(),
-  mode: z.nativeEnum(WriterMode).optional(),
+  authorities: control.authorityZ.array().optional(),
+  mode: z.enum(WriterMode).optional(),
   errOnUnauthorized: z.boolean().optional(),
   enableAutoCommit: z.boolean().optional(),
   autoIndexPersistInterval: TimeSpan.z.optional(),
@@ -74,17 +75,18 @@ const netConfigZ = z.object({
 interface Config extends z.infer<typeof netConfigZ> {}
 
 const reqZ = z.object({
-  command: z.nativeEnum(Command),
+  command: z.enum(WriterCommand),
   config: netConfigZ.optional(),
   frame: frameZ.optional(),
+  buffer: z.instanceof(Uint8Array).optional(),
 });
 
-interface Request extends z.infer<typeof reqZ> {}
+export interface WriteRequest extends z.infer<typeof reqZ> {}
 
 const resZ = z.object({
-  ack: z.boolean(),
-  command: z.nativeEnum(Command),
-  error: errorZ.optional().nullable(),
+  command: z.enum(WriterCommand),
+  end: TimeStamp.z,
+  err: errors.payloadZ.optional(),
 });
 
 interface Response extends z.infer<typeof resZ> {}
@@ -114,6 +116,7 @@ export interface WriterConfig {
   // persisted. To persist every commit to guarantee minimal loss of data, set
   // auto_index_persist_interval to AlwaysAutoIndexPersist.
   autoIndexPersistInterval?: TimeSpan;
+  useExperimentalCodec?: boolean;
 }
 
 /**
@@ -156,34 +159,37 @@ export interface WriterConfig {
  */
 export class Writer {
   private static readonly ENDPOINT = "/frame/write";
-  private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
+  private readonly stream: Stream<typeof reqZ, typeof resZ>;
   private readonly adapter: WriteAdapter;
-  private errAccumulated: boolean = false;
+  private closeErr: Error | null = null;
 
   private constructor(stream: Stream<typeof reqZ, typeof resZ>, adapter: WriteAdapter) {
-    this.stream = new StreamProxy("Writer", stream);
+    this.stream = stream;
     this.adapter = adapter;
   }
 
   static async _open(
     retriever: channel.Retriever,
-    client: StreamClient,
+    client: WebSocketClient,
     {
       channels,
       start = TimeStamp.now(),
-      authorities = control.Authority.ABSOLUTE,
+      authorities = control.ABSOLUTE_AUTHORITY,
       controlSubject: subject,
       mode = WriterMode.PersistStream,
       errOnUnauthorized = false,
       enableAutoCommit = false,
       autoIndexPersistInterval = TimeSpan.SECOND,
+      useExperimentalCodec = true,
     }: WriterConfig,
   ): Promise<Writer> {
     const adapter = await WriteAdapter.open(retriever, channels);
+    if (useExperimentalCodec)
+      client = client.withCodec(new WSWriterCodec(adapter.codec));
     const stream = await client.stream(Writer.ENDPOINT, reqZ, resZ);
     const writer = new Writer(stream, adapter);
     await writer.execute({
-      command: Command.Open,
+      command: WriterCommand.Open,
       config: {
         start: new TimeStamp(start),
         keys: adapter.keys,
@@ -198,21 +204,13 @@ export class Writer {
     return writer;
   }
 
-  private async checkForAccumulatedError(): Promise<boolean> {
-    if (!this.errAccumulated && this.stream.received()) {
-      this.errAccumulated = true;
-      while (this.stream.received()) await this.stream.receive();
-    }
-    return this.errAccumulated;
-  }
-
-  async write(channel: channel.KeyOrName, data: CrudeSeries): Promise<boolean>;
-  async write(channel: channel.KeysOrNames, data: CrudeSeries[]): Promise<boolean>;
-  async write(frame: Crude | Record<channel.KeyOrName, CrudeSeries>): Promise<boolean>;
+  async write(channel: channel.KeyOrName, data: CrudeSeries): Promise<void>;
+  async write(channel: channel.KeysOrNames, data: CrudeSeries[]): Promise<void>;
+  async write(frame: Crude | Record<channel.KeyOrName, CrudeSeries>): Promise<void>;
   async write(
     channelsOrData: channel.Params | Record<channel.KeyOrName, CrudeSeries> | Crude,
     series?: CrudeSeries | CrudeSeries[],
-  ): Promise<boolean>;
+  ): Promise<void>;
 
   /**
    * Writes the given frame to the database.
@@ -231,29 +229,29 @@ export class Writer {
   async write(
     channelsOrData: channel.Params | Record<channel.KeyOrName, CrudeSeries> | Crude,
     series?: CrudeSeries | CrudeSeries[],
-  ): Promise<boolean> {
-    if (await this.checkForAccumulatedError()) return false;
+  ): Promise<void> {
+    if (this.closeErr != null) throw this.closeErr;
+    if (this.stream.received()) return await this.close();
     const frame = await this.adapter.adapt(channelsOrData, series);
-    this.stream.send({ command: Command.Write, frame: frame.toPayload() });
-    return true;
+    this.stream.send({ command: WriterCommand.Write, frame: frame.toPayload() });
   }
 
-  async setAuthority(value: number): Promise<boolean>;
+  async setAuthority(value: number): Promise<void>;
 
   async setAuthority(
     key: channel.KeyOrName,
     authority: control.Authority,
-  ): Promise<boolean>;
+  ): Promise<void>;
 
   async setAuthority(
     value: Record<channel.KeyOrName, control.Authority>,
-  ): Promise<boolean>;
+  ): Promise<void>;
 
   async setAuthority(
     value: Record<channel.KeyOrName, control.Authority> | channel.KeyOrName | number,
     authority?: control.Authority,
-  ): Promise<boolean> {
-    if (await this.checkForAccumulatedError()) return false;
+  ): Promise<void> {
+    if (this.closeErr != null) throw this.closeErr;
     let config: Config;
     if (typeof value === "number" && authority == null)
       config = { keys: [], authorities: [value] };
@@ -268,8 +266,7 @@ export class Writer {
         authorities: Object.values(oValue),
       };
     }
-    const response = await this.execute({ command: Command.SetAuthority, config });
-    return response.ack;
+    await this.execute({ command: WriterCommand.SetAuthority, config });
   }
 
   /**
@@ -280,19 +277,14 @@ export class Writer {
    * should acknowledge the error by calling the error method or closing the writer.
    * After the caller acknowledges the error, they can attempt to commit again.
    */
-  async commit(): Promise<boolean> {
-    if (await this.checkForAccumulatedError()) return false;
-    const res = await this.execute({ command: Command.Commit });
-    return res.ack;
-  }
-
-  /**
-   * @returns  The accumulated error, if any. This method will clear the writer's error
-   * state, allowing the writer to be used again.
-   */
-  async error(): Promise<Error | null> {
-    const res = await this.execute({ command: Command.Error });
-    return res.error != null ? decodeError(res.error) : null;
+  async commit(): Promise<TimeStamp> {
+    if (this.closeErr != null) throw this.closeErr;
+    if (this.stream.received()) {
+      await this.closeInternal(null);
+      return TimeStamp.ZERO;
+    }
+    const res = await this.execute({ command: WriterCommand.Commit });
+    return res.end;
   }
 
   /**
@@ -301,19 +293,33 @@ export class Writer {
    * in a 'finally' block.
    */
   async close(): Promise<void> {
-    await this.stream.closeAndAck();
+    await this.closeInternal(null);
   }
 
-  async execute(req: Request): Promise<Response> {
-    this.stream.send(req);
+  private async closeInternal(err: Error | null): Promise<null> {
+    if (this.closeErr != null) throw this.closeErr;
+    this.closeErr = err;
+    this.stream.closeSend();
     while (true) {
-      const res = await this.stream.receive();
-      if (res.command === req.command) return res;
-      console.warn("writer received unexpected response", res);
+      if (this.closeErr != null) {
+        if (WriterClosedError.matches(this.closeErr)) return null;
+        throw this.closeErr;
+      }
+      const [res, err] = await this.stream.receive();
+      if (err != null) this.closeErr = EOF.matches(err) ? new WriterClosedError() : err;
+      else this.closeErr = errors.decode(res?.err);
     }
   }
 
-  private get errorAccumulated(): boolean {
-    return this.stream.received();
+  private async execute(req: WriteRequest): Promise<Response> {
+    const err = this.stream.send(req);
+    if (err != null) await this.closeInternal(err);
+    while (true) {
+      const [res, err] = await this.stream.receive();
+      if (err != null) await this.closeInternal(err);
+      const resErr = errors.decode(res?.err);
+      if (resErr != null) await this.closeInternal(resErr);
+      if (res?.command == req.command) return res;
+    }
   }
 }

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

@@ -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 { binary, type UnknownRecord } from "@synnaxlabs/x";
+import { binary, type UnknownRecord, unknownRecordZ } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
@@ -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: unknownRecordZ.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,
@@ -24,17 +35,20 @@ export const deviceZ = z.object({
   model: z.string(),
   location: z.string(),
   configured: z.boolean().optional(),
-  properties: z.record(z.unknown()).or(z.string().transform(decodeJSONString)),
+  properties: unknownRecordZ.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({