t1k:nakama:grpc-client

Field	Value
Module	`base`
Version	`1.6.2`
Effort	`low`
Tools	—

Keywords: backoff, client, grpc, health check, microservice, nakama, reconnection

How to invoke

/t1k:nakama:grpc-client

Nakama gRPC Client

Overview

The gRPC client in internal/grpcclient/ manages the connection to the Gameplay microservice with automatic reconnection using Fibonacci-backoff delays.

Key Patterns

Client Initialization

client, err := grpcclient.NewGameplayClient(ctx, logger, addr, apiKey)

Connection Management

Fibonacci backoff: Retry delays follow 1, 1, 2, 3, 5, 8… seconds
Health check: Verifies server is responding after connection
State monitoring: Watches connectivity.State changes, auto-reconnects on failure
IsConnected(): Check before every RPC call

Configuration

GAMEPLAY_GRPC_ADDR — target address (default: gameplay:9550)
GAMEPLAY_API_KEY — service-to-service auth key sent as metadata

Error Handling

if !client.IsConnected() {
    return "", runtime.NewError("gameplay service unavailable", 14)
}
resp, err := client.Method(ctx, req)
if err != nil {
    return "", mapGRPCError(err)
}

Gotchas

Client starts connecting in a goroutine — don’t block InitModule waiting for connection
Health check runs after initial connect to verify the server is actually responding
If Gameplay service is down at startup, client retries indefinitely with backoff
API key is sent as gRPC metadata on every call — not as TLS client cert
Connection state changes are logged — check logs for “connectivity state changed”
Connection pooling: gRPC connections are multiplexed. Creating new connections per-request wastes resources and causes port exhaustion.
Fibonacci backoff ceiling: Cap backoff at 30 seconds. Uncapped backoff leads to minute-long delays after transient failures.
TLS cert validation: In production, always validate server certificates. Skip only in dev with explicit flag.

Checklist

Client created in InitModule with correct address and API key
IsConnected() checked before every gRPC call
gRPC errors mapped via mapGRPCError() to Nakama error codes
Connection timeout is reasonable for the deployment environment
Health check endpoint exists on the Gameplay service