grpc

README

Spice gRPC starter

github.com/spice-framework/starter-grpc is the independently versioned, opt-in gRPC client/server integration for Spice. It wraps the official grpc-go runtime with explicit configuration, bounded resource use, lifecycle cleanup, and payload-free observations. Importing Spice core alone never starts a server, opens a connection, registers reflection, or selects gRPC.

server, cleanup, err := spicegrpc.OpenServer(
    spicegrpc.ServerConfig{
        TLSConfig:    serverTLS,
        EnableHealth: true,
    },
    []spicegrpc.Registration{{
        Service: "orders.v1.Orders",
        Register: func(registrar grpc.ServiceRegistrar) error {
            ordersv1.RegisterOrdersServer(registrar, ordersService)
            return nil
        },
    }},
    observer,
)

OpenServer validates and registers generated services without binding or starting background work. The application owns the listener and calls Serve. Cleanup first drains active RPCs and force-stops only when its caller-owned context expires. The optional standard health service is explicitly enabled.

OpenClient creates a lazy, instance-owned grpc-go connection. TLS 1.2+ certificate and hostname verification are the defaults. Mutual TLS is ordinary tls.Config with caller-owned roots and client certificates. Plaintext requires an explicit AllowInsecure opt-in intended only for isolated local tests.

Message sizes, concurrent streams, service counts, service names, and targets are bounded. Client and server interceptor observations contain only direction, RPC kind, full method, status code, and duration—never credentials, metadata, request payloads, or responses.

Install

go get github.com/spice-framework/starter-grpc@latest

During preview development, applications should pin an exact compatible revision recorded in support metadata. The strict spice-compatibility.json contract declares distinct minimum and current Spice revisions without inventing a runtime dependency resolver.

Verify

Go 1.26.5 is mandatory:

make check
make acceptance
make compatibility
make release-parity
make verify
make verify-release

Acceptance uses local ephemeral TCP listeners and locally issued test certificates. It proves verified TLS and mTLS, unary RPCs, standard health, client/server interceptors, cancellation, graceful drain, forced cleanup, message limits, diagnostic redaction, and concurrent calls without contacting an external service.

The complete verifier checks formatting, module/vendor reproducibility, vet, allowlisted lint and nil safety, gosec, govulncheck, shuffled race tests, at least 85% product coverage, strict minimum/current core compatibility, and offline vendor builds.

Release parity runs the exact spice-dev tool authorized by go.mod and the retained repository builder twice each, entirely from vendor with network and workspace resolution disabled. It requires byte-identical source archives, fully validates their bounded gzip/TAR contents, compares equivalent SBOM package and dependency facts, verifies canonical checksum files, and forbids rehearsal signatures on Windows and Linux.

See the dependency review and support contract before production adoption.

Releases

Each version tag is an ordinary Go module release. The repository also builds an exact-commit source archive, committed-graph SPDX 2.3 SBOM, SHA-256 checksums, and an Ed25519 signature/public key without an external release build system. Production mode requires a clean checkout, exact tag, and protected signing key; an explicit unsigned rehearsal is available for local proof. See docs/releasing.md for the artifact and trust contract. The protected central workflow is the release authority. The retained repository builder remains only an unsigned parity oracle and is held to the dual-builder contract during the migration.

Documentation

Overview

Package grpc provides reviewed, instance-owned gRPC server and client integration for Spice applications.

Index

• func Manifest() spicestarter.Manifest
• func OpenClient(config ClientConfig, observers ...Observer) (*nativegrpc.ClientConn, lifecycle.Cleanup, error)
• type ClientConfig
• type Direction
• type Interaction
• type Kind
• type Limits
• type Observer
• type Registration
• type Result
• type Server
  • func OpenServer(config ServerConfig, registrations []Registration, observers ...Observer) (*Server, lifecycle.Cleanup, error)
  • func (server *Server) Close(ctx context.Context) error
  • func (server *Server) Serve(listener net.Listener) error
  • func (server *Server) SetServing(serving bool) error
• type ServerConfig

Functions

func Manifest

func Manifest() spicestarter.Manifest

Manifest returns gRPC starter compatibility and review metadata.

func OpenClient

func OpenClient(
	config ClientConfig,
	observers ...Observer,
) (*nativegrpc.ClientConn, lifecycle.Cleanup, error)

OpenClient constructs an instance-owned client connection without performing network I/O. Generated protobuf clients accept the returned connection.

Types

type ClientConfig

type ClientConfig struct {
	Target        string
	TLSConfig     *tls.Config
	Limits        Limits
	AllowInsecure bool
}

ClientConfig defines one explicit gRPC client connection. Construction does not perform network I/O.

type Direction

type Direction string

Direction identifies which side of an RPC emitted an observation.

const (
	// DirectionClient identifies an outbound client RPC.
	DirectionClient Direction = "client"
	// DirectionServer identifies an inbound server RPC.
	DirectionServer Direction = "server"
)

type Interaction

type Interaction struct {
	Direction Direction
	Kind      Kind
	Method    string
}

Interaction contains payload-free RPC facts.

type Kind

type Kind string

Kind identifies the RPC transport shape.

const (
	// KindUnary identifies one request and one response.
	KindUnary Kind = "unary"
	// KindStream identifies a client, server, or bidirectional stream.
	KindStream Kind = "stream"
)

type Limits

type Limits struct {
	MaxReceiveBytes      int
	MaxSendBytes         int
	MaxConcurrentStreams uint32
}

Limits bound RPC memory and server concurrency.

type Observer

type Observer interface {
	BeginRPC(context.Context, Interaction) (context.Context, func(Result))
}

Observer receives RPC begin/end information. Implementations must not add request or response payloads to logs, metrics, or traces.

type Registration

type Registration struct {
	Service  string
	Register func(nativegrpc.ServiceRegistrar) error
}

Registration binds one generated protobuf service to a server. Register normally calls the generated Register<Service>Server function.

type Result

type Result struct {
	Interaction Interaction
	Code        codes.Code
	Duration    time.Duration
}

Result describes one completed RPC without exposing request or response values.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server owns one native gRPC server and optional standard health service.

func OpenServer

func OpenServer(
	config ServerConfig,
	registrations []Registration,
	observers ...Observer,
) (*Server, lifecycle.Cleanup, error)

OpenServer constructs and registers an instance-owned server without binding a listener or starting background work.

func (*Server) Close

func (server *Server) Close(ctx context.Context) error

Close gracefully drains active RPCs. If the caller's context expires, Close force-stops the server and returns the cancellation cause.

func (*Server) Serve

func (server *Server) Serve(listener net.Listener) error

Serve runs the complete registered server on a caller-owned listener. It may be called exactly once.

func (*Server) SetServing

func (server *Server) SetServing(serving bool) error

SetServing updates the optional standard gRPC health service.

type ServerConfig

type ServerConfig struct {
	TLSConfig     *tls.Config
	Limits        Limits
	AllowInsecure bool
	EnableHealth  bool
}

ServerConfig defines one explicit gRPC server. A certificate-bearing TLS configuration is required unless local development explicitly opts out.