@synnaxlabs/client 0.2.0 → 0.13.5

package/src/framer/iterator.ts

@@ -0,0 +1,240 @@
+// Copyright 2023 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 { errorZ, type Stream, type StreamClient } from "@synnaxlabs/freighter";
+import {
+  type CrudeTimeSpan,
+  type CrudeTimeStamp,
+  TimeRange,
+  TimeSpan,
+  TimeStamp,
+} from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type Params } from "@/channel/payload";
+import { type Retriever } from "@/channel/retriever";
+import { BackwardFrameAdapter } from "@/framer/adapter";
+import { Frame, frameZ } from "@/framer/frame";
+import { StreamProxy } from "@/framer/streamProxy";
+
+export const AUTO_SPAN = new TimeSpan(-1);
+
+enum Command {
+  Open = 0,
+  Next = 1,
+  Prev = 2,
+  SeekFirst = 3,
+  SeekLast = 4,
+  SeekLE = 5,
+  SeekGE = 6,
+  Valid = 7,
+  Error = 8,
+}
+
+enum ResponseVariant {
+  None = 0,
+  Ack = 1,
+  Data = 2,
+}
+
+const reqZ = z.object({
+  command: z.nativeEnum(Command),
+  span: TimeSpan.z.optional(),
+  bounds: TimeRange.z.optional(),
+  stamp: TimeStamp.z.optional(),
+  keys: z.number().array().optional(),
+});
+
+type Request = z.infer<typeof reqZ>;
+
+const resZ = z.object({
+  variant: z.nativeEnum(ResponseVariant),
+  ack: z.boolean(),
+  command: z.nativeEnum(Command),
+  error: errorZ.optional().nullable(),
+  frame: frameZ.optional(),
+});
+
+/**
+ * Used to iterate over a clusters telemetry in time-order. It should not be
+ * instantiated directly, and should instead be instantiated via the SegmentClient.
+ *
+ * Using an iterator is ideal when querying/processing large ranges of data, but
+ * is relatively complex and difficult to use. If you're looking to retrieve
+ *  telemetry between two timestamps, see the SegmentClient.read method.
+ */
+export class Iterator {
+  private static readonly ENDPOINT = "/frame/iterate";
+  private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
+  private readonly adapter: BackwardFrameAdapter;
+  value: Frame;
+
+  private constructor(
+    stream: Stream<typeof reqZ, typeof resZ>,
+    adapter: BackwardFrameAdapter,
+  ) {
+    this.stream = new StreamProxy("Iterator", stream);
+    this.value = new Frame();
+    this.adapter = adapter;
+  }
+
+  /**
+   * Opens the iterator, configuring it to iterate over the telemetry in the
+   * channels with the given keys within the provided time range.
+   *
+   * @param tr - The time range to iterate over.
+   * @param keys - The keys of the channels to iterate over.
+   */
+  static async _open(
+    tr: TimeRange,
+    channels: Params,
+    retriever: Retriever,
+    client: StreamClient,
+  ): Promise<Iterator> {
+    const adapter = await BackwardFrameAdapter.open(retriever, channels);
+    const stream = await client.stream(Iterator.ENDPOINT, reqZ, resZ);
+    const iter = new Iterator(stream, adapter);
+    await iter.execute({ command: Command.Open, keys: adapter.keys, bounds: tr });
+    return iter;
+  }
+
+  /**
+   * Reads the next time span of telemetry for each channel in the iterator.
+   *
+   * @param span - The time span to read. A negative span is equivalent
+   * to calling prev with the absolute value of the span. If the span is
+   * AUTO_SPAN, the iterator will automatically determine the span to read.
+   * This is useful for iterating over an entire range efficiently.
+   *
+   * @returns false if a segment satisfying the request can't be found for a
+   * particular channel or the iterator has accumulated an error.
+   */
+  async next(span: CrudeTimeSpan = AUTO_SPAN): Promise<boolean> {
+    return await this.execute({ command: Command.Next, span: new TimeSpan(span) });
+  }
+
+  /**
+   * Reads the previous time span of telemetry for each channel in the iterator.
+   *
+   * @param span - The time span to read. A negative span is equivalent
+   * to calling next with the absolute value of the span. If the span is
+   * AUTO_SPAN, the iterator will automatically determine the span to read.
+   * This is useful for iterating over an entire range efficiently.
+   *
+   * @returns false if a segment satisfying the request can't be found for a particular
+   * channel or the iterator has accumulated an error.
+   */
+  async prev(span: CrudeTimeSpan = AUTO_SPAN): Promise<boolean> {
+    return await this.execute({ command: Command.Prev, span: new TimeSpan(span) });
+  }
+
+  /**
+   * Seeks the iterator to the first segment in the time range, but does not read
+   * it. Also invalidates the iterator. The iterator will not be considered valid
+   * until a call to next or prev.
+   *
+   * @returns false if the iterator is not pointing to a valid segment for a particular
+   * channel or has accumulated an error.
+   */
+  async seekFirst(): Promise<boolean> {
+    return await this.execute({ command: Command.SeekFirst });
+  }
+
+  /** Seeks the iterator to the last segment in the time range, but does not read it.
+   * Also invalidates the iterator. The iterator will not be considered valid
+   * until a call to next or prev.
+   *
+   * @returns false if the iterator is not pointing to a valid segment for a particular
+   * channel or has accumulated an error.
+   */
+  async seekLast(): Promise<boolean> {
+    return await this.execute({ command: Command.SeekLast });
+  }
+
+  /**
+   * Seeks the iterator to the first segment whose start is less than or equal to
+   * the provided timestamp. Also invalidates the iterator. The iterator will not be
+   * considered valid until a call to next or prev.
+   *
+   * @returns false if the iterator is not pointing to a valid segment for a particular
+   * channel or has accumulated an error.
+   */
+  async seekLE(stamp: CrudeTimeStamp): Promise<boolean> {
+    return await this.execute({ command: Command.SeekLE, stamp: new TimeStamp(stamp) });
+  }
+
+  /**
+   * Seeks the iterator to the first segment whose start is greater than or equal to
+   * the provided timestamp. Also invalidates the iterator. The iterator will not be
+   * considered valid until a call to next or prev.
+   *
+   * @returns false if the iterator is not pointing to a valid segment for a particular
+   * channel or has accumulated an error.
+   */
+  async seekGE(stamp: CrudeTimeStamp): Promise<boolean> {
+    return await this.execute({ command: Command.SeekGE, stamp: new TimeStamp(stamp) });
+  }
+
+  /**
+   * @returns true if the iterator value contains a valid segment, and fale otherwise.
+   * valid most commonly returns false when the iterator is exhausted or has
+   * accumulated an error.
+   */
+  async valid(): Promise<boolean> {
+    return await this.execute({ command: Command.Valid });
+  }
+
+  /**
+   * Closes the iterator. An iterator MUST be closed after use, and this method
+   * should probably be placed in a 'finally' block. If the iterator is not closed,
+   * it may leak resources.
+   */
+  async close(): Promise<void> {
+    await this.stream.closeAndAck();
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<Frame, any, undefined> {
+    return new IteratorIterator(this);
+  }
+
+  private async execute(request: Request): Promise<boolean> {
+    this.stream.send(request);
+    this.value = new Frame();
+    while (true) {
+      const res = await this.stream.receive();
+      if (res.variant === ResponseVariant.Ack) return res.ack;
+      this.value.push(this.adapter.adapt(new Frame(res.frame)));
+    }
+  }
+}
+
+class IteratorIterator implements AsyncIterator<Frame> {
+  private readonly iter: Iterator;
+  private open: boolean = false;
+
+  constructor(iter: Iterator) {
+    this.iter = iter;
+  }
+
+  async next(): Promise<IteratorResult<Frame, any>> {
+    try {
+      let ok = true;
+      if (!this.open) {
+        if (!(await this.iter.seekFirst())) ok = false;
+        this.open = true;
+      }
+      if (!(await this.iter.next())) ok = false;
+      if (!ok) await this.iter.close();
+      return { done: !ok, value: this.iter.value };
+    } catch (e) {
+      await this.iter.close();
+      throw e;
+    }
+  }
+}

package/src/framer/streamProxy.ts

@@ -0,0 +1,59 @@
+// Copyright 2023 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 Stream, EOF } from "@synnaxlabs/freighter";
+import { type z } from "zod";
+
+import { UnexpectedError } from "@/errors";
+
+export class StreamProxy<RQ extends z.ZodTypeAny, RS extends z.ZodTypeAny> {
+  readonly name: string;
+  private readonly stream: Stream<RQ, RS>;
+
+  constructor(name: string, stream: Stream<RQ, RS>) {
+    this.stream = stream;
+    this.name = name;
+  }
+
+  async receive(): Promise<z.output<RS>> {
+    const [res, err] = await this.stream.receive();
+    if (err != null) throw err;
+    return res;
+  }
+
+  received(): boolean {
+    return this.stream.received();
+  }
+
+  async closeAndAck(): Promise<void> {
+    this.stream.closeSend();
+    const [res, err] = await this.stream.receive();
+    if (res != null)
+      throw new UnexpectedError(
+        `${this.name} received unexpected response on closure. 
+        Please report this error to the Synnax team.`,
+      );
+    if (err == null)
+      throw new UnexpectedError(
+        `${this.name} received unexpected null error on closure. 
+        Please report this error to Synnax team.
+      `,
+      );
+    if (!(err instanceof EOF)) throw err;
+  }
+
+  closeSend(): void {
+    this.stream.closeSend();
+  }
+
+  send(req: z.input<RQ>): void {
+    const err = this.stream.send(req);
+    if (err != null) throw err;
+  }
+}

package/src/framer/streamer.spec.ts

@@ -0,0 +1,42 @@
+// Copyright 2023 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 { DataType, Rate, TimeStamp } from "@synnaxlabs/x";
+import { describe, test, expect } from "vitest";
+
+import { type channel } from "@/channel";
+import { newClient } from "@/setupspecs";
+
+const client = newClient();
+
+const newChannel = async (): Promise<channel.Channel> =>
+  await client.channels.create({
+    name: "test",
+    leaseholder: 1,
+    rate: Rate.hz(25),
+    dataType: DataType.FLOAT64,
+  });
+
+describe("Streamer", () => {
+  test("happy path", async () => {
+    const ch = await newChannel();
+    const streamer = await client.telem.newStreamer(ch.key);
+    const writer = await client.telem.newWriter({
+      start: TimeStamp.now(),
+      channels: ch.key,
+    });
+    try {
+      await writer.write(ch.key, new Float64Array([1, 2, 3]));
+    } finally {
+      await writer.close();
+    }
+    const d = await streamer.read();
+    expect(d.get(ch.key)[0].data).toEqual(new Float64Array([1, 2, 3]));
+  });
+});

package/src/framer/streamer.ts

@@ -0,0 +1,86 @@
+// Copyright 2023 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 { errorZ, type Stream, type StreamClient } from "@synnaxlabs/freighter";
+import { TimeStamp, type CrudeTimeStamp } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type Key, type Params } from "@/channel/payload";
+import { type Retriever } from "@/channel/retriever";
+import { BackwardFrameAdapter } from "@/framer/adapter";
+import { Frame, frameZ } from "@/framer/frame";
+import { StreamProxy } from "@/framer/streamProxy";
+
+const reqZ = z.object({
+  start: TimeStamp.z.optional(),
+  keys: z.number().array(),
+});
+
+const resZ = z.object({
+  frame: frameZ,
+  error: errorZ.optional().nullable(),
+});
+
+const ENDPOINT = "/frame/stream";
+
+export class Streamer implements AsyncIterator<Frame>, AsyncIterable<Frame> {
+  private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
+  private readonly adapter: BackwardFrameAdapter;
+
+  private constructor(
+    stream: Stream<typeof reqZ, typeof resZ>,
+    adapter: BackwardFrameAdapter,
+  ) {
+    this.stream = new StreamProxy("Streamer", stream);
+    this.adapter = adapter;
+  }
+
+  get keys(): Key[] {
+    return this.adapter.keys;
+  }
+
+  static async _open(
+    start: CrudeTimeStamp,
+    channels: Params,
+    retriever: Retriever,
+    client: StreamClient,
+  ): Promise<Streamer> {
+    const adapter = await BackwardFrameAdapter.open(retriever, channels);
+    const stream = await client.stream(ENDPOINT, reqZ, resZ);
+    const streamer = new Streamer(stream, adapter);
+    stream.send({ start: new TimeStamp(start), keys: adapter.keys });
+    return streamer;
+  }
+
+  async next(): Promise<IteratorResult<Frame, any>> {
+    try {
+      const frame = await this.read();
+      return { done: false, value: frame };
+    } catch (EOF) {
+      return { done: true, value: undefined };
+    }
+  }
+
+  async read(): Promise<Frame> {
+    return this.adapter.adapt(new Frame((await this.stream.receive()).frame));
+  }
+
+  async update(params: Params): Promise<void> {
+    await this.adapter.update(params);
+    this.stream.send({ keys: this.adapter.keys });
+  }
+
+  close(): void {
+    this.stream.closeSend();
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<Frame, any, undefined> {
+    return this;
+  }
+}

package/src/framer/writer.spec.ts

@@ -0,0 +1,52 @@
+// Copyright 2023 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 { DataType, Rate, TimeRange, TimeStamp } from "@synnaxlabs/x";
+import { describe, expect, test } from "vitest";
+
+import { type channel } from "@/channel";
+import { newClient } from "@/setupspecs";
+import { randomSeries } from "@/util/telem";
+
+const client = newClient();
+
+const newChannel = async (): Promise<channel.Channel> => {
+  return await client.channels.create({
+    name: "test",
+    leaseholder: 1,
+    rate: Rate.hz(1),
+    dataType: DataType.FLOAT64,
+  });
+};
+
+describe("Writer", () => {
+  describe("Writer", () => {
+    test("basic write", async () => {
+      const ch = await newChannel();
+      const writer = await client.telem.newWriter({ start: 0, channels: ch.key });
+      try {
+        await writer.write(ch.key, randomSeries(10, ch.dataType));
+        await writer.commit();
+      } finally {
+        await writer.close();
+      }
+      expect(true).toBeTruthy();
+    });
+  });
+  describe("Client", () => {
+    test("Client - basic write", async () => {
+      const ch = await newChannel();
+      const data = randomSeries(10, ch.dataType);
+      await client.telem.write(ch.key, TimeStamp.seconds(1), data);
+      const res = await client.telem.read(TimeRange.MAX, ch.key);
+      expect(res.length).toEqual(data.length);
+      expect(res.data).toEqual(data);
+    });
+  });
+});