[{"data":1,"prerenderedAt":191},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fmain\u002Fgrpc":3},{"id":4,"title":5,"body":6,"description":178,"extension":179,"group":180,"meta":181,"navigation":182,"order":183,"path":184,"section":185,"seo":186,"source":187,"stem":188,"version":189,"__hash__":190},"docs\u002Fdocs\u002Fmain\u002Fgrpc.md","gRPC and contracts",{"type":7,"value":8,"toc":163},"minimark",[9,14,27,31,37,41,44,48,59,63,66,70,81,85,92,96,117,121,136,140,146,150],[10,11,13],"h2",{"id":12},"opt-in-to-grpc","Opt in to gRPC",[15,16,17,18,22,23,26],"p",{},"Import ",[19,20,21],"code",{},"github.com\u002Famkargar\u002Fgonex\u002Fgrpc"," only in transport\u002Fbootstrap code. HTTP-only modules do not import it or start gRPC listeners. ",[19,24,25],{},"config.Config{DisableHTTP:true}"," permits a gRPC-only process. Manage servers and client pools with Registrar.Manage so failed startup\u002Fshutdown releases them. Resources exposing Errors() also report asynchronous failures to App.Run.",[10,28,30],{"id":29},"register-a-server","Register a server",[15,32,33,36],{},[19,34,35],{},"grpc.NewServer(ServerOptions{Address:...,TLS:...})"," constructs without binding. Supply generated registration callbacks through Server.Register, then let the app Start\u002FClose it. The built-in standard gRPC health service reports serving status. Application services must not import gRPC or generated messages; map at server\u002Fclient boundaries using ToStatus\u002FFromStatus. Unknown errors are redacted.",[10,38,40],{"id":39},"configure-tls-and-mtls","Configure TLS and mTLS",[15,42,43],{},"TLS is required by default. Load a server certificate and trust roots using crypto\u002Ftls and crypto\u002Fx509. mTLS uses RequireAndVerifyClientCert plus ClientCAs; the client supplies its certificate. Client InsecureSkipVerify is rejected. Only explicit DevelopmentInsecure permits plaintext for local development. Keep caller-provided TLS certificate\u002Fkey material immutable after configuration.",[10,45,47],{"id":46},"reuse-managed-clients","Reuse managed clients",[15,49,50,51,54,55,58],{},"Create one immutable ClientConfig per target\u002Fsecurity\u002Ftransport setup with NewClientConfig. Reuse that config with a shared Clients manager to reuse a connection concurrently. Different immutable configs never share a connection, even when targets are equal; this avoids credential\u002Fidentity\u002Fdialer mixing. ",[19,52,53],{},"grpc.Client(pool, config, generated.NewServiceClient)"," returns a typed generated client. Creation is lazy; ",[19,56,57],{},"pool.Ready(ctx,config)"," separately proves connectivity and requires a bounded caller context. Registry resolves explicit service names to configs. No write retry policy is installed; configured retry policies are disabled.",[10,60,62],{"id":61},"set-deadlines-and-drain-requests","Set deadlines and drain requests",[15,64,65],{},"Default unary and stream RPC timeouts are five seconds, configurable per server\u002Fclient; shorter incoming contexts win. Stream timeouts bound the whole stream lifetime. Handlers must honor their contexts. Server.Close uses graceful stop, then force-stop if the supplied context expires. App.Run supplies its configured shutdown timeout.",[10,67,69],{"id":68},"generate-versioned-contracts","Generate versioned contracts",[15,71,72,73,76,77,80],{},"Contracts are a separate Go module at contracts\u002F. All packages and Go paths are versioned. ",[19,74,75],{},"gonex grpc generate"," compiles with pinned Buf protocompile v0.14.1 and invokes official protoc-gen-go v1.36.10 \u002F protoc-gen-go-grpc v1.6.0. This Go-only compiler is the one used by Buf; protoc installation is unnecessary. ",[19,78,79],{},"--dry-run"," compiles\u002Fchecks without plugins or writes. Generated files are staged; sources and handwritten adapters are preserved. Network\u002Fcache access is needed to obtain pinned tools on first use.",[10,82,84],{"id":83},"check-compatibility","Check compatibility",[15,86,87,88,91],{},"schema.binpb is the generated descriptor set. baseline.binpb is the explicitly frozen initial release contract. ",[19,89,90],{},"gonex grpc check"," rejects removed\u002Fchanged files, messages, fields, enum values and RPC signatures, allowing additions. Generation enforces this baseline too. This conservative checker may require a new major for option-only changes; CI also runs Buf FILE compatibility against the same descriptor baseline. Update baselines only during a reviewed release, never to suppress a failed compatibility gate. buf.yaml and buf.gen.yaml support a standard external Buf toolchain as well.",[10,93,95],{"id":94},"verify-your-applications-contracts","Verify your application's contracts",[15,97,98,99,102,103,106,107,110,111,116],{},"From your generated app or workspace, use ",[19,100,101],{},"go tool gonex grpc generate",", ",[19,104,105],{},"go tool gonex grpc check"," and ",[19,108,109],{},"go tool gonex check",". Test your own provider\u002Fconsumer mapping and failure behavior. Framework TLS integration fixtures are documented separately in ",[112,113,115],"a",{"href":114},"\u002Fdocs\u002Fmain\u002Fcontribute\u002Ftesting\u002F","Contribute: testing",".",[10,118,120],{"id":119},"recovery-and-observability","Recovery and observability",[15,122,123,124,106,127,130,131,135],{},"Unary and stream recovery returns redacted Internal errors. ",[19,125,126],{},"grpc.ServerTLS",[19,128,129],{},"grpc.ClientTLS"," load verified certificate configurations with redacted file errors. The optional observability\u002Fgrpc unary interceptors propagate traceparent and collect fixed-method metrics; see ",[112,132,134],{"href":133},"\u002Fdocs\u002Fmain\u002Foperations\u002F","operations",". Application readiness can check managed server lifecycle and explicitly registered downstream client connectivity.",[10,137,139],{"id":138},"additional-buf-checks","Additional Buf checks",[15,141,142,143,116],{},"Your contracts module includes buf.yaml and buf.gen.yaml for an external Buf workflow. Add Buf lint and compatibility checks to your application's CI when needed. Framework maintainers' pinned tool installer and release gates belong in ",[112,144,145],{"href":114},"contributor testing",[10,147,149],{"id":148},"local-microservices-workflow","Local microservices workflow",[15,151,152,153,157,158,162],{},"Follow ",[112,154,156],{"href":155},"\u002Fdocs\u002Fmain\u002Fmicroservices-quickstart\u002F","First microservice call"," for explicit client profiles and wiring, dev\u002Fdoctor and independently published contracts. Existing generated paths and TLS defaults are retained. ",[112,159,161],{"href":160},"\u002Fdocs\u002Fmain\u002Fmicroservices-compatibility\u002F","Compatibility"," explains skeleton\u002Fexample\u002Fraw profiles, version coexistence and generation checks.",{"title":164,"searchDepth":165,"depth":165,"links":166},"",2,[167,168,169,170,171,172,173,174,175,176,177],{"id":12,"depth":165,"text":13},{"id":29,"depth":165,"text":30},{"id":39,"depth":165,"text":40},{"id":46,"depth":165,"text":47},{"id":61,"depth":165,"text":62},{"id":68,"depth":165,"text":69},{"id":83,"depth":165,"text":84},{"id":94,"depth":165,"text":95},{"id":119,"depth":165,"text":120},{"id":138,"depth":165,"text":139},{"id":148,"depth":165,"text":149},"Configure optional Gonex gRPC servers and clients, versioned Protobuf contracts, deadlines, TLS and mTLS.","md","APPLICATION DESIGN",{},true,120,"\u002Fdocs\u002Fmain\u002Fgrpc","build",{"title":5,"description":178},"grpc.md","docs\u002Fmain\u002Fgrpc","main","0OCTcUxJiwXLsBbqrTVNnls-QCet79ok-svjN8XDY2E",1792521640508]