@synnaxlabs/client 0.56.2 → 0.57.0

package/src/framer/cache/dynamic.ts

@@ -0,0 +1,279 @@
+// 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 { alamos } from "@synnaxlabs/alamos";
+import {
+  DataType,
+  math,
+  MultiSeries,
+  Series,
+  type TimeSpan,
+  TimeStamp,
+} from "@synnaxlabs/x";
+
+import { IDENTITY_TRANSFORM, type Transform } from "@/framer/cache/transform";
+
+/** Response from a write to the {@link Dynamic} cache. */
+export interface WriteResponse {
+  /** Series flushed because the write did not fit in the current buffer. */
+  flushed: MultiSeries;
+  /** A list of series that were allocated during the write. */
+  allocated: MultiSeries;
+}
+
+/** Props for the {@link Dynamic} cache. */
+export interface DynamicProps {
+  /**
+   * Sets the maximum size of the buffer that the cache will maintain before flushing
+   * data out to the caller.
+   */
+  dynamicBufferSize: number | TimeSpan;
+  /** Applied to every series before it enters a buffer. Defaults to identity. */
+  transform?: Transform;
+  /** Used for logging. */
+  instrumentation?: alamos.Instrumentation;
+  /** Pulls the current time. */
+  now?: () => TimeStamp;
+}
+
+// Bounds for dynamically calculated buffer sizes.
+const MIN_SIZE = 100;
+const MAX_SIZE = 1e6;
+// Size used until enough writes have arrived to estimate a rate.
+const DEF_SIZE = 1e4;
+const MAX_DEF_WRITES = 100;
+
+// Variable-rate types allocate bytes, not samples. Rough bytes-per-sample estimate.
+const VARIABLE_DT_MULTIPLIER = 40;
+
+/**
+ * A cache for channel data that maintains a single, rolling Series as a buffer
+ * for channel data. The buffer's data type is derived from the first written series,
+ * so the cache needs no channel metadata.
+ */
+export class Dynamic {
+  private readonly props: Required<Omit<DynamicProps, "now">>;
+
+  private counter = 0;
+  private curr: Series | null = null;
+  /** End timestamp of the last fully written stamped series in the current buffer.
+   * Null when the buffer holds unstamped or partially written data, in which case
+   * the flush falls back to the wall clock. */
+  private currDataEnd: TimeStamp | null = null;
+  private avgRate: number = 0;
+  private timeOfLastWrite: TimeStamp;
+  private totalWrites: number = 0;
+  private readonly now: () => TimeStamp;
+
+  constructor(props: DynamicProps) {
+    const {
+      dynamicBufferSize,
+      transform = IDENTITY_TRANSFORM,
+      instrumentation = alamos.NOOP,
+      now = () => TimeStamp.now(),
+    } = props;
+    this.props = { dynamicBufferSize, transform, instrumentation };
+    this.now = now;
+    this.timeOfLastWrite = this.now();
+  }
+
+  /** @returns the number of samples currently held in the cache. */
+  get length(): number {
+    return this.curr?.length ?? 0;
+  }
+
+  /**
+   * @returns the current buffer being written to by the cache. Under no circumstances
+   * should this be modified by the caller.
+   */
+  get leadingBuffer(): Series | null {
+    return this.curr;
+  }
+
+  /**
+   * @returns a list of buffers that were filled by the cache during the write. If the
+   * current buffer is able to fit all writes, no buffers will be returned.
+   */
+  write(series: MultiSeries): WriteResponse {
+    const res: WriteResponse = {
+      flushed: new MultiSeries([]),
+      allocated: new MultiSeries([]),
+    };
+    const list = series.series;
+    for (let i = 0; i < list.length; i++) this._write(list[i], res);
+    return res;
+  }
+
+  private allocate(
+    capacity: number,
+    alignment: bigint,
+    start: TimeStamp,
+    source: Series,
+    sampleIndex: number,
+  ): Series {
+    this.counter++;
+    const dt = this.props.transform.resolveDataType(source.dataType);
+    // Bigint series narrowed to a non-bigint buffer store each value as a small delta
+    // off a per-buffer anchor to avoid losing precision. For timestamps, now() is
+    // close enough to the values being written. For int64 and uint64 the values can
+    // be anything, so the first sample we see is used as the anchor.
+    const narrowing = source.dataType.usesBigInt && !dt.usesBigInt;
+    let sampleOffset: math.Numeric = 0;
+    if (narrowing)
+      if (source.dataType.equals(DataType.TIMESTAMP)) sampleOffset = start.valueOf();
+      else if (sampleIndex < source.length)
+        sampleOffset = BigInt(source.data[sampleIndex].valueOf());
+    return Series.alloc({
+      capacity: dt.isVariable ? capacity * VARIABLE_DT_MULTIPLIER : capacity,
+      dataType: dt,
+      timeRange: start.range(TimeStamp.MAX),
+      sampleOffset,
+      glBufferUsage: "dynamic",
+      alignment,
+      key: `dynamic-${this.counter}`,
+    });
+  }
+
+  // Unstamped series (virtual channels, writes without an in-frame index) fall back
+  // to the wall clock.
+  private allocStart(series: Series): TimeStamp {
+    return series.timeRange.isZero ? this.now() : series.timeRange.start;
+  }
+
+  private allocCurr(
+    res: WriteResponse,
+    alignment: bigint,
+    start: TimeStamp,
+    source: Series,
+    sampleIndex: number,
+  ): Series {
+    this.curr = this.allocate(
+      this.nextBufferSize(),
+      alignment,
+      start,
+      source,
+      sampleIndex,
+    );
+    res.allocated.push(this.curr);
+    return this.curr;
+  }
+
+  private flushCurr(res: WriteResponse): void {
+    if (this.curr == null) return;
+    this.curr.timeRange.end = this.currDataEnd ?? this.now();
+    this.currDataEnd = null;
+    res.flushed.push(this.curr);
+    this.curr = null;
+  }
+
+  private _write(series: Series, res: WriteResponse): void {
+    const { transform, instrumentation: ins } = this.props;
+    if (this.curr != null) {
+      const resolved = transform.resolveDataType(series.dataType);
+      if (!this.curr.dataType.equals(resolved)) {
+        // The channel's data type changed (e.g. a calculated channel was reconfigured).
+        ins.L.warn("buffer data type changed, resetting", {
+          prev: this.curr.dataType.toString(),
+          next: resolved.toString(),
+        });
+        this.flushCurr(res);
+      } else if (series.alignment < this.curr.alignment) {
+        // The alignment counter rewound (e.g. the Core restarted and reset its
+        // in-memory counter).
+        ins.L.warn("alignment regressed, resetting buffer", {
+          buffer: this.curr.alignment.toString(),
+          incoming: series.alignment.toString(),
+        });
+        this.flushCurr(res);
+      }
+    }
+    let curr = this.curr;
+    if (curr == null)
+      curr = this.allocCurr(res, series.alignment, this.allocStart(series), series, 0);
+    else {
+      // overlap > 0: the incoming series steps back into samples the current buffer
+      // already holds. overlap < 0: there is a gap between the buffer and the series.
+      const overlap = Number(curr.alignment + BigInt(curr.length) - series.alignment);
+      if (overlap > 0) {
+        // Drop the re-sent leading samples; a fresh allocation here would fragment
+        // the cache with overlapping series. sub() is zero-copy.
+        if (overlap >= series.length) return;
+        series = series.sub(overlap);
+      } else if (overlap < 0) {
+        this.flushCurr(res);
+        curr = this.allocCurr(
+          res,
+          series.alignment,
+          this.allocStart(series),
+          series,
+          0,
+        );
+      }
+    }
+    while (true) {
+      const converted = transform.convert(series, curr.sampleOffset);
+      const amountWritten = curr.write(converted);
+      if (amountWritten === series.length) {
+        this.currDataEnd = series.timeRange.isZero ? null : series.timeRange.end;
+        this.updateAvgRate(series);
+        return;
+      }
+      // The timestamp at the split point is unknowable from the data series, so
+      // both sides fall back to the wall clock.
+      this.currDataEnd = null;
+      this.flushCurr(res);
+      curr = this.allocCurr(
+        res,
+        series.alignment + BigInt(amountWritten),
+        this.now(),
+        series,
+        amountWritten,
+      );
+      series = series.slice(amountWritten);
+    }
+  }
+
+  private updateAvgRate(series: Series): void {
+    if (typeof this.props.dynamicBufferSize === "number") return;
+    const now = this.now();
+    const newRate = series.length / now.span(this.timeOfLastWrite).seconds;
+    if (this.totalWrites > 0 && isFinite(newRate) && newRate > 0)
+      this.avgRate =
+        (this.avgRate * (this.totalWrites - 1) + newRate) / this.totalWrites;
+    this.totalWrites++;
+    this.timeOfLastWrite = now;
+  }
+
+  private nextBufferSize(): number {
+    const { dynamicBufferSize } = this.props;
+    if (typeof dynamicBufferSize === "number") return dynamicBufferSize;
+    if (this.totalWrites < MAX_DEF_WRITES) return DEF_SIZE;
+    const size = math.roundToNearestMagnitude(this.avgRate * dynamicBufferSize.seconds);
+    return Math.round(Math.max(Math.min(size, MAX_SIZE), MIN_SIZE));
+  }
+
+  /**
+   * Flushes the leading buffer, stamping its end with the last stamped write or
+   * the wall clock.
+   * @returns the flushed buffer, or null when there is none.
+   */
+  flush(): Series | null {
+    const res: WriteResponse = {
+      flushed: new MultiSeries([]),
+      allocated: new MultiSeries([]),
+    };
+    this.flushCurr(res);
+    return res.flushed.series[0] ?? null;
+  }
+
+  /** Closes the cache. It must not be used afterwards. */
+  close(): void {
+    this.curr = null;
+  }
+}

