server

package
v0.12.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 29, 2026 License: AGPL-3.0 Imports: 21 Imported by: 0

Documentation

Overview

Package controlplane implements the clawker control plane — a privileged long-lived gRPC service that owns authoritative state for managed containers. Serves the AdminService surface (CLI ↔ CP) and supplies the auth + lifecycle plumbing shared with the agent listener (clawkerd ↔ CP, registered separately by cmd/clawkercp).

Index

Constants

This section is empty.

Variables

View Source
var ErrNilFirewallHandler = errors.New("controlplane: NewGRPCStack requires a non-nil firewall handler")

ErrNilFirewallHandler is returned by NewGRPCStack when no firewall handler is supplied. The handler backs the AdminService surface (its embedded UnimplementedAdminServiceServer satisfies method promotion), so a wiring path that reaches the constructor without one is a programming bug — surfaced as an error (not a panic) so the daemon degrades rather than crashing and stranding pinned eBPF.

View Source
var ErrNilRegistry = errors.New("controlplane: NewAdminServer requires a non-nil agent registry")

ErrNilRegistry is returned by NewAdminServer when no agent registry is supplied. CP is the sole sqlite writer in this design, so any wiring path that reaches the constructor without a registry is a programming bug — surfaced as an error (not a panic) so the daemon degrades rather than crashing and stranding eBPF.

Functions

func NewAdminServer

func NewAdminServer(fw *fwhandler.Handler, agents agent.Registry, log *logger.Logger) (adminv1.AdminServiceServer, error)

NewAdminServer returns the composite AdminServiceServer wired from the supplied domain handlers. agents is required — CP is the sole sqlite writer in this design, so any wiring path that reaches here without a registry returns ErrNilRegistry rather than panicking: the control plane must never crash on a wiring fault (it would strand pinned eBPF programs with no supervisor), so the caller logs a structured event=<subsystem>_unavailable line and degrades.

  • log defaults to logger.Nop() when nil. Production wiring passes the CP's structured logger.

Types

type GRPCDeps

type GRPCDeps struct {
	// Handler backs the AdminService surface. Required — see
	// ErrNilFirewallHandler.
	Handler *fwhandler.Handler

	// Registry is the durable agent identity registry, shared with the
	// AdminService.ListAgents RPC and the AgentService.Register handler.
	Registry agent.Registry

	// PeerLookup resolves a live mTLS peer IP to the purpose=agent
	// container owning that endpoint, grounding the IdentityInterceptor's
	// trust check on a kernel-attested source instead of cert claims. A
	// nil-yielding IdentityInterceptor (wiring regression) degrades the
	// AgentService surface — see Serve / the identity gate below.
	PeerLookup agent.ContainerByPeerIP

	// ServerCertPath / ServerKeyPath locate the CP server leaf used for
	// both the admin and agent listeners (same mTLS material).
	ServerCertPath string
	ServerKeyPath  string

	// CACertPool verifies client certificates on both listeners (the CLI
	// CA). Single pool, built once by the orchestrator and reused here.
	CACertPool *x509.CertPool

	// CATLS is the client TLS config the Hydra introspector dials with
	// (same CA pool). Single config, built once by the orchestrator.
	CATLS *tls.Config

	// HydraAdminPort is the port the Hydra introspect endpoint listens on
	// (container-internal). Used to build the introspect URL.
	HydraAdminPort int

	// AdminPort is the host-published gRPC AdminService port (CLI ↔ CP).
	AdminPort int

	// AgentPort is the clawker-network-only gRPC AgentService port
	// (clawkerd ↔ CP, NOT host-published).
	AgentPort int

	// Log is the CP structured logger.
	Log *logger.Logger
}

GRPCDeps is the dependency set for the CP gRPC listener stack. Every field is orchestrator-owned and INJECTED — the stack constructs the gRPC servers and listeners from them but owns none of their lifecycles. In particular the firewall ActionQueue and Handler are orchestrator-owned (the queue's Close() is drain step 1); the stack only registers Handler onto the AdminService surface.

type GRPCStack

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

GRPCStack owns the two CP gRPC listeners: the host-published admin listener (AdminService surface for the CLI) and the clawker-network agent listener (AgentService surface for clawkerd). Both share the same mTLS material; each enforces its own per-method scope vocabulary.

The agent listener is conditional: if the IdentityInterceptor constructor fails (nil peer resolver — a wiring regression), the AgentService surface degrades — no agent listener is brought up and no Register handler is registered — while the admin listener, firewall, registry, and AdminService stay up so operators can still observe and contain. agentServer / agentLis are nil in that case.

func NewGRPCStack

func NewGRPCStack(deps GRPCDeps) (*GRPCStack, error)

NewGRPCStack constructs both gRPC listeners from deps without starting to serve. It loads the server cert, builds both mTLS configs, the shared Hydra introspector and the two per-listener auth interceptors, registers the AdminService on the admin server, and — when the IdentityInterceptor is available — builds the agent server and registers the AgentService.Register handler. Call Serve to start accepting connections.

All failures return an error; the CP serve path never panics (a panic would strand pinned eBPF programs with no supervisor — a security incident). The IdentityInterceptor DEGRADE path is the one non-fatal-by-design outcome: a nil interceptor disables the agent listener and emits event=agent_identity_unavailable, but the constructor still returns a usable stack.

func (*GRPCStack) GracefulStop

func (s *GRPCStack) GracefulStop(ctx context.Context)

GracefulStop drains in-flight RPCs on both listeners, then returns. If ctx expires first it forces a hard Stop on both servers and returns — the orchestrator passes a bounded context so a wedged RPC can't hang drain forever. The agent server is stopped only when it was brought up.

func (*GRPCStack) Serve

func (s *GRPCStack) Serve(failed chan<- error)

Serve starts the recovered serve goroutines for both listeners. The admin listener always serves; the agent listener serves only when it was brought up (identity gate available). A non-nil Serve error from either server is deposited on failed without blocking — the channel is orchestrator-owned and buffered to cover every serve goroutine.

func (*GRPCStack) Stop

func (s *GRPCStack) Stop()

Stop force-closes both servers, cancelling in-flight RPCs. The agent server is stopped only when it was brought up. Idempotent — safe to call after GracefulStop.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL