devframe 0.8.1 → 0.9.0-beta.1

package/dist/{ws-server-J-zkiOyp.d.mts → ws-server-Ces08fjP.d.mts}

@@ -1,13 +1,62 @@
 import { v as RpcFunctionDefinitionAny } from "./types-CnJSgRVa.mjs";
-import { Peer } from "crossws";
 import { BirpcGroup, ChannelOptions } from "birpc";
+import { Hooks, Peer } from "crossws";
 import { NodeAdapter } from "crossws/adapters/node";
-import { Server } from "node:http";
+import { Buffer } from "node:buffer";
+import { IncomingMessage, Server } from "node:http";
 import { Server as Server$1, ServerOptions } from "node:https";
-//#region src/rpc/transports/ws-server.d.ts
+import { AddressInfo } from "node:net";
+import { Duplex } from "node:stream";
+//#region src/rpc/transports/session.d.ts
+/**
+ * Which wire transport produced an RPC connection. Every transport speaks
+ * the same birpc channel protocol; the kind only matters to code that needs
+ * transport-specific behavior (e.g. reaching the WS escape hatch on
+ * {@link DevframeRpcConnection.peer}).
+ */
+type DevframeRpcTransportKind = 'websocket' | 'sse';
+/**
+ * Structural view of the connect-time HTTP request behind an RPC connection
+ * — the WS upgrade request, or the request opening an SSE stream. Shaped to
+ * match both the web `Request` a crossws peer exposes and a plain
+ * `node:http` request wrapper, so auth hooks can read the bearer-token
+ * query param and the `Origin` header without caring which transport (or
+ * runtime) produced the connection.
+ */
+interface DevframeRpcConnectionRequest {
+  /** Request URL (may be path-only, e.g. `/__ws?devframe_auth_token=…`). */
+  url?: string;
+  /** Header lookup, `Headers`-style. */
+  headers?: {
+    get: (name: string) => string | null | undefined;
+  };
+}
+/**
+ * A live RPC connection, independent of the transport that carries it. One
+ * exists per connected client; transport bindings construct it alongside the
+ * session meta and hand both to the connect/disconnect hooks
+ * (`onPeerConnect` / `onPeerDisconnect`, {@link DevframeAuthHandler.onConnect}).
+ */
+interface DevframeRpcConnection {
+  /** Session id — the same value as the session meta's `id`. */
+  id: number;
+  /** The transport carrying this connection. */
+  transport: DevframeRpcTransportKind;
+  /** The connect-time HTTP request (upgrade request / stream request). */
+  request?: DevframeRpcConnectionRequest;
+  /** Send a raw wire frame to this client. Prefer the birpc channel. */
+  send?: (data: string) => void;
+  /** Terminate the connection from the server side. */
+  close?: (code?: number, reason?: string) => void;
+  /**
+   * The crossws peer backing a `websocket` connection — the WS-specific
+   * escape hatch (pub/sub, raw socket access). Absent on other transports.
+   */
+  peer?: Peer;
+}
 interface DevframeNodeRpcSessionMeta {
   id: number;
-  /** The crossws peer backing this session's socket. */
+  /** The crossws peer backing this session's socket (WS transport only). */
   peer?: Peer;
   clientAuthToken?: string;
   isTrusted?: boolean;
@@ -25,6 +74,8 @@ interface DevframeNodeRpcSessionMeta {
    */
   uploadingStreams?: Set<string>;
 }
+//#endregion
+//#region src/rpc/transports/ws-server.d.ts
 interface WsRpcTransportOptions {
   /**
    * Attach to an existing HTTP(S) server, sharing its port. Combine with
@@ -34,17 +85,28 @@ interface WsRpcTransportOptions {
    * this transport detaches the upgrade listener without closing the server.
    */
   server?: Server | Server$1;
-  /** Port for a newly-created standalone WS server. */
+  /**
+   * Port for the standalone WebSocket server. Defaults to `0`, which lets the
+   * operating system assign an available port.
+   */
   port?: number;
-  /** Host for a newly-created standalone WS server. Defaults to `localhost`. */
+  /** Host for the standalone WebSocket server. Defaults to `localhost`. */
   host?: string;
   /**
-   * Restrict the WS endpoint to a single upgrade route (e.g. `/__devframe_ws`). When
+   * Restrict the WS endpoint to a single upgrade route (e.g. `/__ws`). When
    * sharing a `server`, non-matching upgrade requests are left untouched for
    * other listeners to handle, so devframe's socket can sit alongside
    * framework sockets (Vite HMR, etc.).
    */
   path?: string;
+  /**
+   * Create the adapter without binding it to anything: no server is created,
+   * no port is bound, no `upgrade` listener is installed. The caller drives
+   * the socket itself through {@link WsRpcTransport.handleUpgrade} (from its
+   * own `upgrade` listener) or {@link WsRpcTransport.attach} (to bind a
+   * server later). Takes precedence over `server` / `port` / `https`.
+   */
+  unbound?: boolean;
   /**
    * Destroy upgrade requests that don't match `path` instead of leaving them
    * for other listeners. Enable this when devframe owns the shared server
@@ -72,8 +134,8 @@ interface WsRpcTransportOptions {
    * loses dev-time validation for `jsonSerializable: true` declarations.
    */
   definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>;
-  onConnected?: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void;
-  onDisconnected?: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void;
+  onConnected?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
+  onDisconnected?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
   /** Override the default per-call serializer. Most callers should leave this unset. */
   serialize?: ChannelOptions['serialize'];
   /** Override the default per-call deserializer. Most callers should leave this unset. */
@@ -106,6 +168,24 @@ interface WsRpcTransport {
    * `peers` and pub/sub. See https://crossws.h3.dev.
    */
   ws: NodeAdapter;
+  /** Resolves when the transport-owned server is listening. */
+  ready: Promise<void>;
+  /** Returns the bound address, or `null` when the server is not listening. */
+  address: () => AddressInfo | string | null;
+  /**
+   * Complete a `node:http` `upgrade` event on this transport, applying the
+   * same `path` filter and origin gate the transport's own listener uses.
+   * Wire it into a host server directly — `server.on('upgrade',
+   * transport.handleUpgrade)` — or call it from an existing listener.
+   */
+  handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+  /**
+   * Route a server's `upgrade` events to this transport, returning a detach
+   * function. Use it to bind an `unbound` transport once the host server
+   * exists; {@link WsRpcTransport.close} detaches every server attached this
+   * way (without closing them — the caller owns their lifecycle).
+   */
+  attach: (server: Server | Server$1) => () => void;
   /** Remove the upgrade listener from a shared `server` (a no-op otherwise). */
   detach: () => void;
   /**
@@ -124,16 +204,25 @@ declare function isLoopbackHostname(hostname: string): boolean;
  * browser — is rejected.
  */
 declare function isAllowedOrigin(origin: string | undefined, allowedOrigins: readonly string[]): boolean;
+/**
+ * The per-peer lifecycle hooks driving a devframe RPC WebSocket, shaped for
+ * any [crossws](https://crossws.h3.dev) adapter. {@link attachWsRpcTransport}
+ * feeds them to the Node adapter; runtime-specific attachments (e.g. Bun's
+ * fetch-upgrade adapter) reuse the same hooks so every transport speaks the
+ * identical wire protocol — one birpc channel per peer, per-method
+ * `jsonSerializable` dispatch between strict JSON and structured-clone.
+ */
+declare function createWsRpcPeerHooks<ClientFunctions extends object, ServerFunctions extends object>(rpcGroup: BirpcGroup<ClientFunctions, ServerFunctions, false>, options?: Pick<WsRpcTransportOptions, 'onConnected' | 'onDisconnected' | 'definitions' | 'serialize' | 'deserialize'>): Partial<Hooks>;
 /**
  * Attach a WebSocket transport to an existing RPC group, powered by
  * [crossws](https://crossws.h3.dev). Either attach to an existing HTTP(S)
  * `server` (sharing its port, optionally scoped to a `path`), or let this
  * helper create a standalone server from `port` / `host` / `https`.
  *
- * Returns the crossws node adapter plus `detach` (remove the upgrade
- * listener from a shared `server`) and `close` (full deterministic
- * teardown).
+ * Returns the crossws node adapter, standalone-server readiness/address
+ * accessors, `detach` (remove the upgrade listener from a shared `server`),
+ * and `close` (full deterministic teardown).
  */
 declare function attachWsRpcTransport<ClientFunctions extends object, ServerFunctions extends object>(rpcGroup: BirpcGroup<ClientFunctions, ServerFunctions, false>, options?: WsRpcTransportOptions): WsRpcTransport;
 //#endregion
-export { WsRpcTransportOptions as a, isAllowedOrigin as c, WsRpcTransport as i, isLoopbackHostname as l, DevframeNodeRpcSessionMeta as n, attachWsRpcTransport as o, WsOriginRegistry as r, createWsOriginRegistry as s, CreateWsOriginRegistryOptions as t };
+export { attachWsRpcTransport as a, isAllowedOrigin as c, DevframeRpcConnection as d, DevframeRpcConnectionRequest as f, WsRpcTransportOptions as i, isLoopbackHostname as l, WsOriginRegistry as n, createWsOriginRegistry as o, DevframeRpcTransportKind as p, WsRpcTransport as r, createWsRpcPeerHooks as s, CreateWsOriginRegistryOptions as t, DevframeNodeRpcSessionMeta as u };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.8.1",
-  "description": "Framework for building generic devframes",
+  "version": "0.9.0-beta.1",
+  "description": "Framework for building one portable devtool integration that runs in any viewer.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "homepage": "https://github.com/devframes/devframe#readme",
@@ -22,23 +22,26 @@
     ".": "./dist/index.mjs",
     "./adapters/build": "./dist/adapters/build.mjs",
     "./adapters/cac": "./dist/adapters/cac.mjs",
-    "./adapters/cli": "./dist/adapters/cli.mjs",
     "./adapters/dev": "./dist/adapters/dev.mjs",
     "./adapters/embedded": "./dist/adapters/embedded.mjs",
     "./adapters/mcp": "./dist/adapters/mcp.mjs",
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.mjs",
     "./helpers/vite": "./dist/helpers/vite.mjs",
+    "./initiate": "./dist/adapters/initiate.mjs",
+    "./internal": "./dist/internal/index.mjs",
     "./node": "./dist/node/index.mjs",
     "./node/auth": "./dist/node/auth.mjs",
     "./node/hub-internals": "./dist/node/hub-internals.mjs",
     "./recipes/common-rpc-functions": "./dist/recipes/common-rpc-functions.mjs",
     "./recipes/interactive-auth": "./dist/recipes/interactive-auth.mjs",
-    "./recipes/open-helpers": "./dist/recipes/open-helpers.mjs",
     "./rpc": "./dist/rpc/index.mjs",
     "./rpc/client": "./dist/rpc/client.mjs",
     "./rpc/dump": "./dist/rpc/dump.mjs",
     "./rpc/server": "./dist/rpc/server.mjs",
+    "./rpc/transports/sse-client": "./dist/rpc/transports/sse-client.mjs",
+    "./rpc/transports/sse-server": "./dist/rpc/transports/sse-server.mjs",
+    "./rpc/transports/ws-bun": "./dist/rpc/transports/ws-bun.mjs",
     "./rpc/transports/ws-client": "./dist/rpc/transports/ws-client.mjs",
     "./rpc/transports/ws-server": "./dist/rpc/transports/ws-server.mjs",
     "./types": "./dist/types/index.mjs",
@@ -50,9 +53,7 @@
     "./utils/launch-editor": "./dist/utils/launch-editor.mjs",
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
     "./utils/open": "./dist/utils/open.mjs",
-    "./utils/promise": "./dist/utils/promise.mjs",
     "./utils/simple-schema": "./dist/utils/simple-schema.mjs",
-    "./utils/scope": "./dist/utils/scope.mjs",
     "./utils/serve-static": "./dist/utils/serve-static.mjs",
     "./utils/shared-state": "./dist/utils/shared-state.mjs",
     "./utils/streaming-channel": "./dist/utils/streaming-channel.mjs",
@@ -87,7 +88,7 @@
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "birpc": "^4.0.0",
+    "birpc": "^4.1.0",
     "crossws": "^0.4.10",
     "destr": "^2.0.5",
     "h3": "^2.0.1-rc.26",
@@ -101,7 +102,7 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "cac": "^7.0.0",
     "get-port-please": "^3.2.0",
-    "immer": "^11.1.15",
+    "immer": "^11.1.16",
     "launch-editor": "^2.14.1",
     "mlly": "^1.8.2",
     "obug": "^2.1.4",
@@ -115,7 +116,7 @@
     "ua-parser-modern": "^0.1.1",
     "valibot": "^1.4.2",
     "whenexpr": "^0.1.2",
-    "ws": "^8.21.1"
+    "ws": "^8.21.3"
   },
   "scripts": {
     "build": "tsdown",