@volter/world-core 2.0.37 → 3.0.1

package/dist/src/grpc-wire.js

@@ -0,0 +1,170 @@
+// THE gRPC WIRE (architecture, "Other wires": gRPC): unary gRPC calls over the kernel's HTTP/2 server (./h2.ts), each
+// request's one length-prefixed message decoded by the proto unit's schema (./protobuf.ts) and handed to the pack's
+// handler for its operation, whose JSON answer is encoded back with the status trailers
+// (https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). After the older catalog's temporal pack's
+// `temporal-grpc.ts`, over this repository's codec rather than protobufjs. Everything here is framing: which rpcs exist
+// and what they answer is the pack's. Importing it does nothing.
+import { acceptH2Connection } from "./h2.js";
+import { nodeBuiltin, WORLD_BOOT_PATH } from "./serve-http.js";
+import { decodeMessage, encodeMessage } from "./protobuf.js";
+/** gRPC's 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,
+};
+/** A call answered with a gRPC status other than OK: its code and its message. */
+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;
+    return Number(match[1]) * { H: 3_600_000, M: 60_000, S: 1000, m: 1, u: 0.001, n: 0.000001 }[match[2]];
+}
+/** 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 length = new DataView(body.buffer, body.byteOffset + offset, 5).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), (b) => (b >= 0x20 && b <= 0x7e && b !== 0x25 ? String.fromCharCode(b) : `%${b.toString(16).toUpperCase().padStart(2, '0')}`)).join('');
+}
+/** The HTTP/2 stream handler that answers the unary rpcs of a proto unit's schema through `handler`. */
+export function grpcStreamHandler(schema, handler) {
+    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);
+        };
+        if (headers[':method'] !== 'POST' || !(headers['content-type'] ?? '').startsWith('application/grpc')) {
+            response.headers([[':status', '415'], ['content-type', 'text/plain']], true);
+            return;
+        }
+        const path = headers[':path'] ?? '';
+        const rpc = schema.rpcs[path];
+        if (!rpc) {
+            fail(GrpcStatus.UNIMPLEMENTED, `unknown method ${path}`);
+            return;
+        }
+        if (rpc.clientStreams || rpc.serverStreams) {
+            fail(GrpcStatus.UNIMPLEMENTED, `${path} streams; this wire answers unary calls`);
+            return;
+        }
+        const timeout = parseGrpcTimeout(headers['grpc-timeout']);
+        const controller = new AbortController();
+        // a call ends once: its deadline passing answers DEADLINE_EXCEEDED, and the client going away (its stream reset)
+        // is CANCELLED, which no one hears; the handler's later answer, either way, is dropped
+        // (https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md "Timeout", statuscodes.md "CANCELLED")
+        let ended;
+        const end = (code) => { if (ended !== undefined)
+            return; ended = code; controller.abort(); if (code === GrpcStatus.DEADLINE_EXCEEDED)
+            fail(code, 'Deadline Exceeded'); };
+        const timer = timeout !== undefined ? setTimeout(() => end(GrpcStatus.DEADLINE_EXCEEDED), timeout) : undefined;
+        request.signal.addEventListener('abort', () => end(GrpcStatus.CANCELLED), { once: true });
+        const metadata = Object.fromEntries(Object.entries(headers).filter(([k]) => !k.startsWith(':')));
+        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 (no grpc-encoding is advertised)');
+            decoded = decodeMessage(schema, rpc.request, 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 handler({ operation: rpc.operation, path, request: decoded, metadata, signal: controller.signal });
+                if (ended !== undefined || response.closed)
+                    return;
+                response.headers([[':status', '200'], ['content-type', 'application/grpc']]);
+                response.data(grpcFrame(encodeMessage(schema, rpc.response, answer)));
+                response.trailers([['grpc-status', '0']]);
+            }
+            catch (error) {
+                if (ended !== undefined)
+                    return;
+                if (error instanceof GrpcError)
+                    fail(error.code, error.message);
+                else
+                    fail(GrpcStatus.INTERNAL, `internal error: ${error?.message ?? String(error)}`);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        })();
+    };
+}
+/** A gRPC code for the HTTP status a pack's fetch answered: Google's REST error names it (`error.status`), else the
+ *  status's customary code (https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto, "HTTP Mapping"). */
+function codeOf(status, body) {
+    const named = body?.error?.status;
+    if (typeof named === 'string' && named in GrpcStatus)
+        return GrpcStatus[named];
+    return { 400: GrpcStatus.INVALID_ARGUMENT, 401: GrpcStatus.UNAUTHENTICATED, 403: GrpcStatus.PERMISSION_DENIED, 404: GrpcStatus.NOT_FOUND, 409: GrpcStatus.ABORTED, 429: GrpcStatus.RESOURCE_EXHAUSTED, 499: GrpcStatus.CANCELLED, 501: GrpcStatus.UNIMPLEMENTED, 503: GrpcStatus.UNAVAILABLE, 504: GrpcStatus.DEADLINE_EXCEEDED }[status] ?? (status >= 500 ? GrpcStatus.INTERNAL : GrpcStatus.UNKNOWN);
+}
+/** A gRPC call answered by the pack's own fetch, as the derive serves a proto unit's rpc (`POST /<package>.<Service>/
+ *  <Method>`, the request message's JSON form the body): its JSON answer is the response message; any other status its
+ *  gRPC code, the error's message as the status message. */
+export function grpcOverFetch(fetch) {
+    return async (call) => {
+        const res = await fetch(new Request(`http://twin${call.path}`, { method: 'POST', headers: { ...call.metadata, 'content-type': 'application/json' }, body: JSON.stringify(call.request), signal: call.signal }));
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : {};
+        }
+        catch {
+            body = undefined;
+        }
+        if (res.ok)
+            return (body ?? {});
+        const message = body?.error?.message ?? body?.message ?? text;
+        throw new GrpcError(codeOf(res.status, body), String(message).slice(0, 500));
+    };
+}
+/** A pack that speaks gRPC, served on one port: HTTP/2 (gRPC, by the schema through the pack's fetch) and HTTP/1 (the
+ *  pack's fetch: its doors, its REST) on the same socket, as the kernel's HTTP/2 server tells them apart. Inside a World
+ *  it answers the World's boot probe as `serveHttp` does. */
+export async function serveGrpc(options) {
+    const net = nodeBuiltin('node:net');
+    const worldBoot = globalThis.process?.env?.VOLTER_WORLD_BOOT_ID;
+    const fetch = worldBoot ? (request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Promise.resolve(Response.json({ boot: worldBoot })) : options.fetch(request)) : options.fetch;
+    const handler = grpcStreamHandler(options.schema, grpcOverFetch(fetch));
+    const server = net.createServer((socket) => { acceptH2Connection(socket, handler, fetch); });
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, '127.0.0.1', () => resolve()); });
+    const address = server.address();
+    return { port: typeof address === 'object' && address ? address.port : 0, stop: () => { server.close(); } };
+}

package/dist/src/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 pack's server module's. */
+export declare function acceptH2Connection(socket: Socket, handler: H2Handler, http1?: Http1Handler): {
+    teardown(): void;
+};