oysterun 1.5.6 → 1.5.7-beta.1

package/README.md

@@ -248,8 +248,9 @@ npm start
 Useful commands:
 
 ```bash
-npm run setup   # first-run direct Host setup
-npm run setup -- --enable-cloud  # optional Cloud registration
+npm run setup   # first-run Managed Tunnel Host setup
+node host-service/setup.mjs   # source-local Direct Host setup
+node bin/oysterun.mjs setup --local   # explicit local-only Direct setup
 npm start       # plain start, no watch mode
 npm run dev     # watch mode for Host JS files
 npm run cli     # local CLI client
@@ -272,7 +273,8 @@ Port notes:
 - direct mode can also store an optional `public_base_url` there for manual client connection
 - fresh Session Setup runtime defaults, including interface style plus Claude/Codex provider defaults, are stored there under `session_defaults`
 - Host Preferences shows the active config path, so `OYSTERUN_CONFIG_DIR` overrides are visible in the UI
-- Host now defaults to direct Host mode unless Cloud registration is explicitly enabled
+- release setup defaults to Oysterun Managed Tunnel
+- source-local setup and `oysterun setup --local` retain explicit Direct mode
 
 ### Optional: start backend + Host together for repo development
 

package/bin/oysterun.mjs

@@ -191,6 +191,9 @@ Product modules:
 
 First run:
   If Host config is missing or incomplete, 'oysterun' enters setup.
+  Release setup uses Oysterun Managed Tunnel by default.
+  Use 'oysterun setup --local' for local-only Direct Host setup.
+  Use '--enable-cloud-direct' only for advanced Direct Cloud registration.
 
 Install contract:
   npm install -g oysterun installs files only. It does not run setup or start

package/dev/client/connectivity/data-channel-adapter.mjs

@@ -0,0 +1,146 @@
+function toUint8Array(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (globalThis.Buffer?.isBuffer(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  throw new Error("DataChannel message must be binary");
+}
+
+export function adaptBrowserDataChannel(channel) {
+  const messageListeners = new Set();
+  const openListeners = new Set();
+  const bufferedLowListeners = new Set();
+  const closeListeners = new Set();
+  const errorListeners = new Set();
+  channel.binaryType = "arraybuffer";
+
+  channel.addEventListener("message", (event) => {
+    try {
+      const bytes = toUint8Array(event.data);
+      for (const listener of messageListeners) listener(bytes);
+    } catch (error) {
+      for (const listener of errorListeners) listener(error);
+    }
+  });
+  channel.addEventListener("open", () => {
+    for (const listener of openListeners) listener();
+  });
+  channel.addEventListener("bufferedamountlow", () => {
+    for (const listener of bufferedLowListeners) listener();
+  });
+  channel.addEventListener("close", () => {
+    for (const listener of closeListeners) listener();
+  });
+  channel.addEventListener("error", (event) => {
+    const error = new Error(event?.error?.message || "Browser DataChannel error");
+    for (const listener of errorListeners) listener(error);
+  });
+
+  return {
+    label: channel.label,
+    isOpen: () => channel.readyState === "open",
+    bufferedAmount: () => channel.bufferedAmount,
+    setBufferedAmountLowThreshold(bytes) {
+      channel.bufferedAmountLowThreshold = bytes;
+    },
+    sendBinary(bytes) {
+      channel.send(bytes);
+      return { buffered: channel.bufferedAmount > 0 };
+    },
+    onMessage(listener) {
+      messageListeners.add(listener);
+      return () => messageListeners.delete(listener);
+    },
+    onOpen(listener) {
+      openListeners.add(listener);
+      return () => openListeners.delete(listener);
+    },
+    onBufferedAmountLow(listener) {
+      bufferedLowListeners.add(listener);
+      return () => bufferedLowListeners.delete(listener);
+    },
+    onClose(listener) {
+      closeListeners.add(listener);
+      return () => closeListeners.delete(listener);
+    },
+    onError(listener) {
+      errorListeners.add(listener);
+      return () => errorListeners.delete(listener);
+    },
+    close() {
+      channel.close();
+    },
+  };
+}
+
+export function adaptNodeDataChannel(channel) {
+  const messageListeners = new Set();
+  const openListeners = new Set();
+  const bufferedLowListeners = new Set();
+  const closeListeners = new Set();
+  const errorListeners = new Set();
+
+  channel.onMessage((message) => {
+    if (typeof message === "string") {
+      for (const listener of errorListeners) {
+        listener(new Error("Oysterun transport rejects text DataChannel frames"));
+      }
+      return;
+    }
+    const bytes = toUint8Array(message);
+    for (const listener of messageListeners) listener(bytes);
+  });
+  channel.onOpen(() => {
+    for (const listener of openListeners) listener();
+  });
+  channel.onBufferedAmountLow(() => {
+    for (const listener of bufferedLowListeners) listener();
+  });
+  channel.onClosed(() => {
+    for (const listener of closeListeners) listener();
+  });
+  channel.onError((message) => {
+    const error = new Error(String(message));
+    for (const listener of errorListeners) listener(error);
+  });
+
+  return {
+    label: channel.getLabel(),
+    isOpen: () => channel.isOpen(),
+    bufferedAmount: () => channel.bufferedAmount(),
+    setBufferedAmountLowThreshold: (bytes) =>
+      channel.setBufferedAmountLowThreshold(bytes),
+    sendBinary(bytes) {
+      // False means the message was accepted into the native send buffer.
+      // Retrying on false duplicates the frame.
+      return {
+        buffered:
+          channel.sendMessageBinary(globalThis.Buffer.from(bytes)) === false,
+      };
+    },
+    onMessage(listener) {
+      messageListeners.add(listener);
+      return () => messageListeners.delete(listener);
+    },
+    onOpen(listener) {
+      openListeners.add(listener);
+      return () => openListeners.delete(listener);
+    },
+    onBufferedAmountLow(listener) {
+      bufferedLowListeners.add(listener);
+      return () => bufferedLowListeners.delete(listener);
+    },
+    onClose(listener) {
+      closeListeners.add(listener);
+      return () => closeListeners.delete(listener);
+    },
+    onError(listener) {
+      errorListeners.add(listener);
+      return () => errorListeners.delete(listener);
+    },
+    close() {
+      channel.close();
+    },
+  };
+}

package/dev/client/connectivity/logical-host-connection.mjs

@@ -0,0 +1,358 @@
+import { createConnectivityRandomId } from "./random-id.mjs";
+
+const MATRIX_SYNC_PATH = /^\/_matrix\/client\/[^/]+\/sync(?:\?|$)/;
+const DEFAULT_TRANSPORT_RETIRE_TIMEOUT_MS = 35_000;
+
+function deferred() {
+  let resolve;
+  const promise = new Promise((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
+}
+
+async function withTimeout(promise, timeoutMs, message) {
+  let timeoutId;
+  const timeout = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => reject(new Error(message)), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timeoutId));
+}
+
+function headersToObject(headers) {
+  return Object.fromEntries([...headers.entries()]);
+}
+
+export class BootstrapFetchTransport {
+  constructor({ fetchImpl = globalThis.fetch, origin = "", diagnostic } = {}) {
+    if (typeof fetchImpl !== "function") {
+      throw new Error("Bootstrap fetch implementation is required");
+    }
+    this.fetchImpl = fetchImpl;
+    this.origin = origin.replace(/\/+$/, "");
+    this.diagnostic = diagnostic;
+    this.pathKind = "bootstrap";
+  }
+
+  async request(request, { requestId }) {
+    const headers = new Headers(request.headers || {});
+    headers.set("X-Oysterun-Request-Id", requestId);
+    const response = await this.fetchImpl(`${this.origin}${request.path}`, {
+      method: request.method,
+      headers,
+      body: request.body,
+      credentials: "same-origin",
+    });
+    const body = new Uint8Array(await response.arrayBuffer());
+    this.diagnostic?.({
+      event_type: "bootstrap_request_completed",
+      request_id: requestId,
+      status: response.status,
+      response_bytes: body.byteLength,
+    });
+    return {
+      ok: true,
+      response: {
+        status: response.status,
+        status_text: response.statusText,
+        headers: headersToObject(response.headers),
+        body,
+      },
+    };
+  }
+
+  async close() {}
+}
+
+export class OysterunLogicalHostConnection {
+  constructor({
+    bootstrapTransport,
+    diagnostic,
+    transportRetireTimeoutMs = DEFAULT_TRANSPORT_RETIRE_TIMEOUT_MS,
+  }) {
+    if (!bootstrapTransport) {
+      throw new Error("Bootstrap transport is required");
+    }
+    this.bootstrapTransport = bootstrapTransport;
+    this.activeTransport = bootstrapTransport;
+    this.activePathKind = "bootstrap";
+    this.activeConnectionId = null;
+    this.diagnostic = diagnostic;
+    this.transportRetireTimeoutMs = transportRetireTimeoutMs;
+    this.transportStates = new Map();
+    this.retiringTransports = new Set();
+    this.transitionGeneration = 0;
+    this.transitionState = "stable";
+    this.syncOwnerId = null;
+    this.closed = false;
+    this.ensureTransportState(bootstrapTransport);
+  }
+
+  emitDiagnostic(event) {
+    this.diagnostic?.({
+      schema: "oysterun.connectivity.logical_host_connection.v1",
+      at: new Date().toISOString(),
+      active_path_kind: this.activePathKind,
+      active_connection_id: this.activeConnectionId,
+      ...event,
+    });
+  }
+
+  acquireSyncOwner(ownerId) {
+    if (this.closed) throw new Error("Logical Host connection is closed");
+    if (typeof ownerId !== "string" || !ownerId) {
+      throw new Error("sync owner id is required");
+    }
+    if (this.syncOwnerId && this.syncOwnerId !== ownerId) {
+      throw new Error(
+        `Matrix sync is already owned by ${this.syncOwnerId}; duplicate stream rejected`
+      );
+    }
+    this.syncOwnerId = ownerId;
+    this.emitDiagnostic({
+      event_type: "matrix_sync_owner_acquired",
+      sync_owner_id: ownerId,
+    });
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      if (this.syncOwnerId === ownerId) this.syncOwnerId = null;
+      this.emitDiagnostic({
+        event_type: "matrix_sync_owner_released",
+        sync_owner_id: ownerId,
+      });
+    };
+  }
+
+  ensureTransportState(transport) {
+    let state = this.transportStates.get(transport);
+    if (!state) {
+      state = {
+        inFlight: 0,
+        idleWaiters: new Set(),
+        retirePromise: null,
+      };
+      this.transportStates.set(transport, state);
+    }
+    return state;
+  }
+
+  acquireTransportLease(transport) {
+    const state = this.ensureTransportState(transport);
+    state.inFlight += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      state.inFlight -= 1;
+      if (state.inFlight !== 0) return;
+      for (const waiter of state.idleWaiters) waiter.resolve();
+      state.idleWaiters.clear();
+    };
+  }
+
+  async waitForTransportIdle(transport) {
+    const state = this.ensureTransportState(transport);
+    if (state.inFlight === 0) return;
+    const waiter = deferred();
+    state.idleWaiters.add(waiter);
+    try {
+      await withTimeout(
+        waiter.promise,
+        this.transportRetireTimeoutMs,
+        "Previous logical transport did not become idle"
+      );
+    } finally {
+      state.idleWaiters.delete(waiter);
+    }
+  }
+
+  retireTransport(transport, { transitionGeneration, reason }) {
+    if (transport === this.bootstrapTransport) return Promise.resolve();
+    const state = this.ensureTransportState(transport);
+    if (state.retirePromise) return state.retirePromise;
+
+    const retirePromise = (async () => {
+      this.emitDiagnostic({
+        event_type: "logical_transport_retirement_started",
+        transition_generation: transitionGeneration,
+        reason,
+        in_flight_request_count: state.inFlight,
+      });
+      let graceful = true;
+      try {
+        await this.waitForTransportIdle(transport);
+      } catch (error) {
+        graceful = false;
+        this.emitDiagnostic({
+          event_type: "logical_transport_retirement_timed_out",
+          transition_generation: transitionGeneration,
+          reason,
+          in_flight_request_count: state.inFlight,
+          error_code: "logical_transport_retirement_timeout",
+        });
+      }
+      await transport.close?.({ graceful });
+      this.transportStates.delete(transport);
+      this.emitDiagnostic({
+        event_type: "logical_transport_retired",
+        transition_generation: transitionGeneration,
+        reason,
+        graceful,
+      });
+    })();
+    state.retirePromise = retirePromise;
+    this.retiringTransports.add(retirePromise);
+    void retirePromise.finally(() => {
+      this.retiringTransports.delete(retirePromise);
+      if (this.transitionGeneration === transitionGeneration) {
+        this.transitionState = "stable";
+      }
+    });
+    return retirePromise;
+  }
+
+  changeActiveTransport({
+    transport,
+    pathKind,
+    connectionId,
+    reason,
+  }) {
+    const previousTransport = this.activeTransport;
+    const previousPathKind = this.activePathKind;
+    if (
+      previousTransport === transport &&
+      previousPathKind === pathKind &&
+      this.activeConnectionId === connectionId
+    ) {
+      return Promise.resolve();
+    }
+
+    const transitionGeneration = ++this.transitionGeneration;
+    this.transitionState =
+      pathKind === "webrtc" ? "promoting_webrtc" : "falling_back_bootstrap";
+    this.activeTransport = transport;
+    this.activePathKind = pathKind;
+    this.activeConnectionId = connectionId;
+    this.ensureTransportState(transport);
+    this.emitDiagnostic({
+      event_type: "active_path_changed",
+      transition_generation: transitionGeneration,
+      previous_path_kind: previousPathKind,
+      next_path_kind: pathKind,
+      reason,
+    });
+
+    if (
+      previousPathKind === "webrtc" &&
+      previousTransport !== transport
+    ) {
+      return this.retireTransport(previousTransport, {
+        transitionGeneration,
+        reason,
+      });
+    }
+    this.transitionState = "stable";
+    return Promise.resolve();
+  }
+
+  async request(
+    request,
+    { requestId = createConnectivityRandomId(), syncOwnerId = null } = {}
+  ) {
+    if (this.closed) throw new Error("Logical Host connection is closed");
+    if (MATRIX_SYNC_PATH.test(request.path)) {
+      if (!syncOwnerId || syncOwnerId !== this.syncOwnerId) {
+        throw new Error(
+          "Matrix sync request requires the single active sync owner"
+        );
+      }
+    }
+    const transport = this.activeTransport;
+    const pathKind = this.activePathKind;
+    const releaseTransport = this.acquireTransportLease(transport);
+    this.emitDiagnostic({
+      event_type: "logical_request_started",
+      request_id: requestId,
+      path_kind: pathKind,
+    });
+    try {
+      const result = await transport.request(request, { requestId });
+      this.emitDiagnostic({
+        event_type: "logical_request_completed",
+        request_id: requestId,
+        path_kind: pathKind,
+      });
+      return result;
+    } catch (error) {
+      this.emitDiagnostic({
+        event_type: "logical_request_failed",
+        request_id: requestId,
+        path_kind: pathKind,
+        error_code: error?.code || "logical_request_failed",
+      });
+      // Never retry an in-flight mutation on another path. The caller may
+      // resolve its request id before deciding whether a retry is safe.
+      throw error;
+    } finally {
+      releaseTransport();
+    }
+  }
+
+  async activateWebRtc({ transport, connectionId }) {
+    if (this.closed) throw new Error("Logical Host connection is closed");
+    if (!transport || typeof transport.request !== "function") {
+      throw new Error("Ready WebRTC transport is required");
+    }
+    if (typeof connectionId !== "string" || !connectionId) {
+      throw new Error("WebRTC connection id is required");
+    }
+    await this.changeActiveTransport({
+      transport,
+      pathKind: "webrtc",
+      connectionId,
+      reason: "webrtc_ready",
+    });
+  }
+
+  async activateBootstrap({ reason = "webrtc_unavailable" } = {}) {
+    if (this.closed) throw new Error("Logical Host connection is closed");
+    await this.changeActiveTransport({
+      transport: this.bootstrapTransport,
+      pathKind: "bootstrap",
+      connectionId: null,
+      reason,
+    });
+  }
+
+  status() {
+    return {
+      active_path_kind: this.activePathKind,
+      active_connection_id: this.activeConnectionId,
+      transition_generation: this.transitionGeneration,
+      transition_state: this.transitionState,
+      active_in_flight_request_count:
+        this.ensureTransportState(this.activeTransport).inFlight,
+      retiring_transport_count: this.retiringTransports.size,
+      matrix_sync_owner_id: this.syncOwnerId,
+      closed: this.closed,
+    };
+  }
+
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (
+      this.activeTransport !== this.bootstrapTransport &&
+      typeof this.activeTransport.close === "function"
+    ) {
+      await this.waitForTransportIdle(this.activeTransport).catch(() => {});
+      await this.activeTransport.close({ graceful: true });
+    }
+    await Promise.allSettled([...this.retiringTransports]);
+    await this.bootstrapTransport.close?.();
+    this.syncOwnerId = null;
+    this.emitDiagnostic({ event_type: "logical_host_connection_closed" });
+  }
+}

package/dev/client/connectivity/managed-host-browser.d.mts

@@ -0,0 +1,29 @@
+export class ManagedHostBrowserConnection {
+  start(): Promise<void> | null;
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+  status(): Record<string, unknown>;
+  close(): Promise<void>;
+  setTicketProvider(
+    ticketProvider: ManagedHostTicketProvider | null
+  ): void;
+}
+
+export type ManagedHostTicketProvider = (input: {
+  configuration: Record<string, unknown>;
+  connectionAttemptId: string;
+  dtlsFingerprintSha256: string;
+}) => Promise<{
+  credential: string;
+  client_authority_kind: "app_installation" | "host_owner_browser";
+}>;
+
+export function getManagedHostBrowserConnection(): ManagedHostBrowserConnection;
+export function configureManagedHostTicketProvider(
+  ticketProvider: ManagedHostTicketProvider | null
+): void;
+export function startManagedHostConnection(): Promise<void> | null;
+export function managedHostFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit
+): Promise<Response>;
+export function getManagedHostConnectionStatus(): Record<string, unknown>;