@pyric/ui 0.1.0-alpha.11 → 0.1.0-alpha.12

package/src/traffic/hooks/useTrafficFilter.ts

@@ -0,0 +1,74 @@
+import { useMemo, useState } from 'react';
+import type { TrafficEvent } from '../types.js';
+
+/**
+ * `user` keeps everything that isn't a listener re-eval (user ops
+ * plus their transaction/batch sub-ops); `listener` keeps only
+ * listener re-evals; `all` keeps everything.
+ */
+export type TrafficOriginFilter = 'user' | 'all' | 'listener';
+
+export type TrafficResultFilter = 'all' | 'allow' | 'deny';
+
+export interface UseTrafficFilterOptions {
+  events: TrafficEvent[];
+  /**
+   * Default `user` — the probe found listener traffic is 94–99.6%
+   * of events, so it's hidden until explicitly asked for.
+   */
+  initialOrigin?: TrafficOriginFilter;
+  /** Default `all` — the probe found ~75–80% allow in realistic
+   *  sessions, so hiding either side loses diagnostic signal. */
+  initialResult?: TrafficResultFilter;
+  initialPathQuery?: string;
+}
+
+export interface TrafficFilterState {
+  origin: TrafficOriginFilter;
+  result: TrafficResultFilter;
+  pathQuery: string;
+}
+
+export interface UseTrafficFilterResult {
+  /** Events passing all three filters, in the input order. */
+  filtered: TrafficEvent[];
+  filter: TrafficFilterState;
+  setOrigin: (origin: TrafficOriginFilter) => void;
+  setResult: (result: TrafficResultFilter) => void;
+  setPathQuery: (pathQuery: string) => void;
+}
+
+/**
+ * Derives a filtered view over a traffic buffer along three
+ * dimensions: origin, result, and a case-insensitive path substring.
+ * Owns the filter state; pure derivation otherwise.
+ */
+export function useTrafficFilter({
+  events,
+  initialOrigin = 'user',
+  initialResult = 'all',
+  initialPathQuery = '',
+}: UseTrafficFilterOptions): UseTrafficFilterResult {
+  const [origin, setOrigin] = useState<TrafficOriginFilter>(initialOrigin);
+  const [result, setResult] = useState<TrafficResultFilter>(initialResult);
+  const [pathQuery, setPathQuery] = useState(initialPathQuery);
+
+  const filtered = useMemo(() => {
+    const needle = pathQuery.trim().toLowerCase();
+    return events.filter((e) => {
+      if (origin === 'user' && e.origin === 'listener') return false;
+      if (origin === 'listener' && e.origin !== 'listener') return false;
+      if (result !== 'all' && e.result !== result) return false;
+      if (needle && !e.path.toLowerCase().includes(needle)) return false;
+      return true;
+    });
+  }, [events, origin, result, pathQuery]);
+
+  return {
+    filtered,
+    filter: { origin, result, pathQuery },
+    setOrigin,
+    setResult,
+    setPathQuery,
+  };
+}

package/src/traffic/hooks/useTrafficGroups.ts

@@ -0,0 +1,126 @@
+import { useMemo } from 'react';
+import type { TrafficEvent } from '../types.js';
+
+export type TrafficGroupKind = 'batch' | 'transaction' | 'listener-run';
+
+export interface TrafficGroup {
+  type: 'group';
+  kind: TrafficGroupKind;
+  /** `groupId` for batch/transaction; a synthetic key for listener
+   *  runs. Stable enough for a React key. */
+  key: string;
+  events: TrafficEvent[];
+  count: number;
+  denies: number;
+}
+
+export interface TrafficSingle {
+  type: 'single';
+  event: TrafficEvent;
+}
+
+export type TrafficLogItem = TrafficGroup | TrafficSingle;
+
+export interface UseTrafficGroupsOptions {
+  events: TrafficEvent[];
+  /** Collapse consecutive ops sharing a `groupId`. Default true. */
+  groupBatches?: boolean;
+  /**
+   * Collapse a consecutive run of listener re-evals from the same
+   * originating op into one group — the probe found a single write
+   * can trigger 250+ re-evals. Default true.
+   */
+  groupListenerRuns?: boolean;
+}
+
+export interface UseTrafficGroupsResult {
+  /** Events folded into a flat list of singles and groups, in the
+   *  input order. */
+  items: TrafficLogItem[];
+}
+
+function sameTrigger(a: TrafficEvent, b: TrafficEvent): boolean {
+  const ta = a.triggeredBy;
+  const tb = b.triggeredBy;
+  if (!ta && !tb) return true;
+  if (!ta || !tb) return false;
+  return ta.method === tb.method && ta.path === tb.path;
+}
+
+function makeGroup(
+  kind: TrafficGroupKind,
+  key: string,
+  events: TrafficEvent[],
+): TrafficGroup {
+  let denies = 0;
+  for (const e of events) if (e.result === 'deny') denies++;
+  return { type: 'group', kind, key, events, count: events.length, denies };
+}
+
+/**
+ * Folds a traffic buffer into a list of singles and collapsible
+ * groups. Two grouping modes, both over *consecutive* events:
+ *
+ * - `groupId` — batch/transaction sub-ops sharing an id collapse
+ *   into one `batch` / `transaction` group.
+ * - listener runs — a consecutive run of listener re-evals from the
+ *   same originating op collapses into one `listener-run` group.
+ *   A run of length 1 stays a single (no point collapsing one row).
+ *
+ * Pure derivation; the input order is preserved.
+ */
+export function useTrafficGroups({
+  events,
+  groupBatches = true,
+  groupListenerRuns = true,
+}: UseTrafficGroupsOptions): UseTrafficGroupsResult {
+  return useMemo(() => {
+    const items: TrafficLogItem[] = [];
+    let i = 0;
+
+    while (i < events.length) {
+      const event = events[i];
+
+      if (groupBatches && event.groupId) {
+        let j = i + 1;
+        while (j < events.length && events[j].groupId === event.groupId) j++;
+        const run = events.slice(i, j);
+        const kind: TrafficGroupKind =
+          event.origin === 'transaction' ? 'transaction' : 'batch';
+        items.push(makeGroup(kind, event.groupId, run));
+        i = j;
+        continue;
+      }
+
+      if (groupListenerRuns && event.origin === 'listener') {
+        let j = i + 1;
+        while (
+          j < events.length &&
+          events[j].origin === 'listener' &&
+          !events[j].groupId &&
+          sameTrigger(events[j], event)
+        ) {
+          j++;
+        }
+        const run = events.slice(i, j);
+        if (run.length > 1) {
+          const trigger = event.triggeredBy
+            ? `${event.triggeredBy.method}:${event.triggeredBy.path}`
+            : 'unknown';
+          items.push(
+            makeGroup('listener-run', `listener-run:${trigger}:${i}`, run),
+          );
+        } else {
+          items.push({ type: 'single', event });
+        }
+        i = j;
+        continue;
+      }
+
+      items.push({ type: 'single', event });
+      i++;
+    }
+
+    return { items };
+  }, [events, groupBatches, groupListenerRuns]);
+}

package/src/traffic/hooks/useTrafficMetrics.ts

@@ -0,0 +1,250 @@
+import { useMemo } from 'react';
+import type { TimeWindow } from './useTrafficBuckets.js';
+import type { TrafficEvent } from '../types.js';
+
+/**
+ * Billable-metrics + rules-metrics aggregation (Traffic tab: "Billable
+ * metrics" and "Rules"). Mirrors the Firebase Console
+ * Usage tab's shape (per-series totals + a bucketed time series), built
+ * on top of the same half-open `[window.start, window.end)` bucketing
+ * kernel {@link bucketTraffic} already uses.
+ *
+ * ── Billable mapping (documented; verified against the sandbox source) ──
+ *   reads    = get + list
+ *   writes   = create + update + set
+ *   deletes  = delete + remove
+ *
+ * A `list` event does NOT carry the number of documents the query
+ * returned — `local-environment.ts` emits ONE `allow` event per query
+ * before it computes/constrains the doc set, and the returned doc array
+ * never rides back onto the event. Real Firestore bills a list as one
+ * read PER RETURNED DOCUMENT; this stream can only honestly count list
+ * OPERATIONS, not documents. So this series is "read ops", not "billable
+ * reads" — an op-count proxy, not a byte-accurate bill. See the gap note
+ * in the Traffic feature's tracking issue.
+ *
+ * An op only bills if it actually ran against data: a `deny`/`error`/
+ * `unsupported`/`not-applicable` result means nothing was read or
+ * written, so those never count toward billable totals. An `admin`
+ * (rules-bypassed) op DOES run — admin reads/writes still bill in real
+ * Firestore — so admin ops count toward billable totals even though they
+ * never touch the rules-metrics series below.
+ *
+ * ── Rules metrics ──
+ * Allows / denies / errors are rules-ENGINE verdicts: how many times the
+ * rules engine actually ran and what it decided. An admin (bypassed) op
+ * never reaches rules, so it must never inflate "allows" — that would
+ * misrepresent the rules engine as having evaluated something it never
+ * saw. `unsupported` / `not-applicable` results aren't rules verdicts
+ * either (the simulator declined to evaluate) and are excluded too.
+ *
+ * ── Admin classification ──
+ * The base `TrafficEvent` carries only `origin` (no `detail` field — the
+ * sandbox-layer `RequestEvent.detail.admin` doesn't survive the
+ * `operation`-kind adapter path, and rides untyped through the
+ * `request`-kind cast). `origin === 'admin'` is the one signal declared
+ * on the public type, so it's the default `isAdmin` predicate here.
+ * Firestore's admin-lens ops don't currently set `origin: 'admin'`
+ * (RTDB's do) — callers that can see the richer Studio provenance
+ * (`authLens.mode === 'admin'`, as `verdict.ts#verdictFor` already
+ * checks) should pass their own `isAdmin` predicate to close that gap.
+ */
+
+const READ_METHODS = new Set(['get', 'list']);
+const WRITE_METHODS = new Set(['create', 'update', 'set']);
+const DELETE_METHODS = new Set(['delete', 'remove']);
+
+export type BillableSeriesKey = 'reads' | 'writes' | 'deletes';
+export type RulesSeriesKey = 'allows' | 'denies' | 'errors';
+
+export const BILLABLE_SERIES_DEFS: ReadonlyArray<{ key: BillableSeriesKey; label: string }> = [
+  { key: 'reads', label: 'Read ops' },
+  { key: 'writes', label: 'Writes' },
+  { key: 'deletes', label: 'Deletes' },
+];
+
+export const RULES_SERIES_DEFS: ReadonlyArray<{ key: RulesSeriesKey; label: string }> = [
+  { key: 'allows', label: 'Allows' },
+  { key: 'denies', label: 'Denies' },
+  { key: 'errors', label: 'Errors' },
+];
+
+/** Default admin predicate: the one signal the public `TrafficEvent`
+ *  type declares. See the module doc for the known Firestore gap. */
+export function isAdminEvent(event: Pick<TrafficEvent, 'origin'>): boolean {
+  return event.origin === 'admin';
+}
+
+/** Classify a billable op, or `null` if it isn't one / never ran. */
+export function classifyBillable(
+  event: Pick<TrafficEvent, 'method' | 'result' | 'origin'>,
+  isAdmin: (event: Pick<TrafficEvent, 'origin'>) => boolean = isAdminEvent,
+): BillableSeriesKey | null {
+  const executed = event.result === 'allow' || isAdmin(event);
+  if (!executed) return null;
+  if (READ_METHODS.has(event.method)) return 'reads';
+  if (WRITE_METHODS.has(event.method)) return 'writes';
+  if (DELETE_METHODS.has(event.method)) return 'deletes';
+  return null;
+}
+
+/** Classify a rules-engine verdict, or `null` if it isn't one (bypassed,
+ *  unsupported, or not-applicable). */
+export function classifyRules(
+  event: Pick<TrafficEvent, 'result' | 'origin'>,
+  isAdmin: (event: Pick<TrafficEvent, 'origin'>) => boolean = isAdminEvent,
+): RulesSeriesKey | null {
+  if (isAdmin(event)) return null;
+  if (event.result === 'allow') return 'allows';
+  if (event.result === 'deny') return 'denies';
+  if (event.result === 'error') return 'errors';
+  return null;
+}
+
+export interface MetricPoint {
+  /** 0-based bucket index, left (oldest) to right (newest). */
+  index: number;
+  /** Half-open bounds of this bucket `[start, end)` in epoch-ms. */
+  start: number;
+  end: number;
+}
+
+export interface MetricSeries {
+  key: string;
+  label: string;
+  /** One count per bucket, aligned with `points`. */
+  values: number[];
+  /** Sum of `values` — the period total (the legend/card number). */
+  total: number;
+}
+
+export interface TrafficMetricsResult {
+  points: MetricPoint[];
+  series: MetricSeries[];
+  /** The largest single-bucket value across every series — the shared
+   *  y-scale divisor a chart would use by default. */
+  maxValue: number;
+}
+
+const EMPTY = (
+  seriesDefs: ReadonlyArray<{ key: string; label: string }>,
+): TrafficMetricsResult => ({
+  points: [],
+  series: seriesDefs.map((d) => ({ key: d.key, label: d.label, values: [], total: 0 })),
+  maxValue: 0,
+});
+
+/** The shared bucketing kernel behind both metric hooks below. */
+function bucketMetrics<K extends string>(
+  events: readonly TrafficEvent[],
+  window: TimeWindow,
+  bucketCount: number,
+  seriesDefs: ReadonlyArray<{ key: K; label: string }>,
+  classify: (event: TrafficEvent) => K | null,
+): TrafficMetricsResult {
+  const span = window.end - window.start;
+  if (bucketCount <= 0 || span <= 0) return EMPTY(seriesDefs);
+
+  const width = span / bucketCount;
+  const valuesByKey = new Map<K, number[]>(
+    seriesDefs.map((d) => [d.key, new Array<number>(bucketCount).fill(0)]),
+  );
+  const totals = new Map<K, number>(seriesDefs.map((d) => [d.key, 0]));
+
+  for (const event of events) {
+    const at = event.at;
+    if (at < window.start || at >= window.end) continue;
+    const key = classify(event);
+    if (key == null) continue;
+    let i = Math.floor((at - window.start) / width);
+    if (i >= bucketCount) i = bucketCount - 1;
+    const bucketValues = valuesByKey.get(key)!;
+    bucketValues[i]++;
+    totals.set(key, (totals.get(key) ?? 0) + 1);
+  }
+
+  let maxValue = 0;
+  for (const values of valuesByKey.values()) {
+    for (const v of values) if (v > maxValue) maxValue = v;
+  }
+
+  const points: MetricPoint[] = new Array(bucketCount);
+  for (let i = 0; i < bucketCount; i++) {
+    points[i] = { index: i, start: window.start + i * width, end: window.start + (i + 1) * width };
+  }
+
+  const series: MetricSeries[] = seriesDefs.map((d) => ({
+    key: d.key,
+    label: d.label,
+    values: valuesByKey.get(d.key)!,
+    total: totals.get(d.key) ?? 0,
+  }));
+
+  return { points, series, maxValue };
+}
+
+/** Pure kernel behind {@link useBillableMetrics} — usable outside React. */
+export function bucketBillableMetrics(
+  events: readonly TrafficEvent[],
+  window: TimeWindow,
+  bucketCount = 24,
+  isAdmin: (event: Pick<TrafficEvent, 'origin'>) => boolean = isAdminEvent,
+): TrafficMetricsResult {
+  return bucketMetrics(events, window, bucketCount, BILLABLE_SERIES_DEFS, (e) =>
+    classifyBillable(e, isAdmin),
+  );
+}
+
+/** Pure kernel behind {@link useRulesMetrics} — usable outside React. */
+export function bucketRulesMetrics(
+  events: readonly TrafficEvent[],
+  window: TimeWindow,
+  bucketCount = 24,
+  isAdmin: (event: Pick<TrafficEvent, 'origin'>) => boolean = isAdminEvent,
+): TrafficMetricsResult {
+  return bucketMetrics(events, window, bucketCount, RULES_SERIES_DEFS, (e) =>
+    classifyRules(e, isAdmin),
+  );
+}
+
+export interface UseTrafficMetricsOptions {
+  events: TrafficEvent[];
+  window: TimeWindow;
+  /** Number of buckets to divide the window into. The window itself
+   *  should already be sized to the session (sandbox sessions run
+   *  minutes, not days) — bucket count doesn't need to change, only the
+   *  window a caller passes in. Default 24. */
+  bucketCount?: number;
+  /** Override admin classification (e.g. a Studio caller with
+   *  `authLens` provenance available — see the module doc). Defaults to
+   *  `origin === 'admin'`. */
+  isAdmin?: (event: Pick<TrafficEvent, 'origin'>) => boolean;
+}
+
+/** Reads / writes / deletes, bucketed over `window`. See the module doc
+ *  for the billable mapping + the "read ops, not billable reads" caveat. */
+export function useBillableMetrics({
+  events,
+  window,
+  bucketCount = 24,
+  isAdmin,
+}: UseTrafficMetricsOptions): TrafficMetricsResult {
+  return useMemo(
+    () => bucketBillableMetrics(events, window, bucketCount, isAdmin),
+    [events, window.start, window.end, bucketCount, isAdmin],
+  );
+}
+
+/** Allows / denies / errors, bucketed over `window`. Excludes
+ *  rules-bypassed (admin) ops — see the module doc. */
+export function useRulesMetrics({
+  events,
+  window,
+  bucketCount = 24,
+  isAdmin,
+}: UseTrafficMetricsOptions): TrafficMetricsResult {
+  return useMemo(
+    () => bucketRulesMetrics(events, window, bucketCount, isAdmin),
+    [events, window.start, window.end, bucketCount, isAdmin],
+  );
+}

package/src/traffic/hooks/useTrafficMonitor.ts

@@ -0,0 +1,111 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { TrafficEvent, TrafficSource } from '../types.js';
+
+export interface UseTrafficMonitorOptions {
+  /**
+   * The subscription function — `sandbox.onRequest` satisfies this
+   * directly. Pass a stable reference; the hook re-subscribes on
+   * identity change.
+   */
+  source: TrafficSource;
+  /**
+   * Ring-buffer cap. Once exceeded, the oldest events are dropped.
+   * Default 5000 (~3 MB worst case — see the traffic-monitor probe
+   * findings).
+   */
+  bufferSize?: number;
+  /** Whether the buffer starts paused. Default false. */
+  paused?: boolean;
+  /**
+   * Runs per event before buffering — return a (possibly trimmed)
+   * event. Lets the consumer shrink oversized payloads without the
+   * library knowing payload semantics. Identity is read fresh on
+   * each event, so it need not be memoized.
+   */
+  transform?: (event: TrafficEvent) => TrafficEvent;
+}
+
+export interface TrafficCounts {
+  /** Events currently in the buffer. */
+  total: number;
+  /** Of those, how many were denied. */
+  denied: number;
+  /** Of those, how many are listener re-evals. */
+  listener: number;
+}
+
+export interface UseTrafficMonitorResult {
+  /** The buffered events, oldest first. */
+  events: TrafficEvent[];
+  counts: TrafficCounts;
+  isPaused: boolean;
+  /** Stop appending — incoming events are dropped while paused. */
+  pause: () => void;
+  /** Resume appending. */
+  resume: () => void;
+  /** Empty the buffer. */
+  clear: () => void;
+}
+
+/**
+ * Buffers a traffic stream into a capped ring buffer with
+ * pause/resume/clear. Decoupled from `pyric/sandbox` — `source` is
+ * just a `(cb) => unsubscribe` function.
+ *
+ * Pause is consumer-side: while paused, the subscription stays
+ * attached but incoming events are dropped (not queued). This
+ * matches the probe decision — a `load-test`-shaped session can emit
+ * 100k+ events, so queueing-while-paused would defeat the point.
+ */
+export function useTrafficMonitor({
+  source,
+  bufferSize = 5000,
+  paused = false,
+  transform,
+}: UseTrafficMonitorOptions): UseTrafficMonitorResult {
+  const [events, setEvents] = useState<TrafficEvent[]>([]);
+  const [isPaused, setIsPaused] = useState(paused);
+
+  // The subscription callback closes over these once. Refs keep it
+  // reading the live values without forcing a re-subscribe.
+  const pausedRef = useRef(isPaused);
+  pausedRef.current = isPaused;
+  const bufferSizeRef = useRef(bufferSize);
+  bufferSizeRef.current = bufferSize;
+  const transformRef = useRef(transform);
+  transformRef.current = transform;
+
+  useEffect(() => {
+    const unsubscribe = source((event) => {
+      if (pausedRef.current) return;
+      const shaped = transformRef.current
+        ? transformRef.current(event)
+        : event;
+      setEvents((prev) => {
+        const next = prev.length >= bufferSizeRef.current ? prev.slice(1) : prev.slice();
+        next.push(shaped);
+        return next;
+      });
+    });
+    return unsubscribe;
+  }, [source]);
+
+  const counts = useMemo<TrafficCounts>(() => {
+    let denied = 0;
+    let listener = 0;
+    for (const e of events) {
+      if (e.result === 'deny') denied++;
+      if (e.origin === 'listener') listener++;
+    }
+    return { total: events.length, denied, listener };
+  }, [events]);
+
+  return {
+    events,
+    counts,
+    isPaused,
+    pause: () => setIsPaused(true),
+    resume: () => setIsPaused(false),
+    clear: () => setEvents([]),
+  };
+}

