@synnaxlabs/client 0.56.1 → 0.57.0

package/src/channel/payload.spec.ts

@@ -1,117 +0,0 @@
-// Copyright 2026 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 } from "@synnaxlabs/x";
-import { describe, expect, it } from "vitest";
-
-import { channel } from "@/channel";
-
-describe("nameZ", () => {
-  describe("valid names", () => {
-    const validNames = [
-      ["temperature", "lowercase letters"],
-      ["Pressure", "capitalized word"],
-      ["sensor1", "letters followed by digit"],
-      ["sensor_temp", "letters with underscore"],
-      ["temp123", "letters followed by digits"],
-      ["Sensor_temp", "capitalized with underscore"],
-      ["temp123_sensor_temp", "complex valid name"],
-      ["_private", "underscore prefix"],
-      ["__double", "double underscore prefix"],
-      ["a", "single letter"],
-      ["A", "single capital letter"],
-      ["_", "single underscore"],
-      ["_1", "underscore followed by digit"],
-    ];
-    validNames.forEach(([name, description]) => {
-      it(`should accept ${name} (${description})`, () => {
-        const result = channel.nameZ.safeParse(name);
-        expect(result.success).toBe(true);
-      });
-    });
-  });
-
-  describe("invalid names", () => {
-    it("should reject empty string", () => {
-      const result = channel.nameZ.safeParse("");
-      expect(result.success).toBe(false);
-      expect(result.error?.issues[0].message).toContain("Name is required");
-    });
-  });
-});
-
-describe("newZ", () => {
-  const validNewChannel = {
-    name: "temperature_sensor",
-    dataType: DataType.FLOAT32,
-    virtual: true,
-  };
-
-  describe("name validation", () => {
-    it("should accept valid channel names", () => {
-      const result = channel.newZ.safeParse(validNewChannel);
-      expect(result.success).toBe(true);
-    });
-
-    it("should reject empty name", () => {
-      const result = channel.newZ.safeParse({ ...validNewChannel, name: "" });
-      expect(result.success).toBe(false);
-    });
-
-    it("should accept name with underscores", () => {
-      const result = channel.newZ.safeParse({
-        ...validNewChannel,
-        name: "sensor_temp_123",
-      });
-      expect(result.success).toBe(true);
-    });
-
-    it("should accept name starting with underscore", () => {
-      const result = channel.newZ.safeParse({
-        ...validNewChannel,
-        name: "_private_sensor",
-      });
-      expect(result.success).toBe(true);
-    });
-  });
-});
-describe("escapeInvalidName", () => {
-  it("should escape invalid name", () => {
-    const result = channel.escapeInvalidName("sensor-temp");
-    expect(result).toBe("sensor_temp");
-  });
-  it("should escape name starting with digit", () => {
-    const result = channel.escapeInvalidName("1sensor");
-    expect(result).toBe("_1sensor");
-  });
-  it("should escape name with spaces", () => {
-    const result = channel.escapeInvalidName("my channel");
-    expect(result).toBe("my_channel");
-  });
-  it("should escape name with special characters", () => {
-    const result = channel.escapeInvalidName("sensor!");
-    expect(result).toBe("sensor_");
-  });
-  it("should escape name with hyphens", () => {
-    const result = channel.escapeInvalidName("sensor-temp");
-    expect(result).toBe("sensor_temp");
-  });
-  it("should escape name with dots", () => {
-    const result = channel.escapeInvalidName("sensor.temp");
-    expect(result).toBe("sensor_temp");
-  });
-  it("should allow an empty string by default", () => {
-    const result = channel.escapeInvalidName("");
-    expect(result).toBe("");
-  });
-  it("should change empty string to underscore when changeEmptyToUnderscore is true", () => {
-    const result = channel.escapeInvalidName("", true);
-    expect(result).toBe("_");
-  });
-});

package/src/channel/retriever.ts

