broapp 0.1.0

package/src/host/app.ts

@@ -0,0 +1,283 @@
+/**
+ * The host side of a contract.
+ *
+ * `createHostApp(contract)` returns a registry a developer fills in, and
+ * `mount()` hands the result to a Brobridge bridge. The layer is thin by
+ * design: it validates input, draws the error boundary, frames stream events,
+ * and turns cancellation into an `AbortSignal`. Transport, authentication and
+ * session handling stay entirely in Brobridge.
+ *
+ * Where to add an operation: declare it in the shared contract, then call
+ * `app.operation(name, handler)` here. The compiler will not let those two
+ * drift.
+ */
+import type { Bridge, StreamContext } from 'brobridge';
+import type { BridgeStream } from '@brobridgejs/core';
+
+import type {
+  AnyContract,
+  OperationInput,
+  OperationName,
+  OperationOutput,
+  StreamEvent,
+  StreamName,
+  StreamParams,
+} from '../shared/contract.ts';
+import { splitRoute } from '../shared/contract.ts';
+import { PublicError } from '../shared/errors.ts';
+import { encodeEvent } from '../shared/ndjson.ts';
+import { ValidationError } from '../shared/schema.ts';
+
+/**
+ * What an operation handler is told about its caller.
+ *
+ * There is no session identifier here. Brobridge passes a session id to
+ * *stream* handlers (`StreamContext`) but not to the methods of an exposed
+ * service, and Broapp does not invent one. Every call has nonetheless already
+ * passed Brobridge's trust fence and cookie check before a handler runs; the
+ * missing piece is only *which* authenticated tab called, which a v1 starter
+ * has no use for. An application that needs it should use a stream.
+ */
+export interface CallContext {
+  /** The route name, for logging. */
+  readonly route: string;
+}
+
+/** A unary operation implementation. */
+export type OperationHandler<C extends AnyContract, K extends OperationName<C>> = (
+  input: OperationInput<C, K>,
+  context: CallContext,
+) => OperationOutput<C, K> | Promise<OperationOutput<C, K>>;
+
+/** What a stream handler is given to talk back with. */
+export interface StreamSink<E> {
+  /**
+   * Send one event.
+   *
+   * Awaiting it is what applies backpressure: the promise settles when
+   * Brobridge's flow control has room, so a browser that stops reading slows
+   * the producer instead of filling a buffer. It rejects once the stream has
+   * ended, which includes the browser cancelling.
+   */
+  emit(event: E): Promise<void>;
+  /** Aborted when the browser cancels, the tab disconnects, or the host shuts down. */
+  readonly signal: AbortSignal;
+  /** The authenticated Brobridge session this stream belongs to. */
+  readonly sessionId: string;
+}
+
+/** A stream implementation. Returning ends the stream cleanly. */
+export type StreamHandlerFor<C extends AnyContract, K extends StreamName<C>> = (
+  params: StreamParams<C, K>,
+  sink: StreamSink<StreamEvent<C, K>>,
+) => void | Promise<void>;
+
+/** Diagnostics sink. Defaults to `console`. */
+export interface HostLogger {
+  warn(message: string): void;
+  error(message: string): void;
+}
+
+/** Options for {@link createHostApp}. */
+export interface HostAppOptions {
+  readonly logger?: HostLogger;
+}
+
+/** A contract with implementations attached, ready to mount on a bridge. */
+export interface HostApp<C extends AnyContract> {
+  /** Implement one operation from the contract. */
+  operation<K extends OperationName<C>>(name: K, handler: OperationHandler<C, K>): HostApp<C>;
+  /** Implement one stream from the contract. */
+  stream<K extends StreamName<C>>(name: K, handler: StreamHandlerFor<C, K>): HostApp<C>;
+  /**
+   * Register everything with a bridge.
+   *
+   * Throws when the contract declares a route no handler implements: a route
+   * that answers `NOT_FOUND` at runtime is a shipped bug, and startup is when
+   * a developer is present to see it.
+   */
+  mount(bridge: Bridge): void;
+  /** Abort every stream this app currently has open. Called during shutdown. */
+  abortAll(reason: string): void;
+  /** How many streams are running right now. */
+  readonly activeStreams: number;
+}
+
+/** Build the host side of a contract. */
+export function createHostApp<C extends AnyContract>(
+  contract: C,
+  options: HostAppOptions = {},
+): HostApp<C> {
+  const logger: HostLogger = options.logger ?? console;
+  const operations = new Map<string, OperationHandler<C, never>>();
+  const streams = new Map<string, StreamHandlerFor<C, never>>();
+  const running = new Set<AbortController>();
+
+  function known(kind: 'operation' | 'stream', name: string): void {
+    const table = kind === 'operation' ? contract.operations : contract.streams;
+    if (!Object.prototype.hasOwnProperty.call(table, name)) {
+      throw new TypeError(`${kind} ${JSON.stringify(name)} is not declared in the contract`);
+    }
+  }
+
+  const app: HostApp<C> = {
+    operation(name, handler) {
+      known('operation', name);
+      if (operations.has(name)) throw new TypeError(`operation ${JSON.stringify(name)} is already implemented`);
+      operations.set(name, handler as OperationHandler<C, never>);
+      return app;
+    },
+
+    stream(name, handler) {
+      known('stream', name);
+      if (streams.has(name)) throw new TypeError(`stream ${JSON.stringify(name)} is already implemented`);
+      streams.set(name, handler as StreamHandlerFor<C, never>);
+      return app;
+    },
+
+    get activeStreams() {
+      return running.size;
+    },
+
+    abortAll(reason) {
+      for (const controller of running) controller.abort(new Error(reason));
+    },
+
+    mount(bridge) {
+      const missing = [
+        ...contract.routes.operations.filter((route) => !operations.has(route)),
+        ...contract.routes.streams.filter((route) => !streams.has(route)),
+      ];
+      if (missing.length > 0) {
+        throw new TypeError(`contract routes have no implementation: ${missing.join(', ')}`);
+      }
+
+      // Brobridge exposes a *service object* per group, so the contract's
+      // dotted routes are collected back into groups here. This is the only
+      // place the two namings meet.
+      const groups = new Map<string, Record<string, unknown>>();
+      for (const [route, handler] of operations) {
+        const { group, member } = splitRoute(route);
+        const spec = contract.operations[route];
+        if (spec === undefined) continue;
+        const service = groups.get(group) ?? {};
+        service[member] = async (raw: unknown): Promise<unknown> => {
+          const context: CallContext = { route };
+          let input: unknown;
+          try {
+            input = spec.input.parse(raw);
+          } catch (cause) {
+            // A validation message names a field and a constraint from the
+            // contract the browser already has. It carries nothing the caller
+            // did not send, so it is safe to return and useful to see.
+            throw new PublicError(
+              'invalid_input',
+              cause instanceof ValidationError ? cause.message : 'invalid input',
+            ).toBridgeError();
+          }
+          try {
+            const output = await (handler as OperationHandler<C, never>)(
+              input as never,
+              context,
+            );
+            return spec.output.parse(output);
+          } catch (cause) {
+            throw wrap(cause, route, logger);
+          }
+        };
+        groups.set(group, service);
+      }
+      for (const [group, service] of groups) bridge.expose(group, service);
+
+      for (const [route, handler] of streams) {
+        const spec = contract.streams[route];
+        if (spec === undefined) continue;
+        bridge.stream(route, (stream: BridgeStream, streamContext: StreamContext) =>
+          runStream(stream, streamContext, route, spec, handler, running, logger),
+        );
+      }
+    },
+  };
+
+  return app;
+}
+
+/**
+ * Reduce a handler failure to something safe to send.
+ *
+ * A `PublicError` was written for the browser and keeps its message. Anything
+ * else is logged here — with its stack, on the host, where it belongs — and
+ * rethrown unchanged so Brobridge applies its own reduction to `"internal
+ * error"`. Broapp does not need to redact it a second time and must not
+ * accidentally undo the reduction by wrapping the message.
+ */
+function wrap(cause: unknown, route: string, logger: HostLogger): unknown {
+  if (cause instanceof PublicError) return cause.toBridgeError();
+  logger.error(`[broapp] ${route} failed: ${String(cause instanceof Error ? cause.stack ?? cause.message : cause)}`);
+  return cause;
+}
+
+/**
+ * Run one stream handler.
+ *
+ * Cancellation is the part worth reading. Brobridge's `BridgeStream.cancel()`
+ * on the browser side sends a `CANCEL` frame; the host's stream then fails
+ * with a `CANCELLED` `StreamError`, which shows up here as `stream.closed`
+ * rejecting. That rejection is the *only* reliable cancellation signal — a
+ * browser that merely stops iterating sends nothing, and a `for await` loop
+ * that a consumer breaks out of does not cancel the underlying stream. So the
+ * signal is wired from `stream.closed`, and the same `AbortController` is
+ * aborted on shutdown.
+ */
+async function runStream<E>(
+  stream: BridgeStream,
+  streamContext: StreamContext,
+  route: string,
+  spec: { params: { parse(value: unknown): unknown }; event: { parse(value: unknown): unknown } },
+  handler: (params: never, sink: StreamSink<E>) => void | Promise<void>,
+  running: Set<AbortController>,
+  logger: HostLogger,
+): Promise<void> {
+  const controller = new AbortController();
+  running.add(controller);
+
+  // `closed` rejects on cancellation and on a torn-down connection, and
+  // resolves on a clean end. Either way the handler must stop.
+  stream.closed.then(
+    () => controller.abort(new Error('stream closed')),
+    (cause: unknown) => controller.abort(cause),
+  );
+
+  let params: unknown;
+  try {
+    params = spec.params.parse(streamContext.params);
+  } catch (cause) {
+    running.delete(controller);
+    throw new PublicError(
+      'invalid_input',
+      cause instanceof ValidationError ? cause.message : 'invalid stream parameters',
+    ).toBridgeError();
+  }
+
+  const sink: StreamSink<E> = {
+    signal: controller.signal,
+    sessionId: streamContext.sessionId,
+    async emit(event: E): Promise<void> {
+      if (controller.signal.aborted) throw new Error('stream is no longer open');
+      await stream.write(encodeEvent(spec.event.parse(event)));
+    },
+  };
+
+  try {
+    await handler(params as never, sink);
+    if (!controller.signal.aborted) await stream.end();
+  } catch (cause) {
+    // A cancelled stream is not a fault: the browser asked for it, the stream
+    // is already gone, and there is nothing to report.
+    if (controller.signal.aborted) return;
+    throw wrap(cause, route, logger);
+  } finally {
+    running.delete(controller);
+    controller.abort(new Error('handler finished'));
+  }
+}

