@vampgg/utils 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/extension-router.mjs

@@ -1,9 +1,8 @@
 import { Message } from "./bebop.mjs";
-import { createEventIterator } from "./create-event-iterator.mjs";
-import { Deadline, Metadata, MethodType, TempoError, TempoStatusCode, TempoUtil, TempoVersion, stringifyCredential } from "@tempojs/common";
-import { EventEmitter } from "tseep";
-import { tabs } from "webextension-polyfill";
-import { ServerContext, TempoRouterConfiguration } from "@tempojs/server";
+import { RouterCore } from "./router-core.mjs";
+import { Metadata, TempoError, TempoStatusCode, TempoUtil, TempoVersion } from "@tempojs/common";
+import { runtime, tabs } from "webextension-polyfill";
+import { TempoRouterConfiguration } from "@tempojs/server";
 //#region src/extension-router.ts
 /**
 * Interface defining the configuration options for a TempoRouter instance.
@@ -39,6 +38,10 @@ var TempoExtensionRouterConfiguration = class {
 	*/
 	maxRetryAttempts;
 	/**
+	* Optional flag to indicate whether the tempo version, runtime, and variant should be exposed in responses via X-Powered-By (and if the GET endpoint should be enabled). Defaults to false.
+	*/
+	exposeTempo;
+	/**
 	* Constructs a new instance of TempoRouterConfiguration with default values.
 	*/
 	constructor() {
@@ -146,230 +149,80 @@ var ExtensionBaseRouter = class {
 	}
 };
 var TempoExtensionRouter = class extends ExtensionBaseRouter {
-	events = new EventEmitter();
-	clientStreams = /* @__PURE__ */ new Map();
+	core;
 	constructor(logger, registry, configuration = new TempoRouterConfiguration(), authInterceptor) {
 		super(logger, registry, configuration, authInterceptor);
-	}
-	async setAuthContext(request, context) {
-		const authHeader = request.authorization;
-		if (authHeader !== void 0 && this.authInterceptor !== void 0) {
-			const authContext = await this.authInterceptor.intercept(context, authHeader);
-			if (authContext !== void 0) context.authContext = authContext;
-		}
-	}
-	async invokeUnaryMethod(request, context, method) {
-		await this.setAuthContext(request, context);
-		if (this.hooks !== void 0) await this.hooks.executeRequestHooks(context);
-		const record = this.deserializeRequest(request.data, method, "bebop");
-		if (this.hooks !== void 0) await this.hooks.executeDecodeHooks(context, record);
-		return await method.invoke(record, context);
-	}
-	async invokeClientStreamMethod(request, context, method) {
-		await this.setAuthContext(request, context);
-		if (this.hooks !== void 0) await this.hooks.executeRequestHooks(context);
-		const messageId = request.messageId;
-		if (this.clientStreams.has(messageId)) {
-			const invocation = this.clientStreams.get(messageId);
-			this.events.emit(messageId, request);
-			return await invocation;
-		}
-		const generator = () => {
-			return createEventIterator(({ emit, cancel }) => {
-				const eventHandler = async (message) => {
-					if (this.hooks !== void 0) await this.hooks.executeRequestHooks(context);
-					if (message.status === TempoStatusCode.CANCELLED) {
-						cancel();
-						return;
-					}
-					const requestData = message.data;
-					const record = this.deserializeRequest(requestData, method, "bebop");
-					if (this.hooks !== void 0) await this.hooks.executeDecodeHooks(context, record);
-					emit(record);
-				};
-				this.events.on(messageId, eventHandler);
-				return () => {
-					this.events.off(messageId, eventHandler);
-					this.clientStreams.delete(messageId);
-				};
-			});
-		};
-		const invocation = method.invoke(generator, context);
-		this.clientStreams.set(messageId, invocation);
-		this.events.emit(messageId, request);
-		return await invocation.finally(() => {
-			this.clientStreams.delete(messageId);
+		this.core = new RouterCore({
+			logger,
+			maxRetryAttempts: this.maxRetryAttempts,
+			transmitInternalErrors: this.transmitInternalErrors,
+			authInterceptor,
+			getMethod: (methodId) => this.registry.getMethod(methodId),
+			getHooks: () => this.hooks,
+			deserializeRequest: (data, method, contentType) => this.deserializeRequest(data, method, contentType),
+			serializeResponse: (record, method, contentType) => this.serializeResponse(record, method, contentType)
 		});
 	}
-	async invokeServerStreamMethod(request, context, method) {
-		await this.setAuthContext(request, context);
-		if (this.hooks !== void 0) await this.hooks.executeRequestHooks(context);
-		const requestData = request.data;
-		const record = this.deserializeRequest(requestData, method, "bebop");
-		if (!TempoUtil.isAsyncGeneratorFunction(method.invoke.bind(method))) throw new TempoError(TempoStatusCode.INTERNAL, "service method incorrect: method must be async generator");
-		if (this.hooks !== void 0) await this.hooks.executeDecodeHooks(context, record);
-		return method.invoke(record, context);
-	}
-	async invokeDuplexStreamMethod(request, context, method) {
-		await this.setAuthContext(request, context);
-		if (this.hooks !== void 0) await this.hooks.executeRequestHooks(context);
-		const messageId = request.messageId;
-		if (this.clientStreams.has(messageId)) {
-			const invocation = this.clientStreams.get(messageId);
-			this.events.emit(messageId, request);
-			return invocation;
-		}
-		if (!TempoUtil.isAsyncGeneratorFunction(method.invoke.bind(method))) throw new TempoError(TempoStatusCode.INTERNAL, "service method incorrect: method must be async generator");
-		const generator = () => {
-			return createEventIterator(({ emit, cancel }) => {
-				const eventHandler = async (message) => {
-					if (this.hooks !== void 0) await this.hooks.executeRequestHooks(context);
-					if (message.status === TempoStatusCode.CANCELLED) {
-						cancel();
-						return;
-					}
-					const requestData = message.data;
-					const record = this.deserializeRequest(requestData, method, "bebop");
-					if (this.hooks !== void 0) await this.hooks.executeDecodeHooks(context, record);
-					emit(record);
-				};
-				this.events.on(messageId, eventHandler);
-				this.events.emit(messageId, request);
-				return () => {
-					this.events.off(messageId, eventHandler);
-					this.clientStreams.delete(messageId);
-				};
-			});
-		};
-		const invocation = method.invoke(generator, context);
-		this.clientStreams.set(messageId, invocation);
-		return invocation;
-	}
 	/**
 	* Tear down all open streams for this connection. Emits a synthetic CANCELLED
 	* to each in-flight client/duplex stream so its generator ends, then clears
 	* all listeners.
 	*/
 	async closeConnection() {
-		for (const id of [...this.clientStreams.keys()]) {
-			this.events.emit(id, Message({
-				messageId: id,
-				status: TempoStatusCode.CANCELLED,
-				data: new Uint8Array()
-			}));
-			this.clientStreams.delete(id);
-		}
-		this.events.removeAllListeners();
+		this.core.cancelClientStreams();
+		this.core.removeAllListeners();
 	}
 	async process(req, response, ctx) {
-		let request = Message(req);
-		let context;
-		try {
-			const methodId = request.methodId;
-			const method = this.registry.getMethod(methodId);
-			if (!method) throw new TempoError(TempoStatusCode.NOT_FOUND, `no service is registered which contains a method of '${methodId}'`);
-			const metadataHeader = request.customMetadata;
-			const metadata = metadataHeader ? Metadata.fromHttpHeader(metadataHeader) : new Metadata();
-			const previousAttempts = request.previousAttempts;
-			if (previousAttempts !== void 0 && previousAttempts > this.maxRetryAttempts) throw new TempoError(TempoStatusCode.RESOURCE_EXHAUSTED, "max retry attempts exceeded");
-			let deadline;
-			const deadlineHeader = request.deadline;
-			if (deadlineHeader !== void 0) deadline = Deadline.fromUnixTimestamp(deadlineHeader.valueOf());
-			if (deadline !== void 0 && deadline.isExpired()) throw new TempoError(TempoStatusCode.DEADLINE_EXCEEDED, "incoming request has already exceeded its deadline");
-			const outgoingMetadata = new Metadata();
-			const incomingContext = {
-				headers: new Headers(),
-				metadata
-			};
-			if (deadline !== void 0) incomingContext.deadline = deadline;
-			context = new ServerContext(incomingContext, { metadata: outgoingMetadata }, ctx);
-			const handleRequest = async () => {
-				let recordGenerator = void 0;
-				let record;
-				switch (method.type) {
-					case MethodType.Unary:
-						record = await this.invokeUnaryMethod(request, context, method);
-						break;
-					case MethodType.ClientStream:
-						record = await this.invokeClientStreamMethod(request, context, method);
-						break;
-					case MethodType.ServerStream:
-						recordGenerator = await this.invokeServerStreamMethod(request, context, method);
-						break;
-					case MethodType.DuplexStream:
-						recordGenerator = await this.invokeDuplexStreamMethod(request, context, method);
-						break;
-					default: throw new TempoError(TempoStatusCode.INTERNAL, "service method incorrect: unknown method type");
-				}
-				const outgoingCredential = context.outgoingCredential;
-				if (outgoingCredential) response.credential = stringifyCredential(outgoingCredential);
-				response.methodId = request.methodId;
-				response.messageId = request.messageId;
-				response.status = TempoStatusCode.OK;
-				response.timestamp = /* @__PURE__ */ new Date();
-				response.msg = "";
-				if (this.hooks !== void 0) await this.hooks.executeResponseHooks(context);
-				outgoingMetadata.freeze();
-				if (outgoingMetadata.size() > 0) response.customMetadata = outgoingMetadata.data;
-				if (recordGenerator !== void 0) {
-					const writeFrames = async () => {
-						for await (const value of recordGenerator) {
-							const responseData = this.serializeResponse(value, method, "bebop");
-							response.data = new Uint8Array(responseData);
-							await this.send(ctx.sender, response);
-						}
-						response.data = new Uint8Array();
-						response.status = TempoStatusCode.CANCELLED;
-						await this.send(ctx.sender, response);
-					};
-					if (deadline) await deadline.executeWithinDeadline(writeFrames);
-					else await writeFrames();
-				} else {
-					if (record === void 0) throw new TempoError(TempoStatusCode.INTERNAL, "service method did not return a record");
-					const responseData = this.serializeResponse(record, method, "bebop");
-					response.data = new Uint8Array(responseData);
-					await this.send(ctx.sender, response);
-				}
-			};
-			if (deadline !== void 0) await deadline.executeWithinDeadline(handleRequest);
-			else await handleRequest();
-		} catch (e) {
-			let status = TempoStatusCode.UNKNOWN;
-			let message = "unknown error";
-			if (e instanceof TempoError) {
-				status = e.status;
-				message = e.message;
-				if (e.status === TempoStatusCode.INTERNAL && this.transmitInternalErrors !== true) message = "internal error";
-				if (e.status === TempoStatusCode.INTERNAL) this.logger.critical(e.message, void 0, e);
-				else this.logger.error(message, void 0, e);
-			} else if (e instanceof Error) {
-				message = e.message;
-				this.logger.error(message, void 0, e);
-			}
-			if (e instanceof Error && this.hooks !== void 0) await this.hooks.executeErrorHooks(context, e);
-			this.clientStreams.delete(request.messageId);
-			response.status = status;
-			response.msg = message;
-			response.messageId = request.messageId;
-			response.timestamp = request.timestamp;
-			response.methodId = request.methodId;
-			await this.send(ctx.sender, response);
-		}
+		const request = Message(req);
+		const send = (message) => this.send(ctx.sender, message);
+		await this.core.processRequest(request, response, ctx, {
+			send,
+			stampErrorResponse: true,
+			decorateResponse: (message) => {
+				message.msg = "";
+			},
+			writeStreamFrames: (generator, resp, method) => this.core.writeStreamFrames({
+				generator,
+				response: resp,
+				method,
+				send
+			})
+		});
 	}
 	async send(sender, message) {
-		if (!sender.tab?.id || sender.tab?.discarded === true) {
-			this.logger.warn(`ignoring message to discarded tab`, { tab: sender.tab });
-			return;
-		}
+		const payload = Array.from(Message.encode(message));
 		try {
-			await tabs.sendMessage(sender.tab.id, Array.apply(null, Message.encode(message)));
+			if (sender.tab?.id !== void 0 && sender.tab.discarded !== true) await tabs.sendMessage(sender.tab.id, payload);
+			else await runtime.sendMessage(payload);
 		} catch (e) {
-			this.logger.error("failed to send message, tab is likely inactive", {}, e);
+			this.logger.debug("extension reply not delivered; receiver likely gone", { tab: sender.tab }, e);
 		}
 	}
 	async handle(_req, _ctx) {
 		return Message({});
 	}
 };
+/**
+* Inbound guard + dispatch for the background/service-worker `runtime.onMessage`
+* hook, which the router does not install itself. Only frames from this
+* extension that decode to a Message with a registered methodId are processed;
+* everything else (other extensions, reply frames, malformed traffic) is
+* ignored. Replies travel back through the router's send path, so this never
+* uses `sendResponse`.
+*/
+function createExtensionListener(router, registry) {
+	return (raw, sender) => {
+		if (sender.id !== runtime.id) return void 0;
+		if (!Array.isArray(raw)) return void 0;
+		let message;
+		try {
+			message = Message(Message.decode(new Uint8Array(raw)));
+		} catch {
+			return;
+		}
+		if (message.methodId === void 0 || !registry.getMethod(message.methodId)) return;
+		router.process(message, Message({}), { sender });
+	};
+}
 //#endregion
-export { ExtensionBaseRouter, TempoExtensionRouter, TempoExtensionRouterConfiguration };
+export { ExtensionBaseRouter, TempoExtensionRouter, TempoExtensionRouterConfiguration, createExtensionListener };

package/dist/router-core.d.mts

@@ -0,0 +1,121 @@
+import { Message } from "./bebop.mjs";
+import { BebopRecord } from "bebop";
+import { BebopContentType, HookRegistry, Metadata, TempoLogger } from "@tempojs/common";
+import { EventEmitter } from "tseep";
+import { AuthInterceptor, BebopMethodAny, ServerContext } from "@tempojs/server";
+
+//#region src/router-core.d.ts
+/**
+ * The slice of a concrete router (`BaseRouter` / `ExtensionBaseRouter`
+ * subclass) that {@link RouterCore} needs. Supplied as delegate closures from
+ * the router's constructor because the underlying members are `protected`.
+ */
+interface RouterCoreHost {
+  readonly logger: TempoLogger;
+  readonly maxRetryAttempts: number;
+  readonly transmitInternalErrors: boolean;
+  readonly authInterceptor?: AuthInterceptor;
+  /** Resolve a method from the router's service registry. */
+  getMethod(methodId: number): BebopMethodAny | undefined;
+  /** Read the router's current hook registry (set later via `useHooks`). */
+  getHooks(): HookRegistry<ServerContext, any> | undefined;
+  deserializeRequest(requestData: Uint8Array, method: BebopMethodAny, contentType: BebopContentType): BebopRecord;
+  serializeResponse(response: BebopRecord, method: BebopMethodAny, contentType: BebopContentType): Uint8Array;
+}
+/**
+ * The transport-specific pieces of one `process()` invocation, built fresh per
+ * request so the callbacks can close over the transport handle (socket, worker
+ * port, extension sender) and the request envelope.
+ */
+interface ProcessTransport {
+  /** Deliver a fully-populated response envelope to the client. */
+  send(response: Message): void | Promise<void>;
+  /**
+   * Pump a server-stream / duplex generator into response frames (usually via
+   * {@link RouterCore.writeStreamFrames}). Runs inside the request deadline.
+   */
+  writeStreamFrames(generator: AsyncGenerator<BebopRecord, void, unknown>, response: Message, method: BebopMethodAny): Promise<void>;
+  /**
+   * Build the incoming request {@link Metadata} for the ServerContext.
+   * Defaults to parsing the request's custom-metadata header.
+   */
+  buildIncomingMetadata?(request: Message): Metadata;
+  /**
+   * Override the server-stream invocation (the WebSocket router layers
+   * CANCELLED handling and generator tracking on top of the shared one).
+   */
+  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;
+}
+/** Options for {@link RouterCore.writeStreamFrames}. */
+interface StreamWriteOptions {
+  generator: AsyncGenerator<BebopRecord, void, unknown>;
+  response: Message;
+  method: BebopMethodAny;
+  contentType?: BebopContentType;
+  /** Deliver one populated frame to the client. */
+  send: (response: Message) => void | Promise<void>;
+  /**
+   * Serialize one record into owned payload bytes. The default copies out of
+   * bebop's shared write buffer; the WebSocket router substitutes its
+   * encode-once broadcast cache.
+   */
+  serializePayload?: (value: BebopRecord) => Uint8Array;
+  /** Checked before each frame; `true` stops the pump (worker cancellation). */
+  shouldStop?: () => boolean;
+  /** Send the terminal frame even when the generator throws (worker semantics). */
+  alwaysTerminate?: boolean;
+  /** Runs after the pump ends, before the terminal frame (tracking-map reaping). */
+  onEnd?: () => void;
+}
+/**
+ * Shared server-side routing core for the worker, WebSocket, and
+ * browser-extension routers.
+ *
+ * Owns the per-connection stream state (response demultiplexing events and
+ * in-flight client/duplex streams) plus every transport-agnostic step of
+ * dispatching one framed request: auth interception, hook execution, the four
+ * RPC invocation shapes, response population, deadline enforcement, and error
+ * mapping. Each concrete router composes an instance and passes the genuinely
+ * transport-specific bits per request via {@link ProcessTransport}.
+ *
+ * Internal to `@vampgg/utils`; the public routers are `TempoWorkerRouter`,
+ * `TempoWsRouter`, and `TempoExtensionRouter`.
+ */
+declare class RouterCore {
+  private readonly host;
+  /** Per-stream frame listeners keyed by messageId. */
+  readonly events: EventEmitter<Record<string, (message: Message) => void>>;
+  /** In-flight client/duplex stream invocations keyed by messageId. */
+  readonly clientStreams: Map<string, Promise<any>>;
+  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>;
+  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>>;
+  /**
+   * Emit a synthetic CANCELLED to every in-flight client/duplex stream so its
+   * generator ends, and drop the tracking entries (connection teardown).
+   */
+  cancelClientStreams(): void;
+  /** Drop every per-stream frame listener (connection teardown). */
+  removeAllListeners(): void;
+  /**
+   * Pump a server-stream / duplex generator into response frames and emit the
+   * terminal CANCELLED frame that tells the client the stream is complete.
+   */
+  writeStreamFrames(opts: StreamWriteOptions): Promise<void>;
+  /**
+   * Dispatch one decoded request envelope: resolve the method, enforce retry
+   * and deadline limits, build the {@link ServerContext}, invoke the method by
+   * type, populate and deliver the response, and map any failure onto an error
+   * frame. Transport-specific behavior is injected via `transport`.
+   */
+  processRequest(request: Message, response: Message, env: unknown, transport: ProcessTransport, contentType?: BebopContentType): Promise<void>;
+}
+//#endregion
+export { ProcessTransport, RouterCore, RouterCoreHost, StreamWriteOptions };