broapp 0.1.0

package/src/react/hooks.tsx

@@ -0,0 +1,389 @@
+/**
+ * React bindings.
+ *
+ * Deliberately small: a provider that owns the connection, a hook that reads
+ * it, a hook for one operation call, and a hook for one stream subscription.
+ * Everything here is a convenience over `createClient`; nothing in Broapp
+ * requires React, and a template that wanted Svelte would replace this file
+ * and keep the rest.
+ *
+ * The connection lifecycle is the part that is easy to get wrong, so it is
+ * handled once here: connect on mount, expose an honest state, and — the
+ * important one — cancel every live stream when a component unmounts, because
+ * dropping a subscription does not stop the host.
+ */
+import * as React from 'react';
+
+import type {
+  AnyContract,
+  OperationInput,
+  OperationName,
+  OperationOutput,
+  StreamEvent,
+  StreamName,
+  StreamParams,
+} from '../shared/contract.ts';
+import { BroappError } from '../shared/errors.ts';
+import type { BridgeState, BroappClient, CreateClientOptions, Subscription } from '../client/client.ts';
+import { createClient } from '../client/client.ts';
+
+/** How the application should render its connection. */
+export type ConnectionStatus =
+  | { readonly phase: 'connecting' }
+  /** Connected and usable. */
+  | { readonly phase: 'ready'; readonly transport: BridgeState }
+  /**
+   * The socket dropped and is being re-established; live streams will resume.
+   *
+   * `since` is when the connection was lost, and `resumable` says whether a
+   * successful reconnect could still restore live streams. Brobridge retains a
+   * protocol session for `sessionTtlMs` after the last disconnect (60 seconds
+   * by default); past that the session has been reaped and a reconnect starts
+   * a fresh one. This is not an invented timeout — it is the host's documented
+   * retention window, and it is the honest point at which an interface should
+   * stop implying that work in progress is coming back.
+   *
+   * Note what it does *not* tell you: whether the host is still running. A
+   * client cannot distinguish a host that died from one that is slow, so the
+   * state stays `reconnecting` and the retries continue.
+   */
+  | { readonly phase: 'reconnecting'; readonly since: number; readonly resumable: boolean }
+  /**
+   * The connection is gone for good. In a local application the usual cause is
+   * that the host process exited — which also destroys the session, so there
+   * is nothing to reconnect to and the honest instruction is "start it again".
+   */
+  | { readonly phase: 'lost' }
+  /** The first connection never succeeded. */
+  | { readonly phase: 'failed'; readonly error: BroappError };
+
+interface ContextValue<C extends AnyContract> {
+  /** The connected client, once there is one. */
+  readonly client: BroappClient<C> | null;
+  /**
+   * The client as a promise, resolved by the same connection attempt.
+   *
+   * `client` is null for the second or so between the first render and the
+   * connection settling — and a user can click a button inside that window.
+   * Failing those clicks with "not connected yet" is technically true and
+   * useless: the application is starting, not broken. So the hooks await this
+   * instead, and a genuinely failed connection surfaces as this promise
+   * rejecting, which is a real error worth showing.
+   */
+  readonly ready: Promise<BroappClient<C>>;
+  readonly status: ConnectionStatus;
+}
+
+const BroappContext = React.createContext<ContextValue<AnyContract> | null>(null);
+
+/** Props for {@link BroappProvider}. */
+export interface BroappProviderProps<C extends AnyContract> {
+  readonly contract: C;
+  readonly options?: CreateClientOptions;
+  /**
+   * How long the host retains a protocol session after a disconnect. Must
+   * match the host's `sessionTtlMs`; the default is Brobridge's own default.
+   * Used only to decide when `reconnecting` stops being `resumable`.
+   */
+  readonly sessionTtlMs?: number;
+  readonly children: React.ReactNode;
+}
+
+function toStatus(state: BridgeState, since: number, now: number, ttlMs: number): ConnectionStatus {
+  switch (state) {
+    case 'open':
+    case 'degraded':
+      return { phase: 'ready', transport: state };
+    case 'connecting':
+      return { phase: 'connecting' };
+    case 'resuming':
+      return { phase: 'reconnecting', since, resumable: now - since < ttlMs };
+    case 'closed':
+      return { phase: 'lost' };
+  }
+}
+
+/** Owns the connection for everything below it. */
+export function BroappProvider<C extends AnyContract>({
+  contract,
+  options,
+  sessionTtlMs = 60_000,
+  children,
+}: BroappProviderProps<C>): React.ReactElement {
+  const [client, setClient] = React.useState<BroappClient<C> | null>(null);
+  const [status, setStatus] = React.useState<ConnectionStatus>({ phase: 'connecting' });
+  // Created before the effect runs, so the very first render already has
+  // something for a hook to await.
+  const gate = React.useRef<{
+    promise: Promise<BroappClient<C>>;
+    resolve: (client: BroappClient<C>) => void;
+    reject: (cause: unknown) => void;
+  } | null>(null);
+  if (gate.current === null) {
+    let resolve!: (client: BroappClient<C>) => void;
+    let reject!: (cause: unknown) => void;
+    const promise = new Promise<BroappClient<C>>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    // Nothing may await this before a hook does, and an unobserved rejection
+    // would otherwise be reported as unhandled.
+    promise.catch(() => undefined);
+    gate.current = { promise, resolve, reject };
+  }
+  const ready = gate.current.promise;
+
+  React.useEffect(() => {
+    let live = true;
+    let connected: BroappClient<C> | null = null;
+    let unsubscribe: (() => void) | undefined;
+    let lostAt = Date.now();
+    // While reconnecting, the state stops changing but the *meaning* of it
+    // does, so the status is refreshed on a slow tick rather than only on a
+    // transport event.
+    let tick: ReturnType<typeof setInterval> | undefined;
+
+    void createClient(contract, options).then(
+      (next) => {
+        if (!live) {
+          void next.close();
+          return;
+        }
+        connected = next;
+        gate.current?.resolve(next);
+        setClient(next);
+        setStatus(toStatus(next.state, lostAt, Date.now(), sessionTtlMs));
+        unsubscribe = next.onState((state) => {
+          if (state === 'resuming' || state === 'connecting') {
+            // Only the first transition away from `open` starts the clock.
+            if (connected?.state === 'open') lostAt = Date.now();
+          } else {
+            lostAt = Date.now();
+          }
+          setStatus(toStatus(state, lostAt, Date.now(), sessionTtlMs));
+        });
+        tick = setInterval(() => {
+          const current = connected;
+          if (current === null) return;
+          setStatus(toStatus(current.state, lostAt, Date.now(), sessionTtlMs));
+        }, 2_000);
+      },
+      (cause: unknown) => {
+        const error =
+          cause instanceof BroappError
+            ? cause
+            : new BroappError('unavailable', 'Could not reach the application host.', cause);
+        gate.current?.reject(error);
+        if (!live) return;
+        setStatus({ phase: 'failed', error });
+      },
+    );
+
+    return () => {
+      live = false;
+      if (tick !== undefined) clearInterval(tick);
+      unsubscribe?.();
+      void connected?.close();
+    };
+    // The contract is a module-level constant and the options object is
+    // expected to be stable; re-running this effect would drop the connection.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const value = React.useMemo<ContextValue<C>>(
+    () => ({ client, ready, status }),
+    [client, ready, status],
+  );
+  return (
+    <BroappContext.Provider value={value as ContextValue<AnyContract>}>
+      {children}
+    </BroappContext.Provider>
+  );
+}
+
+function useContextValue<C extends AnyContract>(): ContextValue<C> {
+  const value = React.useContext(BroappContext);
+  if (value === null) throw new Error('useBroapp must be used inside <BroappProvider>');
+  return value as ContextValue<C>;
+}
+
+/** The connection status, for a status indicator. */
+export function useConnection(): ConnectionStatus {
+  return useContextValue().status;
+}
+
+/** The client, or `null` until the first connection settles. */
+export function useBroapp<C extends AnyContract>(): BroappClient<C> | null {
+  return useContextValue<C>().client;
+}
+
+/**
+ * The client as a promise.
+ *
+ * Resolves once connected, rejects if the first connection fails. Useful for
+ * code outside a hook that must not care whether startup has finished.
+ */
+export function useBroappReady<C extends AnyContract>(): Promise<BroappClient<C>> {
+  return useContextValue<C>().ready;
+}
+
+/** What {@link useOperation} returns. */
+export interface OperationHook<C extends AnyContract, K extends OperationName<C>> {
+  /** Run it. Never rejects; the outcome lands in `data` or `error`. */
+  run(input: OperationInput<C, K>): Promise<void>;
+  readonly data: OperationOutput<C, K> | null;
+  readonly error: BroappError | null;
+  readonly pending: boolean;
+  /** Clear `data` and `error`. */
+  reset(): void;
+}
+
+/**
+ * One operation, with its loading and error state.
+ *
+ * Only the most recent call may settle the state, so an earlier slow response
+ * cannot overwrite a later one.
+ */
+export function useOperation<C extends AnyContract, K extends OperationName<C>>(
+  name: K,
+): OperationHook<C, K> {
+  const { client, ready } = useContextValue<C>();
+  const [data, setData] = React.useState<OperationOutput<C, K> | null>(null);
+  const [error, setError] = React.useState<BroappError | null>(null);
+  const [pending, setPending] = React.useState(false);
+  const generation = React.useRef(0);
+
+  const run = React.useCallback(
+    async (input: OperationInput<C, K>): Promise<void> => {
+      const mine = (generation.current += 1);
+      setPending(true);
+      setError(null);
+      try {
+        // Awaiting the connection rather than requiring it: a click during the
+        // first second of startup should run, not fail.
+        const connected = client ?? (await ready);
+        const result = await connected.call(name, input);
+        if (generation.current !== mine) return;
+        setData(result);
+      } catch (cause) {
+        if (generation.current !== mine) return;
+        setError(
+          cause instanceof BroappError
+            ? cause
+            : new BroappError('internal', 'The operation failed.', cause),
+        );
+      } finally {
+        if (generation.current === mine) setPending(false);
+      }
+    },
+    [client, ready, name],
+  );
+
+  const reset = React.useCallback(() => {
+    generation.current += 1;
+    setData(null);
+    setError(null);
+    setPending(false);
+  }, []);
+
+  return { run, data, error, pending, reset };
+}
+
+/** What {@link useStream} returns. */
+export interface StreamHook<C extends AnyContract, K extends StreamName<C>> {
+  /** Open the stream. Cancels any stream this hook already had open. */
+  start(params: StreamParams<C, K>): Promise<void>;
+  /** Cancel it. The host stops producing. */
+  cancel(): void;
+  readonly last: StreamEvent<C, K> | null;
+  readonly error: BroappError | null;
+  readonly running: boolean;
+  /** True when the previous run ended because `cancel()` was called. */
+  readonly cancelled: boolean;
+}
+
+/**
+ * One stream, with cancellation.
+ *
+ * The subscription is cancelled on unmount. That matters more here than in a
+ * web application: the producer is a process on the user's machine, and a
+ * stream nobody cancels goes on burning their CPU.
+ */
+export function useStream<C extends AnyContract, K extends StreamName<C>>(
+  name: K,
+): StreamHook<C, K> {
+  const { client, ready } = useContextValue<C>();
+  const [last, setLast] = React.useState<StreamEvent<C, K> | null>(null);
+  const [error, setError] = React.useState<BroappError | null>(null);
+  const [running, setRunning] = React.useState(false);
+  const [cancelled, setCancelled] = React.useState(false);
+  const active = React.useRef<Subscription | null>(null);
+  const mounted = React.useRef(true);
+
+  React.useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      active.current?.cancel();
+      active.current = null;
+    };
+  }, []);
+
+  const cancel = React.useCallback(() => {
+    if (active.current === null) return;
+    active.current.cancel();
+    active.current = null;
+    setCancelled(true);
+    setRunning(false);
+  }, []);
+
+  const start = React.useCallback(
+    async (params: StreamParams<C, K>): Promise<void> => {
+      active.current?.cancel();
+      active.current = null;
+      setError(null);
+      setLast(null);
+      setCancelled(false);
+      setRunning(true);
+      try {
+        const connected = client ?? (await ready);
+        if (!mounted.current) {
+          setRunning(false);
+          return;
+        }
+        const subscription = await connected.subscribe(name, params, {
+          onEvent: (event) => {
+            if (mounted.current) setLast(event);
+          },
+          onDone: () => {
+            if (!mounted.current) return;
+            active.current = null;
+            setRunning(false);
+          },
+          onError: (cause) => {
+            if (!mounted.current) return;
+            active.current = null;
+            setError(cause);
+            setRunning(false);
+          },
+        });
+        if (!mounted.current) {
+          subscription.cancel();
+          return;
+        }
+        active.current = subscription;
+      } catch (cause) {
+        if (!mounted.current) return;
+        setRunning(false);
+        setError(
+          cause instanceof BroappError
+            ? cause
+            : new BroappError('internal', 'The stream could not be started.', cause),
+        );
+      }
+    },
+    [client, ready, name],
+  );
+
+  return { start, cancel, last, error, running, cancelled };
+}

