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

package/dist/router-core.mjs

@@ -0,0 +1,282 @@
+import { Message } from "./bebop.mjs";
+import { createEventIterator } from "./create-event-iterator.mjs";
+import { Deadline, Metadata, MethodType, TempoError, TempoStatusCode, TempoUtil, stringifyCredential } from "@tempojs/common";
+import { EventEmitter } from "tseep";
+import { ServerContext } from "@tempojs/server";
+//#region src/router-core.ts
+/**
+* Parse the request's custom-metadata header into a {@link Metadata} (the
+* default incoming metadata for the worker/extension routers).
+*/
+function customMetadataOf(request) {
+	const metadataHeader = request.customMetadata;
+	return metadataHeader ? Metadata.fromHttpHeader(metadataHeader) : new Metadata();
+}
+/**
+* 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`.
+*/
+var RouterCore = class {
+	host;
+	/** Per-stream frame listeners keyed by messageId. */
+	events = new EventEmitter();
+	/** In-flight client/duplex stream invocations keyed by messageId. */
+	clientStreams = /* @__PURE__ */ new Map();
+	constructor(host) {
+		this.host = host;
+	}
+	async setAuthContext(request, context) {
+		const authHeader = request.authorization;
+		if (authHeader !== void 0 && this.host.authInterceptor !== void 0) {
+			const authContext = await this.host.authInterceptor.intercept(context, authHeader);
+			if (authContext !== void 0) context.authContext = authContext;
+		}
+	}
+	async invokeUnaryMethod(request, context, method, contentType) {
+		await this.setAuthContext(request, context);
+		const hooks = this.host.getHooks();
+		if (hooks !== void 0) await hooks.executeRequestHooks(context);
+		const requestData = request.data;
+		const record = this.host.deserializeRequest(requestData, method, contentType);
+		if (hooks !== void 0) await hooks.executeDecodeHooks(context, record);
+		return await method.invoke(record, context);
+	}
+	async invokeClientStreamMethod(request, context, method, contentType) {
+		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) {
+			this.events.emit(messageId, request);
+			return await stream;
+		}
+		const generator = () => {
+			return createEventIterator(({ emit, cancel }) => {
+				const eventHandler = async (message) => {
+					const hooks = this.host.getHooks();
+					if (hooks !== void 0) await hooks.executeRequestHooks(context);
+					if (message.status === TempoStatusCode.CANCELLED) {
+						cancel();
+						return;
+					}
+					const requestData = message.data;
+					const record = this.host.deserializeRequest(requestData, method, contentType);
+					if (hooks !== void 0) await 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);
+		});
+	}
+	async invokeServerStreamMethod(request, context, method, contentType) {
+		await this.setAuthContext(request, context);
+		const hooks = this.host.getHooks();
+		if (hooks !== void 0) await hooks.executeRequestHooks(context);
+		const requestData = request.data;
+		const record = this.host.deserializeRequest(requestData, method, contentType);
+		if (!TempoUtil.isAsyncGeneratorFunction(method.invoke.bind(method))) throw new TempoError(TempoStatusCode.INTERNAL, "service method incorrect: method must be async generator");
+		if (hooks !== void 0) await hooks.executeDecodeHooks(context, record);
+		return method.invoke(record, context);
+	}
+	async invokeDuplexStreamMethod(request, context, method, contentType) {
+		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) {
+			this.events.emit(messageId, request);
+			return stream;
+		}
+		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) => {
+					const hooks = this.host.getHooks();
+					if (hooks !== void 0) await hooks.executeRequestHooks(context);
+					if (message.status === TempoStatusCode.CANCELLED) {
+						cancel();
+						return;
+					}
+					const requestData = message.data;
+					const record = this.host.deserializeRequest(requestData, method, contentType);
+					if (hooks !== void 0) await 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;
+	}
+	/**
+	* Emit a synthetic CANCELLED to every in-flight client/duplex stream so its
+	* generator ends, and drop the tracking entries (connection teardown).
+	*/
+	cancelClientStreams() {
+		for (const id of [...this.clientStreams.keys()]) {
+			this.events.emit(id, Message({
+				messageId: id,
+				status: TempoStatusCode.CANCELLED,
+				data: new Uint8Array()
+			}));
+			this.clientStreams.delete(id);
+		}
+	}
+	/** Drop every per-stream frame listener (connection teardown). */
+	removeAllListeners() {
+		this.events.removeAllListeners();
+	}
+	/**
+	* Pump a server-stream / duplex generator into response frames and emit the
+	* terminal CANCELLED frame that tells the client the stream is complete.
+	*/
+	async writeStreamFrames(opts) {
+		const contentType = opts.contentType ?? "bebop";
+		const serializePayload = opts.serializePayload ?? ((value) => new Uint8Array(this.host.serializeResponse(value, opts.method, contentType)));
+		const terminate = async () => {
+			opts.onEnd?.();
+			opts.response.data = new Uint8Array();
+			opts.response.status = TempoStatusCode.CANCELLED;
+			await opts.send(opts.response);
+		};
+		const pump = async () => {
+			for await (const value of opts.generator) {
+				if (opts.shouldStop?.()) break;
+				opts.response.data = serializePayload(value);
+				await opts.send(opts.response);
+			}
+		};
+		if (opts.alwaysTerminate) try {
+			await pump();
+		} finally {
+			await terminate();
+		}
+		else {
+			await pump();
+			await terminate();
+		}
+	}
+	/**
+	* 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`.
+	*/
+	async processRequest(request, response, env, transport, contentType = "bebop") {
+		let context;
+		try {
+			const methodId = request.methodId;
+			const method = this.host.getMethod(methodId);
+			if (!method) throw new TempoError(TempoStatusCode.NOT_FOUND, `no service is registered which contains a method of '${methodId}'`);
+			const previousAttempts = request.previousAttempts;
+			if (previousAttempts !== void 0 && previousAttempts > this.host.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: transport.buildIncomingMetadata ? transport.buildIncomingMetadata(request) : customMetadataOf(request)
+			};
+			if (deadline !== void 0) incomingContext.deadline = deadline;
+			const serverContext = new ServerContext(incomingContext, { metadata: outgoingMetadata }, env);
+			context = serverContext;
+			const handleRequest = async () => {
+				let recordGenerator = void 0;
+				let record;
+				switch (method.type) {
+					case MethodType.Unary:
+						record = await this.invokeUnaryMethod(request, serverContext, method, contentType);
+						break;
+					case MethodType.ClientStream:
+						record = await this.invokeClientStreamMethod(request, serverContext, method, contentType);
+						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);
+						break;
+					default: throw new TempoError(TempoStatusCode.INTERNAL, "service method incorrect: unknown method type");
+				}
+				const outgoingCredential = serverContext.outgoingCredential;
+				if (outgoingCredential) response.credential = stringifyCredential(outgoingCredential);
+				response.methodId = request.methodId;
+				response.messageId = request.messageId;
+				response.status = TempoStatusCode.OK;
+				response.timestamp = /* @__PURE__ */ new Date();
+				transport.decorateResponse?.(response);
+				const hooks = this.host.getHooks();
+				if (hooks !== void 0) await hooks.executeResponseHooks(serverContext);
+				outgoingMetadata.freeze();
+				if (outgoingMetadata.size() > 0) response.customMetadata = outgoingMetadata.data;
+				if (recordGenerator !== void 0) {
+					const generator = recordGenerator;
+					const writeFrames = () => transport.writeStreamFrames(generator, response, method);
+					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.host.serializeResponse(record, method, contentType);
+					response.data = new Uint8Array(responseData);
+					await transport.send(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.host.transmitInternalErrors !== true) message = "internal error";
+				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);
+			}
+			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;
+			}
+			await transport.send(response);
+		}
+	}
+};
+//#endregion
+export { RouterCore };

