@synnaxlabs/client 0.2.0 → 0.13.5

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;
+};

package/src/client.ts

@@ -0,0 +1,112 @@
+// 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 { TimeSpan, TimeStamp, URL } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { auth } from "@/auth";
+import { channel } from "@/channel";
+import { connection } from "@/connection";
+import { errorsMiddleware } from "@/errors";
+import { framer } from "@/framer";
+import { ontology } from "@/ontology";
+import { ranger } from "@/ranger";
+import { Transport } from "@/transport";
+import { workspace } from "@/workspace";
+
+export const synnaxPropsZ = z.object({
+  host: z.string().min(1),
+  port: z.number().or(z.string()),
+  username: z.string().optional(),
+  password: z.string().optional(),
+  connectivityPollFrequency: TimeSpan.z.default(TimeSpan.seconds(30)),
+  secure: z.boolean().optional().default(false),
+});
+
+export type SynnaxProps = z.input<typeof synnaxPropsZ>;
+export type ParsedSynnaxProps = z.output<typeof synnaxPropsZ>;
+
+/**
+ * Client to perform operations against a Synnax cluster.
+ *
+ * @property channel - Channel client for creating and retrieving channels.
+ * @property data - Data client for reading and writing telemetry.
+ * @property connectivity - Client for retrieving connectivity information.
+ * @property ontology - Client for querying the cluster's ontology.
+ */
+// eslint-disable-next-line import/no-default-export
+export default class Synnax {
+  private readonly transport: Transport;
+  readonly createdAt: TimeStamp;
+  readonly telem: framer.Client;
+  readonly ranges: ranger.Client;
+  readonly channels: channel.Client;
+  readonly auth: auth.Client | undefined;
+  readonly connectivity: connection.Checker;
+  readonly ontology: ontology.Client;
+  readonly props: ParsedSynnaxProps;
+  readonly workspaces: workspace.Client;
+  static readonly connectivity = connection.Checker;
+
+  /**
+   * @param props.host - Hostname of a node in the cluster.
+   * @param props.port - Port of the node in the cluster.
+   * @param props.username - Username for authentication. Not required if the
+   * cluster is insecure.
+   * @param props.password - Password for authentication. Not required if the
+   * cluster is insecure.
+   * @param props.connectivityPollFrequency - Frequency at which to poll the
+   * cluster for connectivity information. Defaults to 5 seconds.
+   * @param props.secure - Whether to connect to the cluster using TLS. The cluster
+   * must be configured to support TLS. Defaults to false.
+   *
+   * A Synnax client must be closed when it is no longer needed. This will stop
+   * the client from polling the cluster for connectivity information.
+   */
+  constructor(props: SynnaxProps) {
+    this.createdAt = TimeStamp.now();
+    this.props = synnaxPropsZ.parse(props);
+    const { host, port, username, password, connectivityPollFrequency, secure } =
+      this.props;
+    this.transport = new Transport(new URL({ host, port: Number(port) }), secure);
+    this.transport.use(errorsMiddleware);
+    if (username != null && password != null) {
+      this.auth = new auth.Client(this.transport.unary, {
+        username,
+        password,
+      });
+      this.transport.use(this.auth.middleware());
+    }
+    const chRetriever = new channel.CacheRetriever(
+      new channel.ClusterRetriever(this.transport.unary),
+    );
+    const chCreator = new channel.Creator(this.transport.unary);
+    this.telem = new framer.Client(this.transport.stream, chRetriever);
+    this.channels = new channel.Client(this.telem, chRetriever, chCreator);
+    this.connectivity = new connection.Checker(
+      this.transport.unary,
+      connectivityPollFrequency,
+    );
+    this.ontology = new ontology.Client(this.transport.unary, this.telem);
+    const rangeRetriever = new ranger.Retriever(this.transport.unary);
+    const rangeWriter = new ranger.Writer(this.transport.unary);
+    this.ranges = new ranger.Client(
+      this.telem,
+      rangeRetriever,
+      rangeWriter,
+      this.transport.unary,
+      chRetriever,
+    );
+    this.workspaces = new workspace.Client(this.transport.unary);
+  }
+
+  close(): void {
+    this.connectivity.stopChecking();
+  }
+}

package/src/connection/checker.ts

@@ -0,0 +1,104 @@
+// 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 { TimeSpan } from "@synnaxlabs/x";
+import { z } from "zod";
+
+const STATUSES = ["disconnected", "connecting", "connected", "failed"] as const;
+export const status = z.enum(STATUSES);
+export type Status = z.infer<typeof status>;
+
+export const state = z.object({
+  status,
+  error: z.instanceof(Error).optional(),
+  message: z.string().optional(),
+  clusterKey: z.string(),
+});
+
+export type State = z.infer<typeof state>;
+
+const responseZ = z.object({
+  clusterKey: z.string(),
+});
+
+const DEFAULT: State = {
+  clusterKey: "",
+  status: "disconnected",
+  error: undefined,
+  message: "Disconnected",
+};
+
+/** Polls a synnax cluster for connectivity information. */
+export class Checker {
+  private static readonly ENDPOINT = "/connectivity/check";
+  static readonly DEFAULT: State = DEFAULT;
+  private readonly _state: State;
+  private readonly pollFrequency = TimeSpan.seconds(30);
+  private readonly client: UnaryClient;
+  private interval?: NodeJS.Timeout;
+  private readonly onChangeHandlers: Array<(state: State) => void> = [];
+  static readonly connectionStateZ = state;
+
+  /**
+   * @param client - The transport client to use for connectivity checks.
+   * @param pollFreq - The frequency at which to poll the cluster for
+   *   connectivity information.
+   */
+  constructor(client: UnaryClient, pollFreq: TimeSpan = TimeSpan.seconds(30)) {
+    this._state = { ...DEFAULT };
+    this.client = client;
+    this.pollFrequency = pollFreq;
+    void this.check();
+    this.startChecking();
+  }
+
+  /** Stops the connectivity client from polling the cluster for connectivity */
+  stopChecking(): void {
+    if (this.interval != null) clearInterval(this.interval);
+  }
+
+  /**
+   * Executes a connectivity check and updates the client status and error, as
+   * well as calling any registered change handlers.
+   */
+  async check(): Promise<State> {
+    const prevStatus = this._state.status;
+    try {
+      const [res, err] = await this.client.send(Checker.ENDPOINT, null, responseZ);
+      if (err != null) throw err;
+      this._state.status = "connected";
+      this._state.message = `Connected to cluster ${res.clusterKey}`;
+      this._state.clusterKey = res.clusterKey;
+    } catch (err) {
+      this._state.status = "failed";
+      this._state.error = err as Error;
+      this._state.message = this.state.error?.message;
+    }
+    if (this.onChangeHandlers.length > 0 && prevStatus !== this._state.status)
+      this.onChangeHandlers.forEach((handler) => handler(this.state));
+    return this.state;
+  }
+
+  /** @returns a copy of the current client state. */
+  get state(): State {
+    return { ...this._state };
+  }
+
+  /** @param callback - The function to call when the client status changes. */
+  onChange(callback: (state: State) => void): void {
+    this.onChangeHandlers.push(callback);
+  }
+
+  private startChecking(): void {
+    this.interval = setInterval(() => {
+      void this.check();
+    }, this.pollFrequency.milliseconds);
+  }
+}

package/src/connection/connection.spec.ts

@@ -0,0 +1,35 @@
+// 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 { URL } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import { auth } from "@/auth";
+import { Checker } from "@/connection/checker";
+import { HOST, PORT } from "@/setupspecs";
+import { Transport } from "@/transport";
+
+describe("connectivity", () => {
+  it("should connect to the server", async () => {
+    const transport = new Transport(new URL({ host: HOST, port: PORT }));
+    const client = new auth.Client(transport.unary, {
+      username: "synnax",
+      password: "seldon",
+    });
+    await client.authenticating;
+    expect(client.authenticated).toBeTruthy();
+
+    transport.use(client.middleware());
+
+    const connectivity = new Checker(transport.unary);
+
+    await connectivity.check();
+    expect(connectivity.state.status).toEqual("connected");
+  });
+});

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

package/src/control/authority.ts

@@ -0,0 +1,25 @@
+// 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";
+
+export class Authority extends Number {
+  static readonly ABSOLUTE = 255;
+  static readonly DEFAULT = 1;
+
+  static readonly z = z.union([
+    z.instanceof(Authority),
+    z
+      .number()
+      .int()
+      .min(0)
+      .max(255)
+      .transform((n) => new Authority(n)),
+  ]);
+}

package/src/control/external.ts

@@ -0,0 +1,11 @@
+// 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 "@/control/authority";
+export * from "@/control/state";

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

package/src/control/state.spec.ts

@@ -0,0 +1,24 @@
+// 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 { control } from "@/control";
+import { newClient } from "@/setupspecs";
+
+const client = newClient();
+
+describe("state", () => {
+  it("should receive the initial control state from the cluster", async () => {
+    const s = await control.StateTracker.open(client.telem);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(s.states.size).toBeGreaterThan(0);
+    s.close();
+  });
+});

package/src/control/state.ts

@@ -0,0 +1,117 @@
+// 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 Destructor, binary, observe } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type Key as ChannelKey } from "@/channel/payload";
+import { type Authority } from "@/control/authority";
+import { type Client as FrameClient } from "@/framer/client";
+import { type Streamer as FrameStreamer } from "@/framer/streamer";
+
+export const subjectZ = z.object({
+  name: z.string(),
+  key: z.string(),
+});
+
+export interface Subject {
+  name: string;
+  key: string;
+}
+
+export interface State {
+  subject: Subject;
+  resource: ChannelKey;
+  authority: Authority;
+}
+
+interface Release {
+  from: State;
+  to?: null;
+}
+
+interface Acquire {
+  from?: null;
+  to: State;
+}
+
+export type Transfer =
+  | {
+      from: State;
+      to: State;
+    }
+  | Release
+  | Acquire;
+
+export const transferString = (t: Transfer): string => {
+  if (t.to == null) return `${t.from?.resource} - ${t.from?.subject.name} -> released`;
+  if (t.from == null)
+    return `${t.to.resource} - released -> ${
+      t.to.subject.name
+    } (${t.to.authority.toString()})`;
+  return `${t.to.resource} - ${t.from.subject.name} -> ${
+    t.to.subject.name
+  } (${t.to.authority.toString()})`;
+};
+
+interface Update {
+  transfers: Transfer[];
+}
+
+export class StateTracker implements observe.Observable<Transfer[]> {
+  readonly states: Map<ChannelKey, State>;
+  private readonly streamer: FrameStreamer;
+  private readonly ecd: binary.EncoderDecoder;
+  private readonly observer: observe.Observer<Transfer[]>;
+  private readonly closePromise: Promise<void>;
+
+  private constructor(streamer: FrameStreamer) {
+    this.states = new Map();
+    this.ecd = new binary.JSONEncoderDecoder();
+    this.observer = new observe.Observer<Transfer[]>();
+    this.streamer = streamer;
+    this.closePromise = this.stream();
+  }
+
+  subjects(): Subject[] {
+    const subjects = new Map<string, Subject>();
+    this.states.forEach((s) => subjects.set(s.subject.key, s.subject));
+    return Array.from(subjects.values());
+  }
+
+  onChange(handler: observe.Handler<Transfer[]>): Destructor {
+    return this.observer.onChange(handler);
+  }
+
+  async close(): Promise<void> {
+    this.streamer.close();
+    await this.closePromise;
+  }
+
+  static async open(client: FrameClient): Promise<StateTracker> {
+    const streamer = await client.newStreamer("sy_node_1_control");
+    return new StateTracker(streamer);
+  }
+
+  private async stream(): Promise<void> {
+    for await (const frame of this.streamer) {
+      const update: Update = this.ecd.decode(frame.series[0].buffer);
+      this.merge(update);
+      this.observer.notify(update.transfers);
+    }
+  }
+
+  private merge(update: Update): void {
+    update.transfers.forEach((t) => {
+      if (t.from == null && t.to == null) console.warn("Invalid transfer: ", t);
+      if (t.to == null) this.states.delete(t.from.resource);
+      else this.states.set(t.to.resource, t.to);
+    });
+  }
+}