package/src/react/index.ts

@@ -0,0 +1,15 @@
+/** `broapp/react` — React bindings over `broapp/client`. */
+export {
+  BroappProvider,
+  useBroapp,
+  useBroappReady,
+  useConnection,
+  useOperation,
+  useStream,
+} from './hooks.tsx';
+export type {
+  BroappProviderProps,
+  ConnectionStatus,
+  OperationHook,
+  StreamHook,
+} from './hooks.tsx';

package/src/shared/contract.ts

@@ -0,0 +1,134 @@
+/**
+ * The contract: the one description of an application's host surface that
+ * both sides import.
+ *
+ * A contract is data, not code. It names operations and streams and gives
+ * each a schema. The host imports it to register implementations; the browser
+ * imports it to make typed calls. Because it holds no implementation, a
+ * bundler that follows the browser's import of the contract does not pull the
+ * host in with it — which is what keeps host code and host secrets out of the
+ * browser bundle.
+ *
+ * Broapp maps a contract onto Brobridge's existing surface and nothing more:
+ * an operation `"greet"` in group `"system"` is exactly
+ * `bridge.expose("system", { greet })` on the host and
+ * `bridge.call("system.greet", input)` in the browser. There is no second
+ * dispatch path and no re-implemented transport.
+ */
+import type { Infer, Schema } from './schema.ts';
+
+/** One unary operation: JSON in, JSON out. */
+export interface OperationSpec<I = unknown, O = unknown> {
+  readonly input: Schema<I>;
+  readonly output: Schema<O>;
+  /** Shown in generated documentation and in the developer panel. */
+  readonly summary?: string;
+}
+
+/**
+ * One stream route.
+ *
+ * The wire format is newline-delimited JSON: each event is one JSON value on
+ * one line. Brobridge streams carry bytes, and chunk boundaries are not
+ * message boundaries, so Broapp frames them ({@link encodeEvent},
+ * {@link NdjsonDecoder}) rather than assuming one chunk is one event.
+ */
+export interface StreamSpec<P = unknown, E = unknown> {
+  readonly params: Schema<P>;
+  readonly event: Schema<E>;
+  readonly summary?: string;
+}
+
+/** The operation and stream tables an application declares. */
+export interface ContractShape {
+  readonly operations: Record<string, OperationSpec>;
+  readonly streams: Record<string, StreamSpec>;
+}
+
+/** A validated contract. */
+export interface Contract<C extends ContractShape> {
+  readonly operations: C['operations'];
+  readonly streams: C['streams'];
+  /** Route names, for diagnostics and for the developer panel. */
+  readonly routes: {
+    readonly operations: readonly string[];
+    readonly streams: readonly string[];
+  };
+}
+
+/**
+ * Any contract, for a generic parameter's constraint.
+ *
+ * Every public type below is written against `AnyContract` rather than against
+ * `ContractShape`, because the thing an application has in hand is
+ * `typeof contract` — the value `defineContract` returned. Making that the
+ * parameter means `useOperation<AppContract, "demo.greet">` reads the way it
+ * looks like it should, instead of needing the shape to be dug back out.
+ */
+export type AnyContract = Contract<ContractShape>;
+
+/** The shape inside a contract. */
+export type ShapeOf<C> = C extends Contract<infer S> ? S : never;
+
+/** Operation names in a contract. */
+export type OperationName<C extends AnyContract> = keyof ShapeOf<C>['operations'] & string;
+/** Stream names in a contract. */
+export type StreamName<C extends AnyContract> = keyof ShapeOf<C>['streams'] & string;
+
+/** The argument type of one operation. */
+export type OperationInput<C extends AnyContract, K extends OperationName<C>> = Infer<
+  ShapeOf<C>['operations'][K]['input']
+>;
+/** The result type of one operation. */
+export type OperationOutput<C extends AnyContract, K extends OperationName<C>> = Infer<
+  ShapeOf<C>['operations'][K]['output']
+>;
+/** The parameter type of one stream. */
+export type StreamParams<C extends AnyContract, K extends StreamName<C>> = Infer<
+  ShapeOf<C>['streams'][K]['params']
+>;
+/** The event type of one stream. */
+export type StreamEvent<C extends AnyContract, K extends StreamName<C>> = Infer<
+  ShapeOf<C>['streams'][K]['event']
+>;
+
+/**
+ * A route name is `group.member`. Brobridge resolves a unary call by splitting
+ * on the first `.` and looking the group up in its service registry, so both
+ * halves must be present and neither may itself contain a dot.
+ */
+const ROUTE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Split `"system.greet"` into its Brobridge service and method names. */
+export function splitRoute(route: string): { group: string; member: string } {
+  const cut = route.indexOf('.');
+  return { group: route.slice(0, cut), member: route.slice(cut + 1) };
+}
+
+/**
+ * Declare an application's host surface.
+ *
+ * Rejects a malformed route name at startup rather than at the first call,
+ * because a route that Brobridge cannot resolve is a programming error and
+ * should not wait for a user to find it.
+ */
+export function defineContract<const C extends ContractShape>(shape: C): Contract<C> {
+  const operations = Object.keys(shape.operations);
+  const streams = Object.keys(shape.streams);
+  for (const route of [...operations, ...streams]) {
+    if (!ROUTE_PATTERN.test(route)) {
+      throw new TypeError(
+        `route ${JSON.stringify(route)} must be "group.member", where each half is a JavaScript identifier`,
+      );
+    }
+  }
+  const clash = operations.find((route) => streams.includes(route));
+  if (clash !== undefined) {
+    throw new TypeError(`route ${JSON.stringify(clash)} is declared as both an operation and a stream`);
+  }
+  return {
+    operations: shape.operations,
+    streams: shape.streams,
+    routes: { operations, streams },
+  };
+}

