@synnaxlabs/client 0.57.2 → 0.58.0

package/src/framer/streamer.ts

@@ -7,8 +7,13 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { EOF, type Stream, type WebSocketClient } from "@synnaxlabs/freighter";
-import { errors, Rate, zod } from "@synnaxlabs/x";
+import {
+  EOF,
+  type Stream,
+  Unreachable,
+  type WebSocketClient,
+} from "@synnaxlabs/freighter";
+import { errors, Rate, TimeSpan, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { type channel } from "@/channel";
@@ -23,6 +28,7 @@ const reqZ = z.object({
   downsampleFactor: z.int(),
   throttleRate: Rate.z.optional(),
   excludeGroups: z.uint32().array().optional(),
+  keepAlive: TimeSpan.z.optional(),
 });
 
 /**
@@ -31,7 +37,11 @@ const reqZ = z.object({
  */
 export interface StreamerRequest extends z.infer<typeof reqZ> {}
 
-const resZ = z.object({ frame: frameZ });
+const resZ = z.object({
+  frame: frameZ,
+  /** Marks an empty response the Core emits so a dead connection is detectable. */
+  keepAlive: z.boolean().optional(),
+});
 
 /**
  * Response interface for streaming frames from a Synnax cluster.
@@ -49,6 +59,10 @@ const intermediateStreamerConfigZ = z.object({
   /** excludeGroups sets writer group IDs whose frames should be filtered out by the
    Core. Used for telemetry bypass deduplication. */
   excludeGroups: z.uint32().array().default([]),
+  /** Interval at which the Core emits keep-alive responses so a silently dead
+   connection fails reads instead of hanging forever. TimeSpan.ZERO disables
+   detection. Defaults to 5 seconds. */
+  keepAlive: TimeSpan.z.default(TimeSpan.seconds(5)),
 });
 
 /** Zod schema for {@link StreamerConfig}. A bare channel list parses as a config. */
@@ -73,7 +87,11 @@ export interface Streamer extends AsyncIterator<Frame>, AsyncIterable<Frame> {
   update: (channels: channel.Params) => Promise<void>;
   /** Close the streamer and free all associated resources. */
   close: () => void;
-  /** Read the next frame of telemetry. */
+  /**
+   * Read the next frame of telemetry.
+   * @throws {Unreachable} if keep-alives were flowing and the stream then stays silent
+   * past the keep-alive deadline: the connection is presumed dead.
+   */
   read: () => Promise<Frame>;
 }
 
@@ -101,14 +119,19 @@ export const createStreamOpener =
       cfg.downsampleFactor,
       cfg.throttleRate,
       cfg.excludeGroups,
+      cfg.keepAlive,
     );
     stream.send({
       keys: Array.from(adapter.keys),
       downsampleFactor: cfg.downsampleFactor,
       throttleRate: cfg.throttleRate,
       excludeGroups: cfg.excludeGroups,
+      keepAlive: cfg.keepAlive,
     });
-    await stream.receive();
+    // A keep-alive can beat the open ack onto the wire, so the ack is the first
+    // non-keep-alive response.
+    let res = await stream.receive();
+    while (res.keepAlive === true) res = await stream.receive();
     return streamer;
   };
 
@@ -124,12 +147,20 @@ export const openStreamer = async (
   config: StreamerConfig,
 ): Promise<Streamer> => await createStreamOpener(retrieveChannels, client)(config);
 
