@statewalker/webrun-http-browser 0.3.4 → 0.4.2

package/README.md

@@ -30,6 +30,15 @@ the raw platform APIs, and this package fills them:
 Combining both modes means the same handler code works in an app you
 control *and* in an embed you don't.
 
+## Install
+
+```sh
+npm install @statewalker/webrun-http-browser
+```
+
+Browser-only — it needs `navigator.serviceWorker`, so a secure context
+(`https://` or `localhost`) is required. No peer dependencies.
+
 ## How to use
 
 ```sh
@@ -38,7 +47,7 @@ npm install @statewalker/webrun-http-browser
 
 | Subpath | Purpose |
 | --- | --- |
-| `@statewalker/webrun-http-browser` | Page-side relay API: `newRemoteRelayChannel`, `initHttpService`, `callHttpService`, `splitServiceUrl`, `initServiceWorker`, `newServiceWorkerPort`, `getRelayWindowMessageHandler`; the MessagePort call primitives (`callChannel`, `handleChannelCalls`, `newInvokationChannel`, `sendStream`, `handleStreams`, `newRegistry`); plus everything re-exported from `@statewalker/webrun-http-streams` (`HttpError`, the client/server stubs) and `@statewalker/webrun-streams` (stream and error helpers) |
+| `@statewalker/webrun-http-browser` | Page-side relay API: `newRemoteRelayChannel`, `initHttpService`, `callHttpService`, `splitServiceUrl`, `initServiceWorker`, `newServiceWorkerPort`, `getRelayWindowMessageHandler`; the MessagePort call primitives (`callChannel`, `handleChannelCalls`, `newInvokationChannel`, `sendStream`, `handleStreams`, `newRegistry`); plus everything re-exported from `@statewalker/webrun-http-streams` (`HttpError`, the client/server stubs), `@statewalker/webrun-streams` (stream and error helpers) and the `MessageTarget` family from `@statewalker/webrun-rpc` |
 | `@statewalker/webrun-http-browser/sw` | Same-origin adapter classes: `SwHttpAdapter` (page), `SwHttpDispatcher` (SW), `startHttpDispatcher` bootstrap |
 | `@statewalker/webrun-http-browser/relay-sw` | IIFE bundle of the relay SW runtime — load via `importScripts` from a loader script in your relay origin |
 | `@statewalker/webrun-http-browser/sw-worker` | IIFE bundle of the same-origin SW runtime — ditto, for same-origin apps |
@@ -215,6 +224,82 @@ Why it's interesting:
   no tooling. Shows how small the glue between a platform API and a
   `(Request) ⇒ Response` handler can be.
 
+## Exports
+
+The package root re-exports everything from
+[`@statewalker/webrun-streams`](../webrun-streams) and
+[`@statewalker/webrun-http-streams`](../webrun-http-streams), so existing
+imports keep working after those extractions. Its own surface is below.
+
+### Relay mode
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `newRemoteRelayChannel(opts?)` | function | Embeds the hidden relay iframe, handshakes a `MessageChannel`, resolves a `RemoteRelayChannel`. |
+| `RemoteRelayChannelOptions` | interface | `baseUrl`, `url`, `container` — where the relay lives and what to append the iframe to. |
+| `RemoteRelayChannel` | interface | `{ baseUrl, port, close() }`. |
+| `initHttpService(handler, opts)` | function | Registers `handler` as the server for a service `key` on the relay. Returns a cleanup. |
+| `callHttpService(request, opts)` | function | Sends a `Request` to the service under `key`; resolves its `Response`. |
+| `ServiceOptions` | interface | `{ key: string; port: MessageTarget }` — shared by the two above. |
+| `getRelayWindowMessageHandler(opts?)` | function | The `window.onmessage` handler that runs *inside* the relay iframe. |
+| `RelayWindowHandlerOptions` | interface | `swUrl`, `scopeUrl` for that handler. |
+| `splitServiceUrl(url, separator?)` | function | Splits a relay URL into service key + remaining path (default separator `~`). |
+| `SplitServiceUrl` | interface | Its result shape. |
+
+### ServiceWorker lifecycle
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `initServiceWorker(opts)` | function | Registers a SW and resolves once it is activated **and controlling the page**. |
+| `InitServiceWorkerOptions` | interface | `{ swUrl, scopeUrl?, type? }`. |
+| `newServiceWorkerPort()` | function | A `MessagePort` that transparently bridges to the controlling SW. |
+
+### Connection registry
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `initializeConnection(opts)` | function | Sends `CONNECT` for a service `key`; resolves a `MessagePort`, or `null` if no such service. |
+| `InitializeConnectionOptions` | interface | `{ key, communicationPort, ...extra }` — extra fields ride along in the CONNECT payload. |
+| `registerConnectionsHandler(opts)` | function | Registers a `key` and answers inbound `CONNECT`s. Returns a cleanup that unregisters. |
+| `RegisterConnectionsHandlerOptions` | interface | `{ key, handler, communicationPort }`. |
+
+### Messaging primitives
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `callChannel(target, type, data, port?)` | function | One typed request/response over a `MessageTarget`. |
+| `handleChannelCalls(target, type, handler)` | function | Answer those calls. Returns an unsubscribe. |
+| `ChannelCallHandler` | type | The handler signature the two above exchange. |
+| `newInvokationChannel(opts)` | function | Multiplexed invocations over one target. |
+| `InvocationChannel` / `NewInvocationChannelOptions` | interface | Its result and options. |
+| `handleStreams(...)` / `StreamHandler<T>` | function / type | Stream-shaped invocations over the same channel. |
+
+> **These stream primitives have no backpressure.** `sendStream`'s chunk sender
+> discards the promise it is handed, so a fast producer over a slow consumer
+> accumulates without bound; there is also no per-stream timeout and no chunking
+> to a transport's message ceiling. `@statewalker/webrun-rpc`'s `duplexOverPort`
+> is the replacement — one `Duplex` over one port, with the confirmation
+> withheld until the consumer has pulled. Migrating this package onto it is
+> planned, not done.
+| `MessageTarget` / `MessageSource` / `MessageSink` / `MessageListener` | interface / type | The structural port view everything above accepts — a `MessagePort`, a `Worker`, or a SW bridge. Defined in [`@statewalker/webrun-streams`](../webrun-streams) and re-exported here. |
+| `newRegistry(onError?)` | function | Small cleanup registry used for teardown. |
+| `Registry` / `NewRegistryResult` / `CleanupAction` | interface / type | Its shapes. |
+
+### HTTP over a port
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `sendHttpRequest(port, request)` | function | **Deprecated.** Ship a `Request` over a `MessageTarget`, await the `Response`. |
+| `handleHttpRequests(port, handler)` | function | **Deprecated.** Serve an `HttpHandler` on the other end of one. |
+
+### Subpath entry points
+
+| Entry | Purpose |
+| --- | --- |
+| `@statewalker/webrun-http-browser/sw` | `SwHttpAdapter` — the same-origin ServiceWorker adapter. |
+| `@statewalker/webrun-http-browser/relay-sw` | IIFE relay SW runtime, loadable via `importScripts(...)`. |
+| `@statewalker/webrun-http-browser/sw-worker` | IIFE same-origin SW runtime, loadable via `importScripts(...)`. |
+
 ## Internals
 
 ### Source layout
@@ -340,4 +425,4 @@ root).
 
 ## License
 
-MIT © statewalker
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/core/data-channels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-channels.d.ts","sourceRoot":"","sources":["../../src/core/data-channels.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAqBzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC;IACjE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAAC,EACnC,IAAI,EACJ,OAEC,EACD,OAAuB,EACvB,SAAuC,GACxC,EAAE,2BAA2B,GAAG,iBAAiB,CAoEjD;AAED,wBAAuB,UAAU,CAAC,CAAC,EACjC,iBAAiB,EAAE,aAAa,EAChC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAYlC;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAC7B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAElD,wBAAgB,aAAa,CAAC,CAAC,EAC7B,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,MAAM,IAAI,CAqBZ"}
+{"version":3,"file":"data-channels.d.ts","sourceRoot":"","sources":["../../src/core/data-channels.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAqBzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC;IACjE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAAC,EACnC,IAAI,EACJ,OAEC,EACD,OAAuB,EACvB,SAAuC,GACxC,EAAE,2BAA2B,GAAG,iBAAiB,CAoEjD;AAED,wBAAuB,UAAU,CAAC,CAAC,EACjC,iBAAiB,EAAE,aAAa,EAChC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAmBlC;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAC7B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAElD,wBAAgB,aAAa,CAAC,CAAC,EAC7B,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,MAAM,IAAI,CAqBZ"}

package/dist/core/message-target.d.ts

@@ -1,16 +1,2 @@
-export type MessageListener = (event: MessageEvent) => void | Promise<void>;
-/** An object we can listen for `"message"` events on. */
-export interface MessageSource {
-    addEventListener(type: "message", listener: MessageListener): void;
-    removeEventListener(type: "message", listener: MessageListener): void;
-    start?(): void | Promise<void>;
-}
-/** An object we can post messages to (with optional transferable list). */
-export interface MessageSink {
-    postMessage(message: unknown, transfer?: Transferable[]): void;
-}
-/** Full-duplex message target: both sends and receives. */
-export interface MessageTarget extends MessageSource, MessageSink {
-    close?(): void | Promise<void>;
-}
+export type { MessageListener, MessageSink, MessageSource, MessageTarget, } from "@statewalker/webrun-rpc";
 //# sourceMappingURL=message-target.d.ts.map

package/dist/core/message-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../../src/core/message-target.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACnE,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACtE,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;CAChE;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAc,SAAQ,aAAa,EAAE,WAAW;IAC/D,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}
+{"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../../src/core/message-target.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,GACd,MAAM,yBAAyB,CAAC"}

package/dist/http/http-send-recieve.d.ts

@@ -1,23 +1,36 @@
 import { type HttpHandler } from "@statewalker/webrun-http-streams";
 import type { MessageTarget } from "../core/message-target.js";
 /**
- * @deprecated For new code, prefer the `MessagePort`-based stack from
- * `@statewalker/webrun-http-port`. Once a `MessagePort` is established between
- * page and worker, `httpServe(port, handler)` provides equivalent semantics
- * with `callBidi` multiplexing, full-duplex streaming, and `AbortSignal`.
- * This helper remains for existing ServiceWorker setups that still consume the
- * `MessageTarget` surface; it will be reimplemented on top of
- * `webrun-http-port` in a follow-up release.
+ * Serve an `HttpHandler` over a `MessageTarget`, using this package's own
+ * `handleStreams` transport.
+ *
+ * @deprecated Prefer the port stack in `@statewalker/webrun-rpc`: open a port
+ * (`multiplexPort` over one pipe, or `transferPortMux` where the platform can
+ * transfer a real `MessagePort`), turn it into a `Duplex` with
+ * `serveDuplexOverPort`, and serve HTTP on that with
+ * `httpServe(handler, options)` from `@statewalker/webrun-http-streams`.
+ *
+ * That path has backpressure; **this one does not.** `sendStream`'s chunk
+ * sender discards the promise it is given, so a fast producer over a slow
+ * consumer accumulates without bound. It also has no per-stream timeout and no
+ * chunking to a transport's message ceiling.
+ *
+ * Kept for existing ServiceWorker setups built on the `MessageTarget` surface.
  */
 export declare function handleHttpRequests(communicationPort: MessageTarget, handler: HttpHandler): () => void;
 /**
- * @deprecated For new code, prefer the `MessagePort`-based stack from
- * `@statewalker/webrun-http-port/fetch`. Once the page and SW share a
- * `MessagePort`, `fetchOverPort(port, request)` provides the same
- * `Request → Response` semantics with multiplexing via `callBidi`, JSONL
- * envelope framing, and native `AbortSignal` support. This helper remains for
- * existing ServiceWorker setups; it will be reimplemented on top of
- * `webrun-http-port` in a follow-up release.
+ * Ship a `Request` over a `MessageTarget` and await the `Response`, using this
+ * package's own `sendStream` transport.
+ *
+ * @deprecated Prefer the port stack in `@statewalker/webrun-rpc`: open a port
+ * (`multiplexPort` over one pipe, or `transferPortMux` where the platform can
+ * transfer a real `MessagePort`), turn it into a `Duplex` with
+ * `duplexOverPort`, and drive HTTP over it with `httpFetch` from
+ * `@statewalker/webrun-http-streams`.
+ *
+ * Same caveat as {@link handleHttpRequests}: the transport underneath this
+ * helper has no backpressure, no per-stream timeout, and no chunking to a
+ * transport's message ceiling. Kept for existing ServiceWorker setups.
  */
 export declare function sendHttpRequest(communicationPort: MessageTarget, request: Request): Promise<Response>;
 //# sourceMappingURL=http-send-recieve.d.ts.map

package/dist/http/http-send-recieve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-send-recieve.d.ts","sourceRoot":"","sources":["../../src/http/http-send-recieve.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAMjB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA+B/D;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,WAAW,GACnB,MAAM,IAAI,CAOZ;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,CAAC,CAOnB"}
+{"version":3,"file":"http-send-recieve.d.ts","sourceRoot":"","sources":["../../src/http/http-send-recieve.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAMjB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA+B/D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,WAAW,GACnB,MAAM,IAAI,CAOZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,CAAC,CAOnB"}