Examples

Example 1

import { createApplication } from '@setu-ts/kernel';
import { RuntimePlugin } from '@setu-ts/runtime';
import { GrpcPlugin } from '@setu-ts/grpc-plugin';
import { CAPABILITIES, type IGrpcService } from '@setu-ts/common';

const app = createApplication({
  plugins: [RuntimePlugin(), GrpcPlugin()],
});

await app.start({ port: 3000 });

// The plugin registers CAPABILITIES.GRPC during start(), so resolve it
// only AFTER start() resolves — before that, the capability does not exist.
const grpc = app.services.get<IGrpcService>(CAPABILITIES.GRPC);

Classes

c
GrpcDescriptorError(
detail: string,
options?: ErrorOptions
)

Thrown when an embedded descriptor set cannot be decoded, or when a service the plugin expects to find inside one is absent — i.e. the committed base64 constant is truncated, swapped, or regenerated against an incompatible proto.

c
GrpcRuntimeLoadError(
specifier: string,
installCommand: string,
options?: ErrorOptions
)

Thrown when any of the Connect runtime modules cannot be imported. Carries the exact specifier that failed and the suggested install command.

c
GrpcService(init: GrpcServiceOptions)

The gRPC service applications use to register Connect/gRPC services.

c
GrpcUnavailableError()

Thrown when the adapter does not support the RPC interceptor seam (i.e., IHttpAdapter.setRpcHandler? is not available) and an attempt is made to handle a request directly through GrpcService.handleRequest.

Functions

f
adaptConnectModule(modules: ConnectModuleLike): ConnectRuntime

Adapts already-imported Connect and Protobuf-ES modules into the internal ConnectRuntime port. Pure — it performs no I/O, so unit tests drive it with a fake module bundle.

Interfaces

I
GrpcPluginOptions

Options for the gRPC plugin.

  • basePath: string

    Base path under which gRPC/Connect services are served. Defaults to the root ('/', M70i). A gRPC-family client derives its path from the fully-qualified method name alone and has no prefix option, so a prefixed default puts every procedure at an address no such client asks for. At the root, unknown paths fall through to Hono and only registered procedure paths are claimed. This makes Connect and gRPC-Web reachable at their natural addresses; native application/grpc reaches the server too but is deliberately refused with a Trailers-Only UNIMPLEMENTED. Pass '/grpc' to restore the pre-M70i prefix.

  • connectModule: ConnectRuntime

    Injected Connect runtime module(s). When provided, avoids the lazy import. Used by tests to avoid network dependencies.

  • health: boolean

    Whether to enable the gRPC Health v1 service (bridged to M20 health plugin). Defaults to true.

  • interceptors: readonly unknown[]

    Application-supplied Connect interceptors, threaded into createConnectRouter({ interceptors }) (M70f §3.7). The plugin's built-in handler-error logging wraps each application service's implementation (innermost), so a handler throw is logged before an application interceptor observes it. Absent: no application interceptors are installed.

  • reflection: boolean

    Whether to enable server reflection (v1). Defaults to true.

  • services: Array<{ definition: unknown; implementation?: unknown; }>

    Initial services to register. Each entry contains a service definition and an optional implementation object.

I
GrpcServiceDefinition

A gRPC service definition that satisfies the plugin's expectations. This is a structural constraint satisfied by generated descriptor objects from @bufbuild/protobuf. It contains only the fields the plugin needs to route requests and build reflection data.

I
IGrpcService

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

Type Aliases

T
GrpcServingStatus = "unknown" | "serving" | "not-serving" | "service-unknown"

The serving status returned by the health bridge. These values map onto the gRPC v1 Health response enum.

T
RpcFetchHandler = (request: Request) => Promise<Response | null>

A fetch handler that attempts to handle a gRPC/Connect request. Returns a Response if the request was handled as RPC, otherwise returns null so the adapter falls through to normal Hono handling.

Variables

v
CAPABILITIES: { RUNTIME: string; LOGGER: string; CONFIG: string; VALIDATION: string; DATABASE: string; CACHE: string; EVENTS: string; MESSAGING: string; AUTH: string; AUTHORIZATION: string; JWT: string; SCHEDULER: string; METRICS: string; HEALTH: string; OPENAPI: string; TELEMETRY: string; SECRETS: string; AUDIT: string; RESILIENCE: string; STORAGE: string; MAIL: string; NOTIFICATION: string; FEATURE_FLAGS: string; QUEUE: string; CQRS: string; COMMAND_BUS: string; QUERY_BUS: string; MULTI_TENANCY: string; WORKER_POOL: string; DI_CONTAINER: string; HTTP_ADAPTER: string; SSE: string; WEBSOCKET: string; REALTIME_BACKPLANE: string; SSR: string; SESSION: string; SERVICE_DISCOVERY: string; HEALTH_INDICATOR: string; METRIC_REGISTRATION: string; OPENAPI_SCHEMA: string; CLI_COMMAND: string; DECORATOR_HANDLER: string; METADATA_STORE: string; GRPC: string; CLOUDFLARE: string; GRAPHQL: string; STATIC_FILES: string; VIEW: string; }

Standard capability tokens provided by the first-party plugins.

Usage

import * as gRPC_plugin_for_Setu_TS___enables_co_serving_of_Connect_and_gRPC_Web_protocols__native__application_grpc__is_refused_with_a_Trailers_Only__UNIMPLEMENTED___on_the_same_port_as_ordinary_Hono_routes__The_plugin_registers_an___linkcode_IGrpcService__under__CAPABILITIES_GRPC___since_M70a_the_kernel_dispatches_RPC_from_its_terminal_handler_after_the_middleware_pipeline__so_no_HTTP_adapter_interceptor_is_involved__ from "grpc-plugin/src/index.ts";