+// Missing this many keep-alive intervals in a row fails the pending read: one is normal
+// jitter, three is a dead connection.
+const KEEP_ALIVE_DEADLINE_FACTOR = 3;
+
 class BaseStreamer implements Streamer {
   private readonly stream: StreamProxy<typeof reqZ, typeof resZ>;
   private readonly adapter: ReadAdapter;
   private readonly downsampleFactor: number;
   private readonly throttleRate: Rate;
   private readonly excludeGroups: number[];
+  private readonly deadline: TimeSpan;
+  // Set once the Core proves keep-alive support by sending one, so the deadline never
+  // arms against a Core that will not send them.
+  private armed = false;
 
   constructor(
     stream: Stream<typeof reqZ, typeof resZ>,
@@ -137,12 +168,16 @@ class BaseStreamer implements Streamer {
     downsampleFactor: number = 1,
     throttleRate: Rate = new Rate(0),
     excludeGroups: number[] = [],
+    keepAlive: TimeSpan = TimeSpan.ZERO,
   ) {
     this.stream = new StreamProxy("Streamer", stream);
     this.adapter = adapter;
     this.downsampleFactor = downsampleFactor;
     this.throttleRate = throttleRate;
     this.excludeGroups = excludeGroups;
+    this.deadline = TimeSpan.milliseconds(
+      keepAlive.milliseconds * KEEP_ALIVE_DEADLINE_FACTOR,
+    );
   }
 
   get keys(): channel.Key[] {
@@ -160,7 +195,37 @@ class BaseStreamer implements Streamer {
   }
 
   async read(): Promise<Frame> {
-    return this.adapter.adapt(new Frame((await this.stream.receive()).frame));
+    while (true) {
+      const res = await this.receiveWithDeadline();
+      if (res.keepAlive === true) {
+        if (!this.deadline.isZero) this.armed = true;
+        continue;
+      }
+      return this.adapter.adapt(new Frame(res.frame));
+    }
+  }
+
+  private async receiveWithDeadline(): Promise<z.infer<typeof resZ>> {
+    const received = this.stream.receive();
+    if (!this.armed) return await received;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        const silence = this.deadline.toString();
+        const message = `streamer received no response for ${silence}`;
+        reject(new Unreachable({ message }));
+      }, this.deadline.milliseconds);
+    });
+    try {
+      return await Promise.race([received, deadline]);
+    } catch (err) {
+      // The read already failed for its caller; a late settle of the losing receive
+      // must not surface as an unhandled rejection.
+      received.catch(() => {});
+      throw errors.fromUnknown(err);
+    } finally {
+      clearTimeout(timer);
+    }
   }
 
   async update(channels: channel.Params): Promise<void> {

package/src/framer/writer.ts

@@ -146,9 +146,9 @@ const authorityParamsZ = z
     control.authorityZ.optional(),
   ])
   .transform(([value, authority]) => {
-    if (control.authorityZ.safeParse(value).success)
-      return { keys: [], authorities: [value as control.Authority] };
-    if (keyZ.or(nameZ).safeParse(value).success) {
+    if (z.validate(control.authorityZ, value))
+      return { keys: [], authorities: [value] };
+    if (z.validate(keyZ.or(nameZ), value)) {
       if (authority == null)
         throw new Error(
           "authority is required when setting authority for a single channel",
@@ -158,8 +158,7 @@ const authorityParamsZ = z
         authorities: [authority],
       };
     }
-    const oValue = value as Record<channel.Key | channel.Name, control.Authority>;
-    return { keys: Object.keys(oValue), authorities: Object.values(oValue) };
+    return { keys: Object.keys(value), authorities: Object.values(value) };
   });
 
 /**

package/src/index.ts

@@ -7,6 +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 "zod/compile";
+
 export { access } from "@/access";
 export type { Policy } from "@/access/policy/types.gen";
 export type { Role } from "@/access/role/types.gen";

package/src/lineplot/actions.gen.ts

@@ -16,6 +16,7 @@ import { actions } from "@/actions";
 import { channel } from "@/channel";
 import {
   axisKeyZ,
+  customRangeZ,
   downsampleModeZ,
   keyZ,
   type LinePlot,
@@ -154,6 +155,16 @@ export const setRangesPayloadZ = z.object({
 
 export type SetRangesPayload = z.infer<typeof setRangesPayloadZ>;
 
+/**
+ * SetCustomRange sets the window the "custom" range key resolves to. A null custom
+ * clears the window.
+ */
+export const setCustomRangePayloadZ = z.object({
+  custom: zod.nullToUndefined(customRangeZ),
+});
+
+export type SetCustomRangePayload = z.infer<typeof setCustomRangePayloadZ>;
+
 /** SetAxisLabel sets the label rendered along the axis identified by key. */
 export const setAxisLabelPayloadZ = z.object({
   key: axisKeyZ,
@@ -380,6 +391,10 @@ export const actionZ = z.discriminatedUnion("type", [
   z.object({ type: z.literal("add_range"), addRange: addRangePayloadZ }),
   z.object({ type: z.literal("remove_range"), removeRange: removeRangePayloadZ }),
   z.object({ type: z.literal("set_ranges"), setRanges: setRangesPayloadZ }),
+  z.object({
+    type: z.literal("set_custom_range"),
+    setCustomRange: setCustomRangePayloadZ,
+  }),
   z.object({ type: z.literal("set_axis_label"), setAxisLabel: setAxisLabelPayloadZ }),
   z.object({
     type: z.literal("set_axis_label_direction"),
@@ -536,6 +551,15 @@ export const setRanges = (payload: z.input<typeof setRangesPayloadZ>): Action =>
   }),
 });
 
+export const setCustomRange = (
+  payload: z.input<typeof setCustomRangePayloadZ>,
+): Action => ({
+  type: "set_custom_range",
+  setCustomRange: zod.parse(setCustomRangePayloadZ, payload, {
+    label: "line plot set_custom_range action payload",
+  }),
+});
+
 export const setAxisLabel = (
   payload: z.input<typeof setAxisLabelPayloadZ>,
 ): Action => ({
@@ -748,6 +772,10 @@ export interface Handlers {
   addRange: (state: Draft<LinePlot>, payload: AddRangePayload) => HandlerResult;
   removeRange: (state: Draft<LinePlot>, payload: RemoveRangePayload) => HandlerResult;
   setRanges: (state: Draft<LinePlot>, payload: SetRangesPayload) => HandlerResult;
+  setCustomRange: (
+    state: Draft<LinePlot>,
+    payload: SetCustomRangePayload,
+  ) => HandlerResult;
   setAxisLabel: (state: Draft<LinePlot>, payload: SetAxisLabelPayload) => HandlerResult;
   setAxisLabelDirection: (
     state: Draft<LinePlot>,
@@ -830,6 +858,8 @@ export const createReduceAll = (handlers: Handlers) =>
         return handlers.removeRange(state, action.removeRange);
       case "set_ranges":
         return handlers.setRanges(state, action.setRanges);
+      case "set_custom_range":
+        return handlers.setCustomRange(state, action.setCustomRange);
       case "set_axis_label":
         return handlers.setAxisLabel(state, action.setAxisLabel);
       case "set_axis_label_direction":

package/src/lineplot/actions.ts

@@ -25,6 +25,7 @@ import {
   setAxisTickSpacing,
   setAxisType,
   setChannels,
+  setCustomRange,
   setLegendHidden,
   setLegendPosition,
   setLine,
@@ -261,6 +262,19 @@ const handlers: Handlers = {
     };
   },
 
+  setCustomRange: (state, payload) => {
+    const old = state.ranges.custom;
+    state.ranges.custom = payload.custom;
+    return {
+      inverse: [
+        setCustomRange({
+          custom: old === undefined ? undefined : actions.snapshotDraft(old),
+        }),
+      ],
+      targets: ["range:custom"],
+    };
+  },
+
   setAxisLabel: (state, payload) => {
     const axis = state.axes[payload.key];
     const inverse = [setAxisLabel({ key: payload.key, label: axis.label })];

package/src/lineplot/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { color, spatial, text, uuid } from "@synnaxlabs/x";
+import { color, spatial, telem, text, uuid, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { channel } from "@/channel";
@@ -81,26 +81,6 @@ export const channelsZ = z.object({
 });
 export interface Channels extends z.infer<typeof channelsZ> {}
 
-/** Ranges binds range keys to each x-axis. */
-export const rangesZ = z.object({
-  /**
-   * x1 are the range keys plotted against the x1 axis. Range keys are opaque strings
-   * rather than UUIDs because the console layers synthetic rolling-window ranges (e.g.
-   * "recent", "rolling1m") alongside persisted ranges; the server stores whatever the
-   * client sends.
-   */
-  x1: z
-    .string()
-    .array()
-    .default(() => []),
-  /** x2 are the range keys plotted against the x2 axis. */
-  x2: z
-    .string()
-    .array()
-    .default(() => []),
-});
-export interface Ranges extends z.infer<typeof rangesZ> {}
-
 /**
  * ManualBounds controls whether an axis uses a manually-set bound on each side
  * independently. When a side is false (the default), the corresponding entry in
@@ -175,6 +155,42 @@ export interface Rule extends z.infer<typeof ruleZ> {}
 export const keyZ = z.uuid();
 export type Key = z.infer<typeof keyZ>;
 
+/** DynamicCustomRange is a rolling window. */
+export const dynamicCustomRangeZ = z.object({
+  variant: z.literal("dynamic"),
+  /** span is the span of the window, which ends now. */
+  span: telem.numericTimeSpanZ.default(0),
+});
+export interface DynamicCustomRange extends z.infer<typeof dynamicCustomRangeZ> {}
+
+/** StaticCustomRange is a fixed window. */
+export const staticCustomRangeZ = z.object({
+  variant: z.literal("static"),
+  /** start is the inclusive start of the fixed window. */
+  start: telem.stringTimeStampZ,
+  /** end is the exclusive end of the fixed window. */
+  end: telem.stringTimeStampZ,
+});
+export interface StaticCustomRange extends z.infer<typeof staticCustomRangeZ> {}
+
+export const CUSTOM_RANGE_TYPES = ["dynamic", "static"] as const;
+export const customRangeTypeZ = z.enum(CUSTOM_RANGE_TYPES);
+export type CustomRangeType = z.infer<typeof customRangeTypeZ>;
+
+/** CustomRange is the window a plot's synthetic "custom" range key resolves to. */
+export const customRangeZ = z.discriminatedUnion("variant", [
+  dynamicCustomRangeZ,
+  staticCustomRangeZ,
+]);
+export type CustomRange = DynamicCustomRange | StaticCustomRange;
+
+export const CUSTOM_RANGE_SCHEMAS: {
+  [K in CustomRangeType]: z.ZodType<Extract<CustomRange, { variant: K }>>;
+} = {
+  dynamic: dynamicCustomRangeZ,
+  static: staticCustomRangeZ,
+};
+
 /** Axis is the configuration for a single plot axis. */
 export const axisZ = z.object({
   /** key identifies which of the six axes this configuration applies to. */
@@ -203,6 +219,28 @@ export const axisZ = z.object({
 });
 export interface Axis extends z.infer<typeof axisZ> {}
 
+/** Ranges binds range keys to each x-axis. */
+export const rangesZ = z.object({
+  /**
+   * x1 are the range keys plotted against the x1 axis. Range keys are opaque strings
+   * rather than UUIDs because the console layers synthetic rolling-window ranges (e.g.
+   * "recent", "rolling1m") alongside persisted ranges; the server stores whatever the
+   * client sends.
+   */
+  x1: z
+    .string()
+    .array()
+    .default(() => []),
+  /** x2 are the range keys plotted against the x2 axis. */
+  x2: z
+    .string()
+    .array()
+    .default(() => []),
+  /** custom is the window the "custom" range key resolves to. */
+  custom: zod.nullToUndefined(customRangeZ),
+});
+export interface Ranges extends z.infer<typeof rangesZ> {}
+
 /** Axes bundles configuration for all six fixed plot axes. */
 export const axesZ = z.object({
   /** x1 is the x1 axis configuration. */

package/src/panel/client.ts

@@ -263,8 +263,6 @@ export class Client extends query.Retriever<typeof retrieveMultiParamsZ, Key, Pa
     );
   }
 
-  async delete(key: Key, opts?: query.WriteOptions): Promise<void>;
-  async delete(keys: Key[], opts?: query.WriteOptions): Promise<void>;
   async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
     const keysArr = array.toArray(keys);
     const drop = () => [

package/src/project/client.ts

@@ -182,8 +182,6 @@ export class Client extends query.Retriever<typeof retrieveMultiParamsZ, Key, Pr
     this.mergeThrough(key, { layout });
   }
 
-  async delete(key: Key, opts?: query.WriteOptions): Promise<void>;
-  async delete(keys: Key[], opts?: query.WriteOptions): Promise<void>;
   async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
     const keysArr = array.toArray(keys);
     const drop = () => [

package/src/query/indexes.ts

@@ -11,25 +11,32 @@ import { type record, type state } from "@synnaxlabs/x";
 
 /**
  * An exact-match secondary index over a table's live entries. `extract` reads one
- * index value from each entry. Register the index on its owning table's `indexes`
- * param; the table keeps it current across every mutation, rollbacks and resets
- * included. Tombstones are never indexed.
+ * index value from each entry; a null leaves the entry out of the index. Register
+ * the index on its owning table's `indexes` param; the table keeps it current
+ * across every mutation, rollbacks and resets included. Tombstones are never
+ * indexed.
  */
 export class LookupIndex<
   Key extends record.Key = record.Key,
   Value extends state.State = state.State,
   IndexValue extends record.Key = record.Key,
 > {
-  private readonly extract: (value: Value) => IndexValue;
+  private readonly extract: (value: Value) => IndexValue | null;
   private readonly buckets = new Map<IndexValue, Map<Key, Value>>();
   private readonly indexed = new Map<Key, IndexValue>();
 
-  constructor(extract: (value: Value) => IndexValue) {
+  constructor(extract: (value: Value) => IndexValue | null) {
     this.extract = extract;
   }
 
-  /** Returns the entries whose extracted index value equals the given value. */
-  get(value: IndexValue): Value[] {
+  /**
+   * Returns the entries whose extracted index value equals the given value. Given an
+   * array, returns the entries matching any of the values, in the order of the values
+   * and each entry once.
+   */
+  get(value: IndexValue | IndexValue[]): Value[] {
+    if (Array.isArray(value))
+      return Array.from(new Set(value)).flatMap((v) => this.get(v));
     const bucket = this.buckets.get(value);
     if (bucket == null) return [];
     return Array.from(bucket.values());
@@ -43,6 +50,10 @@ export class LookupIndex<
     const next = this.extract(value);
     const prev = this.indexed.get(key);
     if (prev !== undefined && prev !== next) this.unbucket(prev, key);
+    if (next == null) {
+      this.indexed.delete(key);
+      return;
+    }
     let bucket = this.buckets.get(next);
     if (bucket == null) {
       bucket = new Map();

package/src/query/table.ts

@@ -177,7 +177,7 @@ export class Table<
     this.equal = equal;
     this.fetchEntries = fetch;
     this.hydrateMode = hydrate;
-    this.indexes = indexes;
+    this.indexes = [...indexes];
     this.fetchBatcher =
       fetch == null
         ? null
@@ -186,7 +186,27 @@ export class Table<
             exec: async (requests) => {
               const keys = new Set<Key>();
               requests.forEach(({ req }) => req.forEach((key) => keys.add(key)));
-              const fetched = await fetch(Array.from(keys));
+              let fetched: Array<Keyed<Key, Value>>;
+              try {
+                fetched = await fetch(Array.from(keys));
+              } catch (exc) {
+                if (!NotFoundError.matches(exc) || requests.length === 1)
+                  throw errors.fromUnknown(exc);
+                // A strict fetch rejects the whole batch when any caller's key
+                // has vanished. Refetch per caller so each settles exactly as
+                // its own request would have, keeping the batch transparent.
+                await Promise.all(
+                  requests.map(async ({ req, resolve, reject }) => {
+                    try {
+                      const mine = new Set(req);
+                      resolve((await fetch(req)).filter(({ key }) => mine.has(key)));
+                    } catch (exc) {
+                      reject(exc);
+                    }
+                  }),
+                );
+                return;
+              }
               // The window's fetch carries other callers' keys too; each caller
               // hydrates only the entries it asked for.
               requests.forEach(({ req, resolve }) => {
@@ -207,6 +227,17 @@ export class Table<
     for (const index of this.indexes) index.delete(key);
   }
 
+  /**
+   * Registers a secondary index and backfills it from the live entries, for a
+   * domain that owns an index's meaning but not the table it reads.
+   * @returns the index.
+   */
+  index<I extends LookupIndex<Key, Value>>(index: I): I {
+    this.entries.forEach((value, key) => index.set(key, value));
+    this.indexes.push(index);
+    return index;
+  }
+
   private setOne(
     key: Key,
     value: state.SetArg<Value | undefined>,
@@ -281,11 +312,10 @@ export class Table<
     return this.set(arr);
   }
 
-  /** Returns every entry in the table. */
-  get(): Value[];
+  /** Returns every entry in the table, or every entry the filter accepts. */
+  get(filter?: (value: Value) => boolean): Value[];
   get(key: Key): Value | undefined;
   get(keys: Key[]): Value[];
-  get(filter: (value: Value) => boolean): Value[];
   get(keys?: Key | Key[] | ((value: Value) => boolean)): Value | Value[] | undefined {
     if (keys === undefined) return Array.from(this.entries.values());
     if (typeof keys === "function")
@@ -327,9 +357,10 @@ export class Table<
   /**
    * Resolves the given keys to records: serves cached entries and fetches the misses
    * through the table's fetch, hydrating results under the declared mode. With refresh,
-   * every key is fetched regardless of presence. Returns the table's entries for the
-   * found keys in input order, deduplicated; keys the cluster no longer has are
-   * omitted. Tables without a fetch serve cached entries only.
+   * every key is fetched regardless of presence and cached entries the fetch omits are
+   * tombstoned. Returns the table's entries for the found keys in input order,
+   * deduplicated; keys the cluster no longer has are omitted. Tables without a fetch
+   * serve cached entries only.
    */
   async retrieve(keys: Key[], opts: { refresh?: boolean } = {}): Promise<Value[]> {
     if (this.fetchBatcher != null) {
@@ -338,9 +369,19 @@ export class Table<
       if (misses.length > 0) {
         const gen = this.gen;
         const fetched = await this.fetchBatcher.enqueue(misses);
-        if (gen === this.gen && fetched.length > 0)
-          if (opts.refresh === true) this.set(fetched);
-          else this.ingest(fetched);
+        if (gen === this.gen)
+          if (opts.refresh === true) {
+            // A refresh is authoritative for its keys: cached entries the
+            // fetch omitted vanished from the cluster and are tombstoned.
+            const present = new Set<Key>(fetched.map(({ key }) => key));
+            const vanished = misses.filter(
+              (key) => !present.has(key) && this.entries.has(key),
+            );
+            this.batch(() => {
+              if (vanished.length > 0) this.delete(vanished);
+              if (fetched.length > 0) this.set(fetched);
+            });
+          } else if (fetched.length > 0) this.ingest(fetched);
       }
     }
     const seen = new Set<Key>();

package/src/rack/client.ts

@@ -307,11 +307,12 @@ export class Client extends query.Retriever<
   }
 
   private async fetchSingle(q: SingleQuery): Promise<Rack> {
-    // Names are not unique, so only key queries can be served from the table.
-    // A status-bearing hit needs both the record and its status cached.
+    // Names are not unique and the table never holds status, so only keyed status-free
+    // queries can be served from it.
     if ("key" in q && q.includeStatus !== true) {
-      const cached = this.store.get(q.key);
-      if (cached != null) return this.sugar(cached);
+      const racks = await this.store.retrieve([q.key]);
+      checkForMultipleOrNoResults("Rack", q, racks, true);
+      return this.sugar(racks[0]);
     }
     const racks = await this.execRetrieve(q);
     checkForMultipleOrNoResults("Rack", q, racks, true);