@volter/twin-temporal 0.1.0

package/dist/src/temporal-grpc.d.ts

@@ -0,0 +1,51 @@
+import type { H2Handler } from './temporal-h2.js';
+export declare const TEMPORAL_LOOPBACK_HOST = "127.0.0.1";
+/** gRPC status codes (https://grpc.github.io/grpc/core/md_doc_statuscodes.html). */
+export declare const GrpcStatus: {
+    readonly OK: 0;
+    readonly CANCELLED: 1;
+    readonly UNKNOWN: 2;
+    readonly INVALID_ARGUMENT: 3;
+    readonly DEADLINE_EXCEEDED: 4;
+    readonly NOT_FOUND: 5;
+    readonly ALREADY_EXISTS: 6;
+    readonly PERMISSION_DENIED: 7;
+    readonly RESOURCE_EXHAUSTED: 8;
+    readonly FAILED_PRECONDITION: 9;
+    readonly ABORTED: 10;
+    readonly OUT_OF_RANGE: 11;
+    readonly UNIMPLEMENTED: 12;
+    readonly INTERNAL: 13;
+    readonly UNAVAILABLE: 14;
+    readonly DATA_LOSS: 15;
+    readonly UNAUTHENTICATED: 16;
+};
+export declare class GrpcError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+export type GrpcCallContext = {
+    /** aborted when the client cancels the call or its deadline passes */
+    signal: AbortSignal;
+    /** the client's deadline as epoch ms, when it sent one */
+    deadline?: number;
+    metadata: Record<string, string>;
+};
+/** Answers one unary call; a method the handler does not serve throws UNIMPLEMENTED. */
+export type GrpcHandler = (service: string, method: string, request: Record<string, unknown>, ctx: GrpcCallContext) => Promise<Record<string, unknown>>;
+/** `grpc-timeout`: an integer and a unit (H M S m u n), PROTOCOL-HTTP2.md "Timeout". */
+export declare function parseGrpcTimeout(value: string | undefined): number | undefined;
+/** Length-prefixed messages out of a request body: [compressed flag][u32 length][bytes]... */
+export declare function splitGrpcFrames(body: Uint8Array): Array<{
+    compressed: boolean;
+    message: Uint8Array;
+}>;
+export declare function grpcFrame(message: Uint8Array): Uint8Array;
+/** grpc-message is percent-encoded (PROTOCOL-HTTP2.md "Status-Message"). */
+export declare function encodeGrpcMessage(text: string): string;
+/** The HTTP/2 stream handler that answers gRPC for `services` (fully-qualified proto service names)
+ *  through `handler`; the listener that feeds it sockets is temporal-server.ts's. */
+export declare function grpcStreamHandler(options: {
+    services: string[];
+    handler: GrpcHandler;
+}): H2Handler;

package/dist/src/temporal-grpc.js

