model

Documentation

Overview

Package model defines the wire contract shared between Trove agents and the Trove server. Agents import this package; it must stay free of server- or store-specific concerns so that future agents (k8s, proxmox, bare metal) can depend on it without pulling in the world.

Index

• Constants
• func DefaultReportInterval() time.Duration
• type Health
  • func (h Health) Valid() bool
• type Kind
  • func (k Kind) Valid() bool
• type Port
• type Report
  • func (r *Report) Validate() error
• type ReportAgent
• type ReportHost
• type ReportService

Constants

const (
	// DefaultReportIntervalSeconds is how often an agent pushes when not
	// overridden via TROVE_INTERVAL.
	DefaultReportIntervalSeconds = 30

	// StaleAfterIntervals: an agent that misses this many push intervals is
	// considered stale (its services are shown as stale). 3 * 30s = 90s.
	StaleAfterIntervals = 3

	// OfflineAfterIntervals: an agent silent for this many intervals is
	// considered offline. 10 * 30s = 300s (5 min).
	OfflineAfterIntervals = 10
)

Heartbeat / staleness defaults, shared so the agent and server agree on the meaning of the numbers.

const (
	PlatformDocker = "docker"
)

Platform identifies the agent type. Only Docker exists in Phase 1.

const StateRemoved = "removed"

StateRemoved is the synthetic state the server assigns to a service that was previously reported but is absent from the latest full-state report. Agents never send this value.

Functions

func DefaultReportInterval

func DefaultReportInterval() time.Duration

DefaultReportInterval is the typed convenience form of the default interval.

Types

type Health

type Health string

Health is the normalized health enum. Agents map platform-specific status into one of these values; the server derives Stale on its own from heartbeat timing (agents never report Stale themselves).

const (
	HealthHealthy   Health = "healthy"
	HealthUnhealthy Health = "unhealthy"
	HealthUnknown   Health = "unknown"
	HealthStale     Health = "stale"
)

func (Health) Valid

func (h Health) Valid() bool

Valid reports whether h is a health value an agent is allowed to send. HealthStale is intentionally excluded: staleness is server-derived.

type Kind

type Kind string

Kind is the class of thing a service represents. Only Container is used in Phase 1; the rest are reserved so the schema and API don't need to change when later agents arrive.

const (
	KindContainer Kind = "container"
	KindPod       Kind = "pod"
	KindVM        Kind = "vm"
	KindLXC       Kind = "lxc"
	KindProcess   Kind = "process"
	// Kubernetes parent workloads (children are pods, linked via parent).
	KindDeployment  Kind = "deployment"
	KindStatefulSet Kind = "statefulset"
	KindDaemonSet   Kind = "daemonset"
)

func (Kind) Valid

func (k Kind) Valid() bool

type Port

type Port struct {
	Host      int    `json:"host"`
	Container int    `json:"container"`
	Proto     string `json:"proto"`
}

Port is a published port mapping.

type Report

type Report struct {
	Agent    ReportAgent     `json:"agent"`
	Host     ReportHost      `json:"host"`
	Services []ReportService `json:"services"`
}

Report is the full-state payload an agent POSTs to /api/v1/report. Reports are full snapshots, not deltas: the server replaces its view of the host's services with exactly what the report contains. This is idempotent and tolerates lost pushes.

func (*Report) Validate

func (r *Report) Validate() error

Validate performs cheap structural checks on an inbound report so the ingest handler can reject malformed pushes with a 400 before touching the store. It does not enforce business rules beyond the wire contract.

type ReportAgent

type ReportAgent struct {
	Name     string `json:"name"`
	Platform string `json:"platform"`
	Version  string `json:"version"`
	// IntervalSeconds is the agent's configured push interval. The server
	// stores it and derives staleness thresholds per-agent (stale/offline are
	// multiples of this), so a slow-polling agent isn't falsely flagged. Zero
	// or absent means "use the server default".
	IntervalSeconds int `json:"interval_seconds,omitempty"`
}

ReportAgent identifies the pushing agent.

type ReportHost

type ReportHost struct {
	Hostname string            `json:"hostname"`
	Meta     map[string]string `json:"meta,omitempty"`
}

ReportHost describes the machine the agent runs on. Meta carries platform-specific facts (e.g. docker_version) that are useful to surface but not worth first-class columns.

type ReportService

type ReportService struct {
	// ExternalID is the platform-native identifier (e.g. container ID). It is
	// stable across reports and unique within a host, and is what the server
	// uses to correlate a service across pushes.
	ExternalID string `json:"external_id"`
	// ParentExternalID, if set, is the ExternalID of this service's parent
	// within the same report/host — e.g. a pod's owning Deployment. The server
	// resolves it to an internal parent link. Empty for standalone services.
	ParentExternalID string            `json:"parent_external_id,omitempty"`
	Name             string            `json:"name"`
	Kind             Kind              `json:"kind"`
	Image            string            `json:"image"`
	ImageDigest      string            `json:"image_digest,omitempty"`
	State            string            `json:"state"`
	Health           Health            `json:"health"`
	Ports            []Port            `json:"ports,omitempty"`
	Labels           map[string]string `json:"labels,omitempty"`
}

ReportService is one catalog entry: a container now, a pod/vm/lxc later.