@vampgg/utils 1.0.0-beta.7 → 1.0.0-beta.9

package/README.md

@@ -5,6 +5,16 @@ Low-level utilities for building bebop/tempo-based applications. Provides the sh
 - **bebop** — binary serialization library for fast, compact data interchange
 - **tempo** — typed RPC layer built on top of bebop
 
+## Optional peer dependencies
+
+Three entry points need a package that `@vampgg/utils` does not install. Add the one you import:
+
+| Entry point                                                         | Install                 |
+| ------------------------------------------------------------------- | ----------------------- |
+| `@vampgg/utils/pino-logger`                                         | `pino`                  |
+| `@vampgg/utils/ws-channel`                                          | `websocket-ts`          |
+| `@vampgg/utils/extension-channel`, `@vampgg/utils/extension-router` | `webextension-polyfill` |
+
 ## Development
 
 ```bash

package/dist/channel-core.d.mts

@@ -25,8 +25,9 @@ declare abstract class CoreChannel extends BaseChannel {
   /** Per-call response listeners keyed by messageId (response demultiplexing). */
   readonly events: EventEmitter<Record<string, (message: Message) => void>>;
   /**
-   * Reject callbacks for in-flight unary / client-stream calls, keyed by
-   * messageId. Lets close()/error() settle parked requests instead of hanging.
+   * Failure callbacks for every in-flight call (unary, client-stream, and the
+   * server/duplex streams), keyed by messageId. Lets close() and a dropped
+   * connection settle them instead of leaving them parked.
    */
   readonly pending: Map<string, (cause: unknown) => void>;
   protected closed: boolean;
@@ -74,6 +75,12 @@ declare abstract class CoreChannel extends BaseChannel {
    * explicit caller.
    */
   close(reason?: TempoError): void;
+  /**
+   * Fail every in-flight call and stream with `reason` without disposing the
+   * channel. A transport that can reconnect calls this when its connection
+   * drops; the next call reconnects.
+   */
+  protected failInFlight(reason: TempoError): void;
   removeCredential(): Promise<void>;
   getCredential(): Promise<Credential | undefined>;
   /**

package/dist/channel-core.mjs

@@ -25,8 +25,9 @@ var CoreChannel = class extends BaseChannel {
 	/** Per-call response listeners keyed by messageId (response demultiplexing). */
 	events = new EventEmitter();
 	/**
-	* Reject callbacks for in-flight unary / client-stream calls, keyed by
-	* messageId. Lets close()/error() settle parked requests instead of hanging.
+	* Failure callbacks for every in-flight call (unary, client-stream, and the
+	* server/duplex streams), keyed by messageId. Lets close() and a dropped
+	* connection settle them instead of leaving them parked.
 	*/
 	pending = /* @__PURE__ */ new Map();
 	closed = false;
@@ -80,11 +81,20 @@ var CoreChannel = class extends BaseChannel {
 		const err = reason ?? new TempoError(TempoStatusCode.CANCELLED, "channel disposed");
 		this.closeReason = err;
 		this.onClosing(err);
-		for (const reject of this.pending.values()) reject(err);
-		this.pending.clear();
+		this.failInFlight(err);
 		this.events.removeAllListeners();
 		this.closeTransport();
 	}
+	/**
+	* Fail every in-flight call and stream with `reason` without disposing the
+	* channel. A transport that can reconnect calls this when its connection
+	* drops; the next call reconnects.
+	*/
+	failInFlight(reason) {
+		const failures = [...this.pending.values()];
+		this.pending.clear();
+		for (const fail of failures) fail(reason);
+	}
 	async removeCredential() {}
 	async getCredential() {}
 	/**
@@ -180,8 +190,16 @@ var CoreChannel = class extends BaseChannel {
 	fetchServerStream(init, context, method, options) {
 		const messageId = init.messageId;
 		return createEventIterator(({ emit, cancel, error }) => {
+			if (this.closed) {
+				error(this.closeReason ?? new TempoError(TempoStatusCode.CANCELLED, "channel disposed"));
+				return;
+			}
 			let terminated = false;
 			let onAbort;
+			this.pending.set(messageId, (cause) => {
+				terminated = true;
+				error(cause);
+			});
 			const eventHandler = async (message) => {
 				try {
 					if (message.status === TempoStatusCode.CANCELLED) {
@@ -204,6 +222,7 @@ var CoreChannel = class extends BaseChannel {
 			this.events.on(messageId, eventHandler);
 			this.sendFrame(init);
 			return () => {
+				this.pending.delete(messageId);
 				this.events.off(messageId, eventHandler);
 				if (onAbort) options?.controller?.signal.removeEventListener("abort", onAbort);
 				if (terminated || this.closed) return;
@@ -225,8 +244,16 @@ var CoreChannel = class extends BaseChannel {
 				data: this.serializeStreamItem(method, value)
 			}));
 		}, ({ emit, cancel, error }) => {
+			if (this.closed) {
+				error(this.closeReason ?? new TempoError(TempoStatusCode.CANCELLED, "channel disposed"));
+				return;
+			}
 			let terminated = false;
 			let onAbort;
+			this.pending.set(messageId, (cause) => {
+				terminated = true;
+				error(cause);
+			});
 			const eventHandler = async (message) => {
 				try {
 					if (message.status === TempoStatusCode.CANCELLED) {
@@ -248,6 +275,7 @@ var CoreChannel = class extends BaseChannel {
 			}
 			this.events.on(messageId, eventHandler);
 			return () => {
+				this.pending.delete(messageId);
 				this.events.off(messageId, eventHandler);
 				if (onAbort) options?.controller?.signal.removeEventListener("abort", onAbort);
 				if (this.cancelDuplexOnCleanup && !terminated && !this.closed) this.sendFrame(Message({

package/dist/extension-router.mjs

@@ -177,7 +177,6 @@ var TempoExtensionRouter = class extends ExtensionBaseRouter {
 		const send = (message) => this.send(ctx.sender, message);
 		await this.core.processRequest(request, response, ctx, {
 			send,
-			stampErrorResponse: true,
 			decorateResponse: (message) => {
 				message.msg = "";
 			},

package/dist/router-core.d.mts

@@ -47,9 +47,13 @@ interface ProcessTransport {
   invokeServerStream?(request: Message, context: ServerContext, method: BebopMethodAny): Promise<AsyncGenerator<BebopRecord, void, unknown>>;
   /** Mutate the response envelope after the OK headers are populated. */
   decorateResponse?(response: Message): void;
-  /** Stamp messageId/timestamp/methodId from the request onto error frames. */
-  stampErrorResponse?: boolean;
 }
+/**
+ * Returned by the stream invokers for a frame that continues an already-open
+ * client or duplex stream. The frame is delivered to the open invocation, and
+ * no response is sent for it: the call that opened the stream owns the reply.
+ */
+declare const CONTINUATION: unique symbol;
 /** Options for {@link RouterCore.writeStreamFrames}. */
 interface StreamWriteOptions {
   generator: AsyncGenerator<BebopRecord, void, unknown>;
@@ -94,9 +98,9 @@ declare class RouterCore {
   constructor(host: RouterCoreHost);
   private setAuthContext;
   invokeUnaryMethod(request: Message, context: ServerContext, method: BebopMethodAny, contentType: BebopContentType): Promise<BebopRecord>;
-  invokeClientStreamMethod(request: Message, context: ServerContext, method: BebopMethodAny, contentType: BebopContentType): Promise<BebopRecord>;
+  invokeClientStreamMethod(request: Message, context: ServerContext, method: BebopMethodAny, contentType: BebopContentType): Promise<BebopRecord | typeof CONTINUATION>;
   invokeServerStreamMethod(request: Message, context: ServerContext, method: BebopMethodAny, contentType: BebopContentType): Promise<AsyncGenerator<BebopRecord, void, unknown>>;
-  invokeDuplexStreamMethod(request: Message, context: ServerContext, method: BebopMethodAny, contentType: BebopContentType): Promise<AsyncGenerator<BebopRecord, void, unknown>>;
+  invokeDuplexStreamMethod(request: Message, context: ServerContext, method: BebopMethodAny, contentType: BebopContentType): Promise<AsyncGenerator<BebopRecord, void, unknown> | typeof CONTINUATION>;
   /**
    * Emit a synthetic CANCELLED to every in-flight client/duplex stream so its
    * generator ends, and drop the tracking entries (connection teardown).

package/dist/router-core.mjs

@@ -5,6 +5,12 @@ import { EventEmitter } from "tseep";
 import { ServerContext } from "@tempojs/server";
 //#region src/router-core.ts
 /**
+* Returned by the stream invokers for a frame that continues an already-open
+* client or duplex stream. The frame is delivered to the open invocation, and
+* no response is sent for it: the call that opened the stream owns the reply.
+*/
+const CONTINUATION = Symbol("continuation");
+/**
 * Parse the request's custom-metadata header into a {@link Metadata} (the
 * default incoming metadata for the worker/extension routers).
 */
@@ -55,10 +61,9 @@ var RouterCore = class {
 		await this.setAuthContext(request, context);
 		if (this.host.getHooks() !== void 0) await this.host.getHooks().executeRequestHooks(context);
 		const messageId = request.messageId;
-		const stream = this.clientStreams.get(messageId);
-		if (stream) {
+		if (this.clientStreams.has(messageId)) {
 			this.events.emit(messageId, request);
-			return await stream;
+			return CONTINUATION;
 		}
 		const generator = () => {
 			return createEventIterator(({ emit, cancel }) => {
@@ -102,10 +107,9 @@ var RouterCore = class {
 		await this.setAuthContext(request, context);
 		if (this.host.getHooks() !== void 0) await this.host.getHooks().executeRequestHooks(context);
 		const messageId = request.messageId;
-		const stream = this.clientStreams.get(messageId);
-		if (stream) {
+		if (this.clientStreams.has(messageId)) {
 			this.events.emit(messageId, request);
-			return stream;
+			return CONTINUATION;
 		}
 		if (!TempoUtil.isAsyncGeneratorFunction(method.invoke.bind(method))) throw new TempoError(TempoStatusCode.INTERNAL, "service method incorrect: method must be async generator");
 		const generator = () => {
@@ -215,15 +219,21 @@ var RouterCore = class {
 					case MethodType.Unary:
 						record = await this.invokeUnaryMethod(request, serverContext, method, contentType);
 						break;
-					case MethodType.ClientStream:
-						record = await this.invokeClientStreamMethod(request, serverContext, method, contentType);
+					case MethodType.ClientStream: {
+						const result = await this.invokeClientStreamMethod(request, serverContext, method, contentType);
+						if (result === CONTINUATION) return;
+						record = result;
 						break;
+					}
 					case MethodType.ServerStream:
 						recordGenerator = transport.invokeServerStream ? await transport.invokeServerStream(request, serverContext, method) : await this.invokeServerStreamMethod(request, serverContext, method, contentType);
 						break;
-					case MethodType.DuplexStream:
-						recordGenerator = await this.invokeDuplexStreamMethod(request, serverContext, method, contentType);
+					case MethodType.DuplexStream: {
+						const result = await this.invokeDuplexStreamMethod(request, serverContext, method, contentType);
+						if (result === CONTINUATION) return;
+						recordGenerator = result;
 						break;
+					}
 					default: throw new TempoError(TempoStatusCode.INTERNAL, "service method incorrect: unknown method type");
 				}
 				const outgoingCredential = serverContext.outgoingCredential;
@@ -261,19 +271,17 @@ var RouterCore = class {
 				if (e.status === TempoStatusCode.INTERNAL) this.host.logger.critical(e.message, void 0, e);
 				else this.host.logger.error(message, void 0, e);
 			} else if (e instanceof Error) {
-				message = e.message;
-				this.host.logger.error(message, void 0, e);
+				this.host.logger.error(e.message, void 0, e);
+				message = this.host.transmitInternalErrors === true ? e.message : "internal error";
 			}
 			const hooks = this.host.getHooks();
 			if (e instanceof Error && hooks !== void 0) await hooks.executeErrorHooks(context, e);
 			this.clientStreams.delete(request.messageId);
 			response.status = status;
 			response.msg = message;
-			if (transport.stampErrorResponse) {
-				response.messageId = request.messageId;
-				response.timestamp = request.timestamp;
-				response.methodId = request.methodId;
-			}
+			response.messageId = request.messageId;
+			response.timestamp = request.timestamp;
+			response.methodId = request.methodId;
 			await transport.send(response);
 		}
 	}

package/dist/worker-router.mjs

@@ -50,7 +50,6 @@ var TempoWorkerRouter = class extends BaseRouter {
 		};
 		await this.core.processRequest(request, response, env, {
 			send,
-			stampErrorResponse: true,
 			writeStreamFrames: async (generator, resp, method) => {
 				const messageId = request.messageId;
 				const streamInfo = {

package/dist/ws-channel.d.mts

@@ -1,7 +1,6 @@
 import { Message } from "./bebop.mjs";
 import { CoreChannel } from "./channel-core.mjs";
 import { CallCredential, TempoChannelOptions } from "@tempojs/client";
-import * as _tempojs_common0 from "@tempojs/common";
 import { BebopContentType, Credential } from "@tempojs/common";
 import { Websocket, WebsocketOptions } from "websocket-ts";
 
@@ -27,7 +26,7 @@ declare class TempoWSChannel extends CoreChannel {
   private readonly maxSendMessageSize;
   private readonly _url;
   private readonly _wsOptions;
-  get log(): _tempojs_common0.TempoLogger;
+  get log(): import("@tempojs/common").TempoLogger;
   /**
    * Constructs a new TempoChannel instance.
    *

package/dist/ws-channel.mjs

@@ -91,21 +91,21 @@ var TempoWSChannel = class TempoWSChannel extends CoreChannel {
 			this.logger.trace(`opened TempoWSChannel for ${this._url.href} / ${this.userAgent}`);
 		});
 		this.ws.addEventListener(WebsocketEvent.close, (ws) => {
-			if (this.closed) return;
+			if (this.closed || ws !== this.ws) return;
 			if (ws.lastConnection === void 0) return;
 			this.logger.trace(`closed TempoWSChannel for ${this._url.href} / ${this.userAgent}`);
-			this.close(new TempoError(TempoStatusCode.UNAVAILABLE, "channel closed"));
+			this.failInFlight(new TempoError(TempoStatusCode.UNAVAILABLE, "connection closed"));
 		});
 		this.ws.addEventListener(WebsocketEvent.error, (ws) => {
-			if (this.closed) return;
+			if (this.closed || ws !== this.ws) return;
 			if (ws.lastConnection === void 0) return;
-			this.close(new TempoError(TempoStatusCode.UNAVAILABLE, "channel transport error"));
+			this.failInFlight(new TempoError(TempoStatusCode.UNAVAILABLE, "connection error"));
 		});
 		this.ws.addEventListener(WebsocketEvent.message, (_ws, ev) => {
 			const data = ev.data;
 			const byteLength = data instanceof ArrayBuffer ? data.byteLength : data.length;
 			if (byteLength > this.maxReceiveMessageSize) {
-				this.logger.error(`inbound frame ${byteLength}B exceeds maxReceiveMessageSize ${this.maxReceiveMessageSize}B; dropping`);
+				this.failInFlight(new TempoError(TempoStatusCode.RESOURCE_EXHAUSTED, `inbound frame ${byteLength}B exceeds maxReceiveMessageSize ${this.maxReceiveMessageSize}B`));
 				return;
 			}
 			let message;
@@ -153,9 +153,10 @@ var TempoWSChannel = class TempoWSChannel extends CoreChannel {
 				await new Promise((r) => setTimeout(r, 100));
 				this._reconnect();
 			}
+			if (this.closed) throw this.closeReason ?? new TempoError(TempoStatusCode.CANCELLED, "channel disposed");
 			const state = this.ws.readyState;
 			if (state === 1) return;
-			if (state === 2 || state === 3) throw new TempoError(TempoStatusCode.UNAVAILABLE, "socket is closing or closed");
+			if (state === 2 || state === 3) this._reconnect();
 			try {
 				await Deadline.after(5, "seconds").executeWithinDeadline(() => new Promise((resolve, reject) => {
 					const teardown = () => {

package/dist/ws-router.mjs

@@ -107,10 +107,7 @@ var TempoWsRouter = class extends BaseRouter {
 		connection.core.removeAllListeners();
 	}
 	async process(req, response, env) {
-		if (req.byteLength > this.maxReceiveMessageSize) {
-			this.logger.error(`inbound frame ${req.byteLength}B exceeds maxReceiveMessageSize ${this.maxReceiveMessageSize}B; dropping`);
-			return;
-		}
+		if (req.byteLength > this.maxReceiveMessageSize) throw new TempoError(TempoStatusCode.RESOURCE_EXHAUSTED, `inbound frame ${req.byteLength}B exceeds maxReceiveMessageSize ${this.maxReceiveMessageSize}B`);
 		const request = Message.decode(new Uint8Array(req));
 		const [, ws] = env;
 		const connection = this.connection(ws);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vampgg/utils",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "description": "Tempo RPC, Bebop serialization, transports, and async primitives for @vampgg.",
   "homepage": "https://github.com/sammccord/vamp/tree/main/packages/utils#readme",
   "bugs": {
@@ -44,10 +44,7 @@
     "@tempojs/common": "^0.0.12",
     "@tempojs/server": "^0.0.12",
     "bebop": "3.2.3",
-    "pino": "^10.3.1",
-    "tseep": "^1.3.1",
-    "webextension-polyfill": "^0.12.0",
-    "websocket-ts": "^2.2.1"
+    "tseep": "^1.3.1"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
@@ -55,9 +52,28 @@
     "@types/webextension-polyfill": "^0.12.5",
     "@typescript/native-preview": "7.0.0-dev.20260315.1",
     "bebop-tools": "^3.2.3",
+    "pino": "^10.3.1",
     "typescript": "^5.9.3",
     "vite-plus": "^0.1.24",
-    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.24",
+    "webextension-polyfill": "^0.12.0",
+    "websocket-ts": "^2.2.1"
+  },
+  "peerDependencies": {
+    "pino": "^10.3.1",
+    "webextension-polyfill": "^0.12.0",
+    "websocket-ts": "^2.2.1"
+  },
+  "peerDependenciesMeta": {
+    "pino": {
+      "optional": true
+    },
+    "webextension-polyfill": {
+      "optional": true
+    },
+    "websocket-ts": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "bebopc build && vp pack",