gRPC
Nika ships two gRPC packages, and they make opposite trades. Both are protoc-free, but only one of them is a protobuf contract:
| Package | What it is | Use it for |
|---|---|---|
common/grpcapi |
A real protobuf API, with descriptors derived from your structs at startup and served over reflection | a public or polyglot contract that generated clients call |
transport/grpcmq |
A JSON-envelope transport that reuses the microservice handler stack over gRPC | Go-to-Go service-to-service calls inside the framework |
Many services run both, on the same port, for two different callers. Jump to the half you need:
- gRPC API —
common/grpcapi, schema and reflection, no.proto. - gRPC transport —
transport/grpcmq, envelope over gRPC.
See Microservices Overview for the shared envelope, patterns and handler model that the transport half builds on.
gRPC API
common/grpcapi serves a real gRPC API defined in Go — no .proto file and no
code-generation step.
The protobuf descriptors are derived from your request and response structs when the app starts, registered in a descriptor registry, and served over gRPC server reflection. A Python, NestJS, Java or Bruno client discovers the schema exactly as it would for a protoc-generated service, and speaks ordinary protobuf on the wire. There is no custom codec and no envelope.
This is not the gRPC transport
transport/grpcmq carries the framework's JSON envelope and
routes on a pattern, which is what lets one handler also run over Redis and
TCP — and is exactly why a generated gRPC client cannot call it. This package
makes the opposite trade: a genuine protobuf contract for one protocol.
Define a service
package rpc
import (
"context"
"time"
"github.com/nika-framework/nika/common/grpcapi"
)
type GetUserRequest struct {
ID int64 `json:"id" protobuf:"1"`
}
type User struct {
ID int64 `json:"id" protobuf:"1"`
Username string `json:"username" protobuf:"2"`
CreatedAt time.Time `json:"created_at" protobuf:"3"`
// Excluded from the contract entirely.
PasswordHash string `json:"-"`
}
type UserController struct {
service *services.UserService
GetUser grpcapi.Unary[GetUserRequest, User] `grpc:"GetUser"`
}
func (c *UserController) GRPCService() string { return "UserService" }
func NewUserController(service *services.UserService) *UserController {
c := &UserController{service: service}
c.GetUser = func(ctx context.Context, in *GetUserRequest) (*User, error) {
user, err := c.service.FindOne(ctx, in.ID)
if err != nil {
return nil, grpcapi.Internal("could not read the user")
}
if user == nil {
return nil, grpcapi.NotFound("no user with id %d", in.ID)
}
return toWire(user), nil
}
return c
}
Register it like any other controller — the module system already carries it:
Wire it up
grpcapi.Setup(app, grpcapi.Config{
Addr: ":50052",
Package: "user.v1",
Insecure: true, // must be explicit; there is no implicit plaintext
})
Package is the protobuf namespace clients see, so it is a published name —
include a version, and treat changing it as breaking every generated client.
Handlers take and return typed values rather than a *gin.Context, because a gRPC
call has no URL, no query string and no HTTP status; mapping it onto an HTTP
context would misrepresent all three.
Call it from anywhere
grpcurl -plaintext 127.0.0.1:50052 list
# grpc.reflection.v1.ServerReflection
# user.v1.UserService
grpcurl -plaintext 127.0.0.1:50052 describe user.v1.User
# message User {
# int64 id = 1;
# string username = 2;
# .google.protobuf.Timestamp created_at = 3;
# }
grpcurl -plaintext -d '{"id":1}' 127.0.0.1:50052 user.v1.UserService/GetUser
That schema was reconstructed by the client from reflection. No .proto file
exists anywhere in the project.
Bruno: set the URL to 127.0.0.1:50052, TLS off, and click load methods.
Python, with no generated stubs:
import grpc
from grpc_reflection.v1alpha.proto_reflection_descriptor_database import (
ProtoReflectionDescriptorDatabase)
from google.protobuf.descriptor_pool import DescriptorPool
from google.protobuf.message_factory import GetMessageClass
channel = grpc.insecure_channel("127.0.0.1:50052")
pool = DescriptorPool(ProtoReflectionDescriptorDatabase(channel))
request_type = GetMessageClass(pool.FindMessageTypeByName("user.v1.GetUserRequest"))
reply_type = GetMessageClass(pool.FindMessageTypeByName("user.v1.User"))
call = channel.unary_unary(
"/user.v1.UserService/GetUser",
request_serializer=request_type.SerializeToString,
response_deserializer=reply_type.FromString,
)
print(call(request_type(id=1)).username)
NestJS, which wants a file, can be given one — dump the derived descriptors:
Type mapping
| Go | protobuf |
|---|---|
string |
string |
bool |
bool |
int, int64 |
int64 |
int8/16/32 |
int32 |
uint, uint64 |
uint64 |
uint8/16/32 |
uint32 |
float32 / float64 |
float / double |
[]byte |
bytes |
time.Time |
google.protobuf.Timestamp |
nested struct |
nested message |
[]T |
repeated T |
*T |
optional T (presence tracked) |
map[...] |
unsupported — fails at startup |
interface{} |
unsupported — fails at startup |
A field name comes from its json tag, falling back to snake_case of the Go name.
json:"-" or grpc:"-" leaves the field out of the contract entirely — which is
how a password hash stays off the wire structurally, rather than by remembering to
strip it.
Pin field numbers on anything published
Numbers come from declaration order unless a protobuf:"N" tag sets them.
Reordering two struct fields then silently changes the wire format for every
client already generated against it — old clients read the new bytes into the
wrong fields, with no error anywhere. Add protobuf:"N" before anyone else
depends on the schema.
Presence
A Go pointer becomes proto3 optional, so an absent field and a field set to the
zero value stay distinguishable:
type UpdateUserRequest struct {
ID int64 `json:"id" protobuf:"1"`
Username *string `json:"username" protobuf:"2"` // nil means "leave alone"
}
Without it, "clear the username" and "do not touch the username" are the same request — which is why a PATCH-shaped API needs pointers.
Errors
A gRPC client branches on the status code, so returning the right one is not cosmetic:
return nil, grpcapi.NotFound("no user with id %d", id)
return nil, grpcapi.InvalidArgument("email must be a valid address")
return nil, grpcapi.AlreadyExists("that email is taken")
return nil, grpcapi.PermissionDenied("not your account")
return nil, grpcapi.Unavailable("the upstream is down")
return nil, grpcapi.Internal("could not read the user")
Any status.Error is passed through untouched. Any other error becomes
Internal with a generic message — a raw database error can carry a DSN, a
table layout or an internal hostname, so it never reaches the caller. Log the
cause yourself, or add a logging interceptor.
Validation
Wire the framework validator in and the same validate:"..." tags that produce a
422 over REST produce InvalidArgument here:
grpcapi.Setup(app, grpcapi.Config{
...
Validate: func(request any) error {
if errs := validator.ValidateStruct(request); len(errs) > 0 {
return grpcapi.InvalidArgument("%s: %s", errs[0].Field, errs[0].Message)
}
return nil
},
})
It runs on the decoded request before the handler, so a rejected call never reaches your code.
Configuration
| Field | Default | Notes |
|---|---|---|
Addr |
:50051 |
listen address; :0 picks a free port, read it from Addr() |
Package |
— | required; the protobuf namespace |
Insecure |
false |
must be explicit to serve plaintext |
Creds |
— | transport credentials for TLS |
DisableReflection |
false |
reflection is on by default; turn it off on a public port |
MaxRecvMsgSize |
8 MiB | grpc-go's own 4 MiB default silently rejects larger payloads |
KeepaliveMinTime |
30s | without an enforcement policy a client can ping in a tight loop |
GracefulStopTimeout |
15s | GracefulStop alone can hang on a stuck stream |
UnaryInterceptors |
— | ordinary gRPC interceptors |
RegisterServices |
— | register a hand-written or generated service on the same port |
Validate |
— | runs before every handler |
What this does not do yet
- Streaming. Unary only. Server, client and bidirectional streams are not derived.
- Maps and
interface{}. Both fail at startup with a named field rather than producing a lossy schema. - Enums. A Go constant type maps to its underlying integer, not a protobuf enum.
- Breaking-change detection. There is no
.protoin version control to diff, which is the real cost of this approach: nothing stops you renaming a field. Pin field numbers, and if the contract is consumed outside your team, consider dumping the descriptors into CI and diffing them.
When you need any of those, write a .proto, generate it, and register it through
Config.RegisterServices — the two coexist on one port.
gRPC transport
transport/grpcmq is the framework's microservice transport over
gRPC. It gives you the lowest-latency request/reply of any transport here — no
correlation map, no broker hop, HTTP/2 multiplexing, deadlines propagated by the
protocol itself, and mTLS — with no .proto file and no code generation step.
The service is a hand-written grpc.ServiceDesc and the JSON envelope travels
through a registered pass-through codec. The thing to internalise first: gRPC is
not a broker, so there is nothing to hold a message while the far side is down.
Delivery guarantees
There are none, and the difference from every other transport in this section is not a detail:
- There is no store and forward. If the server is down when you
Publish, the message is lost. There is no queue to hold it and nothing to retry into. Publishstill costs a full round trip. It is fire-and-forget only in the sense that the reply is discarded; the TCP round trip and the server's handler both happen beforePublishreturns, and a server that refuses the message returns an error.- There is no fan-out. One call reaches one server.
Use gRPC for synchronous service-to-service calls, where a caller is waiting and a failure should be visible immediately. Use Kafka, NATS or RabbitMQ for events, where the publisher must not care whether a consumer exists yet.
Request is a plain unary call: the RPC itself is the correlation, which is why this is
the cheapest request/reply of the set.
Minimal working setup
A server:
package main
import (
"github.com/gin-gonic/gin"
"google.golang.org/grpc/credentials"
"github.com/nika-framework/nika"
"github.com/nika-framework/nika/common/microservice"
"github.com/nika-framework/nika/common/microservice/transport/grpcmq"
"myapp/src"
)
func main() {
app := nika.NewApp()
creds, err := credentials.NewServerTLSFromFile("server.crt", "server.key")
if err != nil {
panic(err)
}
microservice.Setup(app, microservice.Config{
Transport: grpcmq.MustNew(grpcmq.Options{
Addr: ":9000",
Creds: creds,
}),
Middleware: []gin.HandlerFunc{nika.RecoveryMiddleware()},
})
app.LoadModule(src.NewAppModule())
app.Listen(":3001")
}
Handlers declare transport:"grpc":
type UserController struct {
Create func(*gin.Context) `transport:"grpc" pattern:"user_created"`
FindOne func(*gin.Context) `transport:"grpc" pattern:"user_*"`
}
A client, handling the error:
transport, err := grpcmq.New(grpcmq.Options{
Target: "dns:///users.internal:9000",
TLSConfig: tlsConfig,
})
if err != nil {
return fmt.Errorf("grpc transport: %w", err)
}
client, err := microservice.SetupClient(app, transport)
if err != nil {
return err
}
One transport can do both halves — set Addr and Target together, and the same value
serves handlers and makes calls. New neither listens nor dials; both happen on first
use, so a peer that is briefly down does not stop this process from starting.
Configuration errors are reported by New, because a wiring mistake should stop the
process at startup rather than surface as a failed call under load.
Options
Server
| Field | Default | Purpose |
|---|---|---|
Addr |
— | Listen address, e.g. ":9000" or "127.0.0.1:0". Required by Listen. Port 0 asks the OS for a free port; read it back with Addr(). |
MaxRecvMsgSize |
8 MiB (DefaultMaxRecvMsgSize) |
Bounds an inbound message, and the send side symmetrically. |
MaxConcurrentStreams |
0 (grpc-go's default) |
Caps concurrent streams per HTTP/2 connection, so it is not a process-wide limit. |
KeepaliveMinTime |
30s (DefaultKeepaliveMinTime) |
Minimum interval between client keepalive pings the server accepts. A client that pings faster is disconnected with ENHANCE_YOUR_CALM. |
KeepalivePermitWithoutStream |
false |
Allow pings on an idle connection. Permitting them lets an idle client keep a connection and its resources alive indefinitely for free. |
ConnectionTimeout |
20s (DefaultConnectionTimeout) |
Bounds connection setup, including the TLS handshake, so a half-open connection cannot occupy a slot indefinitely. |
Concurrency |
256 (DefaultConcurrency) |
Handlers running at once across every connection. Negative means no limit. |
UnaryInterceptors, StreamInterceptors |
nil |
Applied in order. These are ordinary gRPC interceptors and work with anything from the ecosystem. |
ServerOptions |
nil |
Appended last, so they can override anything above. |
GracefulStopTimeout |
15s (DefaultGracefulStopTimeout) |
Bounds a graceful shutdown before it is forced. |
Client
| Field | Default | Purpose |
|---|---|---|
Target |
— | Address to call, in gRPC target syntax (host:port, dns:///svc:9000, unix:///tmp/s.sock). Required by Publish and Request. |
DialTimeout |
10s (DefaultDialTimeout) |
Bounds the wait for a usable connection on the first call. |
ClientKeepalive |
zero keepalive.ClientParameters |
Client-side pings. Keep Time at or above the server's KeepaliveMinTime or the server drops the connection. Only applied when Time is above zero. |
WaitForReady |
false |
Wait for a healthy connection instead of failing fast with Unavailable. Right for a transient rollout, wrong when a fast failure is the useful signal. |
ReplyTimeout |
microservice.DefaultRequestTimeout (10s) |
Request deadline when the caller passes none. |
DialOptions |
nil |
Appended last. Use them for retry policies via grpc.WithDefaultServiceConfig. |
Both halves
| Field | Default | Purpose |
|---|---|---|
Creds |
nil |
credentials.TransportCredentials for both halves. Wins over TLSConfig. |
TLSConfig |
nil |
Builds credentials when Creds is nil. |
Insecure |
false |
Must be explicitly true to run without transport security. |
Logger |
slog.Default() |
Receives malformed-message and lifecycle events. |
New requires at least one of Addr and Target.
Plaintext cannot ship by accident
New fails unless transport security is configured or Insecure is explicitly true
There is no implicit plaintext default. Set Creds, or TLSConfig, or set
Insecure: true to accept plaintext gRPC — and New returns an error naming all
three if you set none of them.
gRPC's own history of accidentally-plaintext production deployments is why grpc-go itself now requires an explicit insecure credential, and repeating that requirement here means nobody ships unencrypted traffic by forgetting a field. A message transport carries auth headers and tenant ids, so this matters more here than for a typical API.
For a local test or a loopback sidecar, say so out loud:
The protoc-free codec, and what it costs
gRPC does not care what the message bytes mean. It needs a codec that can turn a Go
value into bytes and back, and it selects one by content-subtype. This transport
registers a codec named nika-raw that passes bytes through untouched, and every call
sets grpc.CallContentSubtype("nika-raw"). On the wire that appears as
application/grpc+nika-raw, so a proxy or a packet capture can tell these RPCs apart
from protobuf ones.
The codec is selected per call, not forced on the server. A protobuf service
registered on the same grpc.Server by other code keeps working — forcing the codec
would break every one of them.
The service is described by hand rather than generated. A grpc.ServiceDesc is just
data: a fully-qualified service name, the method names, and a function per method that
decodes a request, calls the implementation and hands back a response. protoc produces
exactly that struct and nothing magic. The methods are ordinary gRPC paths, so grpcurl,
a service mesh, an interceptor or an access log sees an ordinary service:
| Constant | Value |
|---|---|
grpcmq.ServiceName |
nika.microservice.v1.Messenger |
grpcmq.MethodDispatch |
/nika.microservice.v1.Messenger/Dispatch — unary, one envelope in, one out |
grpcmq.MethodStream |
/nika.microservice.v1.Messenger/Stream — bidirectional |
grpcmq.CodecName |
nika-raw |
The trade-off against real protobuf is deliberate:
- Lost: a schema, generated clients in other languages, field-level compatibility checking, and protobuf's compactness.
- Gained: no codegen step, no
.pb.gofiles to keep in sync with the envelope definition, one wire format across every transport in this framework — the same bytes travel over Redis, NATS, Kafka and AMQP — and a payload you can read in a packet capture.
This transport carries an internal, already-JSON envelope between Go services
that share the microservice package, so the schema and codegen benefits have
nobody to serve. A public, polyglot API is the case where protobuf wins and
this approach should not be used — use the gRPC API half above,
or write a real .proto service alongside it.
MaxRecvMsgSize defaults to 8 MiB, not gRPC's 4
gRPC's own default is 4 MiB, which rejects a larger envelope with ResourceExhausted —
a failure that shows up the first time a real payload is big and looks like a bug in the
handler. The default here is 8 MiB, matching the framework's envelope cap, and it is
applied symmetrically on the send side too: a server that accepts an 8 MiB question but
cannot send an 8 MiB answer fails in a way that looks like the handler's fault.
Keepalive is enforced
Without an enforcement policy a client may ping in a tight loop, which is a cheap way to
burn a server's CPU from outside. The server accepts pings no more often than
KeepaliveMinTime (30s) and, by default, refuses them entirely on a connection with no
active stream. A client whose ClientKeepalive.Time is below the server's minimum gets
its connection dropped with ENHANCE_YOUR_CALM, which is why no client keepalive
interval is set unless you ask for one — a default there would be a trap.
Shutdown is bounded
Cancelling the context passed to Listen drains gracefully; Close is the abrupt path.
GracefulStop stops accepting connections and waits for every active RPC and stream to
finish — with no timeout of its own. One client holding a bidirectional stream open,
or one handler that never returns, blocks it forever, which turns a rolling deploy into
a stuck pod. So the graceful stop is given GracefulStopTimeout (15s), and then the
server is forced down with a logged warning. A shutdown that always terminates is worth
more than one that is always graceful.
Concurrency
MaxConcurrentStreams is per connection, so N clients can still produce
N × MaxConcurrentStreams handlers at once. Concurrency (256) is the process-wide
backstop. When the server is saturated and the caller's deadline passes, the call is
refused with ResourceExhausted rather than queueing forever.
A malformed envelope on the unary method fails that one call with InvalidArgument,
which correctly tells the caller not to retry — the same bytes will fail again. On a
stream it is answered with a 400 / MALFORMED_ENVELOPE error envelope instead of
failing the stream, because a stream carries many messages and killing it over one bad
frame would take down every other in-flight message on it.
Serving a real protobuf contract alongside
The nika-raw codec is what removes protoc from the build, and the price is
that the Messenger service is not a protobuf contract. A Node, Java or Python
client generated from a .proto file cannot call it: it would address
/UserService/GetUserProfile, while this server exposes
/nika.microservice.v1.Messenger/Dispatch and speaks application/grpc+nika-raw.
Routing here lives in the envelope's pattern field, not in the method name —
which is exactly what lets one handler also serve Redis and NATS.
When you need a genuine contract for other languages, you have two choices:
- Use the gRPC API half of this page, which derives a real protobuf contract from your structs.
- Generate the service as usual from a
.protofile and register it on the same server:
transport, err := grpcmq.New(grpcmq.Options{
Addr: ":50051",
Insecure: true,
RegisterServices: func(srv *grpc.Server) {
userpb.RegisterUserServiceServer(srv, &userServer{})
},
})
Both services then share one port, one set of credentials and one interceptor
chain. They coexist because the codec is resolved per call from the
content-subtype rather than forced server-wide: a protobuf client is served by the
protobuf codec, a Nika client by nika-raw, over the same connection.
RegisterServices runs after the Messenger is registered, and grpc-go panics on a
duplicate service name — so a collision fails at startup instead of silently
shadowing something.
Use it when you have a polyglot or public API. For Go-to-Go calls between services
that already share the microservice package, the envelope needs no schema and
this adds only codegen.
Testing
Handlers need no server. nikatest.NewMicroservice(t) runs the whole message stack over
the in-memory transport:
ms := nikatest.NewMicroservice(t)
ms.LoadModule(src.NewAppModule())
ms.Send("user_created", CreateUserDto{Name: "Ada"}).
ExpectStatus(201).
ExpectJSONPath("data.name", "Ada")
See Testing.
The transport's own tests are fully self-contained — there is no broker, so they
bind 127.0.0.1:0 and need no build tag and no environment variable:
Options.Addr: "127.0.0.1:0" plus Ready() and Addr() is the pattern for your own
end-to-end tests: Ready() closes once the listener is bound, so you can learn the
OS-assigned port without polling. Note that with port 0 the OS assigns a fresh port on
every Listen, so the value changes across a supervisor restart — use a fixed port in
production.
When to use it, and when not to
Use gRPC for synchronous service-to-service calls where a caller is blocked on the answer: the lowest latency of the set, mTLS, deadlines carried by the protocol, HTTP/2 multiplexing over one connection, and interceptors that work with the existing ecosystem. If you already run a service mesh, this is the transport it understands.
Do not use it for events. There is no queue, no fan-out and no retry, so a publish against a server that is redeploying is simply lost — use Kafka, NATS or RabbitMQ, where the broker holds the message. Do not use it for a public or polyglot API either: use the gRPC API half above, or write a real protobuf service instead, since the pass-through codec deliberately has no schema. And if you want a synchronous transport with no broker and no gRPC dependency — a sidecar, an embedded pair, a test — TCP is the smaller answer.