interface IGrpcService
Since 0.3.0

The service contract that applications use to register gRPC/Connect services. Provided by the grpc-plugin under the CAPABILITIES.GRPC token.

Examples

Example 1

import { CAPABILITIES } from '@setu-ts/common';
import { GrpcService } from '@setu-ts/grpc-plugin';

const grpc = ctx.services.get<IGrpcService>(CAPABILITIES.GRPC);
grpc.addService(MyService, impl);

Properties

readonly
available: boolean

Whether gRPC dispatch is available.

Before M70a this reported whether the resolved HTTP adapter implemented the setRpcHandler seam. The kernel now dispatches gRPC itself, after the middleware pipeline, so no adapter capability is required and the framework's own service reports true unconditionally.

Methods

addService<TDef extends GrpcServiceDefinition>(
definition: TDef,
implementation?: unknown
): void

Registers a gRPC service definition with an optional implementation.

Since 0.3.0
optional
claims(request: Request): boolean

Whether this service claims a request — that is, whether the request path lies inside the configured basePath.

The kernel terminal handler calls this before IGrpcService.handleRequest so an ordinary unmatched route keeps the kernel's own 404. That guard cannot be derived from handleRequest, which returns Promise<Response> and never null: a path outside the base path is indistinguishable from a claimed path with no such procedure once both have collapsed into a 404.

Detection is prefix-only and deliberately so — Connect's real unary content types include application/json, so media-type sniffing would hijack ordinary application routes.

Optional for source compatibility with implementors written before this member existed. The kernel treats an absent claims as "claims nothing" and falls through to its own 404, because silently claiming every unmatched route is the more damaging default.

Since 0.6.0
optional
refuses(request: Request): Response | null

Whether this service refuses the request outright, decided from its HEADERS alone.

The kernel calls this immediately after IGrpcService.claims and before it reads the request body. That ordering is the whole point. A native application/grpc request is refused whatever its body contains, and buffering first made the refusal unreachable for the case that needs it most: a client-streaming or bidirectional call holds its request stream OPEN, so the body read never resolves and the caller receives no frames at all rather than the refusal (V5-5). grpcurl opens a bidirectional reflection stream before anything else, so it hung on every request — which is why the refusal being correct (M70i) and the base path being right (M70i) neither of them helped.

Returning a Response answers it as-is. Returning null means "no header-only decision", and the kernel proceeds to IGrpcService.handleRequest as before.

Optional for source compatibility. An implementor that omits it keeps the previous behaviour exactly, buffering included.

handleRequest(request: Request): Promise<Response>

Handles an incoming RPC request directly.

Called by the kernel terminal handler after the middleware pipeline has run and IGrpcService.claims has accepted the path; also usable directly by tests and advanced scenarios.

Returns a 404 response for a path this service claims but for which no procedure is registered. It never returns null, which is why IGrpcService.claims exists.

Usage

import { type IGrpcService } from "grpc-plugin/src/index.ts";