@synnaxlabs/client 0.2.1 → 0.13.6

package/src/auth/auth.ts

@@ -0,0 +1,83 @@
+// 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 { Middleware, UnaryClient } from "@synnaxlabs/freighter";
+import { z } from "zod";
+
+import { AuthError } from "@/errors";
+import { user } from "@/user";
+
+export const tokenMiddleware =
+  (token: () => Promise<string>): Middleware =>
+  async (md, next) => {
+    try {
+      const tk = await token();
+      md.params.Authorization = `Bearer ${tk}`;
+    } catch (err) {
+      return [md, err as Error];
+    }
+    return await next(md);
+  };
+
+export const insecureCredentialsZ = z.object({
+  username: z.string(),
+  password: z.string(),
+});
+export type InsecureCredentials = z.infer<typeof insecureCredentialsZ>;
+
+export const tokenResponseZ = z.object({
+  token: z.string(),
+  user: user.payloadZ,
+});
+
+export type TokenResponse = z.infer<typeof tokenResponseZ>;
+
+const LOGIN_ENDPOINT = "/auth/login";
+
+export class Client {
+  private token: string | undefined;
+  private readonly client: UnaryClient;
+  authenticating: Promise<void> | undefined;
+  authenticated: boolean;
+  user: user.Payload | undefined;
+
+  constructor(client: UnaryClient, creds: InsecureCredentials) {
+    this.client = client;
+    this.authenticated = false;
+    this.authenticate(creds);
+  }
+
+  authenticate(creds: InsecureCredentials): void {
+    this.authenticating = new Promise((resolve, reject) => {
+      this.client
+        .send<typeof insecureCredentialsZ, typeof tokenResponseZ>(
+          LOGIN_ENDPOINT,
+          creds,
+          tokenResponseZ,
+        )
+        .then(([res, err]) => {
+          if (err != null) return reject(err);
+          this.token = res?.token;
+          this.user = res?.user;
+          this.authenticated = true;
+          resolve();
+        })
+        .catch(reject);
+    });
+  }
+
+  middleware(): Middleware {
+    return tokenMiddleware(async () => {
+      if (!this.authenticated) await this.authenticating;
+      if (this.token == null)
+        throw new AuthError("[auth] - attempting to authenticate without a token");
+      return this.token;
+    });
+  }
+}

package/src/auth/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 auth from "@/auth/auth";

package/src/channel/channel.spec.ts

@@ -0,0 +1,82 @@
+// 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 } from "@synnaxlabs/x";
+import { describe, test, expect } from "vitest";
+
+import { QueryError } from "@/errors";
+import { newClient } from "@/setupspecs";
+
+const client = newClient();
+
+describe("Channel", () => {
+  describe("create", () => {
+    test("create one", async () => {
+      const channel = await client.channels.create({
+        name: "test",
+        leaseholder: 1,
+        rate: Rate.hz(1),
+        dataType: DataType.FLOAT32,
+      });
+      expect(channel.name, "test").toEqual("test");
+      expect(channel.leaseholder).toEqual(1);
+      expect(channel.rate).toEqual(Rate.hz(1));
+      expect(channel.dataType).toEqual(DataType.FLOAT32);
+    });
+    test("create index and indexed pair", async () => {
+      const one = await client.channels.create({
+        name: "Time",
+        isIndex: true,
+        dataType: DataType.TIMESTAMP,
+      });
+      expect(one.key).not.toEqual(0);
+      const two = await client.channels.create({
+        name: "test",
+        index: one.key,
+        dataType: DataType.FLOAT32,
+      });
+      expect(two.key).not.toEqual(0);
+    });
+  });
+  test("retrieve by key", async () => {
+    const channel = await client.channels.create({
+      name: "test",
+      leaseholder: 1,
+      rate: Rate.hz(1),
+      dataType: DataType.FLOAT32,
+    });
+    const retrieved = await client.channels.retrieve(channel.key);
+    expect(retrieved.name).toEqual("test");
+    expect(retrieved.leaseholder).toEqual(1);
+    expect(retrieved.rate).toEqual(Rate.hz(1));
+    expect(retrieved.dataType).toEqual(DataType.FLOAT32);
+  });
+  test("retrieve by key - not found", async () => {
+    await expect(async () => await client.channels.retrieve("1-1000")).rejects.toThrow(
+      QueryError,
+    );
+  });
+
+  test("retrieve by name", async () => {
+    const retrieved = await client.channels.retrieve(["test"]);
+    expect(retrieved.length).toBeGreaterThan(0);
+    retrieved.forEach((ch) => expect(ch.name).toEqual("test"));
+  });
+  test("retrieve by key - not found", async () => {
+    await expect(async () => await client.channels.retrieve("1-1000")).rejects.toThrow(
+      QueryError,
+    );
+  });
+
+  test("retrieve by name", async () => {
+    const retrieved = await client.channels.retrieve(["test"]);
+    expect(retrieved.length).toBeGreaterThan(0);
+    retrieved.forEach((ch) => expect(ch.name).toEqual("test"));
+  });
+});

