@reddb-io/ui 0.3.0 → 0.3.2

package/src/lib/reddb/cluster-status.ts

@@ -0,0 +1,306 @@
+// Normalised view of reddb's `/cluster/status` and `/replication/status`
+// payloads, plus the topology classification the UI hangs per-mode telemetry
+// off of.
+//
+// Shapes are pinned against the reddb source of truth — do NOT infer them
+// from older UI code, which predates the #738 cluster-status contract:
+//   - cluster/status: crates/reddb-server/src/presentation/cluster_status_json.rs
+//   - replication/status: crates/reddb-server/src/server/handlers_replication.rs
+//
+// Honesty contract (#738): any field reddb cannot measure in the current
+// build is serialised as an `{ "available": false, "reason": "<token>" }`
+// envelope rather than a fabricated default. `Measurable<T>` models that — a
+// field is either its natural value or that envelope.
+
+/** Server's honest "cannot measure this" envelope (#738). */
+export interface Unavailable {
+  available: false;
+  reason: string;
+}
+
+/** A value the server may or may not be able to measure in this build. */
+export type Measurable<T> = T | Unavailable;
+
+export function isUnavailable(value: unknown): value is Unavailable {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    (value as { available?: unknown }).available === false
+  );
+}
+
+/** The measured value, or `undefined` when the server marked it unavailable. */
+export function measured<T>(
+  value: Measurable<T> | null | undefined
+): T | undefined {
+  if (value === null || value === undefined || isUnavailable(value))
+    return undefined;
+  return value;
+}
+
+/** The stable reason token when a field is unavailable, else `undefined`. */
+export function reasonOf(value: unknown): string | undefined {
+  return isUnavailable(value) ? value.reason : undefined;
+}
+
+export type DeploymentShape = "embedded" | "file" | "server" | "serverless";
+export type ProcessRole = "standalone" | "primary" | "replica";
+/** Lifecycle phase, `crates/reddb-server/src/runtime/lifecycle.rs`. */
+export type LifecyclePhase =
+  | "starting"
+  | "ready"
+  | "draining"
+  | "shutting_down"
+  | "stopped";
+
+export interface TransportListener {
+  transport: string;
+  bind_addr: string;
+  explicit: boolean;
+  reason?: string;
+}
+
+export interface ClusterStatusReplica {
+  id: string;
+  last_acked_lsn: number;
+  last_sent_lsn: number;
+  last_durable_lsn: number;
+  last_seen_at_unix_ms: number;
+  /** primary head LSN − this replica's last ack. */
+  lag_records: number;
+  region: string | null;
+}
+
+/** Real `/cluster/status` envelope (#738). */
+export interface ClusterStatus {
+  snapshot_at_unix_ms?: number;
+  version?: string;
+  phase?: LifecyclePhase | string;
+  uptime_secs?: number;
+  started_at_unix_ms?: number;
+  /** Present once the process reached `ready`. */
+  ready_at_unix_ms?: number;
+  read_only?: boolean;
+  deployment?: {
+    shape?: Measurable<DeploymentShape>;
+    process_role?: Measurable<ProcessRole>;
+    container?: Measurable<Record<string, unknown>>;
+  };
+  transports?: {
+    active?: TransportListener[];
+    failed?: TransportListener[];
+  };
+  connections?: {
+    active: number;
+    idle: number;
+    total_checkouts: number;
+    max: Measurable<number>;
+  };
+  storage?: {
+    db_size_bytes?: Measurable<number>;
+    remote_backend?: string | null;
+    paged_mode?: boolean;
+    encryption_at_rest?: { state: string; error?: string };
+  };
+  wal?: {
+    current_lsn: number;
+    last_archived_lsn: number;
+    archive_lag_records: number;
+    bytes: Measurable<number>;
+  };
+  system?: {
+    pid: number;
+    cpu_cores: number;
+    os: string;
+    arch: string;
+    hostname: string;
+    total_memory_bytes?: Measurable<number>;
+    available_memory_bytes?: Measurable<number>;
+    cpu_usage?: Measurable<number>;
+    ram_usage?: Measurable<number>;
+  };
+  throughput?: Measurable<{
+    requests_per_second?: number;
+    reads_per_second?: number;
+    writes_per_second?: number;
+  }>;
+  latency?: Measurable<{ avg_response_ms?: number }>;
+  last_error?: Measurable<{ message?: string; at_unix_ms?: number }>;
+  replication?: {
+    role?: Measurable<ProcessRole>;
+    commit_policy?: string;
+    replica_count?: number;
+    replicas?: ClusterStatusReplica[];
+    apply_health?: Measurable<string>;
+    degraded?: Measurable<boolean>;
+    apply_errors?: Record<string, number>;
+  };
+  /** Defensive: older servers may still wrap responses in `{ ok }`. */
+  ok?: boolean;
+}
+
+/** Per-replica view from a primary's `/replication/status`. */
+export interface ReplicationReplica {
+  id: string;
+  last_acked_lsn: number;
+  last_sent_lsn: number;
+  /** primary head − this replica's ack (record distance). */
+  lag_lsn: number;
+  /** wall-clock seconds since the primary last heard from the replica. */
+  lag_seconds: number;
+  rebootstrapping: boolean;
+}
+
+export interface ReplicationSlot {
+  id: string;
+  restart_lsn: number;
+  confirmed_lsn: number;
+  invalidated: boolean;
+  invalidation_reason?: string;
+}
+
+/** Real `/replication/status` envelope, primary + replica perspectives. */
+export interface ReplicationStatus {
+  ok: boolean;
+  role: ProcessRole;
+  current_term?: number;
+  is_leader?: boolean;
+  leader?: string;
+  state?:
+    | "idle"
+    | "connecting"
+    | "healthy"
+    | "lagging"
+    | "disconnected"
+    | string;
+  // primary perspective
+  wal_lsn?: number;
+  commit_watermark?: number;
+  oldest_lsn?: number;
+  replica_count?: number;
+  replicas?: ReplicationReplica[];
+  full_resync_count?: number;
+  partial_resync_count?: number;
+  replication_lag_lsn?: number;
+  safe_replay_lsn?: number;
+  retention_floor_lsn?: number;
+  slots?: ReplicationSlot[];
+  // replica perspective
+  primary_addr?: string;
+  last_applied_lsn?: number;
+  last_seen_primary_lsn?: number;
+  last_seen_oldest_lsn?: number;
+  last_error?: string;
+}
+
+/**
+ * The four user-facing topologies, plus `server` (a single networked node that
+ * is neither serverless nor part of a replication set) and `unknown`. Derived
+ * from the orthogonal axes the server exposes: deployment *shape* (where it
+ * runs) × process *role* (its replication relationship).
+ */
+export type NodeTopology =
+  | "embedded"
+  | "serverless"
+  | "replicated"
+  | "server"
+  | "unknown";
+
+/**
+ * Classify a node's topology. Role wins over shape: a node in a replication
+ * relationship is `replicated` regardless of where it runs. Falls back to the
+ * preset's configured role when the server exposes neither (older builds).
+ */
+export function topologyOf(
+  cluster?: ClusterStatus,
+  replication?: ReplicationStatus,
+  presetRole?: string
+): NodeTopology {
+  const role =
+    measured(cluster?.deployment?.process_role) ??
+    measured(cluster?.replication?.role) ??
+    replication?.role;
+  if (role === "primary" || role === "replica") return "replicated";
+
+  const shape = measured(cluster?.deployment?.shape);
+  if (shape === "serverless") return "serverless";
+  if (shape === "embedded" || shape === "file") return "embedded";
+  if (shape === "server") return "server";
+
+  // Server exposed nothing usable — lean on how the preset was configured.
+  if (presetRole === "primary" || presetRole === "replica") return "replicated";
+  if (presetRole === "embedded") return "embedded";
+  if (presetRole === "standalone" || presetRole === "server") return "server";
+  return "unknown";
+}
+
+/**
+ * Cold-start duration in ms for a freshly-booted node: `ready_at - started_at`.
+ * `null` when either timestamp is missing (e.g. not yet ready). This is the
+ * serverless hero metric the user asked for — boot time.
+ */
+export function bootDurationMs(cluster?: ClusterStatus): number | null {
+  const started = cluster?.started_at_unix_ms;
+  const ready = cluster?.ready_at_unix_ms;
+  if (started === undefined || ready === undefined) return null;
+  const delta = ready - started;
+  return delta >= 0 ? delta : null;
+}
+
+/**
+ * Worst wall-clock replication lag across replicas, in seconds, from a
+ * primary's `/replication/status`. `null` when no replicas are observed or the
+ * field is absent. This answers "how long is replication taking".
+ */
+export function maxReplicaLagSeconds(
+  replication?: ReplicationStatus
+): number | null {
+  const replicas = replication?.replicas;
+  if (!replicas || replicas.length === 0) return null;
+  let worst = 0;
+  let seen = false;
+  for (const r of replicas) {
+    if (typeof r.lag_seconds === "number" && Number.isFinite(r.lag_seconds)) {
+      worst = Math.max(worst, r.lag_seconds);
+      seen = true;
+    }
+  }
+  return seen ? worst : null;
+}
+
+/** One unavailable field the server explicitly declined to measure. */
+export interface UnavailableField {
+  /** Dotted path into the payload, e.g. `system.cpu_usage`. */
+  path: string;
+  reason: string;
+}
+
+/**
+ * Walk the cluster-status payload and collect every field the server marked
+ * `{ available: false }`, with its reason. This replaces the UI's previously
+ * hand-maintained "not exposed" list — the server is now the source of truth
+ * for what it cannot measure and why (#738).
+ */
+export function unavailableFields(cluster?: ClusterStatus): UnavailableField[] {
+  if (!cluster) return [];
+  const out: UnavailableField[] = [];
+  const walk = (value: unknown, path: string, depth: number) => {
+    if (isUnavailable(value)) {
+      out.push({ path, reason: value.reason });
+      return;
+    }
+    if (
+      depth >= 4 ||
+      !value ||
+      typeof value !== "object" ||
+      Array.isArray(value)
+    ) {
+      return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+      walk(child, path ? `${path}.${key}` : key, depth + 1);
+    }
+  };
+  walk(cluster, "", 0);
+  return out;
+}

