Documentation
¶
Overview ¶
Package agentserver implements the server side of the AgentTransport gRPC service: registration (single-use token or mTLS client cert), heartbeat tracking, and command dispatch to connected remote agents. See docs/adr/0005-remote-agent-transport-and-registration.md.
Index ¶
- Constants
- func MintToken(ctx context.Context, st store.Store, label string, ttl time.Duration) (raw string, tok model.AgentRegistrationToken, err error)
- type GuestBootstrapResolver
- type ResourceForceOrphaner
- type Server
- func (s *Server) Connect(stream boxyagentv1.AgentTransportService_ConnectServer) error
- func (s *Server) ListAgents() []pool.AgentSummary
- func (s *Server) RequestAgentLogs(ctx context.Context, agentID string, since time.Time, limit int) (string, error)
- func (s *Server) ResolveGuestBootstrapCredential(ctx context.Context, req *boxyagentv1.ResolveGuestBootstrapCredentialRequest) (*boxyagentv1.ResolveGuestBootstrapCredentialResponse, error)
- func (s *Server) Revoke(ctx context.Context, agentID, reason string, forceOrphanResources bool) error
- func (s *Server) RunHeartbeatMonitor(ctx context.Context)
- func (s *Server) SetDiagnosticsStore(logs diagnostics.Store)
- func (s *Server) SetGuestBootstrapResolver(resolver GuestBootstrapResolver)
Constants ¶
const DefaultMissedHeartbeatLimit = 3
DefaultMissedHeartbeatLimit is how many consecutive missed heartbeat intervals mark an agent unavailable for new provisioning.
const DefaultTokenTTL = time.Hour
DefaultTokenTTL is how long a freshly minted single-use registration token stays redeemable when no explicit TTL is given.
Variables ¶
This section is empty.
Functions ¶
func MintToken ¶
func MintToken(ctx context.Context, st store.Store, label string, ttl time.Duration) (raw string, tok model.AgentRegistrationToken, err error)
MintToken creates a new single-use registration token: the raw secret is returned exactly once (for the operator to hand to `boxy agent serve --token ...`) and only its hash is persisted.
Types ¶
type GuestBootstrapResolver ¶ added in v0.1.42
type GuestBootstrapResolver func(context.Context, model.Resource) (providersdk.GuestBootstrapCredential, error)
GuestBootstrapResolver supplies the current server-owned credential for an owned resource. It lets the daemon move from one pool bootstrap value to a resource-scoped value without changing the authenticated gRPC contract.
type ResourceForceOrphaner ¶ added in v0.1.32
type ResourceForceOrphaner interface {
ForceOrphanAgentResources(ctx context.Context, agentID, reason string) (int, error)
}
ResourceForceOrphaner force-orphans every resource attributed to a permanently-gone agent. Implemented by pool.Manager. A narrow seam so agentserver does not need pool.Manager's full surface.
type Server ¶
type Server struct {
boxyagentv1.UnimplementedAgentTransportServiceServer
// contains filtered or unexported fields
}
Server implements the generated AgentTransportServiceServer.
func New ¶
func New(st store.Store, registry *pool.AgentRegistry, ca *pki.CA, heartbeatInterval time.Duration, forceOrphaner ResourceForceOrphaner, version string) *Server
New constructs a Server. heartbeatInterval should match the value handed to connecting agents in RegisterResponse. forceOrphaner may be nil (e.g. in tests that don't exercise `boxy agent revoke --force-orphan-resources`); Revoke logs and skips the sweep in that case rather than panicking. version is this server binary's version string; Connect rejects any agent whose RegisterRequest.agent_version doesn't match it exactly (see #167), including a blank agent_version from an agent built before that field existed — deliberately strict, since a silent "unknown version always accepted" exception would defeat the point of the check.
func (*Server) Connect ¶
func (s *Server) Connect(stream boxyagentv1.AgentTransportService_ConnectServer) error
Connect implements the AgentTransportService.Connect bidi-streaming RPC. The first frame must be a RegisterRequest (token-based for a first-time registration, or token-less for a cert-authenticated reconnect — see authenticate) with an agent_version matching this server's own version (see #167); every frame after that is handled by the resulting RemoteAgent's own Serve loop.
func (*Server) ListAgents ¶
func (s *Server) ListAgents() []pool.AgentSummary
ListAgents returns a snapshot of every registered agent, for the GET /api/v1/agents endpoint and `boxy agent list`.
func (*Server) RequestAgentLogs ¶ added in v0.1.64
func (s *Server) RequestAgentLogs(ctx context.Context, agentID string, since time.Time, limit int) (string, error)
RequestAgentLogs starts a pull from a connected remote agent. Disconnected identities remain in the registry for inventory visibility, but have no stream over which a request could be delivered.
func (*Server) ResolveGuestBootstrapCredential ¶ added in v0.1.40
func (s *Server) ResolveGuestBootstrapCredential(ctx context.Context, req *boxyagentv1.ResolveGuestBootstrapCredentialRequest) (*boxyagentv1.ResolveGuestBootstrapCredentialResponse, error)
ResolveGuestBootstrapCredential returns the server-owned bootstrap secret for a resource, but only to the mTLS-authenticated agent that owns it. The resource's recorded OriginPool and Provider.AgentID are the authority; no caller-supplied pool or agent claims are trusted.
func (*Server) Revoke ¶
func (s *Server) Revoke(ctx context.Context, agentID, reason string, forceOrphanResources bool) error
Revoke deregisters agentID, records a deny-list entry keyed by its current certificate serial (looked up even if the agent is currently disconnected), and — if it has a live connection — actively tears down that connection rather than merely removing the registry entry. If forceOrphanResources is set, it also sweeps every resource still attributed to agentID out of Boxy's bookkeeping once deregistration has made the agent verifiably absent from the registry — see pool.AgentProvisioner.ForceOrphan's precondition. Used by `boxy agent revoke <id> [--force-orphan-resources]`.
func (*Server) RunHeartbeatMonitor ¶
RunHeartbeatMonitor periodically marks each connected agent available or unavailable for new provisioning based on how recently it last sent a Heartbeat, without touching already-allocated resources. Mirrors internal/pool/manager.go's provisionBackoffState: in-memory only, resets on daemon restart. Blocks until ctx is done; run it in its own goroutine.
func (*Server) SetDiagnosticsStore ¶ added in v0.1.63
func (s *Server) SetDiagnosticsStore(logs diagnostics.Store)
SetDiagnosticsStore attaches the bounded server-observed agent log store. It must be called before an agent connection is accepted.
func (*Server) SetGuestBootstrapResolver ¶ added in v0.1.42
func (s *Server) SetGuestBootstrapResolver(resolver GuestBootstrapResolver)
SetGuestBootstrapResolver injects the server-owned credential lookup used by remote guest personalization. When unset, the legacy pool state lookup is retained for compatibility with focused agentserver users and migration tests.
Source Files