@synnaxlabs/client 0.41.0 → 0.42.0

package/src/framer/codec.spec.ts

@@ -0,0 +1,303 @@
+import { type WebsocketMessage } from "@synnaxlabs/freighter";
+import { DataType, Series, TimeStamp } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import { type channel } from "@/channel";
+import { ValidationError } from "@/errors";
+import { framer } from "@/framer";
+import {
+  Codec,
+  HIGH_PERF_SPECIAL_CHAR,
+  LOW_PER_SPECIAL_CHAR,
+  WSWriterCodec,
+} from "@/framer/codec";
+import { Frame } from "@/framer/frame";
+import { WriterCommand, type WriteRequest } from "@/framer/writer";
+
+describe("encoder", () => {
+  describe("base codec", () => {
+    interface Spec {
+      name: string;
+      channels: channel.Keys;
+      dataTypes: DataType[];
+      frame: framer.Frame;
+    }
+
+    const SPECS: Spec[] = [
+      {
+        name: "All Channels Present, In Order",
+        channels: [1, 2, 3],
+        dataTypes: [DataType.INT64, DataType.FLOAT32, DataType.FLOAT64],
+        frame: new framer.Frame(
+          [1, 2, 3],
+          [
+            new Series(new BigInt64Array([1n, 2n, 3n])),
+            new Series(new Float32Array([4, 5, 6])),
+            new Series(new Float64Array([7, 8, 9])),
+          ],
+        ),
+      },
+      {
+        name: "All Channels Present, Out of Order",
+        channels: [3, 1, 2],
+        dataTypes: [DataType.FLOAT64, DataType.INT64, DataType.FLOAT32],
+        frame: new framer.Frame(
+          [2, 3, 1],
+          [
+            new Series(new Float32Array([4, 5, 6])),
+            new Series(new Float64Array([7, 8, 9])),
+            new Series(new BigInt64Array([1n, 2n, 3n])),
+          ],
+        ),
+      },
+      {
+        name: "Some Channels Present, In Order",
+        channels: [1, 2, 3],
+        dataTypes: [DataType.UINT8, DataType.FLOAT32, DataType.FLOAT64],
+        frame: new framer.Frame(
+          [1, 3],
+          [
+            new Series(new Uint8Array([1, 2, 3])),
+            new Series(new Float64Array([7, 8, 9])),
+          ],
+        ),
+      },
+      {
+        name: "Some Channels Present, Out of Order",
+        channels: [1, 2, 3],
+        dataTypes: [DataType.UINT8, DataType.FLOAT32, DataType.FLOAT64],
+        frame: new framer.Frame(
+          [3, 1],
+          [
+            new Series(new Float64Array([7, 8, 9])),
+            new Series(new Uint8Array([1, 2, 3])),
+          ],
+        ),
+      },
+      {
+        name: "Only One Channel Present",
+        channels: [1, 2, 3, 4, 5],
+        dataTypes: [
+          DataType.UINT8,
+          DataType.UINT8,
+          DataType.UINT8,
+          DataType.UINT8,
+          DataType.UINT8,
+        ],
+        frame: new framer.Frame([3], [new Series(new Uint8Array([1, 2, 3, 4, 5]))]),
+      },
+      {
+        name: "All Same Time Range",
+        channels: [1, 2],
+        dataTypes: [DataType.UINT8, DataType.FLOAT32],
+        frame: new framer.Frame(
+          [1, 2],
+          [
+            new Series({
+              dataType: DataType.UINT8,
+              data: new Uint8Array([1]),
+              timeRange: new TimeStamp(0).spanRange(5),
+            }),
+            new Series({
+              dataType: DataType.FLOAT32,
+              data: new Float32Array([1, 2, 3, 4]),
+              timeRange: new TimeStamp(0).spanRange(5),
+            }),
+          ],
+        ),
+      },
+      {
+        name: "Different Time Ranges",
+        channels: [1, 2],
+        dataTypes: [DataType.UINT8, DataType.FLOAT32],
+        frame: new framer.Frame(
+          [1, 2],
+          [
+            new Series({
+              dataType: DataType.UINT8,
+              data: new Uint8Array([1]),
+              timeRange: new TimeStamp(0).spanRange(5),
+            }),
+            new Series({
+              dataType: DataType.FLOAT32,
+              data: new Float32Array([1, 2, 3, 4]),
+              timeRange: new TimeStamp(0).spanRange(5),
+            }),
+          ],
+        ),
+      },
+      {
+        name: "Partial Present, Different Lengths",
+        channels: [1, 2, 3],
+        dataTypes: [DataType.UINT8, DataType.FLOAT32, DataType.FLOAT64],
+        frame: new framer.Frame(
+          [1, 3],
+          [new Series(new Uint8Array([1])), new Series(new Float64Array([1, 2, 3, 4]))],
+        ),
+      },
+      {
+        name: "Same Alignments",
+        channels: [1, 2],
+        dataTypes: [DataType.UINT8, DataType.FLOAT32],
+        frame: new framer.Frame(
+          [1, 2],
+          [
+            new Series({
+              dataType: DataType.UINT8,
+              data: new Uint8Array([1]),
+              alignment: 5n,
+            }),
+            new Series({
+              dataType: DataType.FLOAT32,
+              data: new Uint8Array([1, 2, 3, 4]),
+              alignment: 5n,
+            }),
+          ],
+        ),
+      },
+      {
+        name: "Different Alignments",
+        channels: [1, 2],
+        dataTypes: [DataType.UINT8, DataType.FLOAT32],
+        frame: new Frame(
+          [1, 2],
+          [
+            new Series({
+              dataType: DataType.UINT8,
+              data: new Uint8Array([1]),
+              alignment: 5n,
+            }),
+            new Series({
+              dataType: DataType.FLOAT32,
+              data: new Uint8Array([1, 2, 3, 4]),
+              alignment: 10n,
+            }),
+          ],
+        ),
+      },
+      {
+        name: "Variable Data Types",
+        channels: [1, 2, 3],
+        dataTypes: [DataType.UINT8, DataType.STRING, DataType.JSON],
+        frame: new framer.Frame(
+          [1, 2, 3],
+          [
+            new Series(new Uint8Array([1])),
+            new Series({
+              data: ["one", "two", "three"],
+              dataType: DataType.STRING,
+            }),
+            new Series({
+              data: [{ a: 1 }, { b: 2 }, { c: 3 }],
+              dataType: DataType.JSON,
+            }),
+          ],
+        ),
+      },
+    ];
+
+    SPECS.forEach((spec) => {
+      it(`should encode & decode ${spec.name}`, () => {
+        const codec = new Codec(spec.channels, spec.dataTypes);
+        const encoded = codec.encode(spec.frame.toPayload());
+        const decoded = codec.decode(encoded);
+        decoded.keys.forEach((k, i) => {
+          const dcs = decoded.series[i];
+          const ser = spec.frame.get(k);
+          expect(ser.series.length).toBeGreaterThan(0);
+          const os = ser.series[0];
+          if (dcs.timeRange != null && !dcs.timeRange.isZero)
+            expect(dcs.timeRange.toString()).toEqual(os.timeRange?.toString());
+          expect(new Series(dcs).toString()).toEqual(os.toString());
+        });
+      });
+    });
+  });
+
+  describe("dynamic codec", () => {
+    it("should allow the caller to update the codec", () => {
+      const codec = new Codec();
+      codec.update([1], [DataType.INT32]);
+      const encoded = codec.encode(
+        new framer.Frame([1], [new Series(new Int32Array([1, 2, 3]))]),
+      );
+      const decoded1 = new Frame(codec.decode(encoded));
+      expect(Array.from(decoded1.series[0])).toEqual([1, 2, 3]);
+      expect(decoded1.keys[0]).toEqual(1);
+      codec.update([2], [DataType.INT64]);
+      const encoded2 = codec.encode(
+        new framer.Frame([2], [new Series(new BigInt64Array([1n, 2n, 3n]))]),
+      );
+      const decoded2 = new Frame(codec.decode(encoded2));
+      expect(Array.from(decoded2.series[0])).toEqual([1n, 2n, 3n]);
+      expect(decoded2.keys[0]).toEqual(2);
+    });
+
+    it("should throw an error if the codec is not initialized", () => {
+      const codec = new Codec();
+      expect(() =>
+        codec.encode(new framer.Frame([1], [new Series(new Int32Array([1, 2, 3]))])),
+      ).toThrow(ValidationError);
+    });
+
+    it("should use the correct encode/decode state even if the codecs are out of sync", () => {
+      const encoder = new Codec();
+      const decoder = new Codec();
+      encoder.update([1], [DataType.INT32]);
+      decoder.update([1], [DataType.INT32]);
+
+      const fr = new framer.Frame([1], [new Series(new Int32Array([1, 2, 3]))]);
+      let encoded = encoder.encode(fr);
+      let decoded = new Frame(decoder.decode(encoded));
+      expect(decoded.keys[0]).toEqual(1);
+      expect(decoded.series[0].data).toEqual(fr.series[0].data);
+
+      decoder.update([2], [DataType.INT64]);
+      encoded = encoder.encode(fr);
+      decoded = new Frame(decoder.decode(encoded));
+      expect(decoded.keys[0]).toEqual(1);
+      expect(decoded.series[0].data).toEqual(fr.series[0].data);
+
+      encoder.update([2], [DataType.INT64]);
+      expect(() => encoder.encode(fr)).toThrow(ValidationError);
+      const fr2 = new framer.Frame([2], [new Series(new BigInt64Array([1n, 2n, 3n]))]);
+      encoded = encoder.encode(fr2);
+      decoded = new Frame(decoder.decode(encoded));
+      expect(decoded.keys[0]).toEqual(2);
+      expect(decoded.series[0].data).toEqual(fr2.series[0].data);
+    });
+  });
+
+  describe("websocket writer codec", () => {
+    it("should correctly e + d a websocket write request", () => {
+      const baseCodec = new Codec([1], [DataType.INT32]);
+      const fr = new framer.Frame([1], [new Series(new Int32Array([1, 2, 3]))]);
+      const writeReq: WriteRequest = {
+        command: WriterCommand.Write,
+        frame: fr.toPayload(),
+      };
+      const msg: WebsocketMessage<WriteRequest> = { type: "data", payload: writeReq };
+      const codec = new WSWriterCodec(baseCodec);
+      const encoded = codec.encode(msg);
+      expect(encoded[0]).toEqual(HIGH_PERF_SPECIAL_CHAR);
+      const decoded = codec.decode<WebsocketMessage<WriteRequest>>(encoded);
+      expect(decoded.payload?.command).toEqual(WriterCommand.Write);
+      const decodedFr = new Frame(decoded.payload?.frame);
+      expect(decodedFr.series[0].data).toEqual(fr.series[0].data);
+    });
+
+    it("should correctly e +d a WS write set authority request", () => {
+      const baseCodec = new Codec([1], [DataType.INT32]);
+      const writeReq: WriteRequest = {
+        command: WriterCommand.SetAuthority,
+        config: { authorities: [123] },
+      };
+      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);
+      const decoded = codec.decode(encoded);
+      expect(decoded).toEqual(msg);
+    });
+  });
+});

package/src/framer/codec.ts

@@ -0,0 +1,396 @@
+// Copyright 2024 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 { type WebsocketMessage } from "@synnaxlabs/freighter";
+import {
+  binary,
+  DataType,
+  type SeriesPayload,
+  TimeRange,
+  TimeStamp,
+} from "@synnaxlabs/x";
+import { type ZodSchema } from "zod";
+
+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, type WriteRequest } from "@/framer/writer";
+
+// For detailed information about the specifications,
+// please refer to the official RFC 0016 document.
+// Document here: docs/tech/rfc/0016-231001-frame-flight-protocol.md
+
+const seriesPldLength = (series: SeriesPayload): number =>
+  series.data.byteLength / series.dataType.density.valueOf();
+
+interface KeyedSeries extends SeriesPayload {
+  key: number;
+}
+
+const sortFramePayloadByKey = (framePayload: Payload): void => {
+  const { keys, series } = framePayload;
+  keys.forEach((key, index) => {
+    (series[index] as KeyedSeries).key = key;
+  });
+  series.sort((a, b) => (a as KeyedSeries).key - (b as KeyedSeries).key);
+  keys.sort((a, b) => a - b);
+  // @ts-expect-error - deleting static property keys.
+  series.forEach((ser) => delete (ser as KeyedSeries).key);
+};
+
+const ZERO_ALIGNMENTS_FLAG_POS = 5;
+const EQUAL_ALIGNMENTS_FLAG_POS = 4;
+const EQUAL_LENGTHS_FLAG_POS = 3;
+const EQUAL_TIME_RANGES_FLAG_POS = 2;
+const TIME_RANGES_ZERO_FLAG_POS = 1;
+const ALL_CHANNELS_PRESENT_FLAG_POS = 0;
+
+const TIMESTAMP_SIZE = DataType.TIMESTAMP.density.valueOf();
+const ALIGNMENT_SIZE = 8;
+const DATA_LENGTH_SIZE = 4;
+const KEY_SIZE = 4;
+const SEQ_NUM_SIZE = 4;
+const FLAGS_SIZE = 1;
+
+interface CodecState {
+  keys: channel.Keys;
+  keyDataTypes: Map<channel.Key, DataType>;
+  hasVariableDataTypes: boolean;
+}
+
+export class Codec {
+  contentType: string = "application/sy-framer";
+  private states: Map<number, CodecState> = new Map();
+  private currState: CodecState | undefined;
+  private seqNum: number = 0;
+
+  constructor(keys: channel.Keys = [], dataTypes: DataType[] = []) {
+    if (keys.length > 0 || dataTypes.length > 0) this.update(keys, dataTypes);
+  }
+
+  update(keys: channel.Keys, dataTypes: DataType[]): void {
+    this.seqNum++;
+    const state = {
+      keys,
+      keyDataTypes: new Map(),
+      hasVariableDataTypes: false,
+    };
+    keys.forEach((k, i) => {
+      const dt = dataTypes[i];
+      state.keyDataTypes.set(k, dt);
+      if (dt.isVariable) state.hasVariableDataTypes = true;
+    });
+    state.keys.sort();
+    this.states.set(this.seqNum, state);
+    this.currState = state;
+  }
+
+  private throwIfNotUpdated(op: string): void {
+    if (this.seqNum < 1)
+      throw new ValidationError(`
+      The codec has not been updated with a list of channels and data types.
+      Please call the update method before calling ${op}.
+      `);
+  }
+
+  encode(payload: unknown, startOffset: number = 0): Uint8Array {
+    this.throwIfNotUpdated("encode");
+    let src = payload as Payload;
+    if (payload != null && typeof payload === "object" && "toPayload" in payload)
+      src = (payload as Frame).toPayload();
+    sortFramePayloadByKey(src);
+    let currDataSize = -1;
+    let startTime: TimeStamp | undefined;
+    let endTime: TimeStamp | undefined;
+    let currAlignment: bigint | undefined;
+    let byteArraySize = startOffset + FLAGS_SIZE + SEQ_NUM_SIZE;
+    let equalLengthsFlag = !this.currState?.hasVariableDataTypes;
+    let equalTimeRangesFlag = true;
+    let timeRangesZeroFlag = true;
+    let channelFlag = true;
+    let equalAlignmentsFlag = true;
+    let zeroAlignmentsFlag = true;
+
+    if (src.keys.length !== this.currState?.keys.length) {
+      channelFlag = false;
+      byteArraySize += src.keys.length * KEY_SIZE;
+    }
+
+    src.series.forEach((series, i) => {
+      const pldLength = seriesPldLength(series);
+      const key = src.keys[i];
+      const dt = this.currState?.keyDataTypes.get(key);
+      if (dt == null)
+        throw new ValidationError(
+          `Channel ${key} was not provided in the list of channels when opening the writer`,
+        );
+      if (!dt.equals(series.dataType))
+        throw new ValidationError(
+          `Series data type of ${series.dataType.toString()} does not match the data type of ${dt.toString()} for channel ${key}`,
+        );
+
+      byteArraySize += series.data.byteLength;
+      if (currDataSize === -1) {
+        currDataSize = pldLength;
+        startTime = series.timeRange?.start;
+        endTime = series.timeRange?.end;
+        currAlignment = BigInt(series.alignment ?? 0n);
+        return;
+      }
+      if (currDataSize !== pldLength) equalLengthsFlag = false;
+      if (
+        startTime?.valueOf() !== series.timeRange?.start.valueOf() ||
+        endTime?.valueOf() !== series.timeRange?.end.valueOf()
+      )
+        equalTimeRangesFlag = false;
+      if (currAlignment !== BigInt(series.alignment ?? 0)) equalAlignmentsFlag = false;
+    });
+
+    timeRangesZeroFlag = equalTimeRangesFlag && startTime == null && endTime == null;
+
+    zeroAlignmentsFlag =
+      equalAlignmentsFlag && (currAlignment === undefined || currAlignment === 0n);
+
+    if (equalLengthsFlag) byteArraySize += DATA_LENGTH_SIZE;
+    else byteArraySize += src.keys.length * DATA_LENGTH_SIZE;
+
+    if (!timeRangesZeroFlag)
+      if (equalTimeRangesFlag) byteArraySize += TIMESTAMP_SIZE * 2;
+      else byteArraySize += src.keys.length * TIMESTAMP_SIZE * 2;
+
+    if (!zeroAlignmentsFlag)
+      if (equalAlignmentsFlag) byteArraySize += ALIGNMENT_SIZE;
+      else byteArraySize += src.keys.length * ALIGNMENT_SIZE;
+
+    const buffer = new Uint8Array(byteArraySize);
+    const view = new DataView(buffer.buffer);
+    let offset = startOffset;
+    buffer[offset] =
+      (Number(zeroAlignmentsFlag) << ZERO_ALIGNMENTS_FLAG_POS) |
+      (Number(equalAlignmentsFlag) << EQUAL_ALIGNMENTS_FLAG_POS) |
+      (Number(equalLengthsFlag) << EQUAL_LENGTHS_FLAG_POS) |
+      (Number(equalTimeRangesFlag) << EQUAL_TIME_RANGES_FLAG_POS) |
+      (Number(timeRangesZeroFlag) << TIME_RANGES_ZERO_FLAG_POS) |
+      (Number(channelFlag) << ALL_CHANNELS_PRESENT_FLAG_POS);
+    offset++;
+    view.setUint32(offset, this.seqNum, true);
+    offset += SEQ_NUM_SIZE;
+
+    if (equalLengthsFlag) {
+      view.setUint32(offset, currDataSize, true);
+      offset += DATA_LENGTH_SIZE;
+    }
+
+    if (equalTimeRangesFlag && !timeRangesZeroFlag) {
+      view.setBigUint64(offset, startTime?.valueOf() ?? 0n, true);
+      view.setBigUint64(offset, endTime?.valueOf() ?? 0n, true);
+      offset += TIMESTAMP_SIZE * 2;
+    }
+
+    if (equalAlignmentsFlag && !zeroAlignmentsFlag) {
+      view.setBigUint64(offset, currAlignment ?? 0n, true);
+      offset += ALIGNMENT_SIZE;
+    }
+
+    src.series.forEach((series, i) => {
+      if (!channelFlag) {
+        view.setUint32(offset, src.keys[i], true);
+        offset += KEY_SIZE;
+      }
+      if (!equalLengthsFlag) {
+        let seriesLengthOrSize = series.data.byteLength;
+        if (!series.dataType.isVariable) seriesLengthOrSize = seriesPldLength(series);
+        view.setUint32(offset, seriesLengthOrSize, true);
+        offset += DATA_LENGTH_SIZE;
+      }
+      buffer.set(new Uint8Array(series.data), offset);
+      offset += series.data.byteLength;
+      if (!equalTimeRangesFlag && !timeRangesZeroFlag) {
+        view.setBigUint64(offset, series.timeRange?.start.valueOf() ?? 0n, true);
+        view.setBigUint64(offset, series.timeRange?.end.valueOf() ?? 0n, true);
+        offset += TIMESTAMP_SIZE * 2;
+      }
+      if (!equalAlignmentsFlag && !zeroAlignmentsFlag) {
+        view.setBigUint64(offset, series.alignment ?? 0n, true);
+        offset += ALIGNMENT_SIZE;
+      }
+    });
+    return buffer;
+  }
+
+  decode(data: Uint8Array | ArrayBuffer, offset: number = 0): Payload {
+    this.throwIfNotUpdated("decode");
+    const src = data instanceof Uint8Array ? data : new Uint8Array(data);
+    const returnFrame: Payload = { keys: [], series: [] };
+    let index = offset;
+    let sizeRepresentation = 0;
+    let currSize = 0;
+    let startTime: TimeStamp | undefined;
+    let endTime: TimeStamp | undefined;
+    let currAlignment: bigint | undefined;
+
+    const view = new DataView(src.buffer, src.byteOffset, src.byteLength);
+    const zeroAlignmentsFlag = Boolean((src[index] >> ZERO_ALIGNMENTS_FLAG_POS) & 1);
+    const equalAlignmentsFlag = Boolean((src[index] >> EQUAL_ALIGNMENTS_FLAG_POS) & 1);
+    const sizeFlag = Boolean((src[index] >> EQUAL_LENGTHS_FLAG_POS) & 1);
+    const equalTimeRangesFlag = Boolean((src[index] >> EQUAL_TIME_RANGES_FLAG_POS) & 1);
+    const timeRangesZeroFlag = Boolean((src[index] >> TIME_RANGES_ZERO_FLAG_POS) & 1);
+    const channelFlag = Boolean((src[index] >> ALL_CHANNELS_PRESENT_FLAG_POS) & 1);
+    index++;
+
+    const seqNum = view.getUint32(index, true);
+    index += SEQ_NUM_SIZE;
+    const state = this.states.get(seqNum);
+    if (state == null) return returnFrame;
+
+    if (sizeFlag) {
+      if (index + DATA_LENGTH_SIZE > view.byteLength) return returnFrame;
+      sizeRepresentation = view.getUint32(index, true);
+      index += DATA_LENGTH_SIZE;
+    }
+
+    if (equalTimeRangesFlag && !timeRangesZeroFlag) {
+      if (index + TIMESTAMP_SIZE > view.byteLength) return returnFrame;
+      startTime = new TimeStamp(view.getBigUint64(index, true));
+      index += TIMESTAMP_SIZE;
+      endTime = new TimeStamp(view.getBigUint64(index, true));
+      index += TIMESTAMP_SIZE;
+    }
+
+    if (equalAlignmentsFlag && !zeroAlignmentsFlag) {
+      if (index + ALIGNMENT_SIZE > view.byteLength) return returnFrame;
+      currAlignment = view.getBigUint64(index, true);
+      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;
+      currSize = 0;
+      if (!sizeFlag) {
+        if (index + DATA_LENGTH_SIZE > view.byteLength) return;
+        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;
+      }
+      const currSeries: SeriesPayload = {
+        dataType,
+        data: src.slice(index, index + dataByteLength).buffer,
+      };
+      index += dataByteLength;
+      if (!equalTimeRangesFlag && !timeRangesZeroFlag) {
+        if (index + TIMESTAMP_SIZE * 2 > view.byteLength) return;
+        const start = view.getBigUint64(index, true);
+        index += TIMESTAMP_SIZE;
+        const end = view.getBigUint64(index, true);
+        index += TIMESTAMP_SIZE;
+        currSeries.timeRange = new TimeRange({ start, end });
+      } else if (!timeRangesZeroFlag)
+        currSeries.timeRange = new TimeRange({
+          start: startTime?.valueOf() ?? 0n,
+          end: endTime?.valueOf() ?? 0n,
+        });
+      else currSeries.timeRange = new TimeRange({ start: 0n, end: 0n });
+
+      if (!equalAlignmentsFlag && !zeroAlignmentsFlag) {
+        if (index + ALIGNMENT_SIZE > view.byteLength) return;
+        currAlignment = view.getBigUint64(index, true);
+        index += ALIGNMENT_SIZE;
+        currSeries.alignment = currAlignment;
+      } else if (!zeroAlignmentsFlag) currSeries.alignment = currAlignment;
+      else currSeries.alignment = 0n;
+
+      returnFrame.series.push(currSeries);
+    });
+    return returnFrame;
+  }
+}
+
+export const LOW_PER_SPECIAL_CHAR = 254;
+const LOW_PERF_SPECIAL_CHAR_BUF = new Uint8Array([LOW_PER_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";
+
+export class WSWriterCodec 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 {
+    const pld = payload as WebsocketMessage<WriteRequest>;
+    if (pld.type == "close" || pld.payload?.command != WriterCommand.Write) {
+      const data = this.lowPerfCodec.encode(pld);
+      const b = new Uint8Array({ length: data.byteLength + 1 });
+      b.set(LOW_PERF_SPECIAL_CHAR_BUF, 0);
+      b.set(new Uint8Array(data), 1);
+      return b;
+    }
+    const data = this.base.encode(pld.payload?.frame, 1);
+    data.set(HIGH_PERF_SPECIAL_CHAR_BUF, 0);
+    return data;
+  }
+
+  decode<P>(data: Uint8Array | ArrayBuffer, schema?: ZodSchema<P>): P {
+    const dv = new DataView(data instanceof Uint8Array ? data.buffer : data);
+    const codec = dv.getUint8(0);
+    if (codec === LOW_PER_SPECIAL_CHAR)
+      return this.lowPerfCodec.decode(data.slice(1), schema);
+    const v: WebsocketMessage<WriteRequest> = { type: "data" };
+    const frame = this.base.decode(data, 1);
+    v.payload = { command: WriterCommand.Write, frame };
+    return v as P;
+  }
+}
+
+export class WSStreamerCodec 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 {
+    return this.lowPerfCodec.encode(payload);
+  }
+
+  decode<P>(data: Uint8Array | ArrayBuffer, schema?: ZodSchema<P>): P {
+    const dv = new DataView(data instanceof Uint8Array ? data.buffer : data);
+    const codec = dv.getUint8(0);
+    if (codec === LOW_PER_SPECIAL_CHAR)
+      return this.lowPerfCodec.decode(data.slice(1), schema);
+    const v: WebsocketMessage<StreamerResponse> = {
+      type: "data",
+      payload: { frame: this.base.decode(data, 1) },
+    };
+    return v as P;
+  }
+}