@synnaxlabs/client 0.2.1 → 0.13.6

package/src/client.ts

@@ -0,0 +1,116 @@
+// 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 { label } from "@/label";
+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;
+  readonly labels: label.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.labels = new label.Client(this.transport.unary, this.telem);
+    this.ranges = new ranger.Client(
+      this.telem,
+      rangeRetriever,
+      rangeWriter,
+      this.transport.unary,
+      chRetriever,
+      this.labels,
+    );
+    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,26 @@
+// 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)),
+    z.instanceof(Number).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,133 @@
+// 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 { 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 const stateZ = z.object({
+  subject: subjectZ,
+  resource: z.number(),
+  authority: Authority.z,
+});
+
+export interface State {
+  subject: Subject;
+  resource: ChannelKey;
+  authority: Authority;
+}
+
+export const filterTransfersByChannelKey =
+  (...resources: ChannelKey[]) =>
+  (transfers: Transfer[]): Transfer[] =>
+    transfers.filter((t) => {
+      let ok = false;
+      if (t.to != null) ok = resources.includes(t.to.resource);
+      if (t.from != null && !ok) ok = resources.includes(t.from.resource);
+      return ok;
+    });
+
+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);
+    });
+  }
+}

package/src/errors.ts

@@ -0,0 +1,163 @@
+// 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 {
+  BaseTypedError,
+  type Middleware,
+  registerError,
+  Unreachable,
+  type ErrorPayload,
+} from "@synnaxlabs/freighter";
+
+const _FREIGHTER_EXCEPTION_PREFIX = "sy.api.";
+
+enum APIErrorType {
+  General = _FREIGHTER_EXCEPTION_PREFIX + "general",
+  Parse = _FREIGHTER_EXCEPTION_PREFIX + "parse",
+  Auth = _FREIGHTER_EXCEPTION_PREFIX + "auth",
+  Unexpected = _FREIGHTER_EXCEPTION_PREFIX + "unexpected",
+  Validation = _FREIGHTER_EXCEPTION_PREFIX + "validation",
+  Query = _FREIGHTER_EXCEPTION_PREFIX + "query",
+  Route = _FREIGHTER_EXCEPTION_PREFIX + "route",
+}
+
+export interface Field {
+  field: string;
+  message: string;
+}
+
+class BaseError extends BaseTypedError {
+  constructor(message: string) {
+    super(message, _FREIGHTER_EXCEPTION_PREFIX);
+  }
+}
+
+/**
+ * Raised when a validation error occurs.
+ */
+export class ValidationError extends BaseError {
+  fields: Field[];
+
+  constructor(fieldsOrMessage: string | Field[] | Field) {
+    if (typeof fieldsOrMessage === "string") {
+      super(fieldsOrMessage);
+      this.fields = [];
+    } else if (Array.isArray(fieldsOrMessage)) {
+      super(
+        fieldsOrMessage.map((field) => `${field.field}: ${field.message}`).join("\n"),
+      );
+      this.fields = fieldsOrMessage;
+    } else {
+      super(`${fieldsOrMessage.field}: ${fieldsOrMessage.message}`);
+      this.fields = [fieldsOrMessage];
+    }
+  }
+}
+
+/**
+ * GeneralError is raised when a general error occurs.
+ */
+export class GeneralError extends BaseError {}
+
+/**
+ * ParseError is raised when a parse error occurs.
+ */
+export class ParseError extends BaseError {}
+
+/**
+ * AuthError is raised when an authentication error occurs.
+ */
+export class AuthError extends BaseError {}
+
+/**
+ * UnexpectedError is raised when an unexpected error occurs.
+ */
+export class UnexpectedError extends BaseError {
+  constructor(message: string) {
+    super(`
+    Unexpected error encountered:
+
+    ${message}
+
+    Please report this to the Synnax team.
+    `);
+  }
+}
+
+/**
+ * QueryError is raised when a query error occurs.
+ */
+export class QueryError extends BaseError {}
+
+/**
+ * RouteError is raised when a routing error occurs.
+ */
+export class RouteError extends BaseError {
+  path: string;
+
+  constructor(message: string, path: string) {
+    super(message);
+    this.path = path;
+  }
+}
+
+/**
+ * Raised when time-series data is not contiguous.
+ */
+export class ContiguityError extends BaseError {}
+
+const decode = (payload: ErrorPayload): Error | null => {
+  if (!payload.type.startsWith(_FREIGHTER_EXCEPTION_PREFIX)) return null;
+  switch (payload.type) {
+    case APIErrorType.General:
+      return new GeneralError(payload.data);
+    case APIErrorType.Parse:
+      return new ParseError(payload.data);
+    case APIErrorType.Auth:
+      return new AuthError(payload.data);
+    case APIErrorType.Unexpected:
+      return new UnexpectedError(payload.data);
+    case APIErrorType.Validation:
+      return new ValidationError(payload.data);
+    case APIErrorType.Query:
+      return new QueryError(payload.data);
+    case APIErrorType.Route:
+      return new RouteError(payload.data, payload.data);
+    default:
+      return new UnexpectedError(payload.data);
+  }
+};
+
+const encode = (): ErrorPayload => {
+  throw new Error("Not implemented");
+};
+
+registerError({ encode, decode });
+
+export const validateFieldNotNull = (
+  key: string,
+  value: unknown,
+  message: string = "must be provided",
+): void => {
+  if (value == null) throw new ValidationError({ field: key, message });
+};
+
+export const errorsMiddleware: Middleware = async (ctx, next) => {
+  const [res, err] = await next(ctx);
+  if (err == null) return [res, err];
+  if (err instanceof Unreachable)
+    return [
+      res,
+      new Unreachable({
+        message: `Cannot reach cluster at ${err.url.host}:${err.url.port}`,
+        url: err.url,
+      }),
+    ];
+  return [res, err];
+};