@volter/tabnode 0.5.26 → 0.5.28

package/dist/port-bridge.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The page's side of the virtual-port service worker (public/__sw__.js): the
+ * servers a host registered, by port, and the protocol the worker speaks to
+ * reach them, flow control and streaming included. It carries none of Node's
+ * library, so a page whose engine runs in a worker loads no engine to serve
+ * that worker's ports (browser-substrate ADR-0042). An engine's own bridge,
+ * `ServerBridge`, extends it with the servers its guests listen on.
+ */
+import type { ResponseData, LoopbackStreamFlow } from './node-lib/http-bridge';
+/** The bytes this view names, in a buffer of their own. A pooled Buffer is a window on 8 KB. */
+export declare function ownedBytes(view: Uint8Array): Uint8Array;
+export type { ResponseData, LoopbackStreamFlow };
+/**
+ * Interface for virtual servers that can be registered with the bridge
+ */
+export interface IVirtualServer {
+    listening: boolean;
+    /** What `net.Server.address()` answers: an address and a port, or the PATH of a unix-domain socket. */
+    address(): {
+        port: number;
+        address: string;
+        family: string;
+    } | string | null;
+    handleRequest(method: string, url: string, headers: Record<string, string>, body?: Uint8Array | string): Promise<ResponseData>;
+}
+export interface VirtualServer {
+    /**
+     * A server the host registered and answers itself, or null for a guest's
+     * own: a guest's server is a port this engine is listening on, and it is
+     * reached by connecting to it like any other client.
+     */
+    server: IVirtualServer | null;
+    port: number;
+    hostname: string;
+}
+export interface BridgeOptions {
+    baseUrl?: string;
+    onServerReady?: (port: number, url: string) => void;
+}
+export interface InitServiceWorkerOptions {
+    /**
+     * The URL path to the service worker file
+     * @default '/__sw__.js'
+     */
+    swUrl?: string;
+    /**
+     * The page's own documents that are frames of it (a sandbox, a worker
+     * host), by path, so the worker does not take one for the preview's.
+     */
+    ownDocuments?: string[];
+}
+type Listener = (...args: any[]) => void;
+/** The events a bridge announces, `server-ready` and `sw-ready`, without Node's EventEmitter. */
+declare class BridgeEvents {
+    private readonly listenersByEvent;
+    on(event: string | symbol, listener: Listener): this;
+    addListener(event: string | symbol, listener: Listener): this;
+    once(event: string | symbol, listener: Listener): this;
+    off(event: string | symbol, listener: Listener): this;
+    removeListener(event: string | symbol, listener: Listener): this;
+    removeAllListeners(event?: string | symbol): this;
+    listenerCount(event: string | symbol): number;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+}
+/**
+ * Server Bridge manages virtual HTTP servers and routes requests
+ */
+export declare class PortBridge extends BridgeEvents {
+    static DEBUG: boolean;
+    servers: Map<number, VirtualServer>;
+    private baseUrl;
+    private options;
+    private messageChannel;
+    private serviceWorkerReady;
+    private keepaliveInterval;
+    constructor(options?: BridgeOptions);
+    /**
+     * Give back everything this bridge opened: the service worker keepalive,
+     * and in an engine's bridge its upgrade channel. A host that is done with a
+     * container calls it and has its process back; calling it twice is nothing.
+     */
+    close(): void;
+    /**
+     * Register a server on a port
+     */
+    registerServer(server: IVirtualServer | null, port: number, hostname?: string): void;
+    /**
+     * Unregister a server
+     */
+    unregisterServer(port: number): void;
+    /** The server the service worker answers at the origin's root, the preview's; null for none. */
+    private primaryPort;
+    /**
+     * Names the server the service worker serves at the origin's root, as an
+     * app is served at its own origin's root: its documents read their routes
+     * from `location.pathname`, which under /__virtual__/<port>/ is not the
+     * path they expect. Told to the worker now and again whenever the worker
+     * is (re)initialized, since a worker that restarted remembers nothing.
+     */
+    setPrimaryPort(port: number | null): void;
+    /** Every registration the worker should hold, sent again to a worker that was (re)initialized. */
+    private announceServers;
+    private ownDocuments;
+    /**
+     * Get server URL for a port
+     */
+    getServerUrl(port: number): string;
+    /**
+     * Get all registered server ports
+     */
+    getServerPorts(): number[];
+    /**
+     * Handle an incoming request from Service Worker
+     */
+    handleRequest(port: number, method: string, url: string, headers: Record<string, string>, body?: ArrayBuffer): Promise<ResponseData>;
+    /**
+     * Initialize Service Worker communication
+     * @param options - Configuration options for the service worker
+     * @param options.swUrl - Custom URL path to the service worker file (default: '/__sw__.js')
+     */
+    initServiceWorker(options?: InitServiceWorkerOptions): Promise<void>;
+    /**
+     * Handle messages from Service Worker
+     */
+    private handleServiceWorkerMessage;
+    /**
+     * Handle a streaming request - sends chunks as they arrive
+     */
+    /**
+     * A page-side request streamed to the caller as it arrives, the door a host
+     * reads a guest's server through when it wants chunks rather than a body:
+     * a guest's own server is reached over the loopback as any client reaches
+     * it; a server the host registered answers through its own streaming
+     * method where it has one, else its buffered answer is delivered whole.
+     */
+    handleStreamingRequest(port: number, method: string, url: string, headers: Record<string, string>, body: ArrayBuffer | undefined, callbacks: {
+        start(statusCode: number, statusMessage: string, headers: Record<string, string>): void;
+        chunk(chunk: Uint8Array): void;
+        end(): void;
+    }, flow?: LoopbackStreamFlow): Promise<boolean>;
+    private streamToServiceWorker;
+    /**
+     * Send message to Service Worker
+     */
+    private notifyServiceWorker;
+    /** Flow-controlled requests in flight: a pull is one chunk's credit, a cancel ends the upstream. */
+    private readonly controlledStreams;
+    /**
+     * A request the worker sent under flow control: the response starts with
+     * its head, then goes one chunk (at most FLOW_MAX_CHUNK_BYTES) for each
+     * `stream-pull`, and ends with `stream-end` once the server finished and
+     * every chunk went out. The upstream connection is paused while chunks wait
+     * for credit, so a slow reader holds the server back; `stream-cancel` ends it.
+     */
+    private controlledStream;
+    /**
+     * Create a mock request handler for testing without Service Worker
+     */
+    createFetchHandler(): (request: Request) => Promise<Response>;
+    /**
+     * Whether a registration is a guest's own listener, answered over the
+     * engine's loopback rather than by a server object the host registered. A
+     * bridge with no engine in its realm has none: every server it holds was
+     * registered by the host, a worker's proxies among them.
+     */
+    protected isGuest(entry: VirtualServer): boolean;
+    /** A request to a guest's listener, over the engine's loopback. */
+    protected requestGuest(port: number, _method: string, _url: string, _headers: Record<string, string>, _body: Uint8Array | undefined): Promise<ResponseData>;
+    /** A guest's answer streamed off its connection as it arrives. */
+    protected streamGuest(port: number, _method: string, _url: string, _headers: Record<string, string>, _body: Uint8Array | undefined, _onStart: (statusCode: number, statusMessage: string, headers: Record<string, string>) => void, _onChunk: (chunk: Uint8Array) => void, _onEnd: () => void, _flow?: LoopbackStreamFlow): Promise<void>;
+    /** A request's body as the servers of this realm read it. */
+    protected bodyOf(bytes: Uint8Array): Uint8Array;
+}
+/** Get or create this realm's port bridge, for a page whose engine, if any, runs elsewhere. */
+export declare function getPortBridge(options?: BridgeOptions): PortBridge;

package/dist/port-bridge.mjs

@@ -0,0 +1,6 @@
+import { P, g, o } from "./port-bridge-CixAESwA.js";
+export {
+  P as PortBridge,
+  g as getPortBridge,
+  o as ownedBytes
+};

package/dist/server-bridge.d.ts

@@ -3,62 +3,12 @@
  * Connects Service Worker requests to virtual HTTP servers
  */
 import { type ResponseData, type LoopbackStreamFlow } from './node-lib/http-bridge';
-import { EventEmitter } from './node-lib/events-module';
-/**
- * Interface for virtual servers that can be registered with the bridge
- */
-export interface IVirtualServer {
-    listening: boolean;
-    /** What `net.Server.address()` answers: an address and a port, or the PATH of a unix-domain socket. */
-    address(): {
-        port: number;
-        address: string;
-        family: string;
-    } | string | null;
-    handleRequest(method: string, url: string, headers: Record<string, string>, body?: Buffer | string): Promise<ResponseData>;
-}
-export interface VirtualServer {
-    /**
-     * A server the host registered and answers itself, or null for a guest's
-     * own: a guest's server is a port this engine is listening on, and it is
-     * reached by connecting to it like any other client.
-     */
-    server: IVirtualServer | null;
-    port: number;
-    hostname: string;
-}
-export interface BridgeOptions {
-    baseUrl?: string;
-    onServerReady?: (port: number, url: string) => void;
-}
-export interface InitServiceWorkerOptions {
-    /**
-     * The URL path to the service worker file
-     * @default '/__sw__.js'
-     */
-    swUrl?: string;
-    /**
-     * The page's own documents that are frames of it (a sandbox, a worker
-     * host), by path, so the worker does not take one for the preview's.
-     */
-    ownDocuments?: string[];
-}
-export declare class ServerBridge extends EventEmitter {
-    static DEBUG: boolean;
-    servers: Map<number, VirtualServer>;
-    private baseUrl;
-    private options;
-    private messageChannel;
+import { PortBridge, type VirtualServer, type BridgeOptions } from './port-bridge';
+export type { IVirtualServer, VirtualServer, BridgeOptions, InitServiceWorkerOptions } from './port-bridge';
+export declare class ServerBridge extends PortBridge {
     /** The upgrade channel this bridge opened, held so it can be given back. */
     private upgradeChannel;
-    private serviceWorkerReady;
-    private keepaliveInterval;
     constructor(options?: BridgeOptions);
-    /**
-     * Give back everything this bridge opened: the upgrade channel and the
-     * service worker keepalive. A host that is done with a container calls it
-     * and has its process back; calling it twice is nothing.
-     */
     /**
      * Every port a guest starts listening on becomes a server this bridge can
      * answer for, and every port it stops listening on stops being one. The
@@ -68,83 +18,12 @@ export declare class ServerBridge extends EventEmitter {
     private readonly guestServers;
     private watchGuestPorts;
     close(): void;
-    /**
-     * Register a server on a port
-     */
-    registerServer(server: IVirtualServer | null, port: number, hostname?: string): void;
-    /**
-     * Unregister a server
-     */
-    unregisterServer(port: number): void;
-    /** The server the service worker answers at the origin's root, the preview's; null for none. */
-    private primaryPort;
-    /**
-     * Names the server the service worker serves at the origin's root, as an
-     * app is served at its own origin's root: its documents read their routes
-     * from `location.pathname`, which under /__virtual__/<port>/ is not the
-     * path they expect. Told to the worker now and again whenever the worker
-     * is (re)initialized, since a worker that restarted remembers nothing.
-     */
-    setPrimaryPort(port: number | null): void;
-    /** Every registration the worker should hold, sent again to a worker that was (re)initialized. */
-    private announceServers;
-    private ownDocuments;
-    /**
-     * Get server URL for a port
-     */
-    getServerUrl(port: number): string;
-    /**
-     * Get all registered server ports
-     */
-    getServerPorts(): number[];
-    /**
-     * Handle an incoming request from Service Worker
-     */
-    handleRequest(port: number, method: string, url: string, headers: Record<string, string>, body?: ArrayBuffer): Promise<ResponseData>;
-    /**
-     * Initialize Service Worker communication
-     * @param options - Configuration options for the service worker
-     * @param options.swUrl - Custom URL path to the service worker file (default: '/__sw__.js')
-     */
-    initServiceWorker(options?: InitServiceWorkerOptions): Promise<void>;
-    /**
-     * Handle messages from Service Worker
-     */
-    private handleServiceWorkerMessage;
-    /**
-     * Handle a streaming request - sends chunks as they arrive
-     */
-    /**
-     * A page-side request streamed to the caller as it arrives, the door a host
-     * reads a guest's server through when it wants chunks rather than a body:
-     * a guest's own server is reached over the loopback as any client reaches
-     * it; a server the host registered answers through its own streaming
-     * method where it has one, else its buffered answer is delivered whole.
-     */
-    handleStreamingRequest(port: number, method: string, url: string, headers: Record<string, string>, body: ArrayBuffer | undefined, callbacks: {
-        start(statusCode: number, statusMessage: string, headers: Record<string, string>): void;
-        chunk(chunk: Uint8Array): void;
-        end(): void;
-    }, flow?: LoopbackStreamFlow): Promise<boolean>;
-    private streamToServiceWorker;
-    /**
-     * Send message to Service Worker
-     */
-    private notifyServiceWorker;
-    /** Flow-controlled requests in flight: a pull is one chunk's credit, a cancel ends the upstream. */
-    private readonly controlledStreams;
-    /**
-     * A request the worker sent under flow control: the response starts with
-     * its head, then goes one chunk (at most FLOW_MAX_CHUNK_BYTES) for each
-     * `stream-pull`, and ends with `stream-end` once the server finished and
-     * every chunk went out. The upstream connection is paused while chunks wait
-     * for credit, so a slow reader holds the server back; `stream-cancel` ends it.
-     */
-    private controlledStream;
-    /**
-     * Create a mock request handler for testing without Service Worker
-     */
-    createFetchHandler(): (request: Request) => Promise<Response>;
+    /** A guest's listener (the old null sentinel, now a request adapter) is answered over the loopback. */
+    protected isGuest(entry: VirtualServer): boolean;
+    protected requestGuest(port: number, method: string, url: string, headers: Record<string, string>, body: Uint8Array | undefined): Promise<ResponseData>;
+    protected streamGuest(port: number, method: string, url: string, headers: Record<string, string>, body: Uint8Array | undefined, onStart: (statusCode: number, statusMessage: string, headers: Record<string, string>) => void, onChunk: (chunk: Uint8Array) => void, onEnd: () => void, flow?: LoopbackStreamFlow): Promise<void>;
+    /** A server of this engine reads a request's body as Node's Buffer. */
+    protected bodyOf(bytes: Uint8Array): Uint8Array;
 }
 /**
  * Get or create the global server bridge

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/tabnode",
-  "version": "0.5.26",
+  "version": "0.5.28",
   "description": "Node's own library, in a browser tab.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,10 @@
     "./vite": {
       "types": "./dist/vite-plugin.d.ts",
       "default": "./dist/vite-plugin.mjs"
+    },
+    "./port-bridge": {
+      "types": "./dist/port-bridge.d.ts",
+      "default": "./dist/port-bridge.mjs"
     }
   },
   "files": [

package/src/index.ts

@@ -36,6 +36,7 @@ export { utilModule as util } from './node-lib/util-module';
 export * as npm from './npm';
 export { PackageManager, install } from './npm';
 export { ServerBridge, getServerBridge, resetServerBridge } from './server-bridge';
+export { PortBridge, getPortBridge } from './port-bridge';
 export type { InitServiceWorkerOptions } from './server-bridge';
 /** What a page's request is answered with, the shape the bridge answers. */
 export type { ResponseData, LoopbackStreamFlow } from './node-lib/http-bridge';