package/dist/worker-channel.d.mts

@@ -1,24 +1,21 @@
-import { BebopRecord } from "bebop";
-import { BebopContentType, Credential, Deadline, TempoError } from "@tempojs/common";
-import { BaseChannel, CallCredential, CallOptions, ClientContext, MethodInfo, RetryPolicy, TempoChannelOptions } from "@tempojs/client";
+import { Message } from "./bebop.mjs";
+import { CoreChannel } from "./channel-core.mjs";
+import { CallCredential, TempoChannelOptions } from "@tempojs/client";
+import { BebopContentType, TempoError } from "@tempojs/common";
 
 //#region src/worker-channel.d.ts
 /**
  * Represents a Tempo channel for communication with a worker thread.
  */
-declare class TempoWorkerChannel extends BaseChannel {
+declare class TempoWorkerChannel extends CoreChannel {
   static readonly defaultMaxRetryAttempts: number;
   static readonly defaultCredential: CallCredential;
   static readonly defaultContentType: BebopContentType;
   private readonly _worker;
-  private readonly events;
-  private readonly userAgent;
   private _open;
   private _ready;
   private _resolveReady?;
   private _rejectReady?;
-  readonly pending: Map<string, (e: unknown) => void>;
-  private closed;
   get worker(): Bun.Worker;
   get ready(): Promise<void>;
   /**
@@ -29,71 +26,18 @@ declare class TempoWorkerChannel extends BaseChannel {
    * @protected
    */
   constructor(url: string, options?: TempoChannelOptions);
+  /** Reject a pending `ready` before in-flight calls are settled. */
+  protected onClosing(reason: TempoError): void;
+  /** Terminate the owned worker on {@link CoreChannel.close}. */
+  protected closeTransport(): void;
+  protected generateMessageId(): string;
   /**
-   * Tear down the channel: reject every in-flight call and a pending `ready`,
-   * remove all listeners, and terminate the owned worker. Idempotent.
-   */
-  close(reason?: TempoError): void;
-  removeCredential(): Promise<void>;
-  getCredential(): Promise<Credential | undefined>;
-  /**
-   * Executes a function with retries according to the provided retry policy.
-   * The function will be retried if it fails with a TempoError and its status code is included in the retryableStatusCodes of the retry policy.
-   * If a deadline is provided, the deadline for each attempt will be managed by the provided deadline, but the deadline will not be reset upon each retry.
-   *
-   * @template T - The type of the result returned by the function.
-   * @param {((retryAttempt: number) => Promise<T>)} func - A function that returns a Promise with a result. The function will receive a number indicating the current retry attempt.
-   * @param {RetryPolicy} retryPolicy - An object defining the retry policy, including maxAttempts, initialBackoff, maxBackoff, backoffMultiplier, and retryableStatusCodes.
-   * @param {Deadline} [deadline] - An optional deadline object that manages the timeout for each attempt.
-   * @param {AbortController} [abortController] - An optional AbortController instance to cancel the function execution.
-   * @returns {Promise<T>} - A Promise that resolves with the result of the function if it completes within the deadline and retry policy constraints.
-   * @throws {Error} - If the function execution fails and the error does not match the retry policy, or if the maximum number of attempts is reached without a successful result.
-   */
-  executeWithRetry<T>(func: (retryAttempt: number) => Promise<T>, retryPolicy: RetryPolicy, deadline?: Deadline, abortController?: AbortController): Promise<T>;
-  private fetchUnary;
-  private fetchClientStream;
-  private fetchServerStream;
-  private fetchDuplexStream;
-  /**
-   * Creates a `RequestInit` object for a given payload, context, method and optional call options.
-   * This object can be used to make an HTTP request using the Fetch API.
-   *
-   * @private
-   * @param {Uint8Array} payload - The payload to be sent in the request.
-   * @param {ClientContext} context - The context of the client making the request.
-   * @param {MethodInfo<BebopRecord, BebopRecord>} method - Information about the method being called.
-   * @param {CallOptions | undefined} options - Optional configuration for the call.
-   * @returns {Promise<RequestInit>} A Promise resolving to the created `RequestInit` object.
-   * @throws {TempoError} Throws an error if there's a problem while getting the credential header.
-   */
-  private createRequest;
-  /**
-   * Processes the headers of the response from the server, validating their integrity and correctness.
-   * Also sets the incoming metadata from the response headers to the provided context.
+   * {@inheritDoc CoreChannel.sendFrame}
    *
-   * @private
-   * @param {Response} response - The response received from the server.
-   * @param {ClientContext} context - The context of the client making the request.
-   * @param {MethodType} methodType - The type of method being called.
-   * @throws {TempoError} Throws an error if any validation checks fail or if there's a problem parsing or storing credentials.
-   */
-  private processResponseHeaders;
-  /**
-   * {@inheritDoc BaseChannel.startUnary}
-   */
-  startUnary<TRequest extends BebopRecord, TResponse extends BebopRecord>(request: TRequest, context: ClientContext, method: MethodInfo<TRequest, TResponse>, options?: CallOptions): Promise<TResponse>;
-  /**
-   * {@inheritDoc BaseChannel.startClientStream}
-   */
-  startClientStream<TRequest extends BebopRecord, TResponse extends BebopRecord>(generator: () => AsyncGenerator<TRequest, void, undefined>, context: ClientContext, method: MethodInfo<TRequest, TResponse>, options?: CallOptions): Promise<TResponse>;
-  /**
-   * {@inheritDoc BaseChannel.startServerStream}
-   */
-  startServerStream<TRequest extends BebopRecord, TResponse extends BebopRecord>(request: TRequest, context: ClientContext, method: MethodInfo<TRequest, TResponse>, options?: CallOptions): Promise<AsyncGenerator<TResponse, void, undefined>>;
-  /**
-   * {@inheritDoc BaseChannel.startDuplexStream}
+   * `.slice()` owns a fresh ArrayBuffer; transferring it cannot detach bebop's
+   * process-wide singleton write buffer.
    */
-  startDuplexStream<TRequest extends BebopRecord, TResponse extends BebopRecord>(generator: () => AsyncGenerator<TRequest, void, undefined>, context: ClientContext, method: MethodInfo<TRequest, TResponse>, options?: CallOptions): Promise<AsyncGenerator<TResponse, void, undefined>>;
+  protected sendFrame(message: Message): void;
 }
 //#endregion
 export { TempoWorkerChannel };