@@ -0,0 +1,124 @@
+import { decodeMessage, encodeMessage, serviceMethods } from "./temporal-proto.js";
+export const TEMPORAL_LOOPBACK_HOST = '127.0.0.1';
+/** gRPC status codes (https://grpc.github.io/grpc/core/md_doc_statuscodes.html). */
+export const GrpcStatus = {
+    OK: 0, CANCELLED: 1, UNKNOWN: 2, INVALID_ARGUMENT: 3, DEADLINE_EXCEEDED: 4, NOT_FOUND: 5, ALREADY_EXISTS: 6,
+    PERMISSION_DENIED: 7, RESOURCE_EXHAUSTED: 8, FAILED_PRECONDITION: 9, ABORTED: 10, OUT_OF_RANGE: 11,
+    UNIMPLEMENTED: 12, INTERNAL: 13, UNAVAILABLE: 14, DATA_LOSS: 15, UNAUTHENTICATED: 16,
+};
+export class GrpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** `grpc-timeout`: an integer and a unit (H M S m u n), PROTOCOL-HTTP2.md "Timeout". */
+export function parseGrpcTimeout(value) {
+    const match = /^(\d{1,8})([HMSmun])$/.exec(value ?? '');
+    if (!match)
+        return undefined;
+    const amount = Number(match[1]);
+    const ms = { H: 3_600_000, M: 60_000, S: 1000, m: 1, u: 0.001, n: 0.000001 }[match[2]];
+    return amount * ms;
+}
+/** Length-prefixed messages out of a request body: [compressed flag][u32 length][bytes]... */
+export function splitGrpcFrames(body) {
+    const frames = [];
+    let offset = 0;
+    while (offset < body.length) {
+        if (body.length - offset < 5)
+            throw new GrpcError(GrpcStatus.INTERNAL, 'truncated gRPC frame header');
+        const view = new DataView(body.buffer, body.byteOffset + offset, 5);
+        const length = view.getUint32(1);
+        if (body.length - offset - 5 < length)
+            throw new GrpcError(GrpcStatus.INTERNAL, 'truncated gRPC message');
+        frames.push({ compressed: body[offset] === 1, message: body.subarray(offset + 5, offset + 5 + length) });
+        offset += 5 + length;
+    }
+    return frames;
+}
+export function grpcFrame(message) {
+    const out = new Uint8Array(5 + message.length);
+    new DataView(out.buffer).setUint32(1, message.length);
+    out.set(message, 5);
+    return out;
+}
+/** grpc-message is percent-encoded (PROTOCOL-HTTP2.md "Status-Message"). */
+export function encodeGrpcMessage(text) {
+    return Array.from(new TextEncoder().encode(text), (byte) => (byte >= 0x20 && byte <= 0x7e && byte !== 0x25 ? String.fromCharCode(byte) : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`)).join('');
+}
+/** The HTTP/2 stream handler that answers gRPC for `services` (fully-qualified proto service names)
+ *  through `handler`; the listener that feeds it sockets is temporal-server.ts's. */
+export function grpcStreamHandler(options) {
+    const tables = new Map(options.services.map((name) => [name, serviceMethods(name)]));
+    return (request, response) => {
+        const headers = request.headers;
+        const fail = (code, message) => {
+            if (response.closed)
+                return;
+            response.headers([[':status', '200'], ['content-type', 'application/grpc'], ['grpc-status', String(code)], ['grpc-message', encodeGrpcMessage(message)]], true);
+        };
+        const contentType = headers['content-type'] ?? '';
+        if (headers[':method'] !== 'POST' || !contentType.startsWith('application/grpc')) {
+            response.headers([[':status', '415'], ['content-type', 'text/plain']], true);
+            return;
+        }
+        const path = headers[':path'] ?? '';
+        const match = /^\/([^/]+)\/([^/]+)$/.exec(path);
+        const table = match ? tables.get(match[1]) : undefined;
+        const method = match && table ? table.get(match[2]) : undefined;
+        if (!match || !table || !method) {
+            fail(GrpcStatus.UNIMPLEMENTED, `unknown method ${path}`);
+            return;
+        }
+        if (method.requestStream || method.responseStream) {
+            fail(GrpcStatus.UNIMPLEMENTED, `${match[1]}/${match[2]} is a streaming method; this server answers unary calls only`);
+            return;
+        }
+        const timeout = parseGrpcTimeout(headers['grpc-timeout']);
+        const controller = new AbortController();
+        const timer = timeout !== undefined ? setTimeout(() => controller.abort(), timeout) : undefined;
+        request.signal.addEventListener('abort', () => controller.abort(), { once: true });
+        const metadata = {};
+        for (const [key, value] of Object.entries(headers))
+            if (!key.startsWith(':'))
+                metadata[key] = value;
+        let decoded;
+        try {
+            const frames = splitGrpcFrames(request.body);
+            if (frames.length !== 1)
+                throw new GrpcError(GrpcStatus.INTERNAL, `a unary call carries exactly one message (got ${frames.length})`);
+            if (frames[0].compressed)
+                throw new GrpcError(GrpcStatus.UNIMPLEMENTED, 'compressed messages are not accepted (this server advertises no grpc-encoding)');
+            decoded = decodeMessage(method.requestType, frames[0].message);
+        }
+        catch (error) {
+            if (timer)
+                clearTimeout(timer);
+            fail(error instanceof GrpcError ? error.code : GrpcStatus.INTERNAL, error.message);
+            return;
+        }
+        void (async () => {
+            try {
+                const answer = await options.handler(match[1], match[2], decoded, { signal: controller.signal, ...(timeout !== undefined ? { deadline: Date.now() + timeout } : {}), metadata });
+                if (response.closed)
+                    return;
+                const bytes = grpcFrame(encodeMessage(method.responseType, answer));
+                response.headers([[':status', '200'], ['content-type', 'application/grpc']]);
+                response.data(bytes);
+                response.trailers([['grpc-status', '0']]);
+            }
+            catch (error) {
+                if (error instanceof GrpcError)
+                    fail(error.code, error.message);
+                else
+                    fail(GrpcStatus.INTERNAL, `internal error: ${error?.message ?? String(error)}`);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        })();
+    };
+}

package/dist/src/temporal-h2.d.ts

@@ -0,0 +1,40 @@
+import type { Socket } from 'node:net';
+export declare class HpackError extends Error {
+}
+export declare function huffmanDecode(bytes: Uint8Array): string;
+export declare class HpackDecoder {
+    private table;
+    private size;
+    private maxSize;
+    /** the SETTINGS_HEADER_TABLE_SIZE this endpoint advertised (the decoder's ceiling; 4096 is the
+     *  protocol default, which this server never changes) */
+    private readonly limit;
+    constructor(headerTableSize?: number);
+    decode(block: Uint8Array): Array<[string, string]>;
+    private insert;
+    private evict;
+}
+/** Every header as a literal without indexing, new name, no huffman (RFC 7541 §6.2.2). */
+export declare function hpackEncode(headers: Array<[string, string]>): Uint8Array;
+export type H2Request = {
+    headers: Record<string, string>;
+    body: Uint8Array;
+    /** aborted when the peer resets the stream or the connection goes away */
+    signal: AbortSignal;
+};
+export type H2Response = {
+    /** send response headers; `end` closes the stream with them (a trailers-only answer) */
+    headers(headers: Array<[string, string]>, end?: boolean): void;
+    data(bytes: Uint8Array): void;
+    /** close the stream with trailing headers */
+    trailers(headers: Array<[string, string]>): void;
+    readonly closed: boolean;
+};
+export type H2Handler = (request: H2Request, response: H2Response) => void;
+/** An HTTP/1 request arriving on the same port, answered by a fetch handler. */
+export type Http1Handler = (request: Request) => Response | Promise<Response>;
+/** Speak HTTP/2 (h2c with prior knowledge) on an accepted socket; an HTTP/1 request line is handed to
+ *  `http1` when given. The listener that accepts sockets is the server module's (temporal-server.ts). */
+export declare function acceptH2Connection(socket: Socket, handler: H2Handler, http1?: Http1Handler): {
+    teardown(): void;
+};