@synnaxlabs/client 0.2.1 → 0.13.6

package/src/framer/writer.ts

@@ -0,0 +1,236 @@
+// 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.
+
+/* eslint-disable @typescript-eslint/no-throw-literal */
+import type { Stream, StreamClient } from "@synnaxlabs/freighter";
+import { decodeError, errorZ } from "@synnaxlabs/freighter";
+import {
+  type NativeTypedArray,
+  Series,
+  TimeStamp,
+  type CrudeTimeStamp,
+  toArray,
+} from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type Key, type KeyOrName, type Params } from "@/channel/payload";
+import { type Retriever } from "@/channel/retriever";
+import { Authority } from "@/control/authority";
+import {
+  subjectZ as controlSubjectZ,
+  type Subject as ControlSubject,
+} from "@/control/state";
+import { ForwardFrameAdapter } from "@/framer/adapter";
+import { type CrudeFrame, Frame, frameZ } from "@/framer/frame";
+import { StreamProxy } from "@/framer/streamProxy";
+
+enum Command {
+  Open = 0,
+  Write = 1,
+  Commit = 2,
+  Error = 3,
+  SetAuthority = 4,
+}
+
+const netConfigZ = z.object({
+  start: TimeStamp.z.optional(),
+  controlSubject: controlSubjectZ.optional(),
+  keys: z.number().array(),
+  authorities: Authority.z.array().optional(),
+});
+
+const reqZ = z.object({
+  command: z.nativeEnum(Command),
+  config: netConfigZ.optional(),
+  frame: frameZ.optional(),
+});
+
+type Request = z.infer<typeof reqZ>;
+
+const resZ = z.object({
+  ack: z.boolean(),
+  command: z.nativeEnum(Command),
+  error: errorZ.optional().nullable(),
+});
+
+type Response = z.infer<typeof resZ>;
+
+export interface WriterConfig {
+  start: CrudeTimeStamp;
+  channels: Params;
+  controlSubject?: ControlSubject;
+  authorities?: Authority | Authority[];
+}
+
+/**
+ * Writer is used to write telemetry to a set of channels in time order.
+ * It should not be instantiated directly, and should instead be instantited via the
+ * FramerClient {@link FrameClient#openWriter}.
+ *
+ * The writer is a streaming protocol that is heavily optimized for prerformance. This
+ * comes at the cost of icnreased complexity, and should only be used directly when
+ * writing large volumes of data (such as recording telemetry from a sensor or ingsting
+ * data froma file). Simpler methods (such as the frame client's write method) should
+ * be used for most use cases.
+ *
+ * The protocol is as follows:
+ *
+ * 1. The writer is opened with a starting timestamp and a list of channel keys. The
+ * writer will fail to open if the starting timstamp overlaps with any existing telemetry
+ * for any channels specified. If the writer opens successfuly, the caller is then
+ * free to write frames to the writer.
+ *
+ * 2. To write a frame, the caller can use the write method and follow the validation
+ * rules described in its method's documentation. This process is asynchronous, meaning
+ * that write calls may return before teh frame has been written to the cluster. This
+ * also means that the writer can accumulate an error after write is called. If the writer
+ * accumulates an erorr, all subsequent write and commit calls will return False. The
+ * caller can check for errors by calling the error mehtod, which returns the accumulated
+ * error and resets the writer for future use. The caller can also check for errors by
+ * closing the writer, which will throw any accumulated error.
+ *
+ * 3. To commit the written frames to the cluster, the caller can call the commit method.
+ * Unlike write, commit is synchronous, meaning that it will not return until the frames
+ * have been written to the cluster. If the writer has accumulated an erorr, commit will
+ * return false. After the caller acknowledges the erorr, they can attempt to commit again.
+ * Commit can be called several times throughout a writer's lifetime, and will only
+ * commit the frames that have been written since the last commit.
+ *
+ * 4. A writer MUST be closed after use in order to prevent resource leaks. Close should
+ * typically be called in a 'finally' block. If the writer has accumulated an error,
+ * close will throw the error.
+ */
+export class Writer {
+  private static readonly ENDPOINT = "/frame/write";
+  private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
+  private readonly adapter: ForwardFrameAdapter;
+
+  private constructor(
+    stream: Stream<typeof reqZ, typeof resZ>,
+    adapter: ForwardFrameAdapter,
+  ) {
+    this.stream = new StreamProxy("Writer", stream);
+    this.adapter = adapter;
+  }
+
+  static async _open(
+    retriever: Retriever,
+    client: StreamClient,
+    {
+      channels,
+      authorities = Authority.ABSOLUTE,
+      controlSubject: subject,
+      start,
+    }: WriterConfig,
+  ): Promise<Writer> {
+    const adapter = await ForwardFrameAdapter.open(retriever, channels);
+    const stream = await client.stream(Writer.ENDPOINT, reqZ, resZ);
+    const writer = new Writer(stream, adapter);
+    await writer.execute({
+      command: Command.Open,
+      config: {
+        start: new TimeStamp(start),
+        keys: adapter.keys,
+        controlSubject: subject,
+        authorities: toArray(authorities),
+      },
+    });
+    return writer;
+  }
+
+  async write(channel: KeyOrName, data: NativeTypedArray): Promise<boolean>;
+
+  async write(frame: CrudeFrame): Promise<boolean>;
+
+  /**
+   * Writes the given frame to the database.
+   *
+   * @param frame - The frame to write to the database. The frame must:
+   *
+   *    1. Have exactly one array for each key in the list of keys provided to the
+   *    writer's open method.
+   *    2. Have equal length arrays for each key.
+   *    3. When writing to an index (i.e. TimeStamp) channel, the values must be
+   *    monotonically increasing.
+   *
+   * @returns false if the writer has accumulated an error. In this case, the caller
+   * should acknowledge the error by calling the error method or closing the writer.
+   */
+  async write(
+    frame: CrudeFrame | KeyOrName,
+    data?: NativeTypedArray,
+  ): Promise<boolean> {
+    const isKeyOrName = ["string", "number"].includes(typeof frame);
+    if (isKeyOrName) {
+      frame = new Frame(frame, new Series(data as NativeTypedArray));
+    }
+    frame = this.adapter.adapt(new Frame(frame));
+    // @ts-expect-error
+    this.stream.send({ command: Command.Write, frame: frame.toPayload() });
+    return true;
+  }
+
+  async setAuthority(value: Record<Key, Authority>): Promise<boolean> {
+    const res = await this.execute({
+      command: Command.SetAuthority,
+      config: {
+        keys: Object.keys(value).map((k) => Number(k)),
+        authorities: Object.values(value),
+      },
+    });
+    return res.ack;
+  }
+
+  /**
+   * Commits the written frames to the database. Commit is synchronous, meaning that it
+   * will not return until all frames have been commited to the database.
+   *
+   * @returns false if the commit failed due to an error. In this case, the caller
+   * 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 (this.errorAccumulated) 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> {
+    this.stream.send({ command: Command.Error });
+    const res = await this.execute({ command: Command.Error });
+    return res.error != null ? decodeError(res.error) : null;
+  }
+
+  /**
+   * Closes the writer, raising any accumulated error encountered during operation.
+   * A writer MUST be closed after use, and this method should probably be placed
+   * in a 'finally' block.
+   */
+  async close(): Promise<void> {
+    await this.stream.closeAndAck();
+  }
+
+  async execute(req: Request): Promise<Response> {
+    // @ts-expect-error
+    this.stream.send(req);
+    while (true) {
+      const res = await this.stream.receive();
+      if (res.command === req.command) return res;
+      console.warn("writer received unexpected response", res);
+    }
+  }
+
+  private get errorAccumulated(): boolean {
+    return this.stream.received();
+  }
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// 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.
+
+export * from "@/channel";
+export { default as Synnax, synnaxPropsZ } from "@/client";
+export type { SynnaxProps } from "@/client";
+export * from "@/connection";
+export { Channel } from "@/channel/client";
+export {
+  AuthError,
+  ContiguityError,
+  GeneralError,
+  ParseError,
+  QueryError,
+  RouteError,
+  UnexpectedError,
+  ValidationError,
+} from "@/errors";
+export { framer } from "@/framer";
+export { Frame } from "@/framer/frame";
+export { ontology } from "@/ontology";
+export { control } from "@/control";
+export { Authority } from "@/control/authority";
+export {
+  DataType,
+  Density,
+  Rate,
+  Series,
+  TimeRange,
+  TimeSpan,
+  TimeStamp,
+} from "@synnaxlabs/x";
+export type {
+  NativeTypedArray,
+  CrudeDataType,
+  CrudeDensity,
+  CrudeRate,
+  CrudeSize,
+  CrudeTimeSpan,
+  CrudeTimeStamp,
+  SampleValue,
+  TimeStampStringFormat,
+  TZInfo,
+} from "@synnaxlabs/x";
+export { workspace } from "@/workspace";
+export { ranger } from "@/ranger";
+export { label } from "@/label";

package/src/label/client.ts

@@ -0,0 +1,103 @@
+// 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 UnaryClient } from "@synnaxlabs/freighter";
+import { type AsyncTermSearcher } from "@synnaxlabs/x";
+
+import { type framer } from "@/framer";
+import { type Key, type Label, labelZ } from "@/label/payload";
+import { Retriever } from "@/label/retriever";
+import { Writer, type NewLabelPayload } from "@/label/writer";
+import { type ontology } from "@/ontology";
+import { signals } from "@/signals";
+
+const LABEL_SET_NAME = "sy_label_set";
+const LABEL_DELETE_NAME = "sy_label_delete";
+
+export class Client implements AsyncTermSearcher<string, Key, Label> {
+  private readonly retriever: Retriever;
+  private readonly writer: Writer;
+  private readonly frameClient: framer.Client;
+
+  constructor(client: UnaryClient, frameClient: framer.Client) {
+    this.writer = new Writer(client);
+    this.retriever = new Retriever(client);
+    this.frameClient = frameClient;
+  }
+
+  async search(term: string): Promise<Label[]> {
+    return await this.retriever.search(term);
+  }
+
+  async retrieve(key: Key): Promise<Label>;
+
+  async retrieve(keys: Key[]): Promise<Label[]>;
+
+  async retrieve(keys: Key | Key[]): Promise<Label | Label[]> {
+    const isMany = Array.isArray(keys);
+    const res = await this.retriever.retrieve(keys);
+    return isMany ? res : res[0];
+  }
+
+  async retrieveFor(id: ontology.ID): Promise<Label[]> {
+    return await this.retriever.retrieveFor(id);
+  }
+
+  async label(id: ontology.ID, labels: Key[]): Promise<void> {
+    await this.writer.set(id, labels);
+  }
+
+  async removeLabels(id: ontology.ID, labels: Key[]): Promise<void> {
+    await this.writer.remove(id, labels);
+  }
+
+  async page(offset: number, limit: number): Promise<Label[]> {
+    return await this.retriever.page(offset, limit);
+  }
+
+  async create(label: NewLabelPayload): Promise<Label>;
+
+  async create(labels: NewLabelPayload[]): Promise<Label[]>;
+
+  async create(labels: NewLabelPayload | NewLabelPayload[]): Promise<Label | Label[]> {
+    const isMany = Array.isArray(labels);
+    const res = await this.writer.create(labels);
+    return isMany ? res : res[0];
+  }
+
+  async delete(key: Key): Promise<void>;
+
+  async delete(keys: Key[]): Promise<void>;
+
+  async delete(keys: Key | Key[]): Promise<void> {
+    await this.writer.delete(keys);
+  }
+
+  async openChangeTracker(): Promise<signals.Observable<string, Label>> {
+    return await signals.Observable.open<string, Label>(
+      this.frameClient,
+      LABEL_SET_NAME,
+      LABEL_DELETE_NAME,
+      decodeChanges,
+    );
+  }
+}
+
+const decodeChanges: signals.Decoder<string, Label> = (variant, data) => {
+  if (variant === "delete")
+    return data.toUUIDs().map((v) => ({
+      variant,
+      key: v,
+    }));
+  return data.parseJSON(labelZ).map((l) => ({
+    variant,
+    key: l.key,
+    value: l,
+  }));
+};

package/src/label/external.ts

@@ -0,0 +1,13 @@
+// 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.
+
+export * from "@/label/client";
+export * from "@/label/writer";
+export * from "@/label/retriever";
+export * from "@/label/payload";

package/src/label/index.ts

@@ -0,0 +1,10 @@
+// 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.
+
+export * as label from "@/label/external";

package/src/label/label.spec.ts

@@ -0,0 +1,51 @@
+// 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 { describe, expect, it } from "vitest";
+
+import { label } from "@/label";
+import { newClient } from "@/setupspecs";
+
+const client = newClient();
+
+describe("Label", () => {
+  describe("create", () => {
+    it("should create a label", async () => {
+      const v = await client.labels.create({ name: "Label", color: "#E774D0" });
+      expect(v.key).not.toHaveLength(0);
+    });
+  });
+
+  describe("retrieve", () => {
+    it("should retrieve a label by its key", async () => {
+      const v = await client.labels.create({ name: "Label", color: "#E774D0" });
+      const retrieved = await client.labels.retrieve(v.key);
+      expect(retrieved).toEqual(v);
+    });
+  });
+
+  describe("delete", () => {
+    it("should delete a label by its key", async () => {
+      const v = await client.labels.create({ name: "Label", color: "#E774D0" });
+      await client.labels.delete(v.key);
+      await expect(async () => await client.labels.retrieve(v.key)).rejects.toThrow();
+    });
+  });
+
+  describe("label", () => {
+    it("should set a label on an item", async () => {
+      const l1 = await client.labels.create({ name: "Label One", color: "#E774D)" });
+      const l2 = await client.labels.create({ name: "Label Two", color: "#E774D)" });
+      await client.labels.label(label.ontologyID(l1.key), [l2.key]);
+      const labels = await client.labels.retrieveFor(label.ontologyID(l1.key));
+      expect(labels).toHaveLength(1);
+      expect(labels[0].key).toEqual(l2.key);
+    });
+  });
+});

package/src/label/payload.ts

@@ -0,0 +1,29 @@
+// 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 { z } from "zod";
+
+import { ontology } from "@/ontology";
+
+export const keyZ = z.string().uuid();
+
+export type Key = z.infer<typeof keyZ>;
+
+export type Params = Key | Key[];
+
+export const labelZ = z.object({
+  key: keyZ,
+  name: z.string().min(1),
+  color: z.string(),
+});
+
+export type Label = z.infer<typeof labelZ>;
+
+export const ontologyID = (key: Key): ontology.ID =>
+  new ontology.ID({ type: "label", key });

package/src/label/retriever.ts

@@ -0,0 +1,65 @@
+// 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 UnaryClient } from "@synnaxlabs/freighter";
+import { toArray } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { keyZ, type Label, labelZ, type Params } from "@/label/payload";
+import { ontology } from "@/ontology";
+
+const reqZ = z.object({
+  keys: keyZ.array().optional(),
+  for: ontology.idZ.optional(),
+  search: z.string().optional(),
+  offset: z.number().optional(),
+  limit: z.number().optional(),
+});
+
+type Request = z.infer<typeof reqZ>;
+
+const resZ = z.object({
+  labels: labelZ.array().optional().default([]),
+});
+
+export class Retriever {
+  private static readonly ENDPOINT = "/label/retrieve";
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async retrieve(params: Params): Promise<Label[]> {
+    const normalized = toArray(params);
+    return await this.execute({ keys: normalized });
+  }
+
+  async retrieveFor(id: ontology.ID): Promise<Label[]> {
+    return await this.execute({ for: id });
+  }
+
+  async search(term: string): Promise<Label[]> {
+    return await this.execute({ search: term });
+  }
+
+  async page(offset: number, limit: number): Promise<Label[]> {
+    return await this.execute({ offset, limit });
+  }
+
+  private async execute(req: Request): Promise<Label[]> {
+    const [res, err] = await this.client.send<typeof reqZ, typeof resZ>(
+      Retriever.ENDPOINT,
+      req,
+      resZ,
+    );
+    if (err != null) throw err;
+    return res.labels;
+  }
+}

package/src/label/writer.ts

@@ -0,0 +1,90 @@
+// 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 { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { toArray } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type Key, keyZ, type Label, labelZ } from "@/label/payload";
+import { ontology } from "@/ontology";
+
+export const newLabelPayloadZ = labelZ.extend({ key: keyZ.optional() });
+
+export type NewLabelPayload = z.infer<typeof newLabelPayloadZ>;
+
+const createReqZ = z.object({
+  labels: newLabelPayloadZ.array(),
+});
+
+const createResZ = z.object({
+  labels: labelZ.array(),
+});
+
+const deleteReqZ = z.object({
+  keys: keyZ.array(),
+});
+
+const setReqZ = z.object({
+  id: ontology.idZ,
+  labels: keyZ.array(),
+});
+
+const removeReqZ = setReqZ;
+
+const emptyResZ = z.object({});
+
+const CREATE_ENDPOINT = "/label/create";
+const DELETE_ENDPOINT = "/label/delete";
+const SET_ENDPOINT = "/label/set";
+const REMOVE_ENDPOINT = "/label/remove";
+
+export class Writer {
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async create(labels: NewLabelPayload | NewLabelPayload[]): Promise<Label[]> {
+    const res = await sendRequired<typeof createReqZ, typeof createResZ>(
+      this.client,
+      CREATE_ENDPOINT,
+      { labels: toArray(labels) },
+      createResZ,
+    );
+    return res.labels;
+  }
+
+  async delete(keys: Key | Key[]): Promise<void> {
+    await sendRequired<typeof deleteReqZ, typeof emptyResZ>(
+      this.client,
+      DELETE_ENDPOINT,
+      { keys: toArray(keys) },
+      emptyResZ,
+    );
+  }
+
+  async set(id: ontology.ID, labels: Key[]): Promise<void> {
+    await sendRequired<typeof setReqZ, typeof emptyResZ>(
+      this.client,
+      SET_ENDPOINT,
+      { id, labels },
+      emptyResZ,
+    );
+  }
+
+  async remove(id: ontology.ID, labels: Key[]): Promise<void> {
+    await sendRequired<typeof removeReqZ, typeof emptyResZ>(
+      this.client,
+      CREATE_ENDPOINT,
+      { id, labels },
+      emptyResZ,
+    );
+  }
+}