@@ -1,252 +0,0 @@
-// Copyright 2026 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 { array, type CrudeTimeSpan, DataType, debounce, zod } from "@synnaxlabs/x";
-import { Mutex } from "async-mutex";
-import { z } from "zod";
-
-import { type Params, type PrimitiveParams } from "@/channel/payload";
-import { type Key, keyZ, type Name, type Payload, payloadZ } from "@/channel/types.gen";
-import { QueryError } from "@/errors";
-import { keyZ as rangeKeyZ } from "@/ranger/types.gen";
-import {
-  analyzeParams as analyzeParameters,
-  type ParamAnalysisResult,
-} from "@/util/retrieve";
-
-const reqZ = z.object({
-  nodeKey: zod.uint12.optional(),
-  keys: keyZ.array().optional(),
-  names: z.string().array().optional(),
-  searchTerm: z.string().optional(),
-  rangeKey: rangeKeyZ.optional(),
-  limit: z.int().optional(),
-  offset: z.int().optional(),
-  dataTypes: DataType.z.array().optional(),
-  notDataTypes: DataType.z.array().optional(),
-  virtual: z.boolean().optional(),
-  isIndex: z.boolean().optional(),
-  internal: z.boolean().optional(),
-  legacyCalculated: z.boolean().optional(),
-});
-export type RetrieveRequest = z.input<typeof reqZ>;
-
-export type RetrieveOptions = Omit<RetrieveRequest, "keys" | "names" | "search">;
-export type PageOptions = Omit<RetrieveOptions, "offset" | "limit">;
-
-const resZ = z.object({ channels: array.nullishToEmpty(payloadZ) });
-
-export const analyzeParams = (
-  channels: Params,
-): ParamAnalysisResult<Key | Name, { number: "keys"; string: "names" }> => {
-  if (Array.isArray(channels) && channels.length > 0 && typeof channels[0] === "object")
-    channels = (channels as Payload[]).map((c) => c.key);
-  else if (typeof channels === "object" && "key" in channels) channels = [channels.key];
-  return analyzeParameters(channels as PrimitiveParams, {
-    number: "keys",
-    string: "names",
-  });
-};
-
-export interface Retriever {
-  retrieve: ((channels: Params, opts?: RetrieveOptions) => Promise<Payload[]>) &
-    ((request: RetrieveRequest) => Promise<Payload[]>);
-}
-
-export class ClusterRetriever implements Retriever {
-  private readonly client: UnaryClient;
-
-  constructor(client: UnaryClient) {
-    this.client = client;
-  }
-
-  async retrieve(
-    channels: Params | RetrieveRequest,
-    options?: RetrieveOptions,
-  ): Promise<Payload[]> {
-    if (!Array.isArray(channels) && typeof channels === "object")
-      return await this.execute(channels);
-    const res = analyzeParams(channels);
-    const { variant } = res;
-    let { normalized } = res;
-    if (variant === "keys" && (normalized as Key[]).indexOf(0) !== -1)
-      normalized = (normalized as Key[]).filter((k) => k !== 0);
-    if (normalized.length === 0) return [];
-    return await this.execute({ [variant]: normalized, ...options });
-  }
-
-  private async execute(request: RetrieveRequest): Promise<Payload[]> {
-    const res = await this.client.send("/channel/retrieve", request, reqZ, resZ);
-    return res.channels;
-  }
-}
-
-export class CacheRetriever implements Retriever {
-  private readonly cache: Map<number, Payload>;
-  private readonly namesToKeys: Map<string, Set<number>>;
-  private readonly wrapped: Retriever;
-
-  constructor(wrapped: Retriever) {
-    this.cache = new Map();
-    this.namesToKeys = new Map();
-    this.wrapped = wrapped;
-  }
-
-  async retrieve(
-    channels: Params | RetrieveRequest,
-    options?: RetrieveOptions,
-  ): Promise<Payload[]> {
-    if (!Array.isArray(channels) && typeof channels === "object")
-      return await this.wrapped.retrieve(channels);
-    const { normalized } = analyzeParams(channels);
-    const results: Payload[] = [];
-    const toFetch: Key[] | Name[] = [];
-    normalized.forEach((keyOrName) => {
-      const c = this.get(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, options);
-    this.set(fetched);
-    return results.concat(fetched);
-  }
-
-  delete(channels: Params): void {
-    const { variant, normalized } = analyzeParams(channels);
-    if (variant === "names")
-      (normalized as string[]).forEach((name) => {
-        const keys = this.namesToKeys.get(name);
-        if (keys == null) return;
-        keys.forEach((k) => this.cache.delete(k));
-        this.namesToKeys.delete(name);
-      });
-    else
-      (normalized as number[]).forEach((key) => {
-        const channel = this.cache.get(key);
-        if (channel == null) return;
-        this.cache.delete(key);
-        this.namesToKeys.delete(channel.name);
-      });
-  }
-
-  rename(keys: Key[], names: string[]): void {
-    keys.forEach((key, i) => {
-      const name = names[i];
-      const ch = this.cache.get(key);
-      if (ch == null) return;
-      this.cache.delete(key);
-      const keys = this.namesToKeys.get(ch.name);
-      if (keys != null) {
-        keys.delete(key);
-        if (keys.size === 0) this.namesToKeys.delete(ch.name);
-      }
-      ch.name = name;
-      this.cache.set(key, ch);
-      const newKeys = this.namesToKeys.get(name);
-      if (newKeys == null) this.namesToKeys.set(name, new Set([key]));
-      else newKeys.add(key);
-    });
-  }
-
-  set(channels: Payload[]): void {
-    channels.forEach((channel) => {
-      this.cache.set(channel.key, channel);
-      const keys = this.namesToKeys.get(channel.name);
-      if (keys == null) this.namesToKeys.set(channel.name, new Set([channel.key]));
-      else keys.add(channel.key);
-    });
-  }
-
-  private get(channel: Key | Name): Payload[] | undefined {
-    if (typeof channel === "number") {
-      const ch = this.cache.get(channel);
-      if (ch == null) return undefined;
-      return [ch];
-    }
-    const keys = this.namesToKeys.get(channel);
-    if (keys == null) return undefined;
-    const channels: Payload[] = [];
-    keys.forEach((key) => {
-      const ch = this.cache.get(key);
-      if (ch != null) channels.push(ch);
-    });
-    if (channels.length === 0) return undefined;
-    return channels;
-  }
-}
-
-export interface PromiseFns<T> {
-  resolve: (value: T) => void;
-  reject: (reason?: unknown) => void;
-}
-
-// no interval
-export class DebouncedBatchRetriever implements Retriever {
-  private readonly mu = new Mutex();
-  private readonly requests = new Map<Key[], PromiseFns<Payload[]>>();
-  private readonly wrapped: Retriever;
-  private readonly debouncedRun: () => void;
-
-  constructor(wrapped: Retriever, deb: CrudeTimeSpan) {
-    this.wrapped = wrapped;
-    this.debouncedRun = debounce(() => {
-      void this.run();
-    }, deb);
-  }
-
-  async retrieve(channels: Params | RetrieveRequest): Promise<Payload[]> {
-    if (!Array.isArray(channels) && typeof channels === "object")
-      return await this.wrapped.retrieve(channels);
-    const { normalized, variant } = analyzeParams(channels);
-    // Bypass on name fetches for now.
-    if (variant === "names") return await this.wrapped.retrieve(normalized);
-
-    const a = new Promise<Payload[]>((resolve, reject) => {
-      void this.mu.runExclusive(() => {
-        this.requests.set(normalized as Key[], { resolve, reject });
-        this.debouncedRun();
-      });
-    });
-    return await a;
-  }
-
-  async run(): Promise<void> {
-    await this.mu.runExclusive(async () => {
-      const allKeys = new Set<Key>();
-      this.requests.forEach((_, keys) => keys.forEach((k) => allKeys.add(k)));
-      try {
-        const channels = await this.wrapped.retrieve(Array.from(allKeys));
-        this.requests.forEach((fns, keys) =>
-          fns.resolve(channels.filter((c) => keys.includes(c.key))),
-        );
-      } catch (e) {
-        this.requests.forEach((fns) => fns.reject(e));
-      } finally {
-        this.requests.clear();
-      }
-    });
-  }
-}
-
-export const retrieveRequired = async (
-  r: Retriever,
-  channels: Params,
-): Promise<Payload[]> => {
-  const { normalized } = analyzeParams(channels);
-  const results = await r.retrieve(normalized);
-  const notFound: (Key | Name)[] = [];
-  normalized.forEach((v) => {
-    if (results.find((c) => c.name === v || c.key === v) == null) notFound.push(v);
-  });
-  if (notFound.length > 0)
-    throw new QueryError(`Could not find channels: ${JSON.stringify(notFound)}`);
-  return results;
-};

package/src/connection/checker.ts

@@ -1,203 +0,0 @@
-// Copyright 2026 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 {
-  ClockSkewCalculator,
-  type CrudeTimeSpan,
-  errors,
-  migrate,
-  TimeSpan,
-  TimeStamp,
-} from "@synnaxlabs/x";
-import { z } from "zod";
-
-export const statusZ = z.enum(["disconnected", "connecting", "connected", "failed"]);
-export type Status = z.infer<typeof statusZ>;
-
-export const stateZ = z.object({
-  status: statusZ,
-  error: z.instanceof(Error).optional(),
-  message: z.string().optional(),
-  clusterKey: z.string(),
-  clientVersion: z.string(),
-  clientServerCompatible: z.boolean(),
-  nodeVersion: z.string().optional(),
-  clockSkew: TimeSpan.z.default(TimeSpan.ZERO),
-  clockSkewExceeded: z.boolean().default(false),
-});
-export interface State extends z.infer<typeof stateZ> {}
-
-const responseZ = z.object({
-  clusterKey: z.string(),
-  nodeVersion: z.string().optional(),
-  nodeTime: TimeStamp.z,
-});
-const requestZ = z.void();
-
-const DEFAULT: State = {
-  clusterKey: "",
-  status: "disconnected",
-  error: undefined,
-  message: "Disconnected",
-  clientServerCompatible: false,
-  clientVersion: __VERSION__,
-  clockSkew: TimeSpan.ZERO,
-  clockSkewExceeded: false,
-};
-
-const createWarning = (
-  nodeVersion: string | null,
-  clientVersion: string,
-  clientIsNewer: boolean,
-): string => {
-  const toUpgrade = clientIsNewer ? "Core" : "client";
-  return `The Synnax Core version ${nodeVersion != null ? `${nodeVersion} ` : ""}is too ${clientIsNewer ? "old" : "new"} for client version ${clientVersion}.
-  This may cause compatibility issues. We recommend updating the ${toUpgrade}. For more information, see
-  https://docs.synnaxlabs.com/reference/client/resources/troubleshooting#old-${toUpgrade.toLowerCase()}-version`;
-};
-
-/** Polls a synnax cluster for connectivity information. */
-export class Checker {
-  static readonly DEFAULT: State = DEFAULT;
-  private readonly _state: State;
-  private readonly pollFrequency: TimeSpan;
-  private readonly client: UnaryClient;
-  private readonly name?: string;
-  private interval?: NodeJS.Timeout;
-  private readonly clientVersion: string;
-  private readonly onChangeHandlers: Array<(state: State) => void> = [];
-  static readonly connectionStateZ = stateZ;
-  private versionWarned = false;
-  private readonly skewCalc: ClockSkewCalculator;
-  private readonly clockSkewThreshold: TimeSpan;
-  private checking = false;
-
-  /**
-   * @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: CrudeTimeSpan = TimeSpan.seconds(30),
-    clientVersion: string,
-    name?: string,
-    clockSkewThreshold: CrudeTimeSpan = TimeSpan.seconds(1),
-  ) {
-    this._state = { ...DEFAULT };
-    this.client = client;
-    this.pollFrequency = new TimeSpan(pollFreq);
-    this.clientVersion = clientVersion;
-    this.name = name;
-    this.skewCalc = new ClockSkewCalculator();
-    this.clockSkewThreshold = new TimeSpan(clockSkewThreshold).abs();
-    void this.check();
-    this.start();
-  }
-
-  /** Stops the connectivity client from polling the cluster for connectivity */
-  stop(): 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;
-    const prevSkewExceeded = this._state.clockSkewExceeded;
-    const measureSkew = !this.checking;
-    this.checking = true;
-    try {
-      if (measureSkew) this.skewCalc.start();
-      const res = await this.client.send(
-        "/connectivity/check",
-        undefined,
-        requestZ,
-        responseZ,
-      );
-      if (measureSkew) {
-        this.skewCalc.end(res.nodeTime);
-        this._state.clockSkew = this.skewCalc.skew;
-        this._state.clockSkewExceeded = this.skewCalc.exceeds(this.clockSkewThreshold);
-        if (this._state.clockSkewExceeded) {
-          const direction = this.skewCalc.skew.valueOf() > 0n ? "ahead of" : "behind";
-          console.warn(
-            `Measured excessive clock skew between this host and ` +
-              `the Synnax Core. This host is ${direction} the Synnax Core ` +
-              `by approximately ${this.skewCalc.skew.abs().toString()}.`,
-          );
-        }
-      }
-      const nodeVersion = res.nodeVersion;
-      const clientVersion = this.clientVersion;
-      const warned = this.versionWarned;
-      if (nodeVersion == null) {
-        this._state.clientServerCompatible = false;
-        if (!warned) {
-          console.warn(createWarning(null, clientVersion, true));
-          this.versionWarned = true;
-        }
-      } else if (
-        !migrate.versionsEqual(clientVersion, nodeVersion, {
-          checkMajor: true,
-          checkMinor: true,
-          checkPatch: false,
-        })
-      ) {
-        this._state.clientServerCompatible = false;
-        if (!warned) {
-          console.warn(
-            createWarning(
-              nodeVersion,
-              clientVersion,
-              migrate.semVerNewer(clientVersion, nodeVersion),
-            ),
-          );
-          this.versionWarned = true;
-        }
-      } else this._state.clientServerCompatible = true;
-      this._state.status = "connected";
-      this._state.message = `Connected to ${this.name ?? "cluster"}`;
-      this._state.clusterKey = res.clusterKey;
-      this._state.nodeVersion = res.nodeVersion;
-      this._state.clientVersion = this.clientVersion;
-    } catch (err) {
-      this._state.status = "failed";
-      this._state.error = errors.fromUnknown(err);
-      this._state.message = this.state.error?.message;
-    } finally {
-      this.checking = false;
-    }
-    const changed =
-      prevStatus !== this._state.status ||
-      prevSkewExceeded !== this._state.clockSkewExceeded;
-    if (this.onChangeHandlers.length > 0 && changed)
-      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 start(): void {
-    this.interval = setInterval(() => {
-      void this.check();
-    }, this.pollFrequency.milliseconds);
-  }
-}