@synnaxlabs/client 0.54.2 → 0.56.0

package/src/arc/lsp.spec.ts

@@ -27,7 +27,7 @@ type JSONRPCResponse =
     };
 
 type LSPReceiver = {
-  receive: () => Promise<[{ content: string }, null] | [null, Error]>;
+  receive: () => Promise<{ content: string }>;
 };
 
 const MAX_DRAIN = 50;
@@ -38,9 +38,7 @@ const receiveResponse = async (
   expectedId: number,
 ): Promise<JSONRPCResponse> => {
   for (let i = 0; i < MAX_DRAIN; i++) {
-    const [res, err] = await stream.receive();
-    if (err != null) throw err;
-    if (res == null) throw new Error("Expected response");
+    const res = await stream.receive();
     const msg = JSON.parse(res.content);
     if (!("method" in msg) && "id" in msg && msg.id === expectedId)
       return msg as JSONRPCResponse;
@@ -56,9 +54,7 @@ const receiveNotification = async (
   expectedMethod: string,
 ): Promise<JSONRPCRequest> => {
   for (let i = 0; i < MAX_DRAIN; i++) {
-    const [res, err] = await stream.receive();
-    if (err != null) throw err;
-    if (res == null) throw new Error("Expected message");
+    const res = await stream.receive();
     const msg = JSON.parse(res.content);
     if ("method" in msg && msg.method === expectedMethod) return msg as JSONRPCRequest;
   }

package/src/arc/types/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, zod } from "@synnaxlabs/x";
+import { array, record, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 export enum Kind {
@@ -48,9 +48,9 @@ export const chanDirectionZ = z.enum(ChanDirection);
 /** Channels contains channel declarations for reading from and writing to Synnax channels. */
 export const channelsZ = z.object({
   /** read contains readable channel indices mapped to parameter names. */
-  read: z.record(z.uint32(), z.string()),
+  read: record.nullishToEmpty(z.uint32(), z.string()),
   /** write contains writable channel indices mapped to parameter names. */
-  write: z.record(z.uint32(), z.string()),
+  write: record.nullishToEmpty(z.uint32(), z.string()),
 });
 export interface Channels extends z.infer<typeof channelsZ> {}
 

package/src/auth/auth.spec.ts

@@ -33,8 +33,8 @@ describe("auth", () => {
     );
     const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
     const mw = client.middleware();
-    const res = await mw(DUMMY_CTX, async () => [DUMMY_CTX, null]);
-    expect(res).toEqual([DUMMY_CTX, null]);
+    const res = await mw(DUMMY_CTX, async () => DUMMY_CTX);
+    expect(res).toEqual(DUMMY_CTX);
   });
 
   test("invalid credentials", async () => {
@@ -49,8 +49,7 @@ describe("auth", () => {
       password: "wrong",
     });
     const mw = client.middleware();
-    const [, err] = await mw(DUMMY_CTX, async () => [DUMMY_CTX, null]);
-    expect(err).toBeInstanceOf(AuthError);
+    await expect(mw(DUMMY_CTX, async () => DUMMY_CTX)).rejects.toThrow(AuthError);
   });
 
   describe("token retry", () => {
@@ -68,16 +67,16 @@ describe("auth", () => {
         let isFirst = true;
         let tkOne: string | undefined;
         let tkTwo: string | undefined;
-        const [, err] = await mw(DUMMY_CTX, async () => {
+        const res = await mw(DUMMY_CTX, async () => {
           if (isFirst) {
             isFirst = false;
             tkOne = client.token;
-            return [DUMMY_CTX, new ErrorType()];
+            throw new ErrorType();
           }
           tkTwo = client.token;
-          return [DUMMY_CTX, null];
+          return DUMMY_CTX;
         });
-        expect(err).toBeNull();
+        expect(res).toEqual(DUMMY_CTX);
         expect(tkOne).toBeDefined();
         expect(tkTwo).toBeDefined();
       });
@@ -92,11 +91,11 @@ describe("auth", () => {
       );
       const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       const mw = client.middleware();
-      const [, err] = await mw(DUMMY_CTX, async () => [
-        DUMMY_CTX,
-        new InvalidTokenError(),
-      ]);
-      expect(err).toBeInstanceOf(InvalidTokenError);
+      await expect(
+        mw(DUMMY_CTX, async () => {
+          throw new InvalidTokenError();
+        }),
+      ).rejects.toThrow(InvalidTokenError);
     });
   });
 });

package/src/auth/auth.ts

@@ -7,16 +7,28 @@
 // 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, sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { type Middleware, type UnaryClient } from "@synnaxlabs/freighter";
+import { TimeStamp } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ExpiredTokenError, InvalidTokenError } from "@/errors";
 import { user } from "@/user";
 
-const insecureCredentialsZ = z.object({ username: z.string(), password: z.string() });
-interface InsecureCredentials extends z.infer<typeof insecureCredentialsZ> {}
+const credentialsZ = z.object({ username: z.string(), password: z.string() });
+interface Credentials extends z.infer<typeof credentialsZ> {}
 
-const tokenResponseZ = z.object({ token: z.string(), user: user.userZ });
+const clusterInfoZ = z.object({
+  clusterKey: z.string(),
+  nodeVersion: z.string().optional(),
+  nodeKey: z.number().optional(),
+  nodeTime: TimeStamp.z,
+});
+
+const tokenResponseZ = z.object({
+  token: z.string(),
+  user: user.userZ,
+  clusterInfo: clusterInfoZ.optional(),
+});
 
 const LOGIN_ENDPOINT = "/auth/login";
 
@@ -37,12 +49,12 @@ type AuthState =
 
 export class Client {
   private readonly client: UnaryClient;
-  private readonly credentials: InsecureCredentials;
+  private readonly credentials: Credentials;
   private authState: AuthState = { authenticated: false };
   authenticating: Promise<Error | null> | undefined;
   private retryCount: number;
 
-  constructor(client: UnaryClient, credentials: InsecureCredentials) {
+  constructor(client: UnaryClient, credentials: Credentials) {
     this.client = client;
     this.credentials = credentials;
     this.retryCount = 0;
@@ -70,8 +82,7 @@ export class Client {
 
   async changePassword(newPassword: string): Promise<void> {
     if (!this.authenticated) throw new Error("Not authenticated");
-    await sendRequired<typeof changePasswordReqZ, typeof changePasswordResZ>(
-      this.client,
+    await this.client.send(
       "/auth/change-password",
       {
         username: this.credentials.username,
@@ -87,39 +98,42 @@ export class Client {
   middleware(): Middleware {
     const mw: Middleware = async (reqCtx, next) => {
       if (!this.authenticated && !reqCtx.target.endsWith(LOGIN_ENDPOINT)) {
-        this.authenticating ??= new Promise((resolve, reject) => {
-          this.client
-            .send(
+        this.authenticating ??= (async (): Promise<Error | null> => {
+          try {
+            const res = await this.client.send(
               LOGIN_ENDPOINT,
               this.credentials,
-              insecureCredentialsZ,
+              credentialsZ,
               tokenResponseZ,
-            )
-            .then(([res, err]) => {
-              if (err != null) return resolve(err);
-              if (res == null) return resolve(new Error("No response from login"));
-              this.authState = {
-                authenticated: true,
-                user: res.user,
-                token: res.token,
-              };
-              resolve(null);
-            })
-            .catch(reject);
-        });
+            );
+            this.authState = {
+              authenticated: true,
+              user: res.user,
+              token: res.token,
+            };
+            return null;
+          } catch (err) {
+            return err instanceof Error ? err : new Error(String(err));
+          }
+        })();
         const err = await this.authenticating;
-        if (err != null) return [reqCtx, err];
+        if (err != null) throw err;
       }
       reqCtx.params.Authorization = `Bearer ${this.token}`;
-      const [resCtx, err] = await next(reqCtx);
-      if (RETRY_ON.some((e) => e.matches(err)) && this.retryCount < MAX_RETRIES) {
-        this.authState = { authenticated: false };
-        this.authenticating = undefined;
-        this.retryCount += 1;
-        return mw(reqCtx, next);
+      try {
+        const resCtx = await next(reqCtx);
+        this.retryCount = 0;
+        return resCtx;
+      } catch (err) {
+        if (RETRY_ON.some((e) => e.matches(err)) && this.retryCount < MAX_RETRIES) {
+          this.authState = { authenticated: false };
+          this.authenticating = undefined;
+          this.retryCount += 1;
+          return mw(reqCtx, next);
+        }
+        this.retryCount = 0;
+        throw err;
       }
-      this.retryCount = 0;
-      return [resCtx, err];
     };
     return mw;
   }

package/src/channel/batchRetriever.spec.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { DataType, errors, Rate } from "@synnaxlabs/x";
+import { DataType, errors, Rate, TimeSpan } from "@synnaxlabs/x";
 import { describe, expect, it, vi } from "vitest";
 
 import { channel } from "@/channel";
@@ -57,7 +57,10 @@ describe("channelchannel.Retriever", () => {
         operations: [],
       }));
     });
-    const retriever = new channel.DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(
+      base,
+      TimeSpan.milliseconds(10),
+    );
     const res = await Promise.all([
       retriever.retrieve([1]),
       retriever.retrieve([2]),
@@ -86,7 +89,10 @@ describe("channelchannel.Retriever", () => {
         operations: [],
       }));
     });
-    const retriever = new channel.DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(
+      base,
+      TimeSpan.milliseconds(10),
+    );
     const res = await Promise.all([
       retriever.retrieve([1]),
       retriever.retrieve([2]),
@@ -100,7 +106,10 @@ describe("channelchannel.Retriever", () => {
     const base = new MockRetriever(async (): Promise<channel.Payload[]> => {
       throw new Error("failed to fetch");
     });
-    const retriever = new channel.DebouncedBatchRetriever(base, 10);
+    const retriever = new channel.DebouncedBatchRetriever(
+      base,
+      TimeSpan.milliseconds(10),
+    );
     await expect(retriever.retrieve([1])).rejects.toThrow("failed to fetch");
   });
 });

package/src/channel/channel.spec.ts

@@ -226,6 +226,19 @@ describe("Channel", () => {
         async () => await client.channels.retrieve("1-1000"),
       ).rejects.toThrow(NotFoundError);
     });
+    test("retrieve by search term", async () => {
+      const prefix = id.create();
+      const names = [`${prefix}_1`, `${prefix}_2`];
+      await client.channels.create(
+        names.map((name) => ({ name, virtual: true, dataType: DataType.FLOAT32 })),
+      );
+      await expect
+        .poll(async () => {
+          const results = await client.channels.retrieve({ searchTerm: prefix });
+          return results.map((c) => c.name).sort();
+        })
+        .toEqual(names);
+    });
   });
 
   describe("delete", async () => {

package/src/channel/client.ts

@@ -7,15 +7,17 @@
 // 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 { type UnaryClient } from "@synnaxlabs/freighter";
 import {
   array,
   type CrudeDensity,
   type CrudeTimeRange,
+  type CrudeTimeSpan,
   type CrudeTimeStamp,
   DataType,
   type MultiSeries,
   status,
+  TimeSpan,
   type TypedArray,
 } from "@synnaxlabs/x";
 import { z } from "zod";
@@ -387,8 +389,7 @@ export class Client {
    */
   async delete(params: Params): Promise<void> {
     const { normalized, variant } = analyzeParams(params);
-    if (variant === "keys")
-      return await this.writer.delete({ keys: normalized as Key[] });
+    if (variant === "keys") return await this.writer.delete({ keys: normalized });
     return await this.writer.delete({ names: normalized as string[] });
   }
 
@@ -398,7 +399,9 @@ export class Client {
     return await this.writer.rename(array.toArray(keys), array.toArray(names));
   }
 
-  createDebouncedBatchRetriever(deb: number = 10): Retriever {
+  createDebouncedBatchRetriever(
+    deb: CrudeTimeSpan = TimeSpan.milliseconds(10),
+  ): Retriever {
     return new CacheRetriever(
       new DebouncedBatchRetriever(new ClusterRetriever(this.client), deb),
     );
@@ -414,8 +417,7 @@ export class Client {
   }
 
   async retrieveGroup(): Promise<group.Group> {
-    const res = await sendRequired(
-      this.client,
+    const res = await this.client.send(
       "/channel/retrieve-group",
       {},
       retrieveGroupReqZ,

package/src/channel/retriever.ts

@@ -7,8 +7,8 @@
 // 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 { array, DataType, debounce, zod } from "@synnaxlabs/x";
+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";
 
@@ -36,13 +36,10 @@ const reqZ = z.object({
   internal: z.boolean().optional(),
   legacyCalculated: z.boolean().optional(),
 });
-export interface RetrieveRequest extends z.input<typeof reqZ> {}
+export type RetrieveRequest = z.input<typeof reqZ>;
 
-export interface RetrieveOptions extends Omit<
-  RetrieveRequest,
-  "keys" | "names" | "search"
-> {}
-export interface PageOptions extends Omit<RetrieveOptions, "offset" | "limit"> {}
+export type RetrieveOptions = Omit<RetrieveRequest, "keys" | "names" | "search">;
+export type PageOptions = Omit<RetrieveOptions, "offset" | "limit">;
 
 const resZ = z.object({ channels: array.nullishToEmpty(payloadZ) });
 
@@ -86,13 +83,7 @@ export class ClusterRetriever implements Retriever {
   }
 
   private async execute(request: RetrieveRequest): Promise<Payload[]> {
-    const res = await sendRequired(
-      this.client,
-      "/channel/retrieve",
-      request,
-      reqZ,
-      resZ,
-    );
+    const res = await this.client.send("/channel/retrieve", request, reqZ, resZ);
     return res.channels;
   }
 }
@@ -204,7 +195,7 @@ export class DebouncedBatchRetriever implements Retriever {
   private readonly wrapped: Retriever;
   private readonly debouncedRun: () => void;
 
-  constructor(wrapped: Retriever, deb: number) {
+  constructor(wrapped: Retriever, deb: CrudeTimeSpan) {
     this.wrapped = wrapped;
     this.debouncedRun = debounce(() => {
       void this.run();

package/src/channel/types.gen.ts

@@ -85,8 +85,7 @@ export const payloadZ = z.object({
   isIndex: z.boolean(),
   /**
    * index is the channel used to index this channel's values, associating
-   * each value with a timestamp. If zero, the channel's data will be
-   * indexed using its rate.
+   * each value with a timestamp.
    */
   index: keyZ,
   /** alias is an optional alternate name for the channel within a specific context. */

package/src/channel/writer.ts

@@ -7,7 +7,7 @@
 // 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 { type UnaryClient } from "@synnaxlabs/freighter";
 import { type DataType } from "@synnaxlabs/x";
 import { z } from "zod";
 
@@ -47,11 +47,7 @@ export class Writer {
   }
 
   async create(channels: New[]): Promise<Payload[]> {
-    const { channels: created } = await sendRequired<
-      typeof createReqZ,
-      typeof createResZ
-    >(
-      this.client,
+    const { channels: created } = await this.client.send(
       "/channel/create",
       {
         channels: channels.map((c) => ({
@@ -68,25 +64,13 @@ export class Writer {
 
   async delete(props: DeleteProps): Promise<void> {
     const keys = keyZ.array().parse(props.keys ?? []);
-    await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
-      this.client,
-      "/channel/delete",
-      props,
-      deleteReqZ,
-      deleteResZ,
-    );
+    await this.client.send("/channel/delete", props, deleteReqZ, deleteResZ);
     if (keys.length > 0) this.cache.delete(keys);
     if (props.names != null) this.cache.delete(props.names);
   }
 
   async rename(keys: Key[], names: string[]): Promise<void> {
-    await sendRequired<typeof renameReqZ, typeof renameResZ>(
-      this.client,
-      "/channel/rename",
-      { keys, names },
-      renameReqZ,
-      renameResZ,
-    );
+    await this.client.send("/channel/rename", { keys, names }, renameReqZ, renameResZ);
     this.cache.rename(keys, names);
   }
 }

package/src/client.ts

@@ -45,6 +45,7 @@ export const synnaxParamsZ = z.object({
   username: z.string().min(1, "Username is required"),
   password: z.string().min(1, "Password is required"),
   connectivityPollFrequency: TimeSpan.z.default(TimeSpan.seconds(30)),
+  clockSkewThreshold: TimeSpan.z.default(TimeSpan.seconds(1)),
   secure: z.boolean().default(false),
   name: z.string().optional(),
   retry: breaker.breakerConfigZ.optional(),
@@ -116,6 +117,7 @@ export default class Synnax extends framer.Client {
       username,
       password,
       connectivityPollFrequency,
+      clockSkewThreshold,
       secure,
       retry: breaker,
     } = parsedParams;
@@ -141,6 +143,7 @@ export default class Synnax extends framer.Client {
       connectivityPollFrequency,
       this.clientVersion,
       parsedParams.name,
+      clockSkewThreshold,
     );
     this.control = new control.Client(this);
     this.ontology = new ontology.Client(this.transport.unary);

package/src/connection/checker.ts

@@ -7,8 +7,14 @@
 // 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 { migrate, TimeSpan } from "@synnaxlabs/x";
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import {
+  ClockSkewCalculator,
+  type CrudeTimeSpan,
+  migrate,
+  TimeSpan,
+  TimeStamp,
+} from "@synnaxlabs/x";
 import { z } from "zod";
 
 export const statusZ = z.enum(["disconnected", "connecting", "connected", "failed"]);
@@ -22,12 +28,15 @@ export const stateZ = z.object({
   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();
 
@@ -38,6 +47,8 @@ const DEFAULT: State = {
   message: "Disconnected",
   clientServerCompatible: false,
   clientVersion: __VERSION__,
+  clockSkew: TimeSpan.ZERO,
+  clockSkewExceeded: false,
 };
 
 const createWarning = (
@@ -46,16 +57,16 @@ const createWarning = (
   clientIsNewer: boolean,
 ): string => {
   const toUpgrade = clientIsNewer ? "Core" : "client";
-  return `Synnax Core version ${nodeVersion != null ? `${nodeVersion} ` : ""}is too ${clientIsNewer ? "old" : "new"} for client version ${clientVersion}.
+  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}-version`;
+  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.seconds(30);
+  private readonly pollFrequency: TimeSpan;
   private readonly client: UnaryClient;
   private readonly name?: string;
   private interval?: NodeJS.Timeout;
@@ -63,6 +74,9 @@ export class Checker {
   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.
@@ -71,15 +85,18 @@ export class Checker {
    */
   constructor(
     client: UnaryClient,
-    pollFreq: TimeSpan = TimeSpan.seconds(30),
+    pollFreq: CrudeTimeSpan = TimeSpan.seconds(30),
     clientVersion: string,
     name?: string,
+    clockSkewThreshold: CrudeTimeSpan = TimeSpan.seconds(1),
   ) {
     this._state = { ...DEFAULT };
     this.client = client;
-    this.pollFrequency = pollFreq;
+    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();
   }
@@ -95,14 +112,30 @@ export class Checker {
    */
   async check(): Promise<State> {
     const prevStatus = this._state.status;
+    const prevSkewExceeded = this._state.clockSkewExceeded;
+    const measureSkew = !this.checking;
+    this.checking = true;
     try {
-      const res = await sendRequired(
-        this.client,
+      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;
@@ -140,8 +173,13 @@ export class Checker {
       this._state.status = "failed";
       this._state.error = err as Error;
       this._state.message = this.state.error?.message;
+    } finally {
+      this.checking = false;
     }
-    if (this.onChangeHandlers.length > 0 && prevStatus !== this._state.status)
+    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;
   }