CNPG-I gRPC Server Lifecycle#

Overview#

The gRPC server lifecycle for CNPG-I plugins is centralized in pkg/pluginhelper/http inside the cnpg-i-machinery repository. All three plugin types in plugin-barman-cloud — operator, instance, and restore — delegate their Start(ctx) method to the same http.Server.Start implementation rather than managing the gRPC server themselves.

Core Abstraction: http.Server#

The Server struct holds:

• IdentityImpl — the plugin's identity service implementation
• Enrichers []ServerEnricher — a list of functions that register additional gRPC services onto the server
• Transport config: PluginPath (Unix socket) or ServerAddress+TLS cert paths (TCP), which are mutually exclusive

ServerEnricher is a simple function type func(*grpc.Server) error 1 that lets callers register any number of gRPC services without knowing how the server is constructed.

Lifecycle: Server.Start(ctx)#

Start executes the following sequence:

1. Identity query — calls GetPluginMetadata to retrieve the plugin name and version; fails fast if the identity service errors 2.
2. Listener creation — calls createListener, which chooses between a TCP listener (createTCPListener) and a Unix domain socket listener (createUnixDomainSocketListener) based on whether ServerAddress is set 3. For Unix sockets, it removes any stale socket file first 4.
3. gRPC server construction — builds a grpc.Server with chained unary and streaming interceptors: logging injection and failed-request logging (from grpc.go), plus panic recovery via go-grpc-middleware 5.
4. TLS (optional) — if any cert path is set, configures mTLS via setupTLSCerts; certificates are loaded fresh per connection via getConfigForClient 6.
5. Service registration — registers IdentityServer and then calls each ServerEnricher to register plugin-specific services 7.
6. Shutdown goroutine — spawns a goroutine that calls grpcServer.Stop() when ctx.Done() fires 8. This is the sole shutdown mechanism; there is no graceful drain.
7. Serve — calls grpcServer.Serve(listener) on the current goroutine, blocking until the server stops. The net.ErrClosed error (produced by Stop()) is swallowed; other errors are logged and returned 9.

How Plugins Use It#

Each plugin type constructs an http.Server directly and calls srv.Start(ctx):

The pattern is identical across all three: define an enrich closure that registers services, populate http.Server, and return srv.Start(ctx).

Operator plugin — TCP + mTLS#

The operator plugin is the only one that populates TLS cert fields and ServerAddress 10, enabling mTLS over TCP. The instance and restore plugins leave those fields empty and default to a Unix domain socket under the configured PluginPath.

CreateMainCmd — CLI Entry Point#

For plugins that expose a CLI, CreateMainCmd wraps Server.Start in a Cobra serve command. It wires flags (--plugin-path, --server-cert, --server-key, --client-cert, --server-address) to Viper, injects a logger if the caller didn't supply one, and calls srv.Start(cmd.Context()). The cert flags are mutually required together and mutually exclusive with --plugin-path 11, enforcing the Unix-vs-TCP transport choice at the CLI level.

Key Files#