@zmdb/transport-grpc 1.0.0-beta.1

package/dist/runtime.js

@@ -0,0 +1,711 @@
+import { once } from 'node:events';
+import { Client, Metadata, Server, ServerCredentials, credentials, status, } from '@grpc/grpc-js';
+import { GrpcError, } from './types.js';
+class BoundGrpcService {
+    service;
+    methods;
+    #spec;
+    #handlers;
+    constructor(spec, handlers) {
+        this.#spec = spec;
+        this.#handlers = handlers;
+        this.service = spec.definition.name;
+        this.methods = Object.freeze(Object.keys(spec.definition.methods));
+    }
+    register(server) {
+        const definition = Object.create(null);
+        const implementation = Object.create(null);
+        for (const [name, method] of methodEntries(this.#spec.definition.methods)) {
+            definition[name] = {
+                path: method.path,
+                requestStream: method.requestStream,
+                responseStream: method.responseStream,
+                requestSerialize: value => grpcBytes(serializeRequest(method, value)),
+                requestDeserialize: bytes => decodeRequest(method, bytes),
+                responseSerialize: value => grpcBytes(serializeResponse(method, value)),
+                responseDeserialize: bytes => deserializeResponse(method, bytes),
+            };
+            implementation[name] = serverHandler(name, method, this.#spec, this.#handlers);
+        }
+        const serviceDefinition = definition;
+        server.addService(serviceDefinition, implementation);
+    }
+}
+/** Bind one generated service definition to its exhaustive typed handler map. */
+export function bindGrpcService(service, handlers) {
+    validateServiceSpec(service);
+    return new BoundGrpcService(service, handlers);
+}
+/** Attach one gRPC server to the protocol-neutral application lifecycle. */
+export function grpcExtension(options) {
+    let opened;
+    return {
+        name: '@zmdb/transport-grpc',
+        async start() {
+            opened = await openGrpcServer(options);
+        },
+        async stop({ graceMs }) {
+            try {
+                await opened?.close(graceMs);
+            }
+            finally {
+                opened = undefined;
+            }
+        },
+    };
+}
+/** Create a typed client from the same generated service artifact used by the server. */
+export function createGrpcClient(options) {
+    validatePositiveDuration(options.deadlineMs, 'deadlineMs');
+    const channel = new Client(options.address, clientCredentials(options.credentials));
+    const client = Object.create(null);
+    for (const [name, method] of methodEntries(options.definition.methods)) {
+        if (name === 'close') {
+            channel.close();
+            throw new Error('@zmdb/transport-grpc: a gRPC method cannot be named "close" because the typed client owns that member');
+        }
+        Object.defineProperty(client, name, {
+            configurable: false,
+            enumerable: true,
+            value: clientCaller(channel, method, options),
+            writable: false,
+        });
+    }
+    const close = () => {
+        channel.close();
+    };
+    Object.defineProperties(client, {
+        close: { configurable: false, enumerable: false, value: close, writable: false },
+        [Symbol.dispose]: { configurable: false, enumerable: false, value: close, writable: false },
+    });
+    return client;
+}
+/** Start all bound services. Kept internal to the application lifecycle. */
+export async function openGrpcServer(options) {
+    if (options.address.length === 0) {
+        throw new RangeError('@zmdb/transport-grpc: a gRPC server address cannot be empty');
+    }
+    if (options.bindings.length === 0) {
+        throw new RangeError('@zmdb/transport-grpc: a gRPC server requires at least one binding');
+    }
+    const server = new Server();
+    try {
+        for (const binding of options.bindings) {
+            if (!(binding instanceof BoundGrpcService)) {
+                throw new TypeError('@zmdb/transport-grpc: gRPC bindings must be created by bindGrpcService');
+            }
+            binding.register(server);
+        }
+        const port = await bindServer(server, options.address, serverCredentials(options.credentials));
+        let closePromise;
+        return {
+            port,
+            close: graceMs => {
+                closePromise ??= closeServer(server, graceMs);
+                return closePromise;
+            },
+        };
+    }
+    catch (error) {
+        server.forceShutdown();
+        throw error;
+    }
+}
+function methodEntries(methods) {
+    return Object.entries(methods);
+}
+function validateServiceSpec(service) {
+    if (service.definition.name.length === 0) {
+        throw new RangeError('@zmdb/transport-grpc: a gRPC service name cannot be empty');
+    }
+    if (Object.keys(service.definition.methods).length === 0) {
+        throw new RangeError(`@zmdb/transport-grpc: gRPC service "${service.definition.name}" has no methods`);
+    }
+    if (service.maxDurationMs !== undefined) {
+        validatePositiveDuration(service.maxDurationMs, 'maxDurationMs');
+    }
+}
+function validatePositiveDuration(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`@zmdb/transport-grpc: ${name} must be a positive finite number`);
+    }
+}
+function grpcBytes(bytes) {
+    return globalThis.Buffer.from(bytes);
+}
+function decodeRequest(method, bytes) {
+    try {
+        const value = method.deserializeRequest(bytes);
+        return { ok: true, value: method.validateRequest(value) };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+function serializeRequest(method, value) {
+    return method.serializeRequest(method.validateRequest(value));
+}
+function serializeResponse(method, value) {
+    return method.serializeResponse(method.validateResponse(value));
+}
+function deserializeResponse(method, bytes) {
+    return method.validateResponse(method.deserializeResponse(bytes));
+}
+function serverHandler(name, method, spec, handlers) {
+    if (method.requestStream) {
+        return method.responseStream
+            ? (call) => {
+                void runBidi(call, name, method, spec, handlers);
+            }
+            : (call, callback) => {
+                void runClientStream(call, callback, name, method, spec, handlers);
+            };
+    }
+    return method.responseStream
+        ? (call) => {
+            void runServerStream(call, name, method, spec, handlers);
+        }
+        : (call, callback) => {
+            void runUnary(call, callback, name, method, spec, handlers);
+        };
+}
+async function runUnary(call, callback, name, method, spec, handlers) {
+    const scope = callScope(call, spec.maxDurationMs);
+    try {
+        const request = requestValue(call.request);
+        const context = grpcCall(call, spec, name, request, scope);
+        const handler = handlerAt(handlers, name);
+        const response = method.validateResponse(await handler(context));
+        callback(null, response, trailers(scope.trailers));
+    }
+    catch (error) {
+        callback(serverError(boundaryError(error, scope, spec, name)));
+    }
+    finally {
+        scope.close();
+    }
+}
+async function runClientStream(call, callback, name, method, spec, handlers) {
+    const scope = callScope(call, spec.maxDurationMs);
+    try {
+        const requests = requestStream(call, scope);
+        const context = grpcCall(call, spec, name, requests, scope);
+        const handler = handlerAt(handlers, name);
+        const response = method.validateResponse(await handler(context));
+        callback(null, response, trailers(scope.trailers));
+    }
+    catch (error) {
+        callback(serverError(boundaryError(error, scope, spec, name)));
+    }
+    finally {
+        scope.close();
+    }
+}
+async function runServerStream(call, name, method, spec, handlers) {
+    const scope = callScope(call, spec.maxDurationMs);
+    try {
+        const request = requestValue(call.request);
+        const context = grpcCall(call, spec, name, request, scope);
+        const handler = handlerAt(handlers, name);
+        await writeResponses(call, handler(context), method, scope);
+        call.end(trailers(scope.trailers));
+    }
+    catch (error) {
+        call.destroy(serverError(boundaryError(error, scope, spec, name)));
+    }
+    finally {
+        scope.close();
+    }
+}
+async function runBidi(call, name, method, spec, handlers) {
+    const scope = callScope(call, spec.maxDurationMs);
+    try {
+        const requests = requestStream(call, scope);
+        const context = grpcCall(call, spec, name, requests, scope);
+        const handler = handlerAt(handlers, name);
+        await writeResponses(call, handler(context), method, scope);
+        call.end(trailers(scope.trailers));
+    }
+    catch (error) {
+        call.destroy(serverError(boundaryError(error, scope, spec, name)));
+    }
+    finally {
+        scope.close();
+    }
+}
+function requestValue(decoded) {
+    if (!decoded.ok) {
+        throw new GrpcError('INVALID_ARGUMENT', 'invalid request');
+    }
+    return decoded.value;
+}
+async function* requestStream(call, scope) {
+    const iterator = call[Symbol.asyncIterator]();
+    try {
+        for (;;) {
+            const next = await nextRequest(iterator, scope);
+            if (next.done)
+                return;
+            yield requestValue(next.value);
+        }
+    }
+    finally {
+        await iterator.return?.();
+    }
+}
+async function nextRequest(iterator, scope) {
+    if (scope.signal.aborted)
+        throw scope.reason();
+    let removeAbort = () => undefined;
+    const aborted = new Promise((_resolve, reject) => {
+        const onAbort = () => {
+            reject(scope.reason());
+        };
+        scope.signal.addEventListener('abort', onAbort, { once: true });
+        removeAbort = () => {
+            scope.signal.removeEventListener('abort', onAbort);
+        };
+    });
+    try {
+        return await Promise.race([iterator.next(), aborted]);
+    }
+    finally {
+        removeAbort();
+    }
+}
+async function writeResponses(call, responses, method, scope) {
+    for await (const response of responses) {
+        if (scope.signal.aborted)
+            throw scope.reason();
+        const valid = method.validateResponse(response);
+        if (!call.write(valid)) {
+            await waitForDrain(call, scope);
+        }
+    }
+}
+function handlerAt(handlers, name) {
+    return Reflect.get(handlers, name);
+}
+function waitForDrain(call, scope) {
+    if (scope.signal.aborted)
+        return Promise.reject(scope.reason());
+    return new Promise((resolve, reject) => {
+        const onDrain = () => {
+            scope.signal.removeEventListener('abort', onAbort);
+            resolve();
+        };
+        const onAbort = () => {
+            call.removeListener('drain', onDrain);
+            reject(scope.reason());
+        };
+        call.once('drain', onDrain);
+        scope.signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function grpcCall(call, spec, method, payload, scope) {
+    let metadata;
+    try {
+        metadata = validateMetadata(call.metadata, spec.validateMetadata);
+    }
+    catch {
+        throw new GrpcError('INVALID_ARGUMENT', 'invalid metadata');
+    }
+    return {
+        kind: 'grpc',
+        service: spec.definition.name,
+        method,
+        payload,
+        headers: metadata.headers,
+        binaryHeaders: metadata.binaryHeaders,
+        peer: call.getPeer(),
+        signal: scope.signal,
+        remainingMs: () => scope.remainingMs(),
+        setTrailer: (key, value) => {
+            scope.setTrailer(key, value);
+        },
+    };
+}
+function callScope(call, maxDurationMs) {
+    const controller = new AbortController();
+    const trailerValues = Object.create(null);
+    const now = Date.now();
+    const callerDeadline = deadlineTime(call.getDeadline());
+    const serverDeadline = maxDurationMs === undefined ? Number.POSITIVE_INFINITY : now + maxDurationMs;
+    const deadline = Math.min(callerDeadline, serverDeadline);
+    let timer;
+    const abort = (reason) => {
+        if (!controller.signal.aborted)
+            controller.abort(reason);
+    };
+    const onCancelled = () => {
+        const expired = Number.isFinite(deadline) && Date.now() >= deadline;
+        abort(expired ? new GrpcError('DEADLINE_EXCEEDED', 'deadline exceeded') : new GrpcError('CANCELLED', 'call cancelled'));
+    };
+    const scheduleDeadline = () => {
+        if (!Number.isFinite(deadline) || controller.signal.aborted)
+            return;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            abort(new GrpcError('DEADLINE_EXCEEDED', 'deadline exceeded'));
+            return;
+        }
+        timer = setTimeout(scheduleDeadline, Math.min(remaining, 2_147_483_647));
+    };
+    call.on('cancelled', onCancelled);
+    if (call.cancelled)
+        onCancelled();
+    scheduleDeadline();
+    return {
+        signal: controller.signal,
+        trailers: trailerValues,
+        remainingMs: () => {
+            if (controller.signal.aborted)
+                return 0;
+            return Number.isFinite(deadline) ? Math.max(0, deadline - Date.now()) : Number.POSITIVE_INFINITY;
+        },
+        setTrailer: (key, value) => {
+            const probe = new Metadata();
+            probe.set(key, value);
+            trailerValues[key] = value;
+        },
+        reason: () => controller.signal.reason instanceof GrpcError
+            ? controller.signal.reason
+            : new GrpcError('CANCELLED', 'call cancelled'),
+        close: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            call.removeListener('cancelled', onCancelled);
+        },
+    };
+}
+function deadlineTime(deadline) {
+    return deadline instanceof Date ? deadline.getTime() : deadline;
+}
+function validateMetadata(metadata, validate) {
+    return validate(metadataValue(metadata));
+}
+function metadataValue(metadata) {
+    const headers = Object.create(null);
+    const binaryHeaders = Object.create(null);
+    for (const [key, values] of Object.entries(metadata.toJSON())) {
+        const value = values[0];
+        if (typeof value === 'string') {
+            headers[key] = value;
+        }
+        else if (value !== undefined) {
+            binaryHeaders[key] = Uint8Array.from(value);
+        }
+    }
+    return { headers, binaryHeaders };
+}
+function outboundMetadata(metadata) {
+    const result = new Metadata();
+    if (metadata === undefined)
+        return result;
+    for (const [key, value] of Object.entries(metadata.headers))
+        result.set(key, value);
+    for (const [key, value] of Object.entries(metadata.binaryHeaders))
+        result.set(key, grpcBytes(value));
+    return result;
+}
+function trailers(values) {
+    const result = new Metadata();
+    for (const [key, value] of Object.entries(values))
+        result.set(key, value);
+    return result;
+}
+function boundaryError(error, scope, spec, method) {
+    if (error instanceof GrpcError)
+        return error;
+    if (scope.signal.aborted)
+        return scope.reason();
+    try {
+        spec.onError({
+            service: spec.definition.name,
+            method,
+            status: 'INTERNAL',
+            error,
+        });
+    }
+    catch {
+        // Observation must not replace the fixed boundary error.
+    }
+    return new GrpcError('INTERNAL', 'internal error');
+}
+function serverError(error) {
+    return Object.assign(new Error(error.details), {
+        code: statusCode(error.status),
+        details: error.details,
+    });
+}
+function statusCode(value) {
+    switch (value) {
+        case 'OK':
+            return status.OK;
+        case 'CANCELLED':
+            return status.CANCELLED;
+        case 'INVALID_ARGUMENT':
+            return status.INVALID_ARGUMENT;
+        case 'DEADLINE_EXCEEDED':
+            return status.DEADLINE_EXCEEDED;
+        case 'NOT_FOUND':
+            return status.NOT_FOUND;
+        case 'ALREADY_EXISTS':
+            return status.ALREADY_EXISTS;
+        case 'PERMISSION_DENIED':
+            return status.PERMISSION_DENIED;
+        case 'RESOURCE_EXHAUSTED':
+            return status.RESOURCE_EXHAUSTED;
+        case 'FAILED_PRECONDITION':
+            return status.FAILED_PRECONDITION;
+        case 'UNIMPLEMENTED':
+            return status.UNIMPLEMENTED;
+        case 'INTERNAL':
+            return status.INTERNAL;
+        case 'UNAVAILABLE':
+            return status.UNAVAILABLE;
+        case 'UNAUTHENTICATED':
+            return status.UNAUTHENTICATED;
+    }
+}
+function serverCredentials(options) {
+    if (options === 'insecure')
+        return ServerCredentials.createInsecure();
+    return ServerCredentials.createSsl(options.rootCertificates === undefined ? null : grpcBytes(options.rootCertificates), options.keyCertPairs.map(pair => ({
+        private_key: grpcBytes(pair.privateKey),
+        cert_chain: grpcBytes(pair.certificateChain),
+    })), options.checkClientCertificate);
+}
+function clientCredentials(options) {
+    if (options === 'insecure')
+        return credentials.createInsecure();
+    const hasPrivateKey = options.privateKey !== undefined;
+    const hasCertificate = options.certificateChain !== undefined;
+    if (hasPrivateKey !== hasCertificate) {
+        throw new Error('@zmdb/transport-grpc: gRPC client privateKey and certificateChain must be supplied together');
+    }
+    return credentials.createSsl(options.rootCertificates === undefined ? null : grpcBytes(options.rootCertificates), options.privateKey === undefined ? null : grpcBytes(options.privateKey), options.certificateChain === undefined ? null : grpcBytes(options.certificateChain));
+}
+function bindServer(server, address, creds) {
+    return new Promise((resolve, reject) => {
+        server.bindAsync(address, creds, (error, port) => {
+            if (error === null)
+                resolve(port);
+            else
+                reject(error);
+        });
+    });
+}
+function closeServer(server, graceMs) {
+    if (!Number.isFinite(graceMs) || graceMs < 0) {
+        throw new RangeError('@zmdb/transport-grpc: graceMs must be a non-negative finite number');
+    }
+    if (graceMs === 0) {
+        server.forceShutdown();
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            server.forceShutdown();
+            resolve();
+        }, graceMs);
+        server.tryShutdown(error => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error === undefined)
+                resolve();
+            else
+                reject(error);
+        });
+    });
+}
+function clientCaller(client, method, options) {
+    if (method.requestStream) {
+        return method.responseStream
+            ? (payload, callOptions) => bidiCall(client, method, payload, options, callOptions)
+            : (payload, callOptions) => clientStreamCall(client, method, payload, options, callOptions);
+    }
+    return method.responseStream
+        ? (payload, callOptions) => serverStreamCall(client, method, payload, options, callOptions)
+        : (payload, callOptions) => unaryCall(client, method, payload, options, callOptions);
+}
+function unaryCall(client, method, payload, options, callOptions) {
+    const request = method.validateRequest(payload);
+    const deadlineMs = callDeadline(options.deadlineMs, callOptions);
+    return new Promise((resolve, reject) => {
+        let observation;
+        let removeAbort = () => undefined;
+        const call = client.makeUnaryRequest(method.path, value => grpcBytes(method.serializeRequest(method.validateRequest(value))), bytes => method.validateResponse(method.deserializeResponse(bytes)), request, outboundMetadata(callOptions?.metadata), { deadline: Date.now() + deadlineMs }, (error, response) => {
+            removeAbort();
+            if (error !== null) {
+                reject(observation?.error ?? error);
+            }
+            else {
+                resolve(response);
+            }
+        });
+        observation = new ClientObservation(call, options.validateMetadata, callOptions);
+        removeAbort = attachAbort(call, callOptions?.signal);
+    });
+}
+function clientStreamCall(client, method, payload, options, callOptions) {
+    const deadlineMs = callDeadline(options.deadlineMs, callOptions);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let observation;
+        let removeAbort = () => undefined;
+        const call = client.makeClientStreamRequest(method.path, value => grpcBytes(method.serializeRequest(method.validateRequest(value))), bytes => method.validateResponse(method.deserializeResponse(bytes)), outboundMetadata(callOptions?.metadata), { deadline: Date.now() + deadlineMs }, (error, response) => {
+            if (settled)
+                return;
+            settled = true;
+            removeAbort();
+            if (error !== null)
+                reject(observation?.error ?? error);
+            else
+                resolve(response);
+        });
+        observation = new ClientObservation(call, options.validateMetadata, callOptions);
+        removeAbort = attachAbort(call, callOptions?.signal);
+        void pumpRequests(call, payload, method).catch(error => {
+            if (settled)
+                return;
+            settled = true;
+            removeAbort();
+            call.cancel();
+            reject(error);
+        });
+    });
+}
+function serverStreamCall(client, method, payload, options, callOptions) {
+    const request = method.validateRequest(payload);
+    const deadlineMs = callDeadline(options.deadlineMs, callOptions);
+    const call = client.makeServerStreamRequest(method.path, value => grpcBytes(method.serializeRequest(method.validateRequest(value))), bytes => method.validateResponse(method.deserializeResponse(bytes)), request, outboundMetadata(callOptions?.metadata), { deadline: Date.now() + deadlineMs });
+    const observation = new ClientObservation(call, options.validateMetadata, callOptions);
+    const removeAbort = attachAbort(call, callOptions?.signal);
+    return clientResponses(call, observation, removeAbort);
+}
+function bidiCall(client, method, payload, options, callOptions) {
+    const deadlineMs = callDeadline(options.deadlineMs, callOptions);
+    const call = client.makeBidiStreamRequest(method.path, value => grpcBytes(method.serializeRequest(method.validateRequest(value))), bytes => method.validateResponse(method.deserializeResponse(bytes)), outboundMetadata(callOptions?.metadata), { deadline: Date.now() + deadlineMs });
+    const observation = new ClientObservation(call, options.validateMetadata, callOptions);
+    const removeAbort = attachAbort(call, callOptions?.signal);
+    const pumping = requestPump(call, payload, method);
+    return clientResponses(call, observation, removeAbort, pumping);
+}
+function callDeadline(defaultMs, options) {
+    const value = options?.deadlineMs ?? defaultMs;
+    validatePositiveDuration(value, 'deadlineMs');
+    return value;
+}
+async function pumpRequests(call, requests, method) {
+    for await (const request of requests) {
+        const valid = method.validateRequest(request);
+        if (!call.write(valid))
+            await once(call, 'drain');
+    }
+    call.end();
+}
+function requestPump(call, requests, method) {
+    let failure = { failed: false };
+    const done = pumpRequests(call, requests, method).catch(error => {
+        failure = { failed: true, error };
+        call.cancel();
+    });
+    return {
+        done,
+        failure: () => failure,
+    };
+}
+async function* clientResponses(call, observation, removeAbort, pumping) {
+    let completed = false;
+    try {
+        for await (const response of call) {
+            observation.throwIfInvalid();
+            yield response;
+        }
+        if (pumping !== undefined) {
+            await pumping.done;
+            throwPumpFailure(pumping);
+        }
+        await observation.finished;
+        observation.throwIfInvalid();
+        completed = true;
+    }
+    catch (error) {
+        observation.throwIfInvalid();
+        if (pumping !== undefined)
+            throwPumpFailure(pumping);
+        throw error;
+    }
+    finally {
+        removeAbort();
+        if (!completed)
+            call.cancel();
+    }
+}
+function throwPumpFailure(pumping) {
+    const failure = pumping.failure();
+    if (failure.failed)
+        throw failure.error;
+}
+class ClientObservation {
+    error;
+    finished;
+    #finish;
+    #call;
+    #validate;
+    constructor(call, validate, options) {
+        this.#call = call;
+        this.#validate = validate;
+        let finish = () => undefined;
+        this.finished = new Promise(resolve => {
+            finish = resolve;
+        });
+        this.#finish = finish;
+        call.on('metadata', metadata => {
+            this.#observe(metadata, options?.onMetadata);
+        });
+        call.on('status', result => {
+            this.#observe(result.metadata, options?.onTrailer);
+            this.#finish();
+        });
+    }
+    throwIfInvalid() {
+        if (this.error !== undefined)
+            throw this.error;
+    }
+    #observe(metadata, callback) {
+        if (this.error !== undefined)
+            return;
+        try {
+            const value = validateMetadata(metadata, this.#validate);
+            callback?.(value);
+        }
+        catch (error) {
+            this.error = error;
+            this.#call.cancel();
+            this.#finish();
+        }
+    }
+}
+function attachAbort(call, signal) {
+    if (signal === undefined)
+        return () => undefined;
+    const onAbort = () => {
+        call.cancel();
+    };
+    if (signal.aborted)
+        onAbort();
+    else
+        signal.addEventListener('abort', onAbort, { once: true });
+    return () => {
+        signal.removeEventListener('abort', onAbort);
+    };
+}
+//# sourceMappingURL=runtime.js.map