package/src/framer/cache/reader.ts

@@ -0,0 +1,160 @@
+// 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 {
+  debounce,
+  MultiSeries,
+  type Series,
+  sync,
+  TimeRange,
+  TimeSpan,
+} from "@synnaxlabs/x";
+
+import { type channel } from "@/channel";
+import { UnexpectedError } from "@/errors";
+import { type Cache } from "@/framer/cache/cache";
+import { type Frame } from "@/framer/frame";
+
+/** A function that reads a telemetry frame from the Synnax cluster. */
+export interface RemoteReader {
+  (tr: TimeRange, keys: channel.Key[]): Promise<Frame>;
+}
+
+interface ReadRequest {
+  channel: channel.Key;
+  gaps: TimeRange[];
+}
+
+interface BatchFetch {
+  gap: TimeRange;
+  channels: Set<channel.Key>;
+  entries: Set<debounce.Entry<ReadRequest>>;
+}
+
+export interface ReaderProps {
+  /** Function used to read remote data from the server. */
+  readRemote: RemoteReader;
+  /** Will read from and populate the given cache with fetched data. */
+  cache: Cache;
+  /**
+   * Used to batch read requests to the server to minimize traffic. The window is not
+   * extended by later reads, so it is also the maximum wait before a batch fires.
+   * @default TimeSpan.milliseconds(50)
+   */
+  batchDebounce?: TimeSpan;
+  /**
+   * Reads whose gap time ranges are within this threshold merge into one request.
+   * @default TimeSpan.milliseconds(5)
+   */
+  overlapThreshold?: TimeSpan;
+}
+
+/**
+ * Reads historical telemetry, serving from the cache and batch-filling gaps from the
+ * server. A batch failure rejects only the reads whose gaps were in the failed fetch.
+ */
+export class Reader {
+  private readonly props: Required<Omit<ReaderProps, "batchDebounce">>;
+  private readonly batcher: debounce.Batcher<ReadRequest>;
+  // Serializes batch execution against close, so close waits for the batch in flight.
+  private readonly mu = sync.newMutex({ closed: false });
+
+  constructor(props: ReaderProps) {
+    const {
+      readRemote,
+      cache,
+      batchDebounce = TimeSpan.milliseconds(50),
+      overlapThreshold = TimeSpan.milliseconds(5),
+    } = props;
+    this.props = { readRemote, cache, overlapThreshold };
+    this.batcher = new debounce.Batcher({
+      interval: batchDebounce,
+      exec: async (entries) =>
+        await this.mu.runExclusive(async () => {
+          if (this.mu.closed) throw new UnexpectedError("telemetry reader is closed");
+          await this.batchRead(entries);
+        }),
+    });
+  }
+
+  /**
+   * Reads the given time range for the given channel.
+   * @throws {UnexpectedError} if the reader is closed while the read is pending.
+   */
+  async read(tr: TimeRange, channel: channel.Key): Promise<MultiSeries> {
+    const { cache } = this.props;
+    const unary = cache.get(channel);
+    const { series, gaps } = unary.read(tr);
+    if (gaps.length === 0) return series;
+    if (this.mu.closed) throw new UnexpectedError("telemetry reader is closed");
+    await this.batcher.enqueue({ channel, gaps });
+    return unary.read(tr).series;
+  }
+
+  private async batchRead(entries: Array<debounce.Entry<ReadRequest>>): Promise<void> {
+    const { readRemote, cache, overlapThreshold } = this.props;
+    const batched: BatchFetch[] = [];
+    entries.forEach((entry) => {
+      const unary = cache.get(entry.req.channel);
+      entry.req.gaps.forEach((rawGap) => {
+        // A concurrent batch or a streaming write may have filled part of the gap
+        // while this entry sat in the debounce window.
+        unary.read(rawGap).gaps.forEach((gap) => {
+          const g = batched.find((r) => r.gap.equals(gap, overlapThreshold));
+          if (g == null)
+            batched.push({
+              gap,
+              channels: new Set([entry.req.channel]),
+              entries: new Set([entry]),
+            });
+          else {
+            g.channels.add(entry.req.channel);
+            g.gap = TimeRange.max(g.gap, gap);
+            g.entries.add(entry);
+          }
+        });
+      });
+    });
+    const failures = new Map<debounce.Entry<ReadRequest>, unknown>();
+    await Promise.all(
+      batched.map(async ({ gap, channels, entries: served }) => {
+        try {
+          const frame = await readRemote(gap, Array.from(channels));
+          // Group series by key in one pass; per-key get() scans the whole frame.
+          const grouped = new Map<channel.Key, Series[]>();
+          frame.forEach((k, s) => {
+            const key = k as channel.Key;
+            const existing = grouped.get(key);
+            if (existing == null) grouped.set(key, [s]);
+            else existing.push(s);
+          });
+          channels.forEach((key) =>
+            cache.get(key).writeStatic(new MultiSeries(grouped.get(key) ?? [])),
+          );
+        } catch (err) {
+          served.forEach((entry) => {
+            if (!failures.has(entry)) failures.set(entry, err);
+          });
+        }
+      }),
+    );
+    entries.forEach((entry) => {
+      const err = failures.get(entry);
+      if (err == null) entry.resolve();
+      else entry.reject(err);
+    });
+  }
+
+  async close(): Promise<void> {
+    this.batcher.close(new UnexpectedError("telemetry reader is closed"));
+    await this.mu.runExclusive(async () => {
+      this.mu.closed = true;
+    });
+  }
+}

