@reddb-io/ui 0.2.0 → 0.3.1

package/src/lib/reddb/client.ts

@@ -7,6 +7,14 @@ import {
   type RawCapabilities,
   type ServerCapabilities,
 } from "./server-capabilities";
+import type {
+  PermissionCheck,
+  PermissionDecision,
+  PermissionResource,
+} from "../permission-gate";
+import type { ClusterStatus, ReplicationStatus } from "./cluster-status";
+import type { MetricDescriptor, PromResponse } from "./analytics";
+import type { AskResponse, AskOptions } from "./ask";
 
 export interface QueryRow {
   values: Record<string, unknown>;
@@ -104,59 +112,6 @@ export interface Stats {
   read_only_reason?: string;
 }
 
-export interface ClusterStatus {
-  ok?: boolean;
-  deployment?: {
-    mode?: "embedded" | "server" | "docker" | "replicated" | string;
-    file_path?: string;
-    process_kind?: string;
-    container_id?: string;
-    image?: string;
-    configured_by?: string;
-  };
-  storage?: {
-    capacity_bytes?: number;
-    used_bytes?: number;
-    free_bytes?: number;
-  };
-  wal?: {
-    size_bytes?: number;
-    lsn?: number;
-    oldest_lsn?: number;
-  };
-  throughput?: {
-    requests_per_second?: number;
-    reads_per_second?: number;
-    writes_per_second?: number;
-    avg_response_ms?: number;
-  };
-  system?: {
-    cpu_usage_percent?: number;
-    memory_used_bytes?: number;
-    memory_total_bytes?: number;
-  };
-  replication?: {
-    replica_count?: number;
-    lag_ms?: number;
-    lag_lsn?: number;
-  };
-}
-
-export interface ReplicationStatus {
-  ok: boolean;
-  role: "primary" | "replica" | "standalone";
-  state?: "healthy" | "lagging" | "disconnected";
-  primary_addr?: string;
-  /** primary perspective */
-  wal_lsn?: number;
-  oldest_lsn?: number;
-  replica_count?: number;
-  /** replica perspective */
-  last_applied_lsn?: number;
-  last_seen_primary_lsn?: number;
-  last_seen_oldest_lsn?: number;
-}
-
 export interface Whoami {
   ok: boolean;
   authenticated: boolean;
@@ -199,6 +154,12 @@ export interface AuthPolicy {
   created_at?: number;
 }
 
+interface AuthCanResponse {
+  ok?: boolean;
+  results?: Array<Partial<PermissionDecision>>;
+  error?: string;
+}
+
 export interface ChangeEvent {
   lsn: number;
   timestamp: number;
@@ -280,6 +241,18 @@ function unsupportedCollectionMetadataError(baseUrl: string): Error {
   );
 }
 
+function isPermissionResource(value: unknown): value is PermissionResource {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<PermissionResource>;
+  return (
+    typeof candidate.kind === "string" &&
+    candidate.kind.length > 0 &&
+    typeof candidate.name === "string" &&
+    candidate.name.length > 0 &&
+    (candidate.tenant === undefined || typeof candidate.tenant === "string")
+  );
+}
+
 /** One NDJSON frame from `POST /query/stream`. Discriminated by its single key. */
 type NdjsonFrame =
   | { descriptor: { columns: string[]; schema_fingerprint?: string } }
@@ -320,6 +293,27 @@ async function* parseNdjsonFrames(
 
 const SELECT_RE = /^\s*select\b/i;
 
+/**
+ * Extract a human-readable message from any thrown value. Tauri's `invoke` and
+ * the HTTP plugin reject with plain strings or bare objects (not `Error`), so
+ * `(e as Error).message` is often `undefined` — this never returns that.
+ */
+export function errorText(e: unknown): string {
+  if (e instanceof Error) return e.message || String(e);
+  if (typeof e === "string") return e;
+  if (e && typeof e === "object") {
+    const m = (e as { message?: unknown }).message;
+    if (typeof m === "string" && m) return m;
+    try {
+      const s = JSON.stringify(e);
+      if (s && s !== "{}") return s;
+    } catch {
+      /* circular — fall through */
+    }
+  }
+  return String(e);
+}
+
 /**
  * Run a query, preferring the bounded-memory NDJSON stream for a plain SELECT
  * and falling back to the buffered `POST /query` for everything else — and for
@@ -334,7 +328,9 @@ export async function runQueryPreferStream(
   sql: string,
   opts: { maxRows?: number; signal?: AbortSignal } = {}
 ): Promise<QueryResult> {
-  if (!SELECT_RE.test(sql)) return client.query(sql);
+  const queryOpts = opts.signal ? { signal: opts.signal } : undefined;
+  if (!SELECT_RE.test(sql))
+    return queryOpts ? client.query(sql, queryOpts) : client.query(sql);
   try {
     const s = await client.queryStreamCollect(sql, opts);
     return {
@@ -348,8 +344,14 @@ export async function runQueryPreferStream(
       streamed: true,
       truncated: s.truncated,
     };
-  } catch {
-    return client.query(sql);
+  } catch (e) {
+    if (
+      opts.signal?.aborted ||
+      (e instanceof Error && e.name === "AbortError")
+    ) {
+      throw e;
+    }
+    return queryOpts ? client.query(sql, queryOpts) : client.query(sql);
   }
 }
 
@@ -390,6 +392,60 @@ export class RedClient {
     return this.json<ClusterStatus>("/cluster/status");
   }
 
+  /**
+   * List registered metric descriptors from the typed `red.metrics`
+   * projection (reddb #747). One row per `CREATE METRIC`, carrying the
+   * `kind` (counter|gauge|histogram|ratio|derived) the UI uses to auto-select
+   * a chart. Returns `[]` when the server has no analytics surface.
+   */
+  async metricsCatalog(): Promise<MetricDescriptor[]> {
+    const r = await this.query(
+      "SELECT path, kind, role, unit, supports_prometheus_query, created_at_ms FROM red.metrics"
+    );
+    return r.result.records.map((rec) => {
+      const v = rec.values;
+      return {
+        path: String(v.path ?? ""),
+        kind: v.kind as MetricDescriptor["kind"],
+        role: String(v.role ?? "metric"),
+        unit: (v.unit as string | null) ?? null,
+        supports_prometheus_query: v.supports_prometheus_query !== false,
+        created_at_ms:
+          typeof v.created_at_ms === "number" ? v.created_at_ms : undefined,
+      } satisfies MetricDescriptor;
+    });
+  }
+
+  /**
+   * Prometheus instant query (`GET /api/v1/query`). Returns the raw
+   * Prometheus-shaped envelope; callers normalise with `parsePromVector`.
+   */
+  async promQuery(query: string, time?: number): Promise<PromResponse> {
+    const qs = new URLSearchParams({ query });
+    if (time !== undefined) qs.set("time", String(time));
+    return this.json<PromResponse>(`/api/v1/query?${qs}`);
+  }
+
+  /**
+   * Prometheus range query (`GET /api/v1/query_range`). `start`/`end` are unix
+   * seconds, `step` is the resolution in seconds. Normalise with
+   * `parsePromMatrix`.
+   */
+  async promQueryRange(
+    query: string,
+    start: number,
+    end: number,
+    step: number
+  ): Promise<PromResponse> {
+    const qs = new URLSearchParams({
+      query,
+      start: String(start),
+      end: String(end),
+      step: String(step),
+    });
+    return this.json<PromResponse>(`/api/v1/query_range?${qs}`);
+  }
+
   async ping(): Promise<
     { ok: true; rtt_ms: number } | { ok: false; error: string }
   > {
@@ -398,7 +454,7 @@ export class RedClient {
       await this.json("/stats");
       return { ok: true, rtt_ms: Math.round(performance.now() - start) };
     } catch (e) {
-      return { ok: false, error: (e as Error).message };
+      return { ok: false, error: errorText(e) };
     }
   }
 
@@ -497,10 +553,14 @@ export class RedClient {
     );
   }
 
-  async query(query: string): Promise<QueryResult> {
+  async query(
+    query: string,
+    opts: { signal?: AbortSignal } = {}
+  ): Promise<QueryResult> {
     return this.json<QueryResult>("/query", {
       method: "POST",
       body: JSON.stringify({ query }),
+      signal: opts.signal,
     });
   }
 
@@ -654,6 +714,20 @@ export class RedClient {
     return this.json<Whoami>("/auth/whoami");
   }
 
+  /**
+   * Grounded natural-language query (`POST /ai/ask`, ADR 0013). Returns the
+   * synthesised answer plus the `sources_flat` it was grounded on and the
+   * `[^N]` citations linking claims to sources. Requires the server's AI
+   * provider to be configured; an unconfigured server answers with an error
+   * status (surfaced by `json()`).
+   */
+  async ask(question: string, opts: AskOptions = {}): Promise<AskResponse> {
+    return this.json<AskResponse>("/ai/ask", {
+      method: "POST",
+      body: JSON.stringify({ question, ...opts }),
+    });
+  }
+
   async users(): Promise<AuthUser[]> {
     const r = await this.json<{ ok: boolean; users: AuthUser[] }>(
       "/auth/users"
@@ -675,6 +749,33 @@ export class RedClient {
     return r.policies ?? [];
   }
 
+  async authCan(checks: PermissionCheck[]): Promise<PermissionDecision[]> {
+    const r = await this.json<AuthCanResponse>("/auth/can", {
+      method: "POST",
+      body: JSON.stringify({ checks }),
+    });
+    if (!Array.isArray(r.results)) {
+      throw new Error(r.error ?? "POST /auth/can returned no results");
+    }
+    return checks.map((check, index) => {
+      const result = r.results?.[index] ?? {};
+      const resource = isPermissionResource(result.resource)
+        ? result.resource
+        : check.resource;
+      return {
+        action:
+          typeof result.action === "string" ? result.action : check.action,
+        resource,
+        current_tenant:
+          typeof result.current_tenant === "string"
+            ? result.current_tenant
+            : check.current_tenant,
+        allowed: result.allowed === true,
+        reason: typeof result.reason === "string" ? result.reason : undefined,
+      };
+    });
+  }
+
   async changes(
     sinceLsn?: number,
     opts: { collection?: string; limit?: number } = {}

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/index.ts

@@ -1,5 +1,8 @@
 export * from "./uri";
 export * from "./types";
+export * from "./cluster-status";
+export * from "./analytics";
+export * from "./ask";
 export * from "./client";
 export * from "./connection-provider";
 export * from "./local-url-provider";

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,30 @@ 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) {
+        // Tauri's `invoke` rejects with a plain string (the Rust `Err`), not an
+        // Error — so read the message defensively instead of assuming `.message`.
+        const reason =
+          e instanceof Error
+            ? e.message
+            : typeof e === "string"
+              ? e
+              : 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();