@reddb-io/ui 0.1.1

package/src/lib/query-tabs.svelte.ts

@@ -0,0 +1,130 @@
+// Per-query-tab state — keyed on tab id from the tabs store.
+//
+// Each query tab carries its own editor text, last result, error, and
+// running flag. Stored separately from the tabs store so the Tab type
+// stays a thin identity record and switching tabs preserves state.
+
+import type { QueryResult } from '#reddb'
+
+export interface QueryTabState {
+  sql: string
+  result: QueryResult | null
+  error: string | null
+  running: boolean
+}
+
+export type QueryExecutor = (sql: string) => Promise<QueryResult>
+
+function emptyState(): QueryTabState {
+  return { sql: '', result: null, error: null, running: false }
+}
+
+class QueryTabsStore {
+  /** Per-tab state keyed by tab id. */
+  states = $state<Record<string, QueryTabState>>({})
+  /** Monotonic counter for "Query N" labels — survives close so numbers don't reuse. */
+  private counter = 0
+  private executor: QueryExecutor | null = null
+
+  setExecutor(executor: QueryExecutor | null): void {
+    this.executor = executor
+  }
+
+  nextLabel(): string {
+    this.counter += 1
+    return `Query ${this.counter}`
+  }
+
+  ensure(id: string): QueryTabState {
+    if (!this.states[id]) this.states[id] = emptyState()
+    return this.states[id]
+  }
+
+  setSql(id: string, sql: string): void {
+    const s = this.ensure(id)
+    s.sql = sql
+  }
+
+  get(id: string): QueryTabState | undefined {
+    return this.states[id]
+  }
+
+  has(id: string): boolean {
+    return this.states[id] !== undefined
+  }
+
+  remove(id: string): void {
+    delete this.states[id]
+  }
+
+  /**
+   * Returns true when the tab has user-entered text (after trimming) that
+   * was not produced by a successful run. Used to gate the close
+   * confirmation.
+   */
+  isDirty(id: string): boolean {
+    const s = this.states[id]
+    if (!s) return false
+    return s.sql.trim().length > 0
+  }
+
+  /**
+   * Run the tab's current sql through the wired executor. Updates result,
+   * error, running, in place. Safe to call concurrently per tab — the
+   * running flag guards against re-entry.
+   */
+  async run(id: string): Promise<void> {
+    const s = this.ensure(id)
+    if (s.running) return
+    if (!this.executor) {
+      s.error = 'No connection — connect to a reddb instance first.'
+      s.result = null
+      return
+    }
+    const sql = s.sql.trim()
+    if (!sql) {
+      s.error = 'Empty query.'
+      s.result = null
+      return
+    }
+    s.running = true
+    s.error = null
+    try {
+      const r = await this.executor(sql)
+      s.result = r
+      s.error = r.ok ? null : (r.error ?? 'Query failed.')
+    } catch (e) {
+      s.error = (e as Error).message
+      s.result = null
+    } finally {
+      s.running = false
+    }
+  }
+
+  /** Test-only reset. */
+  clear(): void {
+    this.states = {}
+    this.counter = 0
+    this.executor = null
+  }
+}
+
+export const queryTabs = new QueryTabsStore()
+
+/**
+ * Derive a tab title from the SQL text. Defaults to `fallback` (e.g.
+ * "Query 3") when the SQL is empty or the SELECT clause is missing /
+ * trivial.
+ *
+ * Kept pure & exported for unit tests.
+ */
+export function deriveQueryLabel(sql: string, fallback: string, max = 24): string {
+  const trimmed = sql.trim()
+  if (!trimmed) return fallback
+  const match = trimmed.match(/^\s*select\s+([\s\S]+?)\s+from\b/i)
+  if (!match) return fallback
+  const clause = match[1].replace(/\s+/g, ' ').trim()
+  if (!clause || clause === '*') return fallback
+  if (clause.length <= max) return clause
+  return clause.slice(0, max - 1).trimEnd() + '…'
+}

package/src/lib/reddb/boot-params.ts