package/src/traffic/hooks/useTrafficStats.ts

@@ -0,0 +1,77 @@
+import { useMemo } from 'react';
+import type { TrafficEvent } from '../types.js';
+
+export interface TrafficStatBucket {
+  key: string;
+  count: number;
+}
+
+export interface TrafficStatsSummary {
+  total: number;
+  allows: number;
+  denies: number;
+  unsupported: number;
+  /** `denies / total` — 0 for an empty buffer. */
+  denyRate: number;
+  /** Counts by method, sorted descending. */
+  byMethod: TrafficStatBucket[];
+  /** Counts by origin, sorted descending. */
+  byOrigin: TrafficStatBucket[];
+  /** Counts by path, sorted descending, capped at `topPaths`. */
+  byPath: TrafficStatBucket[];
+}
+
+export interface UseTrafficStatsOptions {
+  events: TrafficEvent[];
+  /** Cap on `byPath` entries — paths are unbounded. Default 10. */
+  topPaths?: number;
+}
+
+function buckets(
+  events: TrafficEvent[],
+  pick: (event: TrafficEvent) => string,
+  limit?: number,
+): TrafficStatBucket[] {
+  const counts = new Map<string, number>();
+  for (const event of events) {
+    const key = pick(event);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const sorted = [...counts.entries()]
+    .map(([key, count]) => ({ key, count }))
+    .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
+  return limit === undefined ? sorted : sorted.slice(0, limit);
+}
+
+/**
+ * Aggregations over a traffic buffer: totals, deny rate, and counts
+ * broken down by method, origin, and path. Pure derivation — feed it
+ * the filtered or full event list depending on what the panel
+ * should reflect.
+ */
+export function useTrafficStats({
+  events,
+  topPaths = 10,
+}: UseTrafficStatsOptions): TrafficStatsSummary {
+  return useMemo(() => {
+    let allows = 0;
+    let denies = 0;
+    let unsupported = 0;
+    for (const event of events) {
+      if (event.result === 'allow') allows++;
+      else if (event.result === 'deny') denies++;
+      else unsupported++;
+    }
+    const total = events.length;
+    return {
+      total,
+      allows,
+      denies,
+      unsupported,
+      denyRate: total === 0 ? 0 : denies / total,
+      byMethod: buckets(events, (e) => e.method),
+      byOrigin: buckets(events, (e) => e.origin),
+      byPath: buckets(events, (e) => e.path, topPaths),
+    };
+  }, [events, topPaths]);
+}

package/src/traffic/index.ts

@@ -0,0 +1,13 @@
+export * from './hooks/index.js';
+export * from './components/index.js';
+
+export type {
+  TrafficEvent,
+  TrafficSource,
+  TrafficMethod,
+  TrafficResult,
+  TrafficOrigin,
+  TrafficAuthState,
+  TrafficResourceState,
+  TrafficMatchedRule,
+} from './types.js';