package/src/shared/errors.ts

@@ -0,0 +1,134 @@
+/**
+ * The public/internal error boundary.
+ *
+ * A host operation runs with the invoking user's permissions and sees real
+ * paths, real database handles and real environment. A browser tab must not
+ * learn any of that from a failure, however that tab was authenticated. So
+ * Broapp draws one line: an error a handler raises deliberately with
+ * {@link PublicError} crosses to the browser with its message intact;
+ * everything else is logged on the host and reaches the browser as a fixed
+ * string.
+ *
+ * The transport is Brobridge's, unchanged. Brobridge already reduces any
+ * non-`BridgeError` throw to `INTERNAL_ERROR` with the message `"internal
+ * error"` (`services.ts`), which is exactly the behaviour wanted for the
+ * second case — so Broapp adds nothing there and simply lets it happen. For
+ * the first case Broapp throws a `BridgeError` whose message carries a short
+ * marker, because Brobridge's `ErrorCode` set is a protocol vocabulary and
+ * has no member for "this name is already taken".
+ */
+import { BridgeError, ErrorCode } from '@brobridgejs/core';
+
+/** Machine-readable failure categories a browser may branch on. */
+export type PublicErrorCode =
+  | 'invalid_input'
+  | 'not_found'
+  | 'conflict'
+  | 'unavailable'
+  | 'rejected'
+  | 'internal';
+
+const PUBLIC_CODES: readonly PublicErrorCode[] = [
+  'invalid_input',
+  'not_found',
+  'conflict',
+  'unavailable',
+  'rejected',
+  'internal',
+];
+
+/**
+ * Protocol code carried alongside each public code.
+ *
+ * The mapping is lossy on purpose — several public codes share
+ * `INTERNAL_ERROR` — which is why the public code also travels in the
+ * message. A peer that only understands the protocol still sees a sensible
+ * code; a Broapp client sees both.
+ */
+const PROTOCOL_CODE: Record<PublicErrorCode, ErrorCode> = {
+  invalid_input: ErrorCode.PROTOCOL_VIOLATION,
+  not_found: ErrorCode.NOT_FOUND,
+  conflict: ErrorCode.INTERNAL_ERROR,
+  unavailable: ErrorCode.INTERNAL_ERROR,
+  rejected: ErrorCode.PERMISSION_DENIED,
+  internal: ErrorCode.INTERNAL_ERROR,
+};
+
+/** The marker that tells a Broapp client the message is deliberately public. */
+const MARKER = 'broapp/';
+
+/**
+ * An error whose message is safe for the browser to display.
+ *
+ * Raise it for a condition a user can act on: a name already taken, a path
+ * outside the configured root, a record that is not there. Do not put a
+ * filesystem path, a credential, or a driver message in it — the message is
+ * shown to the browser verbatim.
+ */
+export class PublicError extends Error {
+  readonly code: PublicErrorCode;
+
+  constructor(code: PublicErrorCode, message: string) {
+    super(message);
+    this.name = 'PublicError';
+    this.code = code;
+  }
+
+  /** As a `BridgeError`, which is what Brobridge forwards with its message intact. */
+  toBridgeError(): BridgeError {
+    return new BridgeError(PROTOCOL_CODE[this.code], `${MARKER}${this.code} ${this.message}`);
+  }
+}
+
+/** The message every unhandled host failure becomes, on both sides. */
+export const INTERNAL_ERROR_MESSAGE = 'The application could not complete that operation.';
+
+/** An operation or stream failure, as the browser sees it. */
+export class BroappError extends Error {
+  readonly code: PublicErrorCode;
+  /** The underlying protocol error, when there was one. */
+  override readonly cause: unknown;
+
+  constructor(code: PublicErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.name = 'BroappError';
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Translate anything a call rejected with into a {@link BroappError}.
+ *
+ * A message without the marker is not shown: it came from the protocol layer
+ * or from Brobridge's own internal-error reduction, and neither is written
+ * for a user to read.
+ */
+export function fromTransportError(error: unknown): BroappError {
+  if (error instanceof BroappError) return error;
+  const message = error instanceof Error ? error.message : '';
+  if (message.startsWith(MARKER)) {
+    const space = message.indexOf(' ');
+    const code = space < 0 ? message.slice(MARKER.length) : message.slice(MARKER.length, space);
+    if ((PUBLIC_CODES as readonly string[]).includes(code)) {
+      return new BroappError(
+        code as PublicErrorCode,
+        space < 0 ? INTERNAL_ERROR_MESSAGE : message.slice(space + 1),
+        error,
+      );
+    }
+  }
+  if (error instanceof BridgeError && error.code === ErrorCode.CANCELLED) {
+    return new BroappError('rejected', 'The operation was cancelled.', error);
+  }
+  return new BroappError('internal', INTERNAL_ERROR_MESSAGE, error);
+}
+
+/** Convenience constructors, so a handler reads as prose. */
+export const publicError = {
+  invalidInput: (message: string): PublicError => new PublicError('invalid_input', message),
+  notFound: (message: string): PublicError => new PublicError('not_found', message),
+  conflict: (message: string): PublicError => new PublicError('conflict', message),
+  unavailable: (message: string): PublicError => new PublicError('unavailable', message),
+  rejected: (message: string): PublicError => new PublicError('rejected', message),
+} as const;