@@ -0,0 +1,254 @@
+// Open Contract URL pre-configuration. A Surface can seed the loaded Core with
+// a browser-reachable reddb endpoint (`cs`), an initial app route (`to`), and a
+// short-lived token carried only in the URL hash. The Core currently consumes
+// `cs` + `to` through ConnectionProvider.bootParams(); the token is parsed for
+// the public contract but is deliberately not persisted by this module.
+
+/** Parsed Open Contract from the app URL. */
+export interface OpenContract {
+  /** Browser-reachable reddb HTTP endpoint, e.g. `http://host:5055`. */
+  cs?: string;
+  /** Initial app route, e.g. `/cluster` or `/c/users/p/table`. */
+  to?: string;
+  /** Short-lived bearer token, read only from the URL hash. */
+  token?: string;
+}
+
+/** Non-secret connection config a Surface may seed via the app URL. */
+export interface BootParams {
+  /** reddb endpoint to connect to (e.g. `http://host:5055` or `red://host`). */
+  endpoint?: string;
+  /** Legacy initial top-level view: `query` | `collections` | `cluster` | `security`. */
+  view?: string;
+  /** Open Contract initial route, e.g. `/cluster` or `/c/users/p/table`. */
+  to?: string;
+}
+
+// Query keys that carry the endpoint (mirrors the legacy ?connection= reading).
+const ENDPOINT_KEYS = ["endpoint", "connection", "red_url", "red"];
+const VIEW_KEY = "view";
+const CS_KEY = "cs";
+const TO_KEY = "to";
+const TOKEN_KEY = "token";
+
+// Legacy query secrets are dropped. The Open Contract token is read from the
+// hash only, never from the query string.
+const SECRET_KEY =
+  /(token|secret|password|passwd|auth|credential|api[-_]?key|bearer)/i;
+
+export type OpenContractErrorCode =
+  | "EMPTY_CS"
+  | "FILESYSTEM_PATH"
+  | "MALFORMED_URL"
+  | "UNSUPPORTED_SCHEME"
+  | "SECRET_IN_CS"
+  | "MALFORMED_ROUTE";
+
+export class OpenContractError extends Error {
+  constructor(
+    public readonly code: OpenContractErrorCode,
+    message: string
+  ) {
+    super(message);
+    this.name = "OpenContractError";
+  }
+}
+
+function splitUrlParts(
+  input: string | URL,
+  explicitHash = ""
+): { search: string; hash: string } {
+  if (input instanceof URL) return { search: input.search, hash: input.hash };
+
+  const raw = input ?? "";
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    const url = new URL(raw);
+    return { search: url.search, hash: url.hash };
+  }
+
+  const hashAt = raw.indexOf("#");
+  const search = hashAt >= 0 ? raw.slice(0, hashAt) : raw;
+  const hash = hashAt >= 0 ? raw.slice(hashAt) : explicitHash;
+  return { search, hash };
+}
+
+function looksLikeFilesystemPath(value: string): boolean {
+  return (
+    /^file:/i.test(value) ||
+    /^~(?:\/|\\|$)/.test(value) ||
+    /^(?:\.{1,2})(?:\/|\\|$)/.test(value) ||
+    /^(?:\/|\\)/.test(value) ||
+    /^[a-z]:[\\/]/i.test(value) ||
+    value.includes("\\")
+  );
+}
+
+function normalizeCs(input: string): string {
+  const cs = input.trim().replace(/\/$/, "");
+  if (!cs) throw new OpenContractError("EMPTY_CS", "Open Contract cs is empty");
+  if (looksLikeFilesystemPath(cs)) {
+    throw new OpenContractError(
+      "FILESYSTEM_PATH",
+      "Open Contract cs must be a browser-reachable URL, not a filesystem path"
+    );
+  }
+
+  let url: URL;
+  try {
+    url = new URL(cs);
+  } catch {
+    throw new OpenContractError(
+      "MALFORMED_URL",
+      "Open Contract cs is not a valid URL"
+    );
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new OpenContractError(
+      "UNSUPPORTED_SCHEME",
+      "Open Contract cs must use http:// or https://"
+    );
+  }
+
+  for (const key of url.searchParams.keys()) {
+    if (SECRET_KEY.test(key)) {
+      throw new OpenContractError(
+        "SECRET_IN_CS",
+        "Open Contract secrets must be carried in the app URL hash, not inside cs"
+      );
+    }
+  }
+
+  return cs;
+}
+
+function normalizeRoute(input: string): string {
+  const to = input.trim();
+  if (!to)
+    throw new OpenContractError("MALFORMED_ROUTE", "Open Contract to is empty");
+  if (
+    /^[a-z][a-z0-9+.-]*:/i.test(to) ||
+    to.startsWith("//") ||
+    to.includes("\\")
+  ) {
+    throw new OpenContractError(
+      "MALFORMED_ROUTE",
+      "Open Contract to must be an app route"
+    );
+  }
+  const route = to.startsWith("/") ? to : `/${to}`;
+  if (
+    route === "/query" ||
+    route === "/collections" ||
+    route === "/cluster" ||
+    route === "/security" ||
+    route.startsWith("/c/")
+  ) {
+    return route;
+  }
+  throw new OpenContractError(
+    "MALFORMED_ROUTE",
+    "Open Contract to must target a known red-ui route"
+  );
+}
+
+/** Parse the public Open Contract (`cs`, `to`, `token`) from a URL/search/hash. */
+export function parseOpenContract(
+  input: string | URL,
+  explicitHash = ""
+): OpenContract {
+  const { search, hash } = splitUrlParts(input, explicitHash);
+  const query = new URLSearchParams(search);
+  const hashParams = new URLSearchParams(
+    hash.startsWith("#") ? hash.slice(1) : hash
+  );
+  const out: OpenContract = {};
+
+  const cs = query.get(CS_KEY);
+  if (cs !== null) out.cs = normalizeCs(cs);
+
+  const to = query.get(TO_KEY);
+  if (to !== null) out.to = normalizeRoute(to);
+
+  const token = hashParams.get(TOKEN_KEY);
+  if (token) out.token = token;
+
+  return out;
+}
+
+/** Encode the public Open Contract, carrying `token` only in the hash. */
+export function encodeOpenContract(contract: OpenContract): string {
+  const query = new URLSearchParams();
+  const hash = new URLSearchParams();
+
+  if (contract.cs) query.set(CS_KEY, normalizeCs(contract.cs));
+  if (contract.to) query.set(TO_KEY, normalizeRoute(contract.to));
+  if (contract.token) hash.set(TOKEN_KEY, contract.token);
+
+  const q = query.toString();
+  const h = hash.toString();
+  return `${q ? `?${q}` : ""}${h ? `#${h}` : ""}`;
+}
+
+/**
+ * Parse boot params from a URL query string (e.g. `location.search`). Returns
+ * only the non-secret endpoint + route/view. Query tokens are ignored; hash
+ * tokens remain part of the public Open Contract parser and are not surfaced to
+ * the provider boot params, so they cannot be persisted by the connection flow.
+ */
+export function parseBootParams(search: string, hash = ""): BootParams {
+  const params = new URLSearchParams(search ?? "");
+  const out: BootParams = {};
+
+  const cs = params.get(CS_KEY);
+  if (cs !== null) {
+    try {
+      out.endpoint = normalizeCs(cs);
+    } catch {
+      // Invalid Open Contract endpoints are rejected by omitting the endpoint;
+      // the full parser still throws for callers that need diagnostics.
+    }
+  }
+
+  const to = params.get(TO_KEY);
+  if (to !== null) {
+    try {
+      out.to = normalizeRoute(to);
+    } catch {
+      /* invalid route: ignore for boot */
+    }
+  }
+
+  for (const key of ENDPOINT_KEYS) {
+    if (out.endpoint) break;
+    const v = params.get(key);
+    if (v && !SECRET_KEY.test(key)) {
+      out.endpoint = v;
+      break;
+    }
+  }
+
+  const view = params.get(VIEW_KEY);
+  if (view) out.view = view;
+
+  // Read the token from hash to validate the contract source, but do not copy
+  // it into BootParams. This prevents accidental persistence via connection
+  // history while keeping parseOpenContract() available for the later bootstrap.
+  try {
+    void parseOpenContract(search, hash).token;
+  } catch {
+    /* contract diagnostics are for parseOpenContract callers */
+  }
+
+  return out;
+}
+
+/** True iff the boot params carry an endpoint to auto-connect to. */
+export function hasBootEndpoint(b: BootParams): boolean {
+  return typeof b.endpoint === "string" && b.endpoint.trim().length > 0;
+}
+
+/** True iff the boot params carry an initial app route. */
+export function hasBootRoute(b: BootParams): boolean {
+  return typeof b.to === "string" && b.to.trim().length > 0;
+}