package/src/framer/cache/static.ts

@@ -0,0 +1,215 @@
+// 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 { alamos } from "@synnaxlabs/alamos";
+import {
+  bounds,
+  MultiSeries,
+  type Series,
+  Size,
+  TimeRange,
+  TimeSpan,
+  TimeStamp,
+} from "@synnaxlabs/x";
+
+import { IDENTITY_TRANSFORM, type Transform } from "@/framer/cache/transform";
+
+export interface DirtyReadResult {
+  series: MultiSeries;
+  gaps: TimeRange[];
+}
+
+export interface GCMetrics {
+  purgedSeries: number;
+  purgedBytes: Size;
+}
+
+export const zeroGCMetrics = (): GCMetrics => ({
+  purgedSeries: 0,
+  purgedBytes: Size.bytes(0),
+});
+
+/** Props for the {@link Static} cache. */
+export interface StaticProps {
+  /** Used for logging */
+  instrumentation?: alamos.Instrumentation;
+  /** Applied to every series before it enters the cache. Defaults to identity. */
+  transform?: Transform;
+  /**
+   * Sets the amount of time that a cache entry must be in the cache before it can
+   * be marked as stale and subject to garbage collection.
+   * @default TimeSpan.seconds(20) */
+  staleEntryThreshold?: TimeSpan;
+}
+
+export const DEFAULT_STATIC_PROPS: Required<StaticProps> = {
+  instrumentation: alamos.NOOP,
+  transform: IDENTITY_TRANSFORM,
+  staleEntryThreshold: TimeSpan.seconds(20),
+};
+
+interface CacheEntry {
+  /** The cached samples, after the transform and any insertion trimming. */
+  data: Series;
+  /** When the entry entered the cache, for garbage collection staleness. */
+  addedAt: TimeStamp;
+}
+
+/**
+ * A cache for historical channel data that will not be modified after it is written.
+ * Fetched and streamed entries are held apart because they measure position in
+ * different spaces: a fetched sample carries its committed alignment, the same sample
+ * streamed carries a provisional leading one. Insertion and gap computation both assume
+ * a single space, so each kind gets its own list.
+ */
+export class Static {
+  private fetched: CacheEntry[] = [];
+  private streamed: CacheEntry[] = [];
+  private readonly props: Required<StaticProps>;
+
+  constructor(props: StaticProps) {
+    const {
+      instrumentation = DEFAULT_STATIC_PROPS.instrumentation,
+      transform = DEFAULT_STATIC_PROPS.transform,
+      staleEntryThreshold = DEFAULT_STATIC_PROPS.staleEntryThreshold,
+    } = props;
+    this.props = { instrumentation, transform, staleEntryThreshold };
+  }
+
+  /**
+   * Writes the given series to the cache, merging written series with any existing
+   * series in the cache.
+   * @param streamed - Marks the series as live-streamed data. A fetched write evicts
+   * every streamed entry whose time range it fully covers.
+   */
+  write(series: MultiSeries, streamed: boolean = false): void {
+    if (series.length === 0) return;
+    if (!streamed) this.evictStreamed(series);
+    const entries = streamed ? this.streamed : this.fetched;
+    series.series.forEach((s) =>
+      this.writeOne(this.props.transform.convert(s), entries),
+    );
+    this.repairIntegrity(series, entries);
+  }
+
+  // Containment, not overlap: a fetch stamped wider than the data it returned
+  // (an uncommitted tail) must not evict streamed samples it did not replace.
+  private evictStreamed(written: MultiSeries): void {
+    this.streamed = this.streamed.filter(
+      (e) =>
+        !written.series.some(
+          (s) =>
+            s.timeRange.start.beforeEq(e.data.timeRange.start) &&
+            s.timeRange.end.afterEq(e.data.timeRange.end),
+        ),
+    );
+  }
+
+  /**
+   * Executes a 'dirty' read of the cache, retrieving any series in the cache that
+   * overlap with the given time range. The series may extend before or after the range.
+   * Gaps are computed against fetched entries only. Streamed entries carry provisional
+   * leading alignments that cannot pair with fetched data on another channel, so they
+   * never claim coverage; the fetch they provoke evicts them.
+   * @returns A list of series that overlap with the given time range and a list of
+   * gaps, representing the regions of time the fetched series do not cover.
+   */
+  dirtyRead(tr: TimeRange): DirtyReadResult {
+    const overlapping = (entries: CacheEntry[]): Series[] =>
+      entries.filter((e) => e.data.timeRange.overlapsWith(tr)).map((e) => e.data);
+    const fetched = overlapping(this.fetched);
+    const series = [...fetched, ...overlapping(this.streamed)];
+    if (fetched.length === 0) return { series: new MultiSeries(series), gaps: [tr] };
+    const gaps: TimeRange[] = [];
+    const pushGap = (start: TimeStamp, end: TimeStamp): void => {
+      const gap = new TimeRange(start, end);
+      if (gap.isValid && !gap.span.isZero) gaps.push(gap);
+    };
+    pushGap(tr.start, fetched[0].timeRange.start);
+    for (let i = 1; i < fetched.length; i++)
+      pushGap(fetched[i - 1].timeRange.end, fetched[i].timeRange.start);
+    pushGap(fetched[fetched.length - 1].timeRange.end, tr.end);
+    return { series: new MultiSeries(series), gaps };
+  }
+
+  /**
+   * Garbage collects the cache, removing any stale entries.
+   * @returns metrics about the garbage collection.
+   */
+  gc(): GCMetrics {
+    const { staleEntryThreshold } = this.props;
+    const res = zeroGCMetrics();
+    const collect = (entries: CacheEntry[]): CacheEntry[] =>
+      entries.filter((s) => {
+        const shouldKeep =
+          s.data.refCount > 0 ||
+          TimeStamp.since(s.addedAt).lessThan(staleEntryThreshold);
+        if (!shouldKeep) {
+          res.purgedBytes = res.purgedBytes.add(s.data.byteCapacity);
+          res.purgedSeries++;
+        }
+        return shouldKeep;
+      });
+    this.fetched = collect(this.fetched);
+    this.streamed = collect(this.streamed);
+    return res;
+  }
+
+  /** Closes the cache, freeing all of its resources. */
+  close(): void {
+    this.fetched = [];
+    this.streamed = [];
+  }
+
+  private writeOne(series: Series, entries: CacheEntry[]): void {
+    const {
+      instrumentation: { L },
+    } = this.props;
+    if (series.length === 0) return;
+    const insertionPlan = bounds.buildInsertionPlan(
+      entries.map((s) => s.data.alignmentBounds),
+      series.alignmentBounds,
+    );
+    if (insertionPlan === null)
+      return L.debug("Found no viable insertion plan", () => ({
+        inserting: series.digest,
+        cacheContents: entries.map((s) => s.data.digest),
+      }));
+    const { removeBefore, removeAfter, insertInto, deleteInBetween } = insertionPlan;
+    series = series.slice(removeBefore, series.length - removeAfter);
+    if (series.length === 0) return;
+    entries.splice(insertInto, deleteInBetween, {
+      data: series,
+      addedAt: TimeStamp.now(),
+    });
+  }
+
+  private repairIntegrity(write: MultiSeries, entries: CacheEntry[]): void {
+    const {
+      instrumentation: { L },
+    } = this.props;
+    // Entries are ordered and non-overlapping, so neighbor comparison suffices. An
+    // overlap is an insertion bug: evict both entries and let a refetch heal the gap.
+    for (let i = 1; i < entries.length; i++) {
+      if (
+        !bounds.overlapsWith(
+          entries[i - 1].data.alignmentBounds,
+          entries[i].data.alignmentBounds,
+        )
+      )
+        continue;
+      const [prev, curr] = entries.splice(i - 1, 2);
+      L.error("cache integrity violation - evicting overlapping entries", () => ({
+        write: write.series.map((s) => s.digest),
+        evicted: [prev.data.digest, curr.data.digest],
+      }));
+      i = 0;
+    }
+  }
+}