agent

func Capabilities ¶ added in v1.3.8

func Capabilities() []string

Capabilities lists the command families this build understands. Sent at auth so the server can reject unsupported requests immediately instead of timing out.

func CheckHealth ¶ added in v1.4.0

func CheckHealth(dataDir string, maxAge time.Duration, now time.Time) error

CheckHealth reports whether an agent refreshed its liveness file within maxAge. A missing file is returned as an fs.ErrNotExist-wrapped error so callers can tell "no agent runs here" from "the agent is stuck".

func HashToken ¶ added in v1.3.9

func HashToken(token string) string

HashToken returns the hex-encoded SHA-256 of an enrollment token. This is the only form of the token the database ever sees.

func HealthPath ¶ added in v1.4.0

func HealthPath(dataDir string) string

HealthPath returns the liveness file path inside an agent data directory.

func NewToken ¶ added in v1.3.9

func NewToken() (cleartext, hash, id, prefix string, err error)

NewToken mints an enrollment token and returns its cleartext, the hash that gets persisted, the id derived from that hash, and the display prefix.

The cleartext is returned once and never stored: it exists in the creation response and nowhere else. Everything the server needs afterwards to accept, list or revoke the token is derivable from the hash.

func Run ¶

func Run(ctx context.Context, cfg AgentConfig, logger *slog.Logger) error

Run is the main agent entry point (mode=agent). It detects the local runtime, loads or creates the agent identity, enrolls if needed, then enters the long-lived Push streaming loop (US2).

func RunCollector ¶

func RunCollector(ctx context.Context, id *Identity, rt runtime.Runtime, label, nodeName string, spool *Spool, logger *slog.Logger) error

RunCollector starts collecting events from the local runtime and pushing them to stream. rt is the already-connected runtime resolved by agent.Run; label is the reported runtime kind ("docker", "swarm" or "kubernetes"); nodeName is the Kubernetes node the agent runs on, empty unless the operator set it. Blocks until ctx is cancelled or a fatal push error occurs.

func RunEnrollment ¶

func RunEnrollment(
	ctx context.Context,
	id *Identity,
	dataDir string,
	enrollmentToken string,
	runtimeLabel string,
	label string,
	agentVersion string,
	client *Client,
) error

RunEnrollment sends a RegisterRequest to the server using the enrollment token. On success it marks the identity as registered and persists it to dataDir.

func RunWithReconnect ¶

func RunWithReconnect(
	ctx context.Context,
	c *Client,
	id *Identity,
	logger *slog.Logger,
	hooks StreamHooks,
	onStream func(ctx context.Context, stream *PushStream) error,
) error

RunWithReconnect runs onStream with exponential backoff reconnect. Returns nil when ctx is cancelled, ErrAgentRevokedServer when the server revokes the agent. Backoff: min(60s, 1s * 2^attempt) ±25% jitter. Attempt resets to 0 if stream was stable >30s.

func StartHealthReporter ¶ added in v1.4.0

func StartHealthReporter(ctx context.Context, dataDir string, interval time.Duration, logger *slog.Logger) <-chan struct{}

StartHealthReporter refreshes the liveness file every interval until ctx is done. The returned channel is closed once the reporter has stopped writing, so a caller that needs the directory settled can wait for it: cancelling the context only asks the goroutine to stop, it does not mean an in-flight write has landed.

Reachability of the server is deliberately not part of the signal: an agent that cannot reach the server is already reported as disconnected there, and letting an orchestrator restart the agent over it would fix nothing while hiding the actual outage.

func TokenIDFromHash ¶ added in v1.3.9

func TokenIDFromHash(hash string) string

TokenIDFromHash derives the opaque id used in API paths from the token hash. Truncating is safe: the id identifies a row, it never authorises anything — enrollment matches on the full hash.

func TokenPrefix ¶ added in v1.3.9

func TokenPrefix(token string) string

TokenPrefix returns the leading, non-secret part of a token.

func WriteHealth ¶ added in v1.4.0

func WriteHealth(dataDir string, t time.Time) error

WriteHealth records that the agent loop was alive at t. The file is replaced atomically so a healthcheck reading it concurrently never sees a partial stamp.