package/src/lib/reddb/cdc-stream-client.ts

@@ -0,0 +1,234 @@
+import type { ChangeEvent, RedClient } from './client'
+
+export interface EventSourceLike {
+  close(): void
+  onmessage: ((ev: { data: string }) => void) | null
+  onerror: ((ev: unknown) => void) | null
+  onopen: ((ev: unknown) => void) | null
+}
+
+export type SseFactory = (url: string) => EventSourceLike
+
+export interface CDCStreamClientOptions {
+  /** Used for REST polling fallback (and SSE URL construction when baseUrl absent). */
+  client: Pick<RedClient, 'changes'> & { baseUrl?: string }
+  /** If null, SSE is disabled and REST polling is always used. */
+  sseFactory?: SseFactory | null
+  /**
+   * Called once before the first SSE attempt. If it resolves to false (or throws),
+   * SSE is considered unsupported and REST polling is used for this subscription.
+   * Default: returns true if sseFactory is provided.
+   */
+  sseProbe?: () => Promise<boolean>
+  /** Reconnect backoff schedule, in ms. Default: [1000, 2000, 4000, 8000, 30000]. */
+  backoffMs?: number[]
+  /** REST polling interval. Default: 1000ms. */
+  pollIntervalMs?: number
+  /** Test seam — defaults to globalThis.setTimeout / clearTimeout. */
+  timers?: {
+    setTimeout: (fn: () => void, ms: number) => unknown
+    clearTimeout: (h: unknown) => void
+  }
+}
+
+export interface SubscribeOpts {
+  collection?: string
+  sinceLsn?: number
+}
+
+export interface Subscription {
+  events: ReadableStream<ChangeEvent>
+  close(): void
+}
+
+const DEFAULT_BACKOFF = [1000, 2000, 4000, 8000, 30000]
+
+export class CDCStreamClient {
+  constructor(public readonly opts: CDCStreamClientOptions) {}
+
+  subscribe(opts: SubscribeOpts = {}): Subscription {
+    return new CDCSubscription(this, opts)
+  }
+
+  /** Build the SSE URL. Visible for tests. */
+  buildSseUrl(collection: string | undefined, sinceLsn: number): string {
+    const base = this.opts.client.baseUrl ?? ''
+    const params = new URLSearchParams()
+    if (sinceLsn > 0) params.set('since', String(sinceLsn))
+    if (collection) params.set('collection', collection)
+    const qs = params.toString()
+    return `${base}/changes/stream${qs ? `?${qs}` : ''}`
+  }
+}
+
+class CDCSubscription implements Subscription {
+  events: ReadableStream<ChangeEvent>
+  private controller!: ReadableStreamDefaultController<ChangeEvent>
+  private closed = false
+  private lastSeenLsn: number
+  private currentSse: EventSourceLike | null = null
+  private pollTimer: unknown = null
+  private reconnectTimer: unknown = null
+  private backoffIdx = 0
+  private transport: 'sse' | 'rest' | null = null
+
+  constructor(
+    private parent: CDCStreamClient,
+    private opts: SubscribeOpts,
+  ) {
+    this.lastSeenLsn = opts.sinceLsn ?? 0
+    this.events = new ReadableStream<ChangeEvent>({
+      start: (controller) => {
+        this.controller = controller
+      },
+      cancel: () => this.close(),
+    })
+    void this.connect()
+  }
+
+  private timers() {
+    return (
+      this.parent.opts.timers ?? {
+        setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+        clearTimeout: (h) => globalThis.clearTimeout(h as ReturnType<typeof globalThis.setTimeout>),
+      }
+    )
+  }
+
+  private async connect() {
+    if (this.closed) return
+    if (this.transport === null) {
+      // First connect — choose transport.
+      const factory = this.parent.opts.sseFactory
+      if (factory === null || factory === undefined) {
+        this.transport = 'rest'
+      } else {
+        const probe = this.parent.opts.sseProbe ?? (async () => true)
+        let supported = false
+        try {
+          supported = await probe()
+        } catch {
+          supported = false
+        }
+        if (this.closed) return
+        this.transport = supported ? 'sse' : 'rest'
+      }
+    }
+
+    if (this.transport === 'sse') this.startSse()
+    else this.startRest()
+  }
+
+  private startSse() {
+    const factory = this.parent.opts.sseFactory
+    if (!factory) {
+      this.transport = 'rest'
+      this.startRest()
+      return
+    }
+    const url = this.parent.buildSseUrl(this.opts.collection, this.lastSeenLsn)
+    let es: EventSourceLike
+    try {
+      es = factory(url)
+    } catch {
+      this.scheduleReconnect()
+      return
+    }
+    this.currentSse = es
+    es.onopen = () => {
+      this.backoffIdx = 0
+    }
+    es.onmessage = (ev) => {
+      try {
+        const data = JSON.parse(ev.data) as ChangeEvent
+        this.emit(data)
+      } catch {
+        // ignore malformed payloads
+      }
+    }
+    es.onerror = () => {
+      if (this.closed) return
+      try {
+        es.close()
+      } catch {
+        // ignore
+      }
+      if (this.currentSse === es) this.currentSse = null
+      this.scheduleReconnect()
+    }
+  }
+
+  private startRest() {
+    const tick = async () => {
+      if (this.closed) return
+      try {
+        const events = this.opts.collection
+          ? await this.parent.opts.client.changes(this.lastSeenLsn, { collection: this.opts.collection })
+          : await this.parent.opts.client.changes(this.lastSeenLsn)
+        if (this.closed) return
+        for (const e of events) this.emit(e)
+        this.backoffIdx = 0
+        const interval = this.parent.opts.pollIntervalMs ?? 1000
+        this.pollTimer = this.timers().setTimeout(() => {
+          this.pollTimer = null
+          void tick()
+        }, interval)
+      } catch {
+        if (this.closed) return
+        this.scheduleReconnect()
+      }
+    }
+    void tick()
+  }
+
+  private emit(e: ChangeEvent) {
+    if (this.closed) return
+    if (e.lsn <= this.lastSeenLsn) return
+    this.lastSeenLsn = e.lsn
+    try {
+      this.controller.enqueue(e)
+    } catch {
+      // stream may have been cancelled — close ourselves.
+      this.close()
+    }
+  }
+
+  private scheduleReconnect() {
+    if (this.closed) return
+    const delays = this.parent.opts.backoffMs ?? DEFAULT_BACKOFF
+    const delay = delays[Math.min(this.backoffIdx, delays.length - 1)]
+    this.backoffIdx++
+    this.reconnectTimer = this.timers().setTimeout(() => {
+      this.reconnectTimer = null
+      if (this.transport === 'sse') this.startSse()
+      else this.startRest()
+    }, delay)
+  }
+
+  close() {
+    if (this.closed) return
+    this.closed = true
+    if (this.currentSse) {
+      try {
+        this.currentSse.close()
+      } catch {
+        // ignore
+      }
+      this.currentSse = null
+    }
+    const { clearTimeout } = this.timers()
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer)
+      this.pollTimer = null
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+    try {
+      this.controller.close()
+    } catch {
+      // already closed
+    }
+  }
+}