package/src/channel/client.ts

@@ -0,0 +1,209 @@
+// 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,
+  type NativeTypedArray,
+  type CrudeDensity,
+  type Series,
+  type TimeRange,
+  type AsyncTermSearcher,
+  toArray,
+  type CrudeTimeSpan,
+} from "@synnaxlabs/x";
+
+import { type Creator } from "@/channel/creator";
+import {
+  type Key,
+  type KeyOrName,
+  type Params,
+  type Payload,
+  payload,
+  type NewPayload,
+} from "@/channel/payload";
+import { analyzeParams, type Retriever } from "@/channel/retriever";
+import { QueryError } from "@/errors";
+import { type framer } from "@/framer";
+
+/**
+ * Represents a Channel in a Synnax database. It should not be instantiated
+ * directly, but rather created or retrieved from a {@link Client}.
+ */
+export class Channel {
+  private readonly _frameClient: framer.Client | null;
+  key: Key;
+  name: string;
+  rate: Rate;
+  dataType: DataType;
+  leaseholder: number;
+  index: Key;
+  isIndex: boolean;
+
+  constructor({
+    dataType,
+    rate,
+    name,
+    leaseholder = 0,
+    key = 0,
+    density = 0,
+    isIndex = false,
+    index = 0,
+    frameClient,
+  }: NewPayload & {
+    frameClient?: framer.Client;
+    density?: CrudeDensity;
+  }) {
+    this.key = key;
+    this.name = name;
+    this.rate = new Rate(rate ?? 0);
+    this.dataType = new DataType(dataType);
+    this.leaseholder = leaseholder;
+    this.index = index;
+    this.isIndex = isIndex;
+    this._frameClient = frameClient ?? null;
+  }
+
+  private get framer(): framer.Client {
+    if (this._frameClient == null)
+      throw new Error("cannot read from a channel that has not been created");
+    return this._frameClient;
+  }
+
+  get payload(): Payload {
+    return payload.parse({
+      key: this.key,
+      name: this.name,
+      rate: this.rate.valueOf(),
+      dataType: this.dataType.valueOf(),
+      leaseholder: this.leaseholder,
+      index: this.index,
+      isIndex: this.isIndex,
+    });
+  }
+
+  /**
+   * Reads telemetry from the channel between the two timestamps.
+   *
+   * @param start - The starting timestamp of the range to read from.
+   * @param end - The ending timestamp of the range to read from.
+   * @returns A typed array containing the retrieved
+   */
+  async read(tr: TimeRange): Promise<Series | undefined> {
+    return await this.framer.read(tr, this.key);
+  }
+
+  /**
+   * Writes telemetry to the channel starting at the given timestamp.
+   *
+   * @param start - The starting timestamp of the first sample in data.
+   * @param data - THe telemetry to write to the channel.
+   */
+  async write(start: CrudeTimeSpan, data: NativeTypedArray): Promise<void> {
+    return await this.framer.write(this.key, start, data);
+  }
+}
+
+/**
+ * The core client class for executing channel operations against a Synnax
+ * cluster.
+ */
+export class Client implements AsyncTermSearcher<string, Key, Channel> {
+  private readonly frameClient: framer.Client;
+  private readonly retriever: Retriever;
+  private readonly creator: Creator;
+
+  constructor(segmentClient: framer.Client, retriever: Retriever, creator: Creator) {
+    this.frameClient = segmentClient;
+    this.retriever = retriever;
+    this.creator = creator;
+  }
+
+  async create(channel: NewPayload): Promise<Channel>;
+
+  async create(channels: NewPayload[]): Promise<Channel[]>;
+
+  /**
+   * Creates a new channel with the given properties.
+   *
+   * @param props.rate - The rate of the channel.
+   * @param props.dataType - The data type of the channel.
+   * @param props.name - The name of the channel. Optional.
+   * @param props.nodeKey - The ID of the node that holds the lease on the
+   *   channel. If you don't know what this is, don't worry about it.
+   * @returns The created channel.
+   */
+  async create(channels: NewPayload | NewPayload[]): Promise<Channel | Channel[]> {
+    const single = !Array.isArray(channels);
+    const res = this.sugar(await this.creator.create(toArray(channels)));
+    return single ? res[0] : res;
+  }
+
+  async retrieve(channel: KeyOrName): Promise<Channel>;
+
+  async retrieve(channels: Params): Promise<Channel[]>;
+
+  /**
+   * Retrieves a channel from the database using the given parameters.
+   * @param props.key - The key of the channel to retrieve.
+   * @param props.name - The name of the channel to retrieve. If props.key is set,
+   * this will be ignored.
+   * @returns The retrieved channel.
+   * @raises {QueryError} If the channel does not exist or if multiple results are returned.
+   */
+  async retrieve(channels: Params): Promise<Channel | Channel[]> {
+    const { single, actual, normalized } = analyzeParams(channels);
+    if (normalized.length === 0) return [];
+    const res = this.sugar(await this.retriever.retrieve(channels));
+    if (!single) return res;
+    if (res.length === 0) throw new QueryError(`channel matching ${actual} not found`);
+    if (res.length > 1)
+      throw new QueryError(`multiple channels matching ${actual} found`);
+    return res[0];
+  }
+
+  async search(term: string, rangeKey?: string): Promise<Channel[]> {
+    return this.sugar(await this.retriever.search(term, rangeKey));
+  }
+
+  newSearcherUnderRange(rangeKey?: string): AsyncTermSearcher<string, Key, Channel> {
+    return new SearcherUnderRange(this, rangeKey);
+  }
+
+  async page(offset: number, limit: number): Promise<Channel[]> {
+    return this.sugar(await this.retriever.page(offset, limit));
+  }
+
+  private sugar(payloads: Payload[]): Channel[] {
+    const { frameClient } = this;
+    return payloads.map((p) => new Channel({ ...p, frameClient }));
+  }
+}
+
+class SearcherUnderRange implements AsyncTermSearcher<string, Key, Channel> {
+  private readonly client: Client;
+  private readonly rangeKey?: string;
+
+  constructor(client: Client, rangeKey?: string) {
+    this.client = client;
+    this.rangeKey = rangeKey;
+  }
+
+  async search(term: string): Promise<Channel[]> {
+    return await this.client.search(term, this.rangeKey);
+  }
+
+  async page(offset: number, limit: number): Promise<Channel[]> {
+    return await this.client.page(offset, limit);
+  }
+
+  async retrieve(channels: Key[]): Promise<Channel[]> {
+    return await this.client.retrieve(channels);
+  }
+}