package/src/lib/reddb/desktop-error.ts

@@ -0,0 +1,89 @@
+// The single classifier for desktop-command failures (#115).
+//
+// Tauri's `invoke` rejects with whatever the Rust `Err` serialized to. Every
+// desktop command now returns a structured `{ code, message, detail? }` shape
+// (see apps/desktop/src-tauri/src/lib.rs), but older builds and Tauri's own
+// plugin/runtime failures can still reject with a bare string or an `Error`.
+// This module is the ONE place that inspects the raw thrown value and
+// normalizes it, so the standalone-Surface adapters never re-implement the
+// `e instanceof Error ? … : String(e)` coercion dance.
+
+/** The serializable error shape returned by Rust desktop commands. */
+export interface DesktopCommandError {
+  /** Stable machine token, e.g. `KEYCHAIN`, `EMBEDDED_TIMEOUT`, `SIDECAR_SPAWN`. */
+  code: string;
+  /** Human-readable summary. */
+  message: string;
+  /** Underlying cause (OS/keyring/serde message) when the command had one. */
+  detail?: string;
+}
+
+/** Code used for legacy string errors and anything not shaped as a command error. */
+export const UNKNOWN_DESKTOP_ERROR_CODE = "UNKNOWN";
+
+/** Type guard for the structured shape a desktop command rejects with. */
+export function isDesktopCommandError(x: unknown): x is DesktopCommandError {
+  return (
+    typeof x === "object" &&
+    x !== null &&
+    typeof (x as DesktopCommandError).code === "string" &&
+    typeof (x as DesktopCommandError).message === "string"
+  );
+}
+
+/**
+ * Normalize any value thrown by a desktop command into a `DesktopCommandError`.
+ * Structured errors pass through (with an empty/absent `detail` dropped); bare
+ * strings, `Error` instances, and everything else collapse to the `UNKNOWN`
+ * code so callers always get a `{ code, message }` pair.
+ */
+export function classifyDesktopError(e: unknown): DesktopCommandError {
+  if (isDesktopCommandError(e)) {
+    const detail = e.detail;
+    return {
+      code: e.code,
+      message: e.message,
+      ...(typeof detail === "string" && detail.length > 0 ? { detail } : {}),
+    };
+  }
+  if (typeof e === "string") {
+    return { code: UNKNOWN_DESKTOP_ERROR_CODE, message: e };
+  }
+  if (e instanceof Error) {
+    return { code: UNKNOWN_DESKTOP_ERROR_CODE, message: e.message || String(e) };
+  }
+  return { code: UNKNOWN_DESKTOP_ERROR_CODE, message: String(e) };
+}
+
+/** Human-readable one-liner for a classified desktop error. */
+export function desktopErrorMessage(e: unknown): string {
+  const c = classifyDesktopError(e);
+  return c.detail ? `${c.message}: ${c.detail}` : c.message;
+}
+
+/**
+ * An `Error` carrying the classified `code`/`detail`, with `message` set to the
+ * human-readable one-liner. Adapters throw this so downstream consumers (e.g.
+ * the connection provider) can read `.message` without any coercion, while
+ * still being able to branch on `.code`.
+ */
+export class DesktopError extends Error {
+  readonly code: string;
+  readonly detail?: string;
+
+  constructor(classified: DesktopCommandError) {
+    super(
+      classified.detail
+        ? `${classified.message}: ${classified.detail}`
+        : classified.message
+    );
+    this.name = "DesktopError";
+    this.code = classified.code;
+    this.detail = classified.detail;
+  }
+
+  /** Classify a raw thrown value and wrap it. */
+  static from(e: unknown): DesktopError {
+    return e instanceof DesktopError ? e : new DesktopError(classifyDesktopError(e));
+  }
+}