package/src/host/index.ts

@@ -0,0 +1,25 @@
+/**
+ * `broapp/host` — the host runtime.
+ *
+ * Never import this from browser code. It pulls in `node:fs`, `node:os` and
+ * `Bun.spawn`, none of which exist in a browser, and a bundler that follows
+ * the import would fail loudly — which is the intended outcome.
+ */
+export { createHostApp } from './app.ts';
+export type {
+  CallContext,
+  HostApp,
+  HostAppOptions,
+  HostLogger,
+  OperationHandler,
+  StreamHandlerFor,
+  StreamSink,
+} from './app.ts';
+
+export { startApp } from './runtime.ts';
+export type { LifecycleMode, RunningApp, ShutdownReason, StartAppOptions } from './runtime.ts';
+
+export { dataDir, ensureDataDir, DATA_DIR_ENV } from './paths.ts';
+export { openBrowser } from './open-browser.ts';
+
+export { PublicError, publicError } from '../shared/errors.ts';

package/src/host/open-browser.ts

@@ -0,0 +1,45 @@
+/**
+ * Opening the user's browser.
+ *
+ * Brobridge does not launch browsers — deliberately, since a launcher is
+ * policy, not protocol — so Broapp supplies one. It is the same
+ * platform-handler call every tool of this shape makes.
+ *
+ * The URL carries a one-time launch token. It is passed as a separate `argv`
+ * element to a directly spawned executable, never through a shell, so nothing
+ * in it can be interpreted as a command and nothing lands in a shell history.
+ */
+
+/** Which command opens a URL on this platform. */
+function launcher(url: string): string[] | null {
+  switch (process.platform) {
+    case 'darwin':
+      return ['open', url];
+    case 'win32':
+      // `start` is a `cmd` builtin, so `cmd /c` is unavoidable here. The empty
+      // string is `start`'s title argument: without it `start` would read a
+      // quoted URL as the window title and open nothing.
+      return ['cmd', '/c', 'start', '', url];
+    case 'linux':
+    case 'freebsd':
+    case 'openbsd':
+      return ['xdg-open', url];
+    default:
+      return null;
+  }
+}
+
+/**
+ * Try to open `url`. Resolves `false` when no browser could be launched — the
+ * caller is expected to have already printed the URL for manual use.
+ */
+export async function openBrowser(url: string): Promise<boolean> {
+  const argv = launcher(url);
+  if (argv === null) return false;
+  try {
+    const child = Bun.spawn(argv, { stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+    return (await child.exited) === 0;
+  } catch {
+    return false;
+  }
+}

package/src/host/paths.ts

@@ -0,0 +1,53 @@
+/**
+ * Where a compiled Broapp application keeps its data.
+ *
+ * A single-file executable may sit in `/usr/local/bin`, in a read-only
+ * `/Applications` bundle, or on a share. Writing next to it is therefore not
+ * an option, and neither is writing to the working directory — the same
+ * executable run from two directories would find two different databases.
+ * Broapp resolves one per-user location per application, up front, and hands
+ * it to the application.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+
+/** The environment variable that overrides the resolved directory. */
+export const DATA_DIR_ENV = 'BROAPP_DATA_DIR';
+
+/**
+ * The per-user data directory for `appName`.
+ *
+ * Resolution order:
+ *
+ * 1. `BROAPP_DATA_DIR`, used verbatim — for tests, for portable installs, and
+ *    for a user who keeps application data on another volume.
+ * 2. The platform convention: `%APPDATA%` on Windows,
+ *    `~/Library/Application Support` on macOS, and `$XDG_DATA_HOME` or
+ *    `~/.local/share` elsewhere.
+ *
+ * The directory is not created here. {@link ensureDataDir} does that, so a
+ * `--data-dir`-style diagnostic can print the path without a side effect.
+ */
+export function dataDir(appName: string, env: NodeJS.ProcessEnv = process.env): string {
+  const override = env[DATA_DIR_ENV];
+  if (override !== undefined && override !== '') return override;
+
+  const platform = process.platform;
+  if (platform === 'win32') {
+    const base = env['APPDATA'] ?? join(homedir(), 'AppData', 'Roaming');
+    return join(base, appName);
+  }
+  if (platform === 'darwin') {
+    return join(homedir(), 'Library', 'Application Support', appName);
+  }
+  const base = env['XDG_DATA_HOME'] ?? join(homedir(), '.local', 'share');
+  return join(base, appName);
+}
+
+/** Resolve the data directory and create it, including parents. */
+export function ensureDataDir(appName: string, env: NodeJS.ProcessEnv = process.env): string {
+  const directory = dataDir(appName, env);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  return directory;
+}

package/src/host/runtime.ts

@@ -0,0 +1,198 @@
+/**
+ * Starting, supervising and stopping a Broapp application.
+ *
+ * This is the lifecycle the spec calls for, made explicit. Two modes:
+ *
+ * - `interactive` (the default) — the process exists to serve a browser tab.
+ *   When the last tab has been gone for `idleGraceMs` and no work is running,
+ *   the process exits. A launch that no browser ever reaches gives up after
+ *   `launchTimeoutMs` with a nonzero status, so a broken launcher fails
+ *   loudly instead of leaving a listener behind forever.
+ *
+ * - `background` — the process keeps running when the UI closes, and is
+ *   stopped by `Ctrl+C`, `SIGTERM`, or whatever supervises it. It is an
+ *   ordinary foreground process; Broapp does not daemonise and does not
+ *   install a service.
+ *
+ * "Attached" is not the same as "session exists". Brobridge retains a session
+ * after its socket drops so a reconnecting tab can resume, so counting
+ * `bridge.sessions` would keep the process alive for a minute after the last
+ * tab closed. Attachment is `endpoint.state === "open"`, which is what a live
+ * connection actually looks like.
+ */
+import type { Bridge, BridgeOptions } from 'brobridge';
+import { createBridge } from 'brobridge';
+
+import { openBrowser } from './open-browser.ts';
+
+/** Which lifecycle policy the application follows. */
+export type LifecycleMode = 'interactive' | 'background';
+
+/** Options for {@link startApp}. */
+export interface StartAppOptions {
+  /** The complete, self-contained HTML document served at `/`. */
+  readonly page: string;
+  /** Human-readable application name, used in banner output. */
+  readonly appName: string;
+  /** Application version, used in banner output. */
+  readonly version: string;
+  /** Register routes on the bridge. Called once, before the browser is opened. */
+  readonly register: (bridge: Bridge) => void | Promise<void>;
+  /** Default `"interactive"`. */
+  readonly mode?: LifecycleMode;
+  /** Open the browser at startup. Default `true`. */
+  readonly openBrowser?: boolean;
+  /** Interactive mode: how long with no attached tab before exiting. Default 20 000 ms. */
+  readonly idleGraceMs?: number;
+  /** Interactive mode: how long to wait for the first tab. Default 120 000 ms. */
+  readonly launchTimeoutMs?: number;
+  /** True while work is running that must not be discarded by an idle exit. */
+  readonly isBusy?: () => boolean;
+  /** Run before the bridge closes: flush, checkpoint, close a database. */
+  readonly onShutdown?: (reason: ShutdownReason) => void | Promise<void>;
+  /** Passed through to Brobridge. Loopback binding and auth are not overridable here. */
+  readonly bridge?: Omit<BridgeOptions, 'index' | 'allowNonLoopback' | 'host'>;
+  /** Where banner output goes. Default `console`. */
+  readonly stdout?: { log(message: string): void };
+}
+
+/** Why the application is stopping. */
+export type ShutdownReason = 'signal' | 'idle' | 'never-connected' | 'requested';
+
+/** A running application. */
+export interface RunningApp {
+  readonly bridge: Bridge;
+  /** Resolves with the intended process exit code when the application stops. */
+  readonly done: Promise<number>;
+  /** Stop it. Safe to call more than once. */
+  stop(reason?: ShutdownReason): Promise<void>;
+}
+
+const POLL_INTERVAL_MS = 1_000;
+
+/**
+ * Start an application.
+ *
+ * Binds loopback on an ephemeral port — `allowNonLoopback` is deliberately not
+ * forwarded, so a starter cannot grow LAN exposure through a config typo.
+ */
+export async function startApp(options: StartAppOptions): Promise<RunningApp> {
+  const out = options.stdout ?? console;
+  const mode: LifecycleMode = options.mode ?? 'interactive';
+  const idleGraceMs = options.idleGraceMs ?? 20_000;
+  const launchTimeoutMs = options.launchTimeoutMs ?? 120_000;
+
+  // Attachment is recorded from Brobridge's own session hook rather than by
+  // polling. A tab that connects and closes inside one poll interval — a
+  // reload, a quick script, a test — would otherwise never be *seen* to have
+  // attached, and interactive mode would then treat the run as "no browser
+  // ever connected" and exit with a failure status.
+  let everAttached = false;
+  const bridge = await createBridge({
+    ...options.bridge,
+    index: { body: options.page, contentType: 'text/html; charset=utf-8' },
+    onSession: (session) => {
+      everAttached = true;
+      options.bridge?.onSession?.(session);
+    },
+  });
+
+  try {
+    await options.register(bridge);
+  } catch (cause) {
+    await bridge.close();
+    throw cause;
+  }
+
+  let settle: (code: number) => void = () => undefined;
+  const done = new Promise<number>((resolve) => {
+    settle = resolve;
+  });
+
+  let stopping: Promise<void> | null = null;
+  let poll: ReturnType<typeof setInterval> | null = null;
+
+  const stop = (reason: ShutdownReason = 'requested'): Promise<void> => {
+    if (stopping !== null) return stopping;
+    stopping = (async () => {
+      if (poll !== null) clearInterval(poll);
+      process.off('SIGINT', onSigint);
+      process.off('SIGTERM', onSigterm);
+      try {
+        await options.onShutdown?.(reason);
+      } catch (cause) {
+        out.log(`shutdown hook failed: ${String(cause instanceof Error ? cause.message : cause)}`);
+      }
+      // `close()` sends GOAWAY, ends open streams, then releases the listener.
+      // Handlers observe that as their stream aborting, which is the same path
+      // a browser-side cancel takes.
+      await bridge.close();
+      settle(reason === 'never-connected' ? 1 : 0);
+    })();
+    return stopping;
+  };
+
+  const onSigint = (): void => {
+    out.log('');
+    void stop('signal');
+  };
+  const onSigterm = (): void => void stop('signal');
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+
+  // The launch URL carries a one-time token and is a credential until it is
+  // redeemed. It is written to the terminal on purpose, because a user whose
+  // browser did not open needs it — and to the terminal only. Nothing here
+  // puts it in a log file, and Brobridge sets `Referrer-Policy: no-referrer`
+  // and `Cache-Control: no-store` so the browser does not persist it either.
+  out.log(`${options.appName} v${options.version}`);
+  out.log(`Open this address if your browser does not: ${bridge.url}`);
+  out.log(
+    mode === 'interactive'
+      ? 'Close the tab to quit, or press Ctrl+C.'
+      : 'Running in the background. Press Ctrl+C to quit.',
+  );
+
+  if (options.openBrowser !== false) {
+    void openBrowser(bridge.url).then((opened) => {
+      if (!opened) out.log('Could not open a browser automatically. Use the address above.');
+    });
+  }
+
+  if (mode === 'interactive') {
+    const startedAt = Date.now();
+    let idleSince: number | null = null;
+
+    poll = setInterval(() => {
+      const attached = bridge.sessions.some((session) => session.endpoint.state === 'open');
+      const now = Date.now();
+
+      if (attached) {
+        idleSince = null;
+        return;
+      }
+      if (!everAttached) {
+        if (now - startedAt >= launchTimeoutMs) {
+          out.log('No browser ever connected. Stopping.');
+          void stop('never-connected');
+        }
+        return;
+      }
+      // Work in flight outranks the idle timer: exiting here would discard it
+      // silently, which is the one thing the grace period is meant to prevent.
+      if (options.isBusy?.() === true) {
+        idleSince = null;
+        return;
+      }
+      idleSince ??= now;
+      if (now - idleSince >= idleGraceMs) {
+        out.log('Browser closed. Stopping.');
+        void stop('idle');
+      }
+    }, POLL_INTERVAL_MS);
+    // Do not let the poll timer alone hold the event loop open.
+    poll.unref?.();
+  }
+
+  return { bridge, done, stop };
+}