bazis 0.96.1

package/core/grpc/Grpc.module.ts

@@ -0,0 +1,23 @@
+import { DI, DiContainer, HOSTED_SERVICE, Module, SERVICE_PROVIDER, type BazisModule } from "../di";
+import type { GrpcModuleOptions } from "./contracts";
+import { GrpcServer } from "./GrpcServer";
+import { collectGrpcControllers, GRPC_CONTROLLERS } from "./moduleControllers";
+
+/** gRPC counterpart of httpModule: controllers belong to their feature modules. */
+export function grpcModule(options: GrpcModuleOptions = {}): BazisModule {
+  const selected = collectGrpcControllers(options.imports ?? [], options.controllers);
+  @Module({
+    imports: options.imports,
+    grpcControllers: options.controllers,
+    providers: [DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => {
+      const container = resolver.resolve(SERVICE_PROVIDER);
+      if (!(container instanceof DiContainer)) throw new TypeError("gRPC requires a module DI container.");
+      const controllers = container.getModuleOwnedProviderContributions(GRPC_CONTROLLERS)
+        .filter((entry) => selected.has(entry.payload.controller));
+      return new GrpcServer(options, container, controllers);
+    }))],
+    exports: [],
+  })
+  class GrpcModule {}
+  return GrpcModule;
+}

package/core/grpc/GrpcBinding.contract.ts

@@ -0,0 +1,35 @@
+import { createGeneratedProviderAttachmentChannel, getGeneratedProviderAttachment } from "../di/module/generatedProviderAttachments";
+import type { RequestModelClass } from "../http/Binding/requestModelRegistry";
+import type { Class } from "../di";
+
+interface RequestBinding {
+  readonly model: RequestModelClass;
+  readonly requestStream: boolean;
+}
+type RequestBindings = Readonly<Record<string, RequestBinding>>;
+
+/** @internal Exact-class metadata; committed/rolled back with the generated target. */
+export const GRPC_REQUEST_BINDINGS = createGeneratedProviderAttachmentChannel<RequestBindings>({
+  description: "gRPC request DTOs",
+  normalize(target, value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("Invalid gRPC DTO bindings.");
+    const snapshot: Record<string, RequestBinding> = Object.create(null);
+    for (const [name, binding] of Object.entries(value)) {
+      if (!binding || typeof binding.model !== "function" || !binding.model.prototype
+        || typeof binding.requestStream !== "boolean" || typeof target.prototype[name] !== "function") {
+        throw new TypeError(`Invalid gRPC DTO binding: ${target.name}.${name}.`);
+      }
+      snapshot[name] = Object.freeze({ model: binding.model, requestStream: binding.requestStream });
+    }
+    return Object.freeze(snapshot);
+  },
+  equals(left, right) {
+    return Object.keys(left).length === Object.keys(right).length
+      && Object.keys(left).every((key) => left[key]!.model === right[key]?.model
+        && left[key]!.requestStream === right[key]?.requestStream);
+  },
+});
+
+export function getGrpcRequestBinding(controller: Class<object>, name: string | symbol): RequestBinding | undefined {
+  return typeof name === "string" ? getGeneratedProviderAttachment(GRPC_REQUEST_BINDINGS, controller)?.[name] : undefined;
+}

package/core/grpc/GrpcCall.ts

@@ -0,0 +1,73 @@
+import type { ModuleOwnedProviderActivation, ServiceProvider } from "../di";
+import type { GrpcContext } from "./contracts";
+import type { MethodDefinition } from "./serviceDefinition";
+import { GrpcTransport } from "./GrpcTransport";
+import { GrpcStatus } from "./GrpcStatus";
+import type { GrpcRequestBinding } from "./GrpcRequest.binding";
+
+/** One RPC owns its handler and DI scope, even after the peer disconnects. */
+export class GrpcCall {
+  constructor(
+    private readonly transport: GrpcTransport,
+    private readonly definition: MethodDefinition,
+    private readonly methodName: string | symbol,
+    private readonly activation: ModuleOwnedProviderActivation<object>,
+    private readonly provider: ServiceProvider,
+    private readonly binding?: GrpcRequestBinding,
+  ) {}
+
+  cancel(): void { this.transport.cancel(GrpcStatus.UNAVAILABLE, "Server stopped."); }
+
+  async run(): Promise<void> {
+    const scope = this.provider.createScope();
+    const context = this.transport.context;
+    let result: unknown;
+    let failure: unknown;
+    let failed = false;
+    let inputFailure: unknown;
+    let inputFailed = false;
+    const bind = (value: unknown): unknown => {
+      try { return this.binding?.bind(value) ?? value; }
+      catch (error) { inputFailure = error; inputFailed = true; throw error; }
+    };
+    const requests = this.transport.requests();
+    async function* validatedRequests(): AsyncIterable<unknown> {
+      for await (const value of requests) yield bind(value);
+    }
+    try {
+      context.signal.throwIfAborted();
+      const input = this.definition.requestStream
+        ? (this.binding ? validatedRequests() : requests)
+        : bind(await this.transport.unaryRequest());
+      const instance = await this.activation.activateAsync(scope);
+      context.signal.throwIfAborted();
+      const handler = Reflect.get(instance, this.methodName) as (input: unknown, context: GrpcContext) => unknown;
+      result = await handler.call(instance, input, context);
+      if (inputFailed) throw inputFailure;
+      if (this.definition.responseStream) {
+        if (!result || typeof (result as AsyncIterable<unknown>)[Symbol.asyncIterator] !== "function") {
+          throw new TypeError("A response-streaming gRPC handler must return AsyncIterable.");
+        }
+        for await (const message of result as AsyncIterable<unknown>) {
+          if (inputFailed) throw inputFailure;
+          context.signal.throwIfAborted();
+          await this.transport.write(message);
+        }
+      }
+      if (inputFailed) throw inputFailure;
+      context.signal.throwIfAborted();
+    } catch (error) {
+      failure = error; failed = true;
+    } finally {
+      // Do not dispose dependencies while non-cooperative handler code is running.
+      try { await scope.dispose(); } catch (error) { failure = error; failed = true; }
+    }
+    if (failed) this.transport.fail(failure);
+    else {
+      try {
+        if (!this.definition.responseStream) await this.transport.write(result);
+        this.transport.finish();
+      } catch (error) { this.transport.fail(error); }
+    }
+  }
+}

package/core/grpc/GrpcClient.ts

@@ -0,0 +1,172 @@
+import { connect, type ClientHttp2Session, type SecureClientSessionOptions } from "node:http2";
+import type { GrpcCallOptions, GrpcClientOptions, GrpcResponse, GrpcResponseStream } from "./clientContracts";
+import { GrpcClientCall } from "./GrpcClientCall";
+import { GrpcError } from "./GrpcError";
+import { GrpcStatus } from "./GrpcStatus";
+import { Metadata } from "./Metadata";
+import type { MethodDefinition, ServiceDefinition } from "./serviceDefinition";
+
+/** Standard gRPC/HTTP2 client using only built-in networking and Bazis codecs. */
+export class GrpcClient {
+  private readonly methods = new Map<string, MethodDefinition | null>();
+  private readonly sessions = new Map<ClientHttp2Session, Set<GrpcClientCall<unknown>>>();
+  private readonly calls = new Set<GrpcClientCall<unknown>>();
+  private readonly address: string;
+  private readonly tls: SecureClientSessionOptions;
+  private readonly metadata: Metadata;
+  private readonly timeout: number;
+  private readonly sendLimit: number;
+  private readonly receiveLimit: number;
+  private readonly callLimit: number;
+  private current?: ClientHttp2Session;
+  private closed = false;
+
+  constructor(service: ServiceDefinition, options: GrpcClientOptions) {
+    fields(options, ["address", "tls", "metadata", "timeoutMs", "maxSendMessageLength", "maxReceiveMessageLength", "maxConcurrentCalls"], "GrpcClientOptions");
+    if (typeof options.address !== "string" || options.address.trim() !== options.address || !options.address) throw new TypeError("gRPC address is required.");
+    const hasScheme = options.address.includes("://");
+    if (!hasScheme && !/^(?:\[[^\]]+\]|[^:/?#@\s]+):\d+$/.test(options.address)) throw new TypeError("gRPC address must be host:port or an HTTP(S) origin.");
+    const url = new URL(hasScheme ? options.address : `http://${options.address}`);
+    if (!["http:", "https:"].includes(url.protocol) || !url.hostname || url.username || url.password
+      || url.pathname !== "/" || url.search || url.hash || url.port === "0") throw new TypeError("Invalid gRPC address.");
+    this.address = url.origin;
+    this.tls = { rejectUnauthorized: true, settings: { enablePush: false, maxHeaderListSize: 8192 }, maxHeaderListPairs: 128 };
+    if (options.tls !== undefined) {
+      fields(options.tls, ["ca", "cert", "key", "servername"], "GrpcClientTlsOptions");
+      if (url.protocol !== "https:") throw new TypeError("gRPC TLS options require an https address.");
+      for (const key of ["ca", "cert", "key"] as const) {
+        const value = options.tls[key];
+        if (value !== undefined) {
+          if (!(typeof value === "string" && value.length > 0) && !(Buffer.isBuffer(value) && value.length > 0)) throw new TypeError(`Invalid TLS ${key}.`);
+          this.tls[key] = Buffer.isBuffer(value) ? Buffer.from(value) : value;
+        }
+      }
+      if ((options.tls.cert === undefined) !== (options.tls.key === undefined)) throw new TypeError("TLS cert and key must be provided together.");
+      if (options.tls.servername !== undefined) {
+        if (typeof options.tls.servername !== "string" || !options.tls.servername.trim()) throw new TypeError("Invalid TLS servername.");
+        this.tls.servername = options.tls.servername;
+      }
+    }
+    this.metadata = metadataCopy(options.metadata);
+    this.timeout = integer(options.timeoutMs, 30_000, 1, 2_147_483_647, "timeoutMs");
+    this.sendLimit = integer(options.maxSendMessageLength, 4 * 1024 * 1024, 0, 2_147_483_647, "maxSendMessageLength");
+    this.receiveLimit = integer(options.maxReceiveMessageLength, 4 * 1024 * 1024, 0, 2_147_483_647, "maxReceiveMessageLength");
+    this.callLimit = integer(options.maxConcurrentCalls, 1024, 1, Number.MAX_SAFE_INTEGER, "maxConcurrentCalls");
+    if (!service || typeof service !== "object" || !Object.keys(service).length) throw new TypeError("GrpcClient requires a non-empty service definition.");
+    const paths = new Set<string>();
+    for (const [key, value] of Object.entries(service)) {
+      if (!value || typeof value.path !== "string" || !/^\/[^/\s?#]+\/[^/\s?#]+$/.test(value.path)
+        || typeof value.requestStream !== "boolean" || typeof value.responseStream !== "boolean"
+        || typeof value.requestSerialize !== "function" || typeof value.responseDeserialize !== "function"
+        || value.originalName !== undefined && typeof value.originalName !== "string"
+        || paths.has(value.path)) throw new TypeError(`Invalid gRPC client method: ${key}.`);
+      paths.add(value.path);
+      const method = Object.freeze({ ...value });
+      for (const alias of new Set([key, value.originalName, value.path.split("/").at(-1)])) {
+        if (alias) this.methods.set(alias, this.methods.has(alias) ? null : method);
+      }
+    }
+  }
+
+  get activeCalls(): number { return this.calls.size; }
+
+  async unary<Request, Response>(method: string, request: Request, options?: GrpcCallOptions): Promise<GrpcResponse<Response>> {
+    return this.single(this.open<Response>(method, [request], false, false, options));
+  }
+  serverStream<Request, Response>(method: string, request: Request, options?: GrpcCallOptions): GrpcResponseStream<Response> {
+    return this.open<Response>(method, [request], false, true, options);
+  }
+  async clientStream<Request, Response>(method: string, requests: Iterable<Request> | AsyncIterable<Request>, options?: GrpcCallOptions): Promise<GrpcResponse<Response>> {
+    return this.single(this.open<Response>(method, requests, true, false, options));
+  }
+  bidi<Request, Response>(method: string, requests: Iterable<Request> | AsyncIterable<Request>, options?: GrpcCallOptions): GrpcResponseStream<Response> {
+    return this.open<Response>(method, requests, true, true, options);
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const call of this.calls) call.cancel();
+    for (const session of this.sessions.keys()) session.destroy();
+    this.sessions.clear(); this.current = undefined;
+  }
+  dispose(): void { this.close(); }
+
+  private async single<T>(call: GrpcClientCall<T>): Promise<GrpcResponse<T>> {
+    let data!: T;
+    for await (const value of call) data = value;
+    return { data, metadata: await call.metadata, trailers: await call.trailers };
+  }
+
+  private open<T>(name: string, requests: Iterable<unknown> | AsyncIterable<unknown>, requestStream: boolean, responseStream: boolean, options: GrpcCallOptions = {}): GrpcClientCall<T> {
+    const method = this.methods.get(name);
+    if (!method) throw new TypeError(`Unknown or ambiguous gRPC method: ${name}.`);
+    if (method.requestStream !== requestStream || method.responseStream !== responseStream) throw new TypeError(`Wrong gRPC call mode: ${name}.`);
+    if (!requests || typeof (requests as Iterable<unknown>)[Symbol.iterator] !== "function"
+      && typeof (requests as AsyncIterable<unknown>)[Symbol.asyncIterator] !== "function") throw new TypeError("Streaming requests must be Iterable or AsyncIterable.");
+    fields(options, ["metadata", "timeoutMs", "deadline", "signal"], "GrpcCallOptions");
+    const metadata = this.metadata.clone(); metadata.merge(metadataCopy(options.metadata));
+    const timeout = integer(options.timeoutMs, this.timeout, 1, 2_147_483_647, "timeoutMs");
+    let deadline = Date.now() + timeout;
+    if (options.deadline !== undefined) {
+      const explicit = options.deadline instanceof Date ? options.deadline.getTime() : options.deadline;
+      if (typeof explicit !== "number" || !Number.isFinite(explicit)) throw new TypeError("Invalid gRPC deadline.");
+      deadline = Math.min(deadline, explicit);
+    }
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError("Invalid gRPC signal.");
+    if (options.signal?.aborted) throw new GrpcError(GrpcStatus.CANCELLED, "RPC cancelled.");
+    if (deadline <= Date.now()) throw new GrpcError(GrpcStatus.DEADLINE_EXCEEDED, "Deadline exceeded.");
+    if (this.closed) throw new GrpcError(GrpcStatus.CANCELLED, "gRPC client is closed.");
+    if (this.calls.size >= this.callLimit) throw new GrpcError(GrpcStatus.RESOURCE_EXHAUSTED, "Too many concurrent gRPC calls.");
+    let session: ClientHttp2Session, stream: ReturnType<ClientHttp2Session["request"]>;
+    try {
+      session = this.session();
+      const remaining = Math.max(1, Math.ceil(deadline - Date.now()));
+      const wireTimeout = remaining <= 99_999_999 ? `${remaining}m` : `${Math.ceil(remaining / 1000)}S`;
+      stream = session.request({ ...metadata.toHttp2Headers(), ":method": "POST", ":path": method.path,
+        "content-type": "application/grpc+proto", te: "trailers", "grpc-accept-encoding": "identity", "grpc-timeout": wireTimeout }, { endStream: false });
+    } catch { throw new GrpcError(GrpcStatus.UNAVAILABLE, "Unable to open gRPC connection."); }
+    const call = new GrpcClientCall<T>(stream, method, { deadline, signal: options.signal, sendLimit: this.sendLimit, receiveLimit: this.receiveLimit }, () => {
+      this.calls.delete(call);
+      this.sessions.get(session)?.delete(call);
+      if (session.connecting && !this.sessions.get(session)?.size) session.destroy();
+    });
+    this.calls.add(call); this.sessions.get(session)!.add(call);
+    call.start(requests);
+    return call;
+  }
+
+  private session(): ClientHttp2Session {
+    if (this.current && !this.current.closed && !this.current.destroyed) return this.current;
+    const session = connect(this.address, this.tls);
+    this.current = session;
+    const calls = new Set<GrpcClientCall<unknown>>();
+    this.sessions.set(session, calls);
+    const disconnected = (): void => {
+      if (this.current === session) this.current = undefined;
+      for (const call of calls) call.connectionClosed();
+    };
+    session.on("error", disconnected);
+    session.on("close", () => { disconnected(); this.sessions.delete(session); });
+    session.on("goaway", () => {
+      if (this.current === session) this.current = undefined;
+      session.close();
+    });
+    return session;
+  }
+}
+
+function fields(value: unknown, allowed: readonly string[], label: string): void {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label} must be an object.`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new TypeError(`Unknown ${label} option: ${key}.`);
+}
+function integer(value: unknown, fallback: number, min: number, max: number, label: string): number {
+  if (value === undefined) return fallback;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) throw new TypeError(`Invalid gRPC ${label}.`);
+  return value;
+}
+function metadataCopy(value: Metadata | undefined): Metadata {
+  if (value === undefined) return new Metadata();
+  if (!(value instanceof Metadata)) throw new TypeError("Expected Bazis Metadata.");
+  return value.clone();
+}

package/core/grpc/GrpcClientCall.ts

@@ -0,0 +1,267 @@
+import { constants, type Http2Session, type ClientHttp2Stream, type IncomingHttpHeaders } from "node:http2";
+import type { GrpcResponseStream } from "./clientContracts";
+import { GrpcError } from "./GrpcError";
+import { GrpcStatus } from "./GrpcStatus";
+import { Metadata } from "./Metadata";
+import type { MethodDefinition } from "./serviceDefinition";
+
+interface CallSettings {
+  readonly deadline: number;
+  readonly signal?: AbortSignal;
+  readonly sendLimit: number;
+  readonly receiveLimit: number;
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void, reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no; });
+  // Metadata is optional to observe; ignoring it must not cause an unhandled rejection.
+  void promise.catch(() => {});
+  return { promise, resolve, reject };
+}
+
+/** @internal One RPC; bounded framing, pull-based download and cancellation ownership. */
+export class GrpcClientCall<T> implements GrpcResponseStream<T> {
+  private readonly initial = deferred<Metadata>();
+  private readonly terminal = deferred<Metadata>();
+  readonly metadata = this.initial.promise;
+  readonly trailers = this.terminal.promise;
+  private readonly abort = new AbortController();
+  private readonly uploadAbort = new AbortController();
+  private headers?: IncomingHttpHeaders;
+  private terminalHeaders?: IncomingHttpHeaders;
+  private timer?: ReturnType<typeof setTimeout>;
+  private input?: AsyncIterator<unknown> | Iterator<unknown>;
+  private consumed = false;
+  private finished = false;
+  private failure?: GrpcError;
+  private readonly session?: Http2Session;
+  private readonly externalCancel = (): void => this.cancel();
+
+  constructor(
+    private readonly stream: ClientHttp2Stream,
+    private readonly method: MethodDefinition,
+    private readonly settings: CallSettings,
+    private readonly onFinish: () => void,
+  ) {
+    this.session = stream.session;
+    stream.on("response", (headers: IncomingHttpHeaders, flags: number) => {
+      if (this.finished) return;
+      this.headers = headers;
+      try {
+        this.initial.resolve(Metadata.fromHttp2Headers(headers));
+        if (flags & constants.NGHTTP2_FLAG_END_STREAM) this.receiveTrailers(headers);
+        else if (headers["grpc-status"] !== undefined) throw new GrpcError(GrpcStatus.INTERNAL, "Non-terminal grpc-status.");
+      } catch (error) { this.fail(protocolError(error)); }
+    });
+    stream.on("trailers", (headers: IncomingHttpHeaders) => this.receiveTrailers(headers));
+    stream.on("error", (error: Error) => {
+      // A remote status has priority over a subsequent transport reset.
+      if (!this.terminalHeaders) this.fail(this.networkError(error));
+    });
+    stream.on("close", () => {
+      if (!this.finished && !this.terminalHeaders && !stream.readableEnded) {
+        this.fail(stream.rstCode || !this.headers ? this.networkError() : this.missingStatus());
+      }
+    });
+  }
+
+  start(requests: Iterable<unknown> | AsyncIterable<unknown>): void {
+    this.settings.signal?.addEventListener("abort", this.externalCancel, { once: true });
+    if (this.settings.signal?.aborted) { this.cancel(); return; }
+    const remaining = this.settings.deadline - Date.now();
+    if (remaining <= 0) { this.expire(); return; }
+    this.timer = setTimeout(() => this.expire(), remaining);
+    void this.send(requests).catch((error: unknown) => {
+      if (!this.uploadAbort.signal.aborted) this.fail(error instanceof GrpcError ? error
+        : new GrpcError(GrpcStatus.INVALID_ARGUMENT, "Failed to read or encode gRPC request."));
+    });
+  }
+
+  cancel(): void { this.fail(new GrpcError(GrpcStatus.CANCELLED, "RPC cancelled.")); }
+  connectionClosed(): void {
+    if (!this.terminalHeaders) this.fail(new GrpcError(GrpcStatus.UNAVAILABLE, "gRPC connection closed before completion."));
+  }
+  fail(error: GrpcError): void {
+    if (this.finished) return;
+    this.failure = error;
+    this.abort.abort(error);
+    this.initial.reject(error); this.terminal.reject(error);
+    this.finish(false);
+  }
+  private expire(): void { this.fail(new GrpcError(GrpcStatus.DEADLINE_EXCEEDED, "Deadline exceeded.")); }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    if (this.consumed) throw new TypeError("gRPC response stream can only be consumed once.");
+    this.consumed = true;
+    const reader = this.read();
+    // return() before the first next() must also cancel (generator finally would not run).
+    return {
+      next: () => reader.next(),
+      return: async () => { this.cancel(); return reader.return(undefined); },
+      throw: async (error) => { this.cancel(); return reader.throw(error); },
+    };
+  }
+
+  private async send(requests: Iterable<unknown> | AsyncIterable<unknown>): Promise<void> {
+    const stream = this.stream;
+    const asyncSource = requests as AsyncIterable<unknown>;
+    this.input = typeof asyncSource[Symbol.asyncIterator] === "function"
+      ? asyncSource[Symbol.asyncIterator]() : (requests as Iterable<unknown>)[Symbol.iterator]();
+    while (!this.uploadAbort.signal.aborted) {
+      const next = await abortable(Promise.resolve(this.input.next()), this.uploadAbort.signal);
+      if (next.done) { this.input = undefined; break; }
+      this.uploadAbort.signal.throwIfAborted();
+      const body = this.method.requestSerialize(next.value);
+      if (!Buffer.isBuffer(body)) throw new TypeError("gRPC codecs must return Buffer.");
+      if (body.length > this.settings.sendLimit) throw new GrpcError(GrpcStatus.RESOURCE_EXHAUSTED, "gRPC request message is too large.");
+      const frame = Buffer.allocUnsafe(body.length + 5);
+      frame[0] = 0; frame.writeUInt32BE(body.length, 1); body.copy(frame, 5);
+      await abortable(new Promise<void>((resolve, reject) => {
+        stream.write(frame, (error?: Error | null) => error ? reject(this.networkError()) : resolve());
+      }), this.uploadAbort.signal);
+    }
+    if (!stream.writableEnded && !stream.destroyed) stream.end();
+  }
+
+  private receiveTrailers(headers: IncomingHttpHeaders): void {
+    if (this.finished) return;
+    if (this.terminalHeaders) { this.fail(new GrpcError(GrpcStatus.INTERNAL, "Duplicate gRPC trailers.")); return; }
+    this.terminalHeaders = headers;
+    this.stopUpload();
+    // Servers may finish before consuming the request stream.
+    if (!this.stream.writableEnded && !this.stream.destroyed) this.stream.end();
+  }
+
+  private async *read(): AsyncGenerator<T> {
+    const iterator = this.stream.iterator({ destroyOnReturn: false });
+    const prefix = Buffer.alloc(5);
+    let prefixBytes = 0, message: Buffer | undefined, messageBytes = 0, count = 0, discarded = 0;
+    try {
+      while (true) {
+        this.abort.signal.throwIfAborted();
+        const next = await abortable(iterator.next(), this.abort.signal);
+        if (next.done) break;
+        const chunk = next.value as Buffer;
+        if (!this.validContentType() || Number(this.headers?.[":status"]) !== 200) {
+          discarded += chunk.length;
+          if (discarded > this.settings.receiveLimit) throw new GrpcError(GrpcStatus.RESOURCE_EXHAUSTED, "Non-gRPC response is too large.");
+          continue;
+        }
+        let offset = 0;
+        while (offset < chunk.length) {
+          this.abort.signal.throwIfAborted();
+          if (!message) {
+            const amount = Math.min(5 - prefixBytes, chunk.length - offset);
+            chunk.copy(prefix, prefixBytes, offset, offset + amount);
+            prefixBytes += amount; offset += amount;
+            if (prefixBytes !== 5) continue;
+            if (prefix[0] !== 0) throw new GrpcError(prefix[0] === 1 ? GrpcStatus.UNIMPLEMENTED : GrpcStatus.INTERNAL,
+              prefix[0] === 1 ? "Compressed gRPC messages are not supported." : "Invalid gRPC compression flag.");
+            const length = prefix.readUInt32BE(1);
+            if (length > this.settings.receiveLimit) throw new GrpcError(GrpcStatus.RESOURCE_EXHAUSTED, "gRPC response message is too large.");
+            message = Buffer.alloc(length); messageBytes = 0;
+          }
+          const amount = Math.min(message.length - messageBytes, chunk.length - offset);
+          chunk.copy(message, messageBytes, offset, offset + amount);
+          messageBytes += amount; offset += amount;
+          if (messageBytes === message.length) {
+            if (++count > 1 && !this.method.responseStream) throw new GrpcError(GrpcStatus.INTERNAL, "Unary response requires exactly one message.");
+            let value: T;
+            try { value = this.method.responseDeserialize(message) as T; }
+            catch { throw new GrpcError(GrpcStatus.INTERNAL, "Invalid protobuf response."); }
+            message = undefined; prefixBytes = 0;
+            yield value;
+          }
+        }
+      }
+      this.abort.signal.throwIfAborted();
+      const trailers = this.checkStatus();
+      if (message || prefixBytes !== 0) throw new GrpcError(GrpcStatus.INTERNAL, "Incomplete gRPC message.");
+      if (!this.method.responseStream && count !== 1) throw new GrpcError(GrpcStatus.INTERNAL, "Unary response requires exactly one message.");
+      this.terminal.resolve(trailers);
+      this.finish(true);
+    } catch (error) {
+      let failure = this.failure;
+      if (!failure) {
+        try { if (this.terminalHeaders) this.checkStatus(); }
+        catch (statusError) { failure = protocolError(statusError); }
+      }
+      failure ??= error instanceof GrpcError ? error : this.networkError();
+      this.fail(failure);
+      throw failure;
+    } finally {
+      if (!this.finished) this.cancel();
+      void iterator.return?.().catch(() => {});
+    }
+  }
+
+  private checkStatus(): Metadata {
+    if (!this.terminalHeaders && this.stream.rstCode) throw this.networkError();
+    if (!this.headers) throw this.networkError();
+    if (!this.terminalHeaders || this.terminalHeaders["grpc-status"] === undefined) throw this.missingStatus();
+    const raw = this.terminalHeaders["grpc-status"];
+    if (typeof raw !== "string" || !/^(?:[0-9]|1[0-6])$/.test(raw)) throw new GrpcError(GrpcStatus.UNKNOWN, "Invalid grpc-status.");
+    const metadata = Metadata.fromHttp2Headers(this.terminalHeaders);
+    const code = Number(raw);
+    if (code !== GrpcStatus.OK) {
+      const value = this.terminalHeaders["grpc-message"];
+      let message = typeof value === "string" ? value : "RPC failed.";
+      try { message = decodeURIComponent(message); } catch { /* Preserve malformed remote text, never hide status. */ }
+      throw new GrpcError(code, message, metadata);
+    }
+    if (Number(this.headers?.[":status"]) !== 200 || !this.validContentType()) throw new GrpcError(GrpcStatus.INTERNAL, "Invalid gRPC response headers.");
+    return metadata;
+  }
+  private validContentType(): boolean {
+    const value = this.headers?.["content-type"];
+    return typeof value === "string" && /^application\/grpc(?:\+proto)?(?:;.*)?$/i.test(value);
+  }
+  private missingStatus(): GrpcError {
+    const http = Number(this.headers?.[":status"]);
+    const code = http === 400 ? GrpcStatus.INTERNAL : http === 401 ? GrpcStatus.UNAUTHENTICATED
+      : http === 403 ? GrpcStatus.PERMISSION_DENIED : http === 404 ? GrpcStatus.UNIMPLEMENTED
+      : [429, 502, 503, 504].includes(http) ? GrpcStatus.UNAVAILABLE : GrpcStatus.UNKNOWN;
+    return new GrpcError(code, "Response ended without grpc-status.");
+  }
+  private networkError(cause?: Error): GrpcError {
+    // Local connection setup failures may surface as INTERNAL_ERROR on the stream.
+    const transportFailure = this.session?.destroyed || this.session?.closed
+      || cause && (cause as NodeJS.ErrnoException).code !== "ERR_HTTP2_STREAM_ERROR";
+    const reset = this.stream.id === undefined || transportFailure ? undefined : this.stream.rstCode;
+    const code = reset === constants.NGHTTP2_CANCEL ? GrpcStatus.CANCELLED
+      : reset === constants.NGHTTP2_ENHANCE_YOUR_CALM ? GrpcStatus.RESOURCE_EXHAUSTED
+      : reset === constants.NGHTTP2_INADEQUATE_SECURITY ? GrpcStatus.PERMISSION_DENIED
+      : reset && reset !== constants.NGHTTP2_REFUSED_STREAM ? GrpcStatus.INTERNAL : GrpcStatus.UNAVAILABLE;
+    return new GrpcError(code, "gRPC connection closed before completion.");
+  }
+  private stopUpload(): void {
+    if (this.uploadAbort.signal.aborted) return;
+    this.uploadAbort.abort(new GrpcError(GrpcStatus.CANCELLED, "Request upload stopped."));
+    const input = this.input; this.input = undefined;
+    try { void Promise.resolve(input?.return?.()).catch(() => {}); } catch { /* Best-effort user cleanup. */ }
+  }
+  private finish(success: boolean): void {
+    if (this.finished) return;
+    this.finished = true;
+    if (this.timer) clearTimeout(this.timer);
+    this.settings.signal?.removeEventListener("abort", this.externalCancel);
+    this.stopUpload();
+    try {
+      if (!this.stream.closed && !this.stream.destroyed) this.stream.close(success ? constants.NGHTTP2_NO_ERROR : constants.NGHTTP2_CANCEL);
+    } finally { this.onFinish(); }
+  }
+}
+
+function protocolError(error: unknown): GrpcError {
+  return error instanceof GrpcError ? error : new GrpcError(GrpcStatus.INTERNAL, "Invalid gRPC response metadata.");
+}
+
+function abortable<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const cancel = (): void => reject(signal.reason);
+    if (signal.aborted) { void pending.catch(() => {}); reject(signal.reason); return; }
+    signal.addEventListener("abort", cancel, { once: true });
+    pending.then(resolve, reject).finally(() => signal.removeEventListener("abort", cancel));
+  });
+}

package/core/grpc/GrpcError.ts

@@ -0,0 +1,19 @@
+import { Metadata } from "./Metadata";
+import { GrpcStatus as status } from "./GrpcStatus";
+
+/** An intentional, public RPC error. Other exceptions are redacted to INTERNAL. */
+export class GrpcError extends Error {
+  constructor(
+    readonly code: status,
+    message: string,
+    readonly metadata?: Metadata,
+  ) {
+    super(message);
+    this.name = "GrpcError";
+    if (!Number.isInteger(code) || code <= status.OK || code > status.UNAUTHENTICATED) {
+      throw new TypeError("GrpcError requires a non-OK gRPC status code.");
+    }
+    if (typeof message !== "string") throw new TypeError("GrpcError message must be a string.");
+    if (metadata !== undefined && !(metadata instanceof Metadata)) throw new TypeError("GrpcError metadata must be Bazis Metadata.");
+  }
+}

package/core/grpc/GrpcRequest.binding.ts

@@ -0,0 +1,45 @@
+import { bindModel } from "../http/Binding/modelBinder";
+import type { ModelValidationIssue, ModelValidator } from "../http/Binding/modelValidator";
+import type { RequestModelClass } from "../http/Binding/requestModelRegistry";
+import { BadRequestError, ModelValidationError } from "../http/Errors/HttpError";
+import { GrpcError } from "./GrpcError";
+import { GrpcStatus } from "./GrpcStatus";
+import { Metadata } from "./Metadata";
+
+/** A route-owned binding; all per-message state remains local to bindModel. */
+export class GrpcRequestBinding {
+  constructor(private readonly model: RequestModelClass, private readonly validator: ModelValidator) {}
+
+  bind(value: unknown): object {
+    try {
+      return bindModel(this.model, value, this.validator, { allowBinary: true });
+    } catch (error) {
+      if (!(error instanceof BadRequestError)) throw error;
+      const issues = error instanceof ModelValidationError ? error.errors
+        : [{ property: "$", message: "Invalid request structure.", code: "structure" }];
+      throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, "Request validation failed.", validationMetadata(issues));
+    }
+  }
+}
+
+function validationMetadata(issues: readonly ModelValidationIssue[]): Metadata {
+  const errors: ModelValidationIssue[] = [];
+  let truncated = false;
+  let size = Buffer.byteLength('{"errors":[],"truncated":false}');
+  for (const issue of issues) {
+    const bounded = (value: string, limit: number): string => {
+      if (value.length > limit) truncated = true;
+      return value.slice(0, limit);
+    };
+    const item = {
+      property: bounded(issue.property, 256), message: bounded(issue.message, 512),
+      ...(issue.code === undefined ? {} : { code: bounded(issue.code, 64) }),
+    };
+    size += Buffer.byteLength(JSON.stringify(item)) + (errors.length === 0 ? 0 : 1);
+    if (size > 4096) { truncated = true; break; }
+    errors.push(item);
+  }
+  const metadata = new Metadata();
+  metadata.set("bazis-validation-errors-bin", Buffer.from(JSON.stringify({ errors, truncated })));
+  return metadata;
+}