package/src/lib/reddb/dev-console.ts

@@ -0,0 +1,186 @@
+// Instrumented developer console (#128). A deliberately framework-agnostic,
+// rune-free observable store so the data layer (`RedClient`, transports) can
+// log every query and HTTP call *without* importing Svelte — the client seam
+// must not depend on the UI runtime. The Svelte panel bridges this store into
+// reactivity by subscribing and copying the snapshot into `$state`.
+//
+// Every entry is one round-trip the client made: the verb (HTTP method /
+// statement head), the target (path or endpoint), how long it took, how many
+// rows came back, and a *sanitized* payload — secrets are redacted before an
+// entry is ever stored, so a copy action can never leak a token.
+
+/** What kind of round-trip an entry records. */
+export type ConsoleEntryKind = "query" | "http";
+
+export interface ConsoleEntry {
+  /** Monotonic id, assigned on record. Stable for keying/dedup in the panel. */
+  id: number;
+  kind: ConsoleEntryKind;
+  /** HTTP method or statement head, e.g. `POST`, `GET`, `SELECT`. */
+  verb: string;
+  /** Endpoint path or logical target the call hit, e.g. `/query`. */
+  target: string;
+  /** Absolute wall-clock time the call started. */
+  startedAt: number;
+  /** Round-trip duration in milliseconds. */
+  durationMs: number;
+  /** True when the call succeeded (2xx / resolved). */
+  ok: boolean;
+  /** HTTP status code when one is known. */
+  status?: number;
+  /** Rows returned, when the response carries a row/record count. */
+  rowCount?: number;
+  /** Sanitized request payload or query text — copyable, never contains secrets. */
+  payload?: string;
+  /** Error text when the call failed. */
+  error?: string;
+}
+
+/** A record as handed to the store — the store owns `id`. */
+export type ConsoleEntryInput = Omit<ConsoleEntry, "id">;
+
+/**
+ * A per-entry tap on the console. Unlike `subscribe` (which observes the whole
+ * snapshot for rendering), a sink receives each entry exactly once, as it is
+ * recorded — the shape an embedding host wants for mirroring red-ui's traffic
+ * into its own developer console.
+ */
+export type ConsoleSink = (entry: ConsoleEntry) => void;
+
+type Listener = (entries: readonly ConsoleEntry[]) => void;
+
+/** Keys whose values are always masked, matched case-insensitively as substrings. */
+const SENSITIVE_KEY_RE =
+  /pass(word)?|secret|token|api[-_]?key|authorization|auth|credential|cookie|session|bearer|private[-_]?key|mfa/i;
+
+const REDACTED = "«redacted»";
+
+/**
+ * Recursively redact sensitive values from an arbitrary structure, returning a
+ * plain clone safe to stringify. A value under a sensitive key is replaced with
+ * a marker rather than dropped, so the reader still sees *that* a field existed.
+ * Depth- and breadth-bounded so a pathological payload can't blow the console.
+ */
+export function redactSecrets(value: unknown, depth = 0): unknown {
+  if (depth > 6) return "«…»";
+  if (Array.isArray(value)) {
+    return value.slice(0, 100).map((v) => redactSecrets(v, depth + 1));
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = SENSITIVE_KEY_RE.test(k)
+        ? REDACTED
+        : redactSecrets(v, depth + 1);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Turn a request body (a JSON string, an object, or anything else) into a
+ * sanitized, human-readable string for the entry's copyable payload. Parses
+ * JSON so keys can be redacted; falls back to a truncated raw string when the
+ * body isn't JSON. Returns `undefined` for an absent body.
+ */
+export function sanitizePayload(body: unknown): string | undefined {
+  if (body === undefined || body === null) return undefined;
+  let parsed: unknown = body;
+  if (typeof body === "string") {
+    if (body.length === 0) return undefined;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      return body.length > 2000 ? `${body.slice(0, 2000)}…` : body;
+    }
+  }
+  try {
+    const json = JSON.stringify(redactSecrets(parsed), null, 2);
+    return json.length > 4000 ? `${json.slice(0, 4000)}…` : json;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The developer console log. A bounded ring of entries with a minimal
+ * subscribe/emit surface — no framework, no runes. `record` is the single
+ * write path the client seam calls; `subscribe` is how the panel observes.
+ */
+export class DevConsoleStore {
+  private entries: ConsoleEntry[] = [];
+  private readonly listeners = new Set<Listener>();
+  private readonly sinks = new Set<ConsoleSink>();
+  private nextId = 1;
+
+  /** Cap on retained entries; oldest are dropped past this. */
+  constructor(private readonly capacity = 500) {}
+
+  /** Append one round-trip. Assigns the id, trims to capacity, notifies. */
+  record(input: ConsoleEntryInput): ConsoleEntry {
+    const entry: ConsoleEntry = { ...input, id: this.nextId++ };
+    this.entries.push(entry);
+    if (this.entries.length > this.capacity) {
+      this.entries.splice(0, this.entries.length - this.capacity);
+    }
+    this.emit();
+    for (const sink of this.sinks) {
+      try {
+        sink(entry);
+      } catch {
+        // A host-owned sink must never be able to break the client seam.
+      }
+    }
+    return entry;
+  }
+
+  /**
+   * Tap every future entry. Entries recorded before the sink was added are
+   * not replayed — a host mirrors live traffic, it doesn't import history.
+   * Returns an unsubscribe.
+   */
+  addSink(sink: ConsoleSink): () => void {
+    this.sinks.add(sink);
+    return () => {
+      this.sinks.delete(sink);
+    };
+  }
+
+  /** A frozen, newest-last snapshot of the log. */
+  snapshot(): readonly ConsoleEntry[] {
+    return this.entries.slice();
+  }
+
+  /** Number of retained entries. */
+  get size(): number {
+    return this.entries.length;
+  }
+
+  /** Drop every entry and notify. */
+  clear(): void {
+    if (this.entries.length === 0) return;
+    this.entries = [];
+    this.emit();
+  }
+
+  /**
+   * Observe the log. The listener fires immediately with the current snapshot
+   * and again on every change. Returns an unsubscribe.
+   */
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    listener(this.snapshot());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private emit(): void {
+    const snap = this.snapshot();
+    for (const listener of this.listeners) listener(snap);
+  }
+}
+
+/** The singleton the client seam records into and the panel observes. */
+export const devConsole = new DevConsoleStore();

package/src/lib/reddb/index.ts

@@ -1,6 +1,10 @@
 export * from "./uri";
 export * from "./types";
+export * from "./cluster-status";
+export * from "./analytics";
+export * from "./ask";
 export * from "./client";
+export * from "./dev-console";
 export * from "./connection-provider";
 export * from "./local-url-provider";
 export * from "./injected-client-provider";
@@ -12,3 +16,4 @@ export * from "./cdc-stream-client";
 export * from "./secure-store";
 export * from "./web-encrypted-store";
 export * from "./tauri-encrypted-store";
+export * from "./desktop-error";

package/src/lib/reddb/local-url-provider.ts

@@ -50,6 +50,14 @@ export interface LocalUrlProviderOptions {
    * auto-connect without the Connect flow. Tokens must never be placed here.
    */
   bootParams?: BootParams;
+  /**
+   * Resolve a `file://` connection to a reachable URL (#embedded-file). Only a
+   * Tauri Surface supplies this: it spawns a local file-backed reddb sidecar
+   * and returns its `http://127.0.0.1:<port>` URL, which the HTTP client then
+   * talks to. Absent on the browser Surface, where `file://` is unreachable by
+   * design. Receives the original `file://…` string, returns the client URL.
+   */
+  embeddedResolver?: (fileUrl: string) => Promise<string>;
 }
 
 export interface HandoffTokenConsumer {
@@ -102,6 +110,7 @@ export class LocalUrlProvider implements ConnectionProvider {
   private readonly historyMax: number;
   private readonly supportedTransports: Transport[];
   private readonly boot: BootParams | null;
+  private readonly embeddedResolver?: (fileUrl: string) => Promise<string>;
   private readonly handoffTokens = new Map<string, string>();
   private active: ActiveConnection | null = null;
 
@@ -120,6 +129,7 @@ export class LocalUrlProvider implements ConnectionProvider {
       (hasBootEndpoint(opts.bootParams) || hasBootRoute(opts.bootParams))
         ? { ...opts.bootParams }
         : null;
+    this.embeddedResolver = opts.embeddedResolver;
   }
 
   transports(): Transport[] {
@@ -162,9 +172,26 @@ export class LocalUrlProvider implements ConnectionProvider {
     const target = this.resolve(id);
     if (!target) throw new UnknownConnectionError(id);
 
+    // A `file://` target is opened by the Surface's embedded resolver (Tauri
+    // spawns a local file-backed reddb and hands back its http URL). The
+    // displayed connection keeps the `file://` identity; only the client talks
+    // to the resolved local URL.
+    let clientUrl = target.url;
+    if (this.embeddedResolver && /^file:\/\//i.test(target.url)) {
+      try {
+        clientUrl = await this.embeddedResolver(target.url);
+      } catch (e) {
+        // The resolver (the standalone-Surface adapter) already classified the
+        // command failure into an Error with a human-readable message — no
+        // defensive shape-coercion here; just carry the reason through.
+        const reason = e instanceof Error ? e.message : String(e);
+        throw new UnreachableConnectionError(target.id, reason);
+      }
+    }
+
     const token = this.consumeHandoffToken(target.url);
     const client = this.clientFactory(
-      target.url,
+      clientUrl,
       token ? { headers: { Authorization: `Bearer ${token}` } } : undefined
     );
     const ping = await client.ping();