@prisma/streams-server 0.0.1 → 0.1.1

package/src/memory.ts

@@ -0,0 +1,155 @@
+export class MemoryGuard {
+  private readonly limitBytes: number;
+  private readonly resumeBytes: number;
+  private readonly intervalMs: number;
+  private readonly onSample?: (rssBytes: number, overLimit: boolean, limitBytes: number) => void;
+  private readonly heapSnapshotPath?: string;
+  private readonly heapSnapshotMinIntervalMs: number;
+  private timer: any | null = null;
+  private overLimit = false;
+  private maxRssBytes = 0;
+  private lastRssBytes = 0;
+  private lastGcMs = 0;
+  private lastSnapshotMs = 0;
+
+  constructor(
+    limitBytes: number,
+    opts: {
+      resumeFraction?: number;
+      intervalMs?: number;
+      onSample?: (rssBytes: number, overLimit: boolean, limitBytes: number) => void;
+      heapSnapshotPath?: string;
+      heapSnapshotMinIntervalMs?: number;
+    } = {}
+  ) {
+    this.limitBytes = Math.max(0, limitBytes);
+    // Resume as soon as RSS drops back below the limit by default (no hysteresis),
+    // so the server doesn't "deadlock" itself under a stable high-water mark.
+    const resumeFraction = Math.min(1.0, Math.max(0.5, opts.resumeFraction ?? 1.0));
+    this.resumeBytes = Math.floor(this.limitBytes * resumeFraction);
+    this.intervalMs = Math.max(50, opts.intervalMs ?? 1000);
+    this.onSample = opts.onSample;
+    this.heapSnapshotPath = opts.heapSnapshotPath;
+    this.heapSnapshotMinIntervalMs = Math.max(1000, opts.heapSnapshotMinIntervalMs ?? 60_000);
+  }
+
+  start(): void {
+    if (this.timer) return;
+    this.sample();
+    this.timer = setInterval(() => this.sample(), this.intervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  private sample(): void {
+    const rss = process.memoryUsage().rss;
+    this.lastRssBytes = rss;
+    if (rss > this.maxRssBytes) this.maxRssBytes = rss;
+    if (this.onSample) {
+      const overLimit = this.limitBytes > 0 && rss > this.limitBytes;
+      try {
+        this.onSample(rss, overLimit, this.limitBytes);
+      } catch {
+        // ignore
+      }
+    }
+    if (this.limitBytes <= 0) return;
+    if (this.overLimit) {
+      if (rss <= this.resumeBytes) this.overLimit = false;
+    } else if (rss > this.limitBytes) {
+      this.overLimit = true;
+    }
+  }
+
+  shouldAllow(): boolean {
+    if (this.limitBytes <= 0) return true;
+    return !this.overLimit;
+  }
+
+  isOverLimit(): boolean {
+    return this.overLimit;
+  }
+
+  getMaxRssBytes(): number {
+    return this.maxRssBytes;
+  }
+
+  snapshotMaxRssBytes(reset = true): number {
+    const max = this.maxRssBytes;
+    if (reset) this.maxRssBytes = this.lastRssBytes;
+    return max;
+  }
+
+  getLastRssBytes(): number {
+    return this.lastRssBytes;
+  }
+
+  getLimitBytes(): number {
+    return this.limitBytes;
+  }
+
+  maybeGc(reason: string): void {
+    const gcFn = (globalThis as any)?.Bun?.gc;
+    if (typeof gcFn !== "function") return;
+    const now = Date.now();
+    if (now - this.lastGcMs < 10_000) return;
+    this.lastGcMs = now;
+    const before = process.memoryUsage().rss;
+    try {
+      gcFn(true);
+    } catch {
+      try {
+        gcFn();
+      } catch {
+        return;
+      }
+    }
+    const after = process.memoryUsage().rss;
+    // eslint-disable-next-line no-console
+    console.warn(`[gc] forced GC (${reason}) rss ${formatBytes(before)} -> ${formatBytes(after)}`);
+  }
+
+  maybeHeapSnapshot(reason: string): void {
+    if (!this.heapSnapshotPath) return;
+    const now = Date.now();
+    if (now - this.lastSnapshotMs < this.heapSnapshotMinIntervalMs) return;
+    this.lastSnapshotMs = now;
+    void this.writeHeapSnapshot(reason);
+  }
+
+  private async writeHeapSnapshot(reason: string): Promise<void> {
+    try {
+      const v8 = await import("v8");
+      if (typeof v8.writeHeapSnapshot !== "function") return;
+      const fs = await import("node:fs");
+      try {
+        fs.unlinkSync(this.heapSnapshotPath!);
+      } catch {
+        // ignore
+      }
+      const before = process.memoryUsage().rss;
+      v8.writeHeapSnapshot(this.heapSnapshotPath);
+      const after = process.memoryUsage().rss;
+      // eslint-disable-next-line no-console
+      console.warn(`[heap] snapshot (${reason}) rss ${formatBytes(before)} -> ${formatBytes(after)} path=${this.heapSnapshotPath}`);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(`[heap] snapshot failed (${reason}): ${String(err)}`);
+    }
+  }
+}
+
+export function formatBytes(bytes: number): string {
+  const units = ["b", "kb", "mb", "gb"];
+  let value = bytes;
+  let idx = 0;
+  while (value >= 1024 && idx < units.length - 1) {
+    value /= 1024;
+    idx += 1;
+  }
+  const digits = idx === 0 ? 0 : 1;
+  return `${value.toFixed(digits)}${units[idx]}`;
+}

package/src/metrics.ts

@@ -0,0 +1,161 @@
+type Tags = Record<string, string>;
+
+type MetricEvent = {
+  apiVersion: "durable.streams/metrics/v1";
+  kind: "interval";
+  metric: string;
+  unit: "ns" | "bytes" | "count";
+  windowStart: number;
+  windowEnd: number;
+  intervalMs: number;
+  instance: string;
+  stream?: string;
+  tags?: Tags;
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+  avg: number;
+  p50: number;
+  p95: number;
+  p99: number;
+  buckets: Record<string, number>;
+};
+
+class Histogram {
+  private readonly maxSamples: number;
+  private samples: number[] = [];
+  count = 0;
+  sum = 0;
+  min = Number.POSITIVE_INFINITY;
+  max = Number.NEGATIVE_INFINITY;
+  buckets: Record<string, number> = {};
+
+  constructor(maxSamples = 1024) {
+    this.maxSamples = maxSamples;
+  }
+
+  add(value: number): void {
+    this.count++;
+    this.sum += value;
+    if (value < this.min) this.min = value;
+    if (value > this.max) this.max = value;
+    const bucket = Math.floor(Math.log2(Math.max(1, value)));
+    const key = String(1 << bucket);
+    this.buckets[key] = (this.buckets[key] ?? 0) + 1;
+    if (this.samples.length < this.maxSamples) {
+      this.samples.push(value);
+    } else {
+      const idx = Math.floor(Math.random() * this.count);
+      if (idx < this.maxSamples) this.samples[idx] = value;
+    }
+  }
+
+  snapshotAndReset(): { count: number; sum: number; min: number; max: number; avg: number; p50: number; p95: number; p99: number; buckets: Record<string, number> } {
+    const count = this.count;
+    const sum = this.sum;
+    const min = count === 0 ? 0 : this.min;
+    const max = count === 0 ? 0 : this.max;
+    const avg = count === 0 ? 0 : sum / count;
+    const sorted = this.samples.slice().sort((a, b) => a - b);
+    const p = (q: number) => (sorted.length === 0 ? 0 : sorted[Math.min(sorted.length - 1, Math.floor(q * (sorted.length - 1)))]);
+    const p50 = p(0.5);
+    const p95 = p(0.95);
+    const p99 = p(0.99);
+    const buckets = { ...this.buckets };
+    this.samples = [];
+    this.count = 0;
+    this.sum = 0;
+    this.min = Number.POSITIVE_INFINITY;
+    this.max = Number.NEGATIVE_INFINITY;
+    this.buckets = {};
+    return { count, sum, min, max, avg, p50, p95, p99, buckets };
+  }
+}
+
+type SeriesKey = string;
+
+class MetricSeries {
+  readonly metric: string;
+  readonly unit: "ns" | "bytes" | "count";
+  readonly stream?: string;
+  readonly tags?: Tags;
+  readonly hist = new Histogram();
+
+  constructor(metric: string, unit: "ns" | "bytes" | "count", stream?: string, tags?: Tags) {
+    this.metric = metric;
+    this.unit = unit;
+    this.stream = stream;
+    this.tags = tags;
+  }
+}
+
+function keyFor(metric: string, unit: string, stream?: string, tags?: Tags): SeriesKey {
+  const tagStr = tags ? JSON.stringify(tags) : "";
+  return `${metric}|${unit}|${stream ?? ""}|${tagStr}`;
+}
+
+function instanceId(): string {
+  const host = typeof process !== "undefined" ? process.pid.toString() : "node";
+  const rand = Math.random().toString(16).slice(2, 8);
+  return `${host}-${rand}`;
+}
+
+export class Metrics {
+  private readonly startMs = Date.now();
+  private windowStartMs = Date.now();
+  private readonly series = new Map<SeriesKey, MetricSeries>();
+  private readonly instance = instanceId();
+
+  record(metric: string, value: number, unit: "ns" | "bytes" | "count", tags?: Tags, stream?: string): void {
+    const key = keyFor(metric, unit, stream, tags);
+    let s = this.series.get(key);
+    if (!s) {
+      s = new MetricSeries(metric, unit, stream, tags);
+      this.series.set(key, s);
+    }
+    s.hist.add(value);
+  }
+
+  recordAppend(bytes: number, entries: number): void {
+    this.record("tieredstore.append.bytes", bytes, "bytes");
+    this.record("tieredstore.append.entries", entries, "count");
+  }
+
+  recordRead(bytes: number, entries: number): void {
+    this.record("tieredstore.read.bytes", bytes, "bytes");
+    this.record("tieredstore.read.entries", entries, "count");
+  }
+
+  snapshot(): any {
+    return {
+      uptime_ms: Date.now() - this.startMs,
+      series: this.series.size,
+    };
+  }
+
+  flushInterval(): MetricEvent[] {
+    const windowEnd = Date.now();
+    const intervalMs = windowEnd - this.windowStartMs;
+    const events: MetricEvent[] = [];
+    for (const s of this.series.values()) {
+      const snap = s.hist.snapshotAndReset();
+      if (snap.count === 0) continue;
+      events.push({
+        apiVersion: "durable.streams/metrics/v1",
+        kind: "interval",
+        metric: s.metric,
+        unit: s.unit,
+        windowStart: this.windowStartMs,
+        windowEnd,
+        intervalMs,
+        instance: this.instance,
+        stream: s.stream,
+        tags: s.tags,
+        ...snap,
+      });
+    }
+    this.windowStartMs = windowEnd;
+    return events;
+  }
+}

package/src/metrics_emitter.ts

@@ -0,0 +1,50 @@
+import type { IngestQueue } from "./ingest";
+import type { Metrics } from "./metrics";
+
+export class MetricsEmitter {
+  private readonly metrics: Metrics;
+  private readonly ingest: IngestQueue;
+  private readonly intervalMs: number;
+  private timer: any | null = null;
+
+  constructor(metrics: Metrics, ingest: IngestQueue, intervalMs: number) {
+    this.metrics = metrics;
+    this.ingest = ingest;
+    this.intervalMs = intervalMs;
+  }
+
+  start(): void {
+    if (this.intervalMs <= 0 || this.timer) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.intervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  private async flush(): Promise<void> {
+    const queue = this.ingest.getQueueStats();
+    this.metrics.record("tieredstore.ingest.queue.bytes", queue.bytes, "bytes");
+    this.metrics.record("tieredstore.ingest.queue.requests", queue.requests, "count");
+    const events = this.metrics.flushInterval();
+    if (events.length === 0) return;
+    const rows = events.map((e) => ({
+      routingKey: e.stream ? new TextEncoder().encode(e.stream) : null,
+      contentType: "application/json",
+      payload: new TextEncoder().encode(JSON.stringify(e)),
+    }));
+    try {
+      await this.ingest.appendInternal({
+        stream: "__stream_metrics__",
+        baseAppendMs: BigInt(Date.now()),
+        rows,
+        contentType: "application/json",
+      });
+    } catch {
+      // best-effort; drop on failure
+    }
+  }
+}

package/src/notifier.ts

@@ -0,0 +1,64 @@
+type Waiter = { afterSeq: bigint; resolve: () => void };
+
+export class StreamNotifier {
+  private readonly waiters = new Map<string, Set<Waiter>>();
+  private readonly latestSeq = new Map<string, bigint>();
+
+  notify(stream: string, newEndSeq: bigint): void {
+    this.latestSeq.set(stream, newEndSeq);
+    const set = this.waiters.get(stream);
+    if (!set || set.size === 0) return;
+    for (const w of Array.from(set)) {
+      if (newEndSeq > w.afterSeq) {
+        set.delete(w);
+        w.resolve();
+      }
+    }
+    if (set.size === 0) this.waiters.delete(stream);
+  }
+
+  waitFor(stream: string, afterSeq: bigint, timeoutMs: number, signal?: AbortSignal): Promise<void> {
+    if (signal?.aborted) return Promise.resolve();
+    const latest = this.latestSeq.get(stream);
+    if (latest != null && latest > afterSeq) return Promise.resolve();
+    return new Promise((resolve) => {
+      let done = false;
+      const set = this.waiters.get(stream) ?? new Set();
+      const cleanup = () => {
+        if (done) return;
+        done = true;
+        const s = this.waiters.get(stream);
+        if (s) {
+          s.delete(waiter);
+          if (s.size === 0) this.waiters.delete(stream);
+        }
+        if (timeoutId) clearTimeout(timeoutId);
+        if (signal) signal.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      const waiter: Waiter = { afterSeq, resolve: cleanup };
+      set.add(waiter);
+      this.waiters.set(stream, set);
+
+      const onAbort = () => cleanup();
+      if (signal) signal.addEventListener("abort", onAbort, { once: true });
+
+      let timeoutId: any | null = null;
+      if (timeoutMs > 0) {
+        timeoutId = setTimeout(() => {
+          cleanup();
+        }, timeoutMs);
+      }
+    });
+  }
+
+  notifyClose(stream: string): void {
+    const set = this.waiters.get(stream);
+    if (!set || set.size === 0) return;
+    for (const w of Array.from(set)) {
+      set.delete(w);
+      w.resolve();
+    }
+    if (set.size === 0) this.waiters.delete(stream);
+  }
+}

package/src/objectstore/interface.ts

@@ -0,0 +1,13 @@
+export type PutResult = { etag: string };
+
+export type GetRange = { start: number; end?: number }; // end is inclusive; omit for EOF
+export type GetOptions = { range?: GetRange };
+
+export interface ObjectStore {
+  put(key: string, data: Uint8Array, opts?: { contentType?: string; contentLength?: number }): Promise<PutResult>;
+  putFile?(key: string, path: string, size: number, opts?: { contentType?: string }): Promise<PutResult>;
+  get(key: string, opts?: GetOptions): Promise<Uint8Array | null>;
+  head(key: string): Promise<{ etag: string; size: number } | null>;
+  delete(key: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+}