package/src/channel/creator.ts

@@ -0,0 +1,43 @@
+// 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 { z } from "zod";
+
+import {
+  type Payload,
+  payload,
+  parseChannels,
+  newPayload,
+  type NewPayload,
+} from "@/channel/payload";
+
+const reqZ = z.object({ channels: newPayload.array() });
+
+const resZ = z.object({ channels: payload.array() });
+
+export class Creator {
+  private static readonly ENDPOINT = "/channel/create";
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async create(channels: NewPayload[]): Promise<Payload[]> {
+    const req = { channels: parseChannels(channels) };
+    const [res, err] = await this.client.send<typeof reqZ, typeof resZ>(
+      Creator.ENDPOINT,
+      req,
+      resZ,
+    );
+    if (err != null) throw err;
+    return res.channels;
+  }
+}

package/src/channel/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 "@/channel/creator";
+export * from "@/channel/client";
+export * from "@/channel/payload";
+export * from "@/channel/retriever";

package/src/channel/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 channel from "@/channel/external";

package/src/channel/payload.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 } from "@synnaxlabs/x";
+import { z } from "zod";
+
+export const keyZ = z.number();
+export type Key = number;
+export type Keys = number[];
+export type Name = string;
+export type Names = string[];
+export type KeyOrName = Key | Name;
+export type KeysOrNames = Keys | Names;
+export type Params = Key | Name | Keys | Names;
+
+export const payload = z.object({
+  name: z.string(),
+  key: z.number(),
+  rate: Rate.z,
+  dataType: DataType.z,
+  leaseholder: z.number(),
+  index: z.number(),
+  isIndex: z.boolean(),
+});
+
+export type Payload = z.infer<typeof payload>;
+
+export const newPayload = payload.extend({
+  key: z.number().optional(),
+  leaseholder: z.number().optional(),
+  index: z.number().optional(),
+  rate: Rate.z.optional(),
+  isIndex: z.boolean().optional(),
+});
+
+export type NewPayload = z.input<typeof newPayload>;
+
+export const parseChannels = (channels: NewPayload[]): NewPayload[] =>
+  channels.map((channel) => ({
+    name: channel.name,
+    dataType: new DataType(channel.dataType),
+    rate: new Rate(channel.rate ?? 0),
+    leaseholder: channel.leaseholder,
+    index: channel.index,
+    isIndex: channel.isIndex,
+  }));

