inventory

type BootConverger interface {
	// HostUptime returns hostID's current kernel uptime. ok is false when the
	// host's podman cannot report it (e.g. too old, or a format this client
	// doesn't parse) — callers must treat that as "unknown", never as "just
	// booted".
	HostUptime(ctx context.Context, hostID string) (uptime time.Duration, ok bool, err error)
	// ReconcileSpecsOnHost re-creates any stored spec whose pod is missing.
	// Deliberately tolerant (see the method's own doc comment): it logs and
	// continues per-instance and never propagates an error, so calling it
	// speculatively here is safe.
	ReconcileSpecsOnHost(ctx context.Context, hostID string)
}

type Poller struct {
	Svc      Refresher
	Interval time.Duration
	Timeout  time.Duration

	// Stats, when non-nil, samples container resource usage on every tick,
	// alongside the inventory refresh. Its failures are logged and otherwise
	// ignored: reachability is the inventory refresh's to decide, and the
	// Grafana alert rules all gate on podman_api_host_reachable.
	Stats StatsRefresher

	// StatsTimeout bounds one host's stats sample, independently of Timeout.
	// Zero means defaultStatsTimeout — never "no timeout", so a caller that
	// forgets to set it cannot hand the sampler an unbounded call. See tick for
	// why this is a separate budget rather than a share of Timeout (#212).
	StatsTimeout time.Duration

	// Boot, when non-nil, probes each host's uptime on every tick and
	// re-converges stored specs for a host whose uptime resets — i.e. it
	// rebooted while podman-api kept running (#231). nil disables the check
	// entirely: no extra calls, same as a nil Stats.
	Boot BootConverger

	// BootTimeout bounds one host's uptime probe when Boot is set,
	// independently of Timeout — mirrors StatsTimeout, and for the same
	// #212 reason: a slow-but-successful refresh must not starve this probe
	// of its own budget by sharing the refresh's hctx. Zero means
	// defaultBootTimeout.
	//
	// This bounds ONLY the lightweight HostUptime probe. The
	// ReconcileSpecsOnHost call triggered by a detected reboot deliberately
	// does NOT share this budget (#231 review finding #1): it is a full sweep
	// of every stored spec on the host (PodInspect/GetSpec/GetTemplate/render/
	// PlayKube per instance, plus an ingress reconcile), and a host with more
	// than a handful of instances would have that recreation loop silently
	// truncated by a 5s deadline meant for one cheap uptime read. It runs
	// instead under the tick's own long-lived context (cancelled only on
	// poller shutdown), the same convention server.go's one-shot startup boot
	// converge already uses for "let a full per-host reconcile actually
	// finish".
	BootTimeout time.Duration
	// contains filtered or unexported fields
}

type Refresher interface {
	RefreshHost(ctx context.Context, host string) error
}

type StatsRefresher interface {
	RefreshHostStats(ctx context.Context, host string) error
	// DropHostStats discards the host's cached samples. Called when the host is
	// not going to be sampled at all. No context: it does no I/O.
	DropHostStats(host string)
}

type VolumeUsageRefresher interface {
	RefreshHostVolumeUsage(ctx context.Context, host string) error
}