@reddb-io/ui 0.1.1

package/src/lib/reddb/connection-bootstrap.ts

@@ -0,0 +1,260 @@
+import { parseOpenContract } from "./boot-params";
+
+export const DEFAULT_PERSISTED_CONNECTION_KEY = "red-ui:connection";
+
+export interface ConnectionBootstrap {
+  target: string | null;
+  token?: string;
+  route?: string;
+}
+
+export type ConnectionBootstrapPayload =
+  | {
+      target?: unknown;
+      token?: unknown;
+      route?: unknown;
+    }
+  | null
+  | undefined;
+
+type MaybePromise<T> = T | Promise<T>;
+type BootstrapSource = () => MaybePromise<ConnectionBootstrapPayload>;
+type TauriInvoke = <T>(
+  command: string,
+  args?: Record<string, unknown>
+) => Promise<T>;
+
+export interface BootstrapStorage {
+  getItem(key: string): string | null;
+}
+
+export interface UrlBootstrapLocation {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+export interface UrlBootstrapHistory {
+  readonly state: unknown;
+  replaceState(data: unknown, unused: string, url?: string | URL | null): void;
+}
+
+export interface UrlBootstrapReadOptions {
+  consume?: boolean;
+  location?: UrlBootstrapLocation;
+  history?: UrlBootstrapHistory;
+}
+
+export interface ConnectionBootstrapResolverOptions {
+  readTauri?: BootstrapSource;
+  readInjectedGlobal?: BootstrapSource;
+  readUrl?: BootstrapSource;
+  readPersisted?: BootstrapSource;
+}
+
+const GLOBAL_BOOTSTRAP_KEYS = [
+  "__RED_BOOTSTRAP__",
+  "__RED_UI_CONNECTION_BOOTSTRAP__",
+  "__RED_UI_BOOTSTRAP__",
+];
+
+function clean(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function normalizeBootstrap(
+  payload: ConnectionBootstrapPayload
+): ConnectionBootstrap | null {
+  if (!payload || typeof payload !== "object") return null;
+
+  const target = clean(payload.target);
+  const token = clean(payload.token);
+  const route = clean(payload.route);
+
+  if (!target && !token && !route) return null;
+
+  return {
+    target: target ?? null,
+    ...(token ? { token } : {}),
+    ...(route ? { route } : {}),
+  };
+}
+
+async function firstPresent(
+  sources: BootstrapSource[]
+): Promise<ConnectionBootstrap | null> {
+  for (const source of sources) {
+    let resolved: ConnectionBootstrap | null;
+    try {
+      resolved = normalizeBootstrap(await source());
+    } catch {
+      resolved = null;
+    }
+    if (resolved) return resolved;
+  }
+  return null;
+}
+
+async function loadTauriInvoke(): Promise<TauriInvoke | null> {
+  if (typeof window === "undefined") return null;
+  if (!("__TAURI_INTERNALS__" in window || "__TAURI__" in window)) return null;
+
+  try {
+    const mod = await import("@tauri-apps/api/core");
+    return mod.invoke as TauriInvoke;
+  } catch {
+    return null;
+  }
+}
+
+export async function readTauriIpcBootstrap(
+  invoke?: TauriInvoke
+): Promise<ConnectionBootstrapPayload> {
+  const call = invoke ?? (await loadTauriInvoke());
+  if (!call) return null;
+
+  try {
+    return await call<ConnectionBootstrapPayload>("connection_bootstrap");
+  } catch {
+    return null;
+  }
+}
+
+export async function readInjectedGlobalBootstrap(
+  root: unknown = globalThis
+): Promise<ConnectionBootstrapPayload> {
+  if (!root || typeof root !== "object") return null;
+  const bag = root as Record<string, unknown>;
+
+  for (const key of GLOBAL_BOOTSTRAP_KEYS) {
+    const candidate = bag[key];
+    if (!candidate) continue;
+    try {
+      if (typeof candidate === "function") {
+        return await (
+          candidate as () => MaybePromise<ConnectionBootstrapPayload>
+        )();
+      }
+      return candidate as ConnectionBootstrapPayload;
+    } finally {
+      try {
+        delete bag[key];
+      } catch {
+        bag[key] = undefined;
+      }
+    }
+  }
+
+  return null;
+}
+
+function liveUrlBootstrapOptions(): UrlBootstrapReadOptions {
+  return {
+    consume: true,
+    location:
+      typeof location === "undefined"
+        ? undefined
+        : {
+            pathname: location.pathname,
+            search: location.search,
+            hash: location.hash,
+          },
+    history:
+      typeof history === "undefined"
+        ? undefined
+        : {
+            state: history.state,
+            replaceState: (data, unused, url) =>
+              history.replaceState(data, unused, url),
+          },
+  };
+}
+
+function stripTokenFromHistory(options: UrlBootstrapReadOptions): void {
+  if (!options.consume || !options.location || !options.history) return;
+  const hash = options.location.hash;
+  if (!hash) return;
+
+  const params = new URLSearchParams(
+    hash.startsWith("#") ? hash.slice(1) : hash
+  );
+  if (!params.has("token")) return;
+  params.delete("token");
+
+  const nextHash = params.toString();
+  const nextUrl = `${options.location.pathname}${options.location.search}${
+    nextHash ? `#${nextHash}` : ""
+  }`;
+  try {
+    options.history.replaceState(options.history.state, "", nextUrl);
+  } catch {
+    /* best-effort URL cleanup */
+  }
+}
+
+export function readUrlOpenContractBootstrap(
+  search = typeof location === "undefined" ? "" : location.search,
+  hash = typeof location === "undefined" ? "" : location.hash,
+  options: UrlBootstrapReadOptions = liveUrlBootstrapOptions()
+): ConnectionBootstrapPayload {
+  try {
+    const contract = parseOpenContract(search, hash);
+    if (contract.token) stripTokenFromHistory(options);
+    if (!contract.cs && !contract.to && !contract.token) return null;
+    return {
+      target: contract.cs,
+      token: contract.token,
+      route: contract.to,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function defaultStorage(): BootstrapStorage | undefined {
+  try {
+    return typeof localStorage === "undefined" ? undefined : localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+export function readPersistedLocalBootstrap(
+  storage = defaultStorage(),
+  key = DEFAULT_PERSISTED_CONNECTION_KEY
+): ConnectionBootstrapPayload {
+  if (!storage) return null;
+
+  try {
+    const raw = storage.getItem(key);
+    if (!raw) return null;
+
+    const parsed = JSON.parse(raw) as { url?: unknown };
+    const target = clean(parsed?.url);
+    return target ? { target } : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function resolveConnectionBootstrap(
+  options: ConnectionBootstrapResolverOptions = {}
+): Promise<ConnectionBootstrap> {
+  const readUrl = options.readUrl ?? (() => readUrlOpenContractBootstrap());
+  const resolved = await firstPresent([
+    options.readTauri ?? readTauriIpcBootstrap,
+    options.readInjectedGlobal ?? readInjectedGlobalBootstrap,
+    readUrl,
+    options.readPersisted ?? (() => readPersistedLocalBootstrap()),
+  ]);
+
+  if (resolved && !options.readUrl) {
+    try {
+      readUrlOpenContractBootstrap();
+    } catch {
+      /* best-effort live URL cleanup after a higher-priority boot source */
+    }
+  }
+
+  return resolved ?? { target: null };
+}

package/src/lib/reddb/connection-provider.contract.ts

@@ -0,0 +1,72 @@
+// Contract tests for ConnectionProvider. Every implementation (LocalUrlProvider,
+// the in-memory mock, future ReddbIoSsoProvider) runs through this suite, so
+// the seam stays honest: behaviour, not just types.
+
+import { describe, expect, it } from 'vitest'
+import {
+  NotConnectedError,
+  UnknownConnectionError,
+  type Connection,
+  type ConnectionProvider,
+} from './connection-provider'
+
+export interface ContractFixture {
+  provider: ConnectionProvider
+  /** A connection id the provider promises to resolve in connect(). */
+  knownId: string
+  /** A connection id the provider promises NOT to resolve. */
+  unknownId: string
+}
+
+export function runConnectionProviderContract(
+  name: string,
+  build: () => ContractFixture | Promise<ContractFixture>,
+) {
+  describe(`ConnectionProvider contract — ${name}`, () => {
+    it('list() returns Connection objects with id/label/url', async () => {
+      const { provider } = await build()
+      const items = await provider.list()
+      expect(Array.isArray(items)).toBe(true)
+      for (const c of items) {
+        expect(typeof c.id).toBe('string')
+        expect(typeof c.label).toBe('string')
+        expect(typeof c.url).toBe('string')
+      }
+    })
+
+    it('list() entries have unique ids', async () => {
+      const { provider } = await build()
+      const items: Connection[] = await provider.list()
+      const ids = items.map((c) => c.id)
+      expect(new Set(ids).size).toBe(ids.length)
+    })
+
+    it('connect(knownId) resolves to an ActiveConnection', async () => {
+      const { provider, knownId } = await build()
+      const active = await provider.connect(knownId)
+      expect(active.connection.id).toBe(knownId)
+      expect(active.client).toBeTruthy()
+      expect(typeof active.rtt_ms).toBe('number')
+      expect(active.rtt_ms).toBeGreaterThanOrEqual(0)
+    })
+
+    it('connect(unknownId) rejects with UnknownConnectionError', async () => {
+      const { provider, unknownId } = await build()
+      await expect(provider.connect(unknownId)).rejects.toBeInstanceOf(UnknownConnectionError)
+    })
+
+    it('whoami() before connect rejects with NotConnectedError', async () => {
+      const { provider } = await build()
+      await expect(provider.whoami()).rejects.toBeInstanceOf(NotConnectedError)
+    })
+
+    it('whoami() after connect resolves to an Identity', async () => {
+      const { provider, knownId } = await build()
+      await provider.connect(knownId)
+      const id = await provider.whoami()
+      expect(typeof id.authenticated).toBe('boolean')
+      expect(typeof id.username).toBe('string')
+      expect(typeof id.role).toBe('string')
+    })
+  })
+}

package/src/lib/reddb/connection-provider.ts

@@ -0,0 +1,72 @@
+// ConnectionProvider — deep module: the UI's only seam for "how do I
+// discover and select databases?". Local OSS lives behind LocalUrlProvider;
+// cloud SSO (ReddbIoSsoProvider) will land in a separate slice without
+// touching the consumers.
+
+import type { RedClient } from './client'
+import type { Transport } from './types'
+import type { BootParams } from './boot-params'
+
+export type ConnectionRole = 'primary' | 'replica' | 'embedded'
+
+export interface Connection {
+  id: string
+  label: string
+  url: string
+  role?: ConnectionRole
+  description?: string
+}
+
+export interface Identity {
+  authenticated: boolean
+  username: string
+  role: string
+}
+
+export interface ActiveConnection {
+  connection: Connection
+  client: RedClient
+  rtt_ms: number
+}
+
+export interface ConnectionProvider {
+  list(): Promise<Connection[]>
+  connect(id: string): Promise<ActiveConnection>
+  whoami(): Promise<Identity>
+  /**
+   * The wire transports this provider can actually materialize on its Surface
+   * (#34, ADR-0003). The Connect UI offers only these, so the user never picks
+   * a transport that fails. Optional: a provider that omits it is treated as
+   * browser-reachable (http/https + coerced red://) by the consumer.
+   */
+  transports?(): Transport[]
+
+  /**
+   * Non-secret connection config seeded by the Surface (#36, ADR-0005) — the
+   * endpoint and initial view from the app URL. The Core reads it through this
+   * seam (not a special MCP branch) to connect without the Connect flow.
+   * Tokens never appear here. Returns null when nothing was seeded.
+   */
+  bootParams?(): BootParams | null
+}
+
+export class UnknownConnectionError extends Error {
+  constructor(public readonly id: string) {
+    super(`Unknown connection: ${id}`)
+    this.name = 'UnknownConnectionError'
+  }
+}
+
+export class NotConnectedError extends Error {
+  constructor() {
+    super('No active connection — call connect() first')
+    this.name = 'NotConnectedError'
+  }
+}
+
+export class UnreachableConnectionError extends Error {
+  constructor(public readonly id: string, public readonly reason: string) {
+    super(`Connection ${id} unreachable: ${reason}`)
+    this.name = 'UnreachableConnectionError'
+  }
+}

package/src/lib/reddb/index.ts

@@ -0,0 +1,14 @@
+export * from "./uri";
+export * from "./types";
+export * from "./client";
+export * from "./connection-provider";
+export * from "./local-url-provider";
+export * from "./injected-client-provider";
+export * from "./server-capabilities";
+export * from "./transports";
+export * from "./boot-params";
+export * from "./connection-bootstrap";
+export * from "./cdc-stream-client";
+export * from "./secure-store";
+export * from "./web-encrypted-store";
+export * from "./tauri-encrypted-store";

package/src/lib/reddb/injected-client-provider.ts

@@ -0,0 +1,76 @@
+// InjectedClientProvider — the embed-Surface implementation of
+// ConnectionProvider. The embedding host owns auth (ADR-0001 / ADR-0005): it
+// constructs and authenticates a RedClient, then hands it to the Core. The
+// Core stays agnostic — it acquires its client through the same
+// ConnectionProvider seam as the PWA/Desktop Surfaces, never knowing whether
+// the connection came from a Connect flow or from its host.
+//
+// Unlike LocalUrlProvider this is a *single-connection* provider: there is no
+// discovery, no history, no Connect flow. `list()` surfaces exactly one
+// connection and `connect()` returns the host-supplied client immediately. A
+// ping only measures RTT for the status bar — a failed probe does NOT block
+// the mount, because the host vouches for the client it injected.
+
+import type { RedClient } from './client'
+import {
+  NotConnectedError,
+  UnknownConnectionError,
+  type ActiveConnection,
+  type Connection,
+  type ConnectionProvider,
+  type Identity,
+} from './connection-provider'
+
+export interface InjectedClientOptions {
+  /** The host-supplied, already-authenticated client. */
+  client: RedClient
+  /** UI metadata for the single connection this provider exposes. */
+  connection?: Partial<Connection>
+}
+
+export class InjectedClientProvider implements ConnectionProvider {
+  private readonly client: RedClient
+  /** The sole connection this provider resolves. */
+  readonly connection: Connection
+  private connected = false
+
+  constructor(opts: InjectedClientOptions) {
+    this.client = opts.client
+    this.connection = {
+      id: opts.connection?.id ?? 'host',
+      label: opts.connection?.label ?? 'Host connection',
+      url: opts.connection?.url ?? '',
+      role: opts.connection?.role ?? 'primary',
+      description: opts.connection?.description ?? 'Injected by the embedding host.',
+    }
+  }
+
+  async list(): Promise<Connection[]> {
+    return [this.connection]
+  }
+
+  /**
+   * Resolve the single host connection. Any other id throws
+   * UnknownConnectionError — there is nothing else to connect to. The probe is
+   * best-effort: an unreachable host still yields an ActiveConnection (rtt 0)
+   * rather than rejecting, since the host owns the client's lifecycle.
+   */
+  async connect(id: string): Promise<ActiveConnection> {
+    if (id !== this.connection.id) throw new UnknownConnectionError(id)
+    let rtt_ms = 0
+    try {
+      const ping = await this.client.ping()
+      if (ping.ok) rtt_ms = ping.rtt_ms
+    } catch {
+      /* host vouches for the client — surface rtt 0, don't block the mount */
+    }
+    this.connected = true
+    return { connection: this.connection, client: this.client, rtt_ms }
+  }
+
+  async whoami(): Promise<Identity> {
+    if (!this.connected) throw new NotConnectedError()
+    const w = await this.client.whoami()
+    return { authenticated: w.authenticated, username: w.username, role: w.role }
+  }
+}