package/src/channel/retriever.ts

@@ -0,0 +1,160 @@
+// 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 {
+  type Key,
+  type KeyOrName,
+  type Keys,
+  type KeysOrNames,
+  type Name,
+  type Names,
+  type Params,
+  type Payload,
+  payload,
+} from "@/channel/payload";
+import { QueryError } from "@/errors";
+
+const reqZ = z.object({
+  leaseholder: z.number().optional(),
+  keys: z.number().array().optional(),
+  names: z.string().array().optional(),
+  search: z.string().optional(),
+  searchRangeKey: z.string().optional(),
+  limit: z.number().optional(),
+  offset: z.number().optional(),
+});
+
+type Request = z.infer<typeof reqZ>;
+
+const resZ = z.object({
+  channels: payload.array(),
+});
+
+export interface Retriever {
+  retrieve: (channels: Params) => Promise<Payload[]>;
+  search: (term: string, rangeKey?: string) => Promise<Payload[]>;
+  page: (offset: number, limit: number) => Promise<Payload[]>;
+}
+
+export class ClusterRetriever implements Retriever {
+  private static readonly ENDPOINT = "/channel/retrieve";
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async search(term: string, rangeKey?: string): Promise<Payload[]> {
+    return await this.execute({ search: term, searchRangeKey: rangeKey });
+  }
+
+  async retrieve(channels: Params): Promise<Payload[]> {
+    const { variant, normalized } = analyzeParams(channels);
+    return await this.execute({ [variant]: normalized });
+  }
+
+  async page(offset: number, limit: number): Promise<Payload[]> {
+    return await this.execute({ offset, limit });
+  }
+
+  private async execute(request: Request): Promise<Payload[]> {
+    const [res, err] = await this.client.send(ClusterRetriever.ENDPOINT, request, resZ);
+    if (err != null) throw err;
+    return res.channels;
+  }
+}
+
+export class CacheRetriever implements Retriever {
+  private readonly cache: Map<number, Payload>;
+  private readonly namesToKeys: Map<string, number>;
+  private readonly wrapped: Retriever;
+
+  constructor(wrapped: Retriever) {
+    this.cache = new Map();
+    this.namesToKeys = new Map();
+    this.wrapped = wrapped;
+  }
+
+  async search(term: string, searchRangeKey?: string): Promise<Payload[]> {
+    return await this.wrapped.search(term, searchRangeKey);
+  }
+
+  async page(offset: number, limit: number): Promise<Payload[]> {
+    return await this.wrapped.page(offset, limit);
+  }
+
+  async retrieve(channels: Params): Promise<Payload[]> {
+    const { normalized } = analyzeParams(channels);
+    const results: Payload[] = [];
+    const toFetch: KeysOrNames = [];
+    normalized.forEach((keyOrName) => {
+      const c = this.getFromCache(keyOrName);
+      if (c != null) results.push(c);
+      else toFetch.push(keyOrName as never);
+    });
+    if (toFetch.length === 0) return results;
+    const fetched = await this.wrapped.retrieve(toFetch);
+    this.updateCache(fetched);
+    return results.concat(fetched);
+  }
+
+  private updateCache(channels: Payload[]): void {
+    channels.forEach((channel) => {
+      this.cache.set(channel.key, channel);
+      this.namesToKeys.set(channel.name, channel.key);
+    });
+  }
+
+  private getFromCache(channel: KeyOrName): Payload | undefined {
+    const key = typeof channel === "number" ? channel : this.namesToKeys.get(channel);
+    if (key == null) return undefined;
+    return this.cache.get(key);
+  }
+}
+
+export type ParamAnalysisResult =
+  | {
+      single: true;
+      variant: "names";
+      normalized: Names;
+      actual: Name;
+    }
+  | {
+      single: true;
+      variant: "keys";
+      normalized: Keys;
+      actual: Key;
+    }
+  | {
+      single: false;
+      variant: "keys";
+      normalized: Keys;
+      actual: Keys;
+    }
+  | {
+      single: false;
+      variant: "names";
+      normalized: Names;
+      actual: Names;
+    };
+
+export const analyzeParams = (channels: Params): ParamAnalysisResult => {
+  const normal = toArray(channels) as KeysOrNames;
+  if (normal.length === 0) throw new QueryError("No channels provided");
+  return {
+    single: !Array.isArray(channels),
+    variant: typeof normal[0] === "number" ? "keys" : "names",
+    normalized: normal,
+    actual: channels,
+  } as const as ParamAnalysisResult;
+};