@synnaxlabs/client 0.54.2 → 0.56.0

package/src/connection/connection.spec.ts

@@ -7,8 +7,9 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { URL } from "@synnaxlabs/x";
-import { describe, expect, it } from "vitest";
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import { TimeSpan, TimeStamp, URL } from "@synnaxlabs/x";
+import { describe, expect, it, vi } from "vitest";
 import { z } from "zod";
 
 import { auth } from "@/auth";
@@ -87,4 +88,65 @@ describe("connectivity", () => {
       expect(state.clientVersion).toBe("0.0.0");
     });
   });
+  describe("clock skew", () => {
+    const createMockClient = (nodeTime: TimeStamp): UnaryClient => ({
+      send: vi.fn().mockResolvedValue({
+        clusterKey: "test-cluster",
+        nodeVersion: __VERSION__,
+        nodeTime,
+      }),
+      use: vi.fn(),
+    });
+
+    it("should detect clock skew exceeding threshold", async () => {
+      const farFuture = TimeStamp.now().add(TimeSpan.hours(1));
+      const checker = new connection.Checker(
+        createMockClient(farFuture),
+        TimeSpan.seconds(30),
+        __VERSION__,
+        undefined,
+        TimeSpan.seconds(1),
+      );
+      const state = await checker.check();
+      expect(state.clockSkewExceeded).toBe(true);
+      expect(state.clockSkew.valueOf()).not.toBe(0n);
+      checker.stop();
+    });
+
+    it("should not flag skew within threshold", async () => {
+      const now = TimeStamp.now();
+      const checker = new connection.Checker(
+        createMockClient(now),
+        TimeSpan.seconds(30),
+        __VERSION__,
+        undefined,
+        TimeSpan.seconds(1),
+      );
+      const state = await checker.check();
+      expect(state.clockSkewExceeded).toBe(false);
+      checker.stop();
+    });
+
+    it("should fire onChange when clockSkewExceeded changes", async () => {
+      let callCount = 0;
+      const farFuture = TimeStamp.now().add(TimeSpan.hours(1));
+      const checker = new connection.Checker(
+        createMockClient(farFuture),
+        TimeSpan.seconds(30),
+        __VERSION__,
+        undefined,
+        TimeSpan.seconds(1),
+      );
+      // Wait for the constructor's initial check to complete
+      await checker.check();
+      checker.onChange(() => {
+        callCount++;
+      });
+      // Trigger another check - skewExceeded stays true, status stays connected,
+      // so onChange should not fire
+      await checker.check();
+      expect(callCount).toBe(0);
+      checker.stop();
+    });
+  });
 });

package/src/control/state.ts

@@ -46,13 +46,14 @@ export class StateTracker
   implements observe.ObservableAsyncCloseable<Transfer[]>
 {
   readonly states: Map<channel.Key, State>;
-  private readonly codec: binary.Codec;
+  private readonly codec: binary.JSONCodec;
 
   constructor(streamer: framer.Streamer) {
     super(streamer, (frame) => {
-      const update: Update = this.codec.decode(frame.series[0].buffer, updateZ);
-      this.merge(update);
-      return [update.transfers, true];
+      const raw = Array.from(frame.series[0].as("string"));
+      const updates: Update[] = raw.map((r) => this.codec.decodeString(r, updateZ));
+      updates.forEach((u) => this.merge(u));
+      return [updates.flatMap((u) => u.transfers), true];
     });
     this.states = new Map();
     this.codec = new binary.JSONCodec();

package/src/device/client.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 { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { type UnaryClient } from "@synnaxlabs/freighter";
 import { array, type record, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
@@ -122,10 +122,9 @@ export class Client {
   async retrieve(
     args: RetrieveArgs & { schemas?: DeviceSchemas },
   ): Promise<Device | Array<Device>> {
-    const { schemas, ...rest } = args as RetrieveArgs & { schemas?: DeviceSchemas };
+    const { schemas, ...rest } = args;
     const isSingle = typeof rest === "object" && "key" in rest;
-    const res = await sendRequired(
-      this.client,
+    const res = await this.client.send(
       "/device/retrieve",
       rest,
       retrieveArgsZ,
@@ -166,8 +165,7 @@ export class Client {
     schemas?: DeviceSchemas,
   ): Promise<Device | Device[]> {
     const isSingle = !Array.isArray(devices);
-    const res = await sendRequired(
-      this.client,
+    const res = await this.client.send(
       "/device/create",
       { devices: array.toArray(devices) },
       createReqZ(schemas),
@@ -177,8 +175,7 @@ export class Client {
   }
 
   async delete(keys: Key | Key[]): Promise<void> {
-    await sendRequired(
-      this.client,
+    await this.client.send(
       "/device/delete",
       { keys: array.toArray(keys) },
       deleteReqZ,

package/src/device/device.spec.ts

@@ -312,11 +312,13 @@ describe("Device", async () => {
       });
 
       it("should retrieve devices by search term", async () => {
-        const result = await client.devices.retrieve({
-          searchTerm: "sensor1",
-        });
-        expect(result.length).toBeGreaterThanOrEqual(2);
-        expect(result.every((d) => d.name.includes("sensor"))).toBe(true);
+        const sensor1 = testDevices.find((d) => d.name === "sensor1")!;
+        await expect
+          .poll(async () => {
+            const result = await client.devices.retrieve({ searchTerm: "sensor1" });
+            return result.find((d) => d.key === sensor1.key);
+          })
+          .toMatchObject({ name: "sensor1", key: sensor1.key });
       });
 
       it("should support pagination with limit and offset", async () => {

package/src/device/types.gen.ts

@@ -15,18 +15,18 @@ import { z } from "zod";
 import { ontology } from "@/ontology";
 import { rack } from "@/rack";
 
+export const keyZ = z.string();
+export type Key = z.infer<typeof keyZ>;
+
 /** StatusDetails contains device-specific status details identifying the device and its associated rack. */
 export const statusDetailsZ = z.object({
   /** rack is the key of the rack this device belongs to. */
   rack: rack.keyZ,
   /** device is the device identifier. */
-  device: z.string(),
+  device: keyZ,
 });
 export interface StatusDetails extends z.infer<typeof statusDetailsZ> {}
 
-export const keyZ = z.string();
-export type Key = z.infer<typeof keyZ>;
-
 export const statusZ = status.statusZ({ details: statusDetailsZ });
 export type Status = z.infer<typeof statusZ>;
 

package/src/errors.ts

@@ -157,15 +157,14 @@ export const validateFieldNotNull = (
 };
 
 export const errorsMiddleware: Middleware = async (ctx, next) => {
-  const [res, err] = await next(ctx);
-  if (err == null) return [res, err];
-  if (err instanceof Unreachable)
-    return [
-      res,
-      new Unreachable({
+  try {
+    return await next(ctx);
+  } catch (err) {
+    if (err instanceof Unreachable)
+      throw new Unreachable({
         message: `Cannot reach Core at ${err.url.host}:${err.url.port}`,
         url: err.url,
-      }),
-    ];
-  return [res, err];
+      });
+    throw err;
+  }
 };

package/src/framer/adapter.ts

@@ -164,16 +164,14 @@ export class WriteAdapter {
         throw new ValidationError(`
         Received a single channel name or key but no series.
         `);
-      if (Array.isArray(series)) {
+      if (Array.isArray(series))
         if (series.some((s) => s instanceof Series || Array.isArray(s)))
           throw new ValidationError(`
           Received a single channel name or key but multiple series.
           `);
 
-        series = series as CrudeSeries;
-      }
       const pld = await this.fetchChannel(columnsOrData);
-      const s = new Series({ data: series as CrudeSeries, dataType: pld.dataType });
+      const s = new Series({ data: series, dataType: pld.dataType });
       return new Frame(pld.key, s);
     }
 

package/src/framer/client.ts

@@ -180,6 +180,18 @@ export class Client {
 
   async readLatest(channels: channel.Params, n: number): Promise<Frame>;
 
+  /**
+   * Reads the latest n samples from the given channel(s).
+   *
+   * If fewer than n samples are available, returns only the samples that
+   * exist.
+   *
+   * @param channels - A single channel key/name or an array of channel
+   * keys/names.
+   * @param n - The maximum number of samples to read. Defaults to 1.
+   * @returns A MultiSeries when a single channel is provided, or a Frame when
+   * multiple channels are provided.
+   */
   async readLatest(
     channels: channel.Params,
     n: number = 1,

package/src/framer/codec.spec.ts

@@ -17,11 +17,13 @@ import { framer } from "@/framer";
 import {
   Codec,
   HIGH_PERF_SPECIAL_CHAR,
-  LOW_PER_SPECIAL_CHAR,
+  LOW_PERF_SPECIAL_CHAR,
+  WSIteratorCodec,
   WSWriterCodec,
 } from "@/framer/codec";
 import { Frame } from "@/framer/frame";
-import { WriterCommand } from "@/framer/types.gen";
+import { type IteratorResponse } from "@/framer/iterator";
+import { IteratorResponseVariant, WriterCommand } from "@/framer/types.gen";
 import { type WriteRequest } from "@/framer/writer";
 
 describe("encoder", () => {
@@ -325,9 +327,57 @@ describe("encoder", () => {
       const codec = new WSWriterCodec(baseCodec);
       const msg: WebsocketMessage<WriteRequest> = { type: "data", payload: writeReq };
       const encoded = codec.encode(msg);
-      expect(encoded[0]).toEqual(LOW_PER_SPECIAL_CHAR);
+      expect(encoded[0]).toEqual(LOW_PERF_SPECIAL_CHAR);
       const decoded = codec.decode(encoded);
       expect(decoded).toEqual(msg);
     });
   });
+
+  describe("websocket iterator codec", () => {
+    it("should JSON-encode an iterator request without a special char prefix", () => {
+      const baseCodec = new Codec([1], [DataType.INT32]);
+      const codec = new WSIteratorCodec(baseCodec);
+      const msg: WebsocketMessage<unknown> = {
+        type: "data",
+        payload: { command: 1, span: 0 },
+      };
+      const encoded = codec.encode(msg);
+      // Iterator requests are sent as raw JSON; no special-char prefix.
+      // Confirm the first byte is JSON ('{' or '[').
+      expect([0x7b, 0x5b]).toContain(encoded[0]);
+    });
+
+    it("should binary-decode a data variant response and synthesize variant=Data", () => {
+      const baseCodec = new Codec([1], [DataType.INT32]);
+      const fr = new framer.Frame([1], [new Series(new Int32Array([1, 2, 3]))]);
+      const codec = new WSIteratorCodec(baseCodec);
+      const encoded = new Uint8Array(baseCodec.encode(fr.toPayload(), 1));
+      encoded[0] = HIGH_PERF_SPECIAL_CHAR;
+      const decoded = codec.decode(encoded) as WebsocketMessage<IteratorResponse>;
+      expect(decoded.payload?.variant).toEqual(IteratorResponseVariant.Data);
+      const decodedFr = new Frame(decoded.payload?.frame);
+      expect(decodedFr.series[0].data).toEqual(fr.series[0].data);
+    });
+
+    it("should JSON-decode an ack variant response prefixed with the low-perf char", () => {
+      const baseCodec = new Codec([1], [DataType.INT32]);
+      const codec = new WSIteratorCodec(baseCodec);
+      const ackMsg: WebsocketMessage<IteratorResponse> = {
+        type: "data",
+        payload: {
+          variant: IteratorResponseVariant.Ack,
+          ack: true,
+          command: 1,
+        },
+      };
+      // Simulate what the server sends: LOW_PERF_SPECIAL_CHAR + JSON-encoded message.
+      const json = new TextEncoder().encode(JSON.stringify(ackMsg));
+      const encoded = new Uint8Array(json.byteLength + 1);
+      encoded[0] = LOW_PERF_SPECIAL_CHAR;
+      encoded.set(json, 1);
+      const decoded = codec.decode(encoded) as WebsocketMessage<IteratorResponse>;
+      expect(decoded.payload?.variant).toEqual(IteratorResponseVariant.Ack);
+      expect(decoded.payload?.ack).toEqual(true);
+    });
+  });
 });

package/src/framer/codec.ts

@@ -21,7 +21,7 @@ import { type channel } from "@/channel";
 import { ValidationError } from "@/errors";
 import { type Frame, type Payload } from "@/framer/frame";
 import { type StreamerResponse } from "@/framer/streamer";
-import { WriterCommand } from "@/framer/types.gen";
+import { IteratorResponseVariant, WriterCommand } from "@/framer/types.gen";
 import { type WriteRequest } from "@/framer/writer";
 
 const seriesPldLength = (series: SeriesPayload): number =>
@@ -63,7 +63,7 @@ interface CodecState {
 }
 
 export class Codec {
-  contentType: string = "application/sy-framer";
+  contentType: string = CONTENT_TYPE;
   private states: Map<number, CodecState> = new Map();
   private currState: CodecState | undefined;
   private seqNum: number = 0;
@@ -269,36 +269,26 @@ export class Codec {
       index += ALIGNMENT_SIZE;
     }
 
-    if (channelFlag) returnFrame.keys = [...state.keys];
-    state.keys.forEach((k, i) => {
-      if (!channelFlag) {
-        if (index >= view.byteLength) return;
-        const frameKey = view.getUint32(index, true);
-        if (frameKey !== k) return;
-        index += KEY_SIZE;
-        returnFrame.keys.push(k);
-      }
-      const dataType = state.keyDataTypes.get(k) as DataType;
+    const decodeSeries = (k: channel.Key): boolean => {
+      const dataType = state.keyDataTypes.get(k);
+      if (dataType == null) return false;
       currSize = 0;
       if (!sizeFlag) {
-        if (index + DATA_LENGTH_SIZE > view.byteLength) return;
+        if (index + DATA_LENGTH_SIZE > view.byteLength) return false;
         currSize = view.getUint32(index, true);
         index += DATA_LENGTH_SIZE;
       } else currSize = sizeRepresentation;
 
       let dataByteLength = currSize;
       if (!dataType.isVariable) dataByteLength *= dataType.density.valueOf();
-      if (index + dataByteLength > view.byteLength) {
-        returnFrame.keys.splice(i, 1);
-        return;
-      }
+      if (index + dataByteLength > view.byteLength) return false;
       const currSeries: SeriesPayload = {
         dataType,
         data: src.slice(index, index + dataByteLength).buffer,
       };
       index += dataByteLength;
       if (!equalTimeRangesFlag && !timeRangesZeroFlag) {
-        if (index + TIMESTAMP_SIZE * 2 > view.byteLength) return;
+        if (index + TIMESTAMP_SIZE * 2 > view.byteLength) return false;
         const start = view.getBigUint64(index, true);
         index += TIMESTAMP_SIZE;
         const end = view.getBigUint64(index, true);
@@ -312,7 +302,7 @@ export class Codec {
       else currSeries.timeRange = new TimeRange({ start: 0n, end: 0n });
 
       if (!equalAlignmentsFlag && !zeroAlignmentsFlag) {
-        if (index + ALIGNMENT_SIZE > view.byteLength) return;
+        if (index + ALIGNMENT_SIZE > view.byteLength) return false;
         currAlignment = view.getBigUint64(index, true);
         index += ALIGNMENT_SIZE;
         currSeries.alignment = currAlignment;
@@ -320,16 +310,27 @@ export class Codec {
       else currSeries.alignment = 0n;
 
       returnFrame.series.push(currSeries);
-    });
+      returnFrame.keys.push(k);
+      return true;
+    };
+
+    if (channelFlag) state.keys.forEach((k) => decodeSeries(k));
+    else
+      while (index < view.byteLength) {
+        if (index + KEY_SIZE > view.byteLength) break;
+        const frameKey = view.getUint32(index, true);
+        index += KEY_SIZE;
+        if (!decodeSeries(frameKey)) break;
+      }
     return returnFrame;
   }
 }
 
-export const LOW_PER_SPECIAL_CHAR = 254;
-const LOW_PERF_SPECIAL_CHAR_BUF = new Uint8Array([LOW_PER_SPECIAL_CHAR]);
+export const LOW_PERF_SPECIAL_CHAR = 254;
+const LOW_PERF_SPECIAL_CHAR_BUF = new Uint8Array([LOW_PERF_SPECIAL_CHAR]);
 export const HIGH_PERF_SPECIAL_CHAR = 255;
 const HIGH_PERF_SPECIAL_CHAR_BUF = new Uint8Array([HIGH_PERF_SPECIAL_CHAR]);
-const CONTENT_TYPE = "application/sy-framer";
+const CONTENT_TYPE = "application/vnd.synnax.frame";
 
 export class WSWriterCodec implements binary.Codec {
   contentType = CONTENT_TYPE;
@@ -358,7 +359,7 @@ export class WSWriterCodec implements binary.Codec {
   decode<P extends z.ZodType>(data: Uint8Array | ArrayBuffer, schema?: P): z.infer<P> {
     const dv = new DataView(data instanceof Uint8Array ? data.buffer : data);
     const codec = dv.getUint8(0);
-    if (codec === LOW_PER_SPECIAL_CHAR)
+    if (codec === LOW_PERF_SPECIAL_CHAR)
       return this.lowPerfCodec.decode(data.slice(1), schema);
     const v: WebsocketMessage<WriteRequest> = { type: "data" };
     const frame = this.base.decode(data, 1);
@@ -384,7 +385,7 @@ export class WSStreamerCodec implements binary.Codec {
   decode<P extends z.ZodType>(data: Uint8Array | ArrayBuffer, schema?: P): z.infer<P> {
     const dv = new DataView(data instanceof Uint8Array ? data.buffer : data);
     const codec = dv.getUint8(0);
-    if (codec === LOW_PER_SPECIAL_CHAR)
+    if (codec === LOW_PERF_SPECIAL_CHAR)
       return this.lowPerfCodec.decode(data.slice(1), schema);
     const v: WebsocketMessage<StreamerResponse> = {
       type: "data",
@@ -393,3 +394,35 @@ export class WSStreamerCodec implements binary.Codec {
     return v as z.infer<P>;
   }
 }
+
+export class WSIteratorCodec implements binary.Codec {
+  contentType = CONTENT_TYPE;
+  private base: Codec;
+  private lowPerfCodec: binary.Codec;
+
+  constructor(base: Codec) {
+    this.base = base;
+    this.lowPerfCodec = binary.JSON_CODEC;
+  }
+
+  encode(payload: unknown): Uint8Array<ArrayBuffer> {
+    return this.lowPerfCodec.encode(payload);
+  }
+
+  decode<P extends z.ZodType>(data: Uint8Array | ArrayBuffer, schema?: P): z.infer<P> {
+    const dv = new DataView(data instanceof Uint8Array ? data.buffer : data);
+    const codec = dv.getUint8(0);
+    if (codec === LOW_PERF_SPECIAL_CHAR)
+      return this.lowPerfCodec.decode(data.slice(1), schema);
+    const v: WebsocketMessage<unknown> = {
+      type: "data",
+      payload: {
+        variant: IteratorResponseVariant.Data,
+        ack: false,
+        command: 0,
+        frame: this.base.decode(data, 1),
+      },
+    };
+    return v as z.infer<P>;
+  }
+}

package/src/framer/deleter.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 { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { type UnaryClient } from "@synnaxlabs/freighter";
 import { TimeRange } from "@synnaxlabs/x";
 import { z } from "zod";
 
@@ -33,12 +33,6 @@ export class Deleter {
   }
 
   async delete(props: Request): Promise<void> {
-    await sendRequired<typeof reqZ, typeof resZ>(
-      this.client,
-      "/frame/delete",
-      props,
-      reqZ,
-      resZ,
-    );
+    await this.client.send("/frame/delete", props, reqZ, resZ);
   }
 }