@synnaxlabs/client 0.55.0 → 0.56.0

package/src/channel/batchRetriever.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, errors, Rate } from "@synnaxlabs/x";
+import { DataType, errors, Rate, TimeSpan } from "@synnaxlabs/x";
 import { describe, expect, it, vi } from "vitest";
 
 import { channel } from "@/channel";
@@ -57,7 +57,10 @@ describe("channelchannel.Retriever", () => {
         operations: [],
       }));
     });
-    const retriever = new channel.DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(
+      base,
+      TimeSpan.milliseconds(10),
+    );
     const res = await Promise.all([
       retriever.retrieve([1]),
       retriever.retrieve([2]),
@@ -86,7 +89,10 @@ describe("channelchannel.Retriever", () => {
         operations: [],
       }));
     });
-    const retriever = new channel.DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(
+      base,
+      TimeSpan.milliseconds(10),
+    );
     const res = await Promise.all([
       retriever.retrieve([1]),
       retriever.retrieve([2]),
@@ -100,7 +106,10 @@ describe("channelchannel.Retriever", () => {
     const base = new MockRetriever(async (): Promise<channel.Payload[]> => {
       throw new Error("failed to fetch");
     });
-    const retriever = new channel.DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(
+      base,
+      TimeSpan.milliseconds(10),
+    );
     await expect(retriever.retrieve([1])).rejects.toThrow("failed to fetch");
   });
 });

package/src/channel/client.ts

@@ -7,15 +7,17 @@
 // 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 CrudeDensity,
   type CrudeTimeRange,
+  type CrudeTimeSpan,
   type CrudeTimeStamp,
   DataType,
   type MultiSeries,
   status,
+  TimeSpan,
   type TypedArray,
 } from "@synnaxlabs/x";
 import { z } from "zod";
@@ -387,8 +389,7 @@ export class Client {
    */
   async delete(params: Params): Promise<void> {
     const { normalized, variant } = analyzeParams(params);
-    if (variant === "keys")
-      return await this.writer.delete({ keys: normalized as Key[] });
+    if (variant === "keys") return await this.writer.delete({ keys: normalized });
     return await this.writer.delete({ names: normalized as string[] });
   }
 
@@ -398,7 +399,9 @@ export class Client {
     return await this.writer.rename(array.toArray(keys), array.toArray(names));
   }
 
-  createDebouncedBatchRetriever(deb: number = 10): Retriever {
+  createDebouncedBatchRetriever(
+    deb: CrudeTimeSpan = TimeSpan.milliseconds(10),
+  ): Retriever {
     return new CacheRetriever(
       new DebouncedBatchRetriever(new ClusterRetriever(this.client), deb),
     );
@@ -414,8 +417,7 @@ export class Client {
   }
 
   async retrieveGroup(): Promise<group.Group> {
-    const res = await sendRequired(
-      this.client,
+    const res = await this.client.send(
       "/channel/retrieve-group",
       {},
       retrieveGroupReqZ,

package/src/channel/retriever.ts

@@ -7,8 +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 { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { array, DataType, debounce, zod } from "@synnaxlabs/x";
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import { array, type CrudeTimeSpan, DataType, debounce, zod } from "@synnaxlabs/x";
 import { Mutex } from "async-mutex";
 import { z } from "zod";
 
@@ -36,13 +36,10 @@ const reqZ = z.object({
   internal: z.boolean().optional(),
   legacyCalculated: z.boolean().optional(),
 });
-export interface RetrieveRequest extends z.input<typeof reqZ> {}
+export type RetrieveRequest = z.input<typeof reqZ>;
 
-export interface RetrieveOptions extends Omit<
-  RetrieveRequest,
-  "keys" | "names" | "search"
-> {}
-export interface PageOptions extends Omit<RetrieveOptions, "offset" | "limit"> {}
+export type RetrieveOptions = Omit<RetrieveRequest, "keys" | "names" | "search">;
+export type PageOptions = Omit<RetrieveOptions, "offset" | "limit">;
 
 const resZ = z.object({ channels: array.nullishToEmpty(payloadZ) });
 
@@ -86,13 +83,7 @@ export class ClusterRetriever implements Retriever {
   }
 
   private async execute(request: RetrieveRequest): Promise<Payload[]> {
-    const res = await sendRequired(
-      this.client,
-      "/channel/retrieve",
-      request,
-      reqZ,
-      resZ,
-    );
+    const res = await this.client.send("/channel/retrieve", request, reqZ, resZ);
     return res.channels;
   }
 }
@@ -204,7 +195,7 @@ export class DebouncedBatchRetriever implements Retriever {
   private readonly wrapped: Retriever;
   private readonly debouncedRun: () => void;
 
-  constructor(wrapped: Retriever, deb: number) {
+  constructor(wrapped: Retriever, deb: CrudeTimeSpan) {
     this.wrapped = wrapped;
     this.debouncedRun = debounce(() => {
       void this.run();

package/src/channel/writer.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 { type DataType } from "@synnaxlabs/x";
 import { z } from "zod";
 
@@ -47,11 +47,7 @@ export class Writer {
   }
 
   async create(channels: New[]): Promise<Payload[]> {
-    const { channels: created } = await sendRequired<
-      typeof createReqZ,
-      typeof createResZ
-    >(
-      this.client,
+    const { channels: created } = await this.client.send(
       "/channel/create",
       {
         channels: channels.map((c) => ({
@@ -68,25 +64,13 @@ export class Writer {
 
   async delete(props: DeleteProps): Promise<void> {
     const keys = keyZ.array().parse(props.keys ?? []);
-    await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
-      this.client,
-      "/channel/delete",
-      props,
-      deleteReqZ,
-      deleteResZ,
-    );
+    await this.client.send("/channel/delete", props, deleteReqZ, deleteResZ);
     if (keys.length > 0) this.cache.delete(keys);
     if (props.names != null) this.cache.delete(props.names);
   }
 
   async rename(keys: Key[], names: string[]): Promise<void> {
-    await sendRequired<typeof renameReqZ, typeof renameResZ>(
-      this.client,
-      "/channel/rename",
-      { keys, names },
-      renameReqZ,
-      renameResZ,
-    );
+    await this.client.send("/channel/rename", { keys, names }, renameReqZ, renameResZ);
     this.cache.rename(keys, names);
   }
 }

package/src/connection/checker.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 {
   ClockSkewCalculator,
   type CrudeTimeSpan,
@@ -85,14 +85,14 @@ export class Checker {
    */
   constructor(
     client: UnaryClient,
-    pollFreq: TimeSpan = TimeSpan.seconds(30),
+    pollFreq: CrudeTimeSpan = TimeSpan.seconds(30),
     clientVersion: string,
     name?: string,
     clockSkewThreshold: CrudeTimeSpan = TimeSpan.seconds(1),
   ) {
     this._state = { ...DEFAULT };
     this.client = client;
-    this.pollFrequency = pollFreq;
+    this.pollFrequency = new TimeSpan(pollFreq);
     this.clientVersion = clientVersion;
     this.name = name;
     this.skewCalc = new ClockSkewCalculator();
@@ -117,8 +117,7 @@ export class Checker {
     this.checking = true;
     try {
       if (measureSkew) this.skewCalc.start();
-      const res = await sendRequired(
-        this.client,
+      const res = await this.client.send(
         "/connectivity/check",
         undefined,
         requestZ,

package/src/connection/connection.spec.ts

@@ -90,14 +90,11 @@ describe("connectivity", () => {
   });
   describe("clock skew", () => {
     const createMockClient = (nodeTime: TimeStamp): UnaryClient => ({
-      send: vi.fn().mockResolvedValue([
-        {
-          clusterKey: "test-cluster",
-          nodeVersion: __VERSION__,
-          nodeTime,
-        },
-        null,
-      ]) as UnaryClient["send"],
+      send: vi.fn().mockResolvedValue({
+        clusterKey: "test-cluster",
+        nodeVersion: __VERSION__,
+        nodeTime,
+      }),
       use: vi.fn(),
     });
 

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/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/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);
   }
 }