@volter/twin-temporal 0.1.0

package/src/temporal-grpc.ts

@@ -0,0 +1,139 @@
+// THE gRPC WIRE — a DELIBERATELY THIN adapter (the smtp pack's rule, one layer up) over this pack's
+// HTTP/2 framing (temporal-h2.ts).
+//
+// Everything this file knows is FRAMING: gRPC's length-prefixed messages over an HTTP/2 stream, the
+// `grpc-timeout` header, and the status trailers (https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md).
+// Which RPCs exist and what they answer is the twin's (`temporal-twin.ts` → `temporal-engine.ts`),
+// so a test that calls the handler and a client on the socket run the same code.
+//
+// Loopback bind only, as smtp: this server fakes auth (Temporal's dev server has none either) and
+// accepts any namespace's work, so it is never offered on another interface.
+import type protobuf from 'protobufjs';
+import type { H2Handler } from './temporal-h2.ts';
+import { decodeMessage, encodeMessage, serviceMethods } from './temporal-proto.ts';
+
+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,
+} as const;
+
+export class GrpcError extends Error {
+  readonly code: number;
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+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>>;
+
+type MethodTable = Map<string, { requestType: protobuf.Type; responseType: protobuf.Type; requestStream: boolean; responseStream: boolean }>;
+
+/** `grpc-timeout`: an integer and a unit (H M S m u n), PROTOCOL-HTTP2.md "Timeout". */
+export function parseGrpcTimeout(value: string | undefined): number | undefined {
+  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] as 'H'];
+  return amount * ms;
+}
+
+/** Length-prefixed messages out of a request body: [compressed flag][u32 length][bytes]... */
+export function splitGrpcFrames(body: Uint8Array): Array<{ compressed: boolean; message: Uint8Array }> {
+  const frames: Array<{ compressed: boolean; message: Uint8Array }> = [];
+  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: Uint8Array): Uint8Array {
+  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: string): string {
+  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: { services: string[]; handler: GrpcHandler }): H2Handler {
+  const tables = new Map<string, MethodTable>(options.services.map((name) => [name, serviceMethods(name)]));
+  return (request, response) => {
+      const headers = request.headers;
+      const fail = (code: number, message: string): void => {
+        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: Record<string, string> = {};
+      for (const [key, value] of Object.entries(headers)) if (!key.startsWith(':')) metadata[key] = value;
+      let decoded: Record<string, unknown>;
+      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 as 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 as Error)?.message ?? String(error)}`);
+        } finally {
+          if (timer) clearTimeout(timer);
+        }
+      })();
+  };
+}
+