Concepts
A reader who is comfortable with REST but new to the gRPC ecosystem will hit unfamiliar terms in the first few pages — interceptor, gateway, vtprotobuf, OTLP, span. This page collects them in one place so you can scan a definition and follow the link for depth.
Table of contents
gRPC
A high-performance RPC framework from Google that uses HTTP/2 as the transport and Protocol Buffers as the schema/wire format. Methods are typed (request and response messages are defined in .proto files) and code is generated for both client and server, so the network call looks like a local function call. ColdBrew is gRPC-first — every service starts as a gRPC server, and the HTTP/JSON surface is generated from the same proto definition. See grpc.io for the upstream docs and APIs how-to for how ColdBrew wires it up.
gRPC reflection
Server reflection is a gRPC feature that lets a client discover the available methods and message types at runtime, without needing the .proto files locally. Tools like grpcurl, grpcui, and Postman use reflection to call services interactively. ColdBrew enables it by default; disable it on public-facing services with DISABLE_GRPC_REFLECTION=true (see Production Deployment).
grpc-gateway
grpc-gateway is a code generator that produces a reverse-proxy HTTP/1.1+JSON server in front of your gRPC service, mapping HTTP routes to gRPC methods using google.api.http annotations in the proto. ColdBrew runs the gateway in-process alongside the gRPC server so a single binary speaks both protocols. See APIs how-to for the routing annotations and HTTP Gateway Extensions for adding custom marshalers or middleware.
Interceptors
Interceptors are gRPC’s middleware. They wrap each unary or streaming RPC, running code before and after the handler — logging, tracing, metrics, validation, panic recovery, auth. ColdBrew ships a default chain (response-time logging → trace ID → OpenTelemetry → Prometheus → error notification → New Relic → panic recovery) and exposes hooks to insert your own. See Interceptors how-to for the chain order and how to add custom interceptors, and Authentication for an auth-interceptor example.
vtprotobuf
vtprotobuf is a code generator that produces faster Marshal/Unmarshal methods for Protocol Buffer messages — typically 2–3× faster than the reflection-based standard implementation. ColdBrew uses vtprotobuf as its default gRPC codec with automatic fallback to standard protobuf when a message type doesn’t have generated VT methods. See vtprotobuf how-to for the generator setup.
Protovalidate
Protovalidate defines validation rules as proto annotations (buf.validate.field) and enforces them at runtime. ColdBrew applies validation automatically on both gRPC and HTTP requests, so a malformed payload is rejected with InvalidArgument before it reaches your handler. See Interceptors how-to — Proto Validation.
OTLP
OpenTelemetry Protocol — the wire format used by OpenTelemetry to ship traces, metrics, and logs from your service to a collector or backend. Most modern observability stacks (Jaeger, Tempo, Honeycomb, Datadog, New Relic) accept OTLP, so configuring ColdBrew with OTLP_ENDPOINT keeps you portable. See Tracing how-to and Production Deployment — Distributed tracing.
Trace ID
A unique identifier attached to a request that follows it across every service, log line, and span. ColdBrew generates one per request (or accepts one from the TRACE_HEADER_NAME HTTP header / proto trace_id field), propagates it through context, and adds it to every log line and span automatically. The trace ID is what makes “find every log for this user’s failed checkout” tractable in a centralized log sink. See Tracing how-to and Debugging.
Span
A span represents one unit of work inside a trace — a function call, a database query, an outbound HTTP call. Spans nest inside each other, so a single trace becomes a tree showing where time was spent. ColdBrew exposes three helpers — tracing.NewInternalSpan, tracing.NewDatastoreSpan, tracing.NewExternalSpan — that create the right span type for the operation and put it in context.Context. See Tracing how-to.
Circuit breaker
A circuit breaker watches the failure rate of an outbound call (a downstream gRPC service, a database, an external API) and “opens” — fast-fails subsequent calls — once failures exceed a threshold, giving the dependency time to recover instead of being hammered. ColdBrew exposes interceptors.SetDefaultExecutor so you can plug in any resilience library; failsafe-go is the recommended one. See Circuit Breaker / Resilience for setup and gRPC how-to — Calling other services for context.
Healthcheck vs readycheck
Two HTTP endpoints with different jobs. /healthcheck (liveness) answers is the process alive? — if it fails, Kubernetes restarts the pod. /readycheck (readiness) answers can it accept traffic right now? — if it fails, Kubernetes stops routing traffic to the pod but does not restart it. During graceful shutdown, ColdBrew fails /readycheck first, waits the drain period, then exits — so in-flight requests finish without new ones being routed in. See Production Deployment — Health probes and Readiness Patterns.
Lifecycle hooks
Optional interfaces a service can implement to run code at well-defined points in startup and shutdown: CBPreStarter (before servers listen), CBPostStarter (after they listen), CBPreStopper / CBStopper / CBPostStopper (during graceful shutdown), and CBGracefulStopper.FailCheck (toggle readiness). Use them to open and drain database pools, register/deregister with service discovery, flush buffers, and so on — without touching core itself. See Shutdown Lifecycle for the full table.
Where to go next
- Quick Start — Generate a service from the cookiecutter and run it locally.
- How-To Guides — Task-oriented guides grouped by Build / Operate / Integrate / Advanced.
- Architecture — How the pieces fit together end-to-end.