sdk

package module
v0.0.0-...-53576e4 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2026 License: AGPL-3.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrEmptyImage is returned when a workload specification has no container image.
	ErrEmptyImage = errors.New("workload image cannot be empty")

	// ErrInvalidPortMapping is returned when one port is configured without the other.
	ErrInvalidPortMapping = errors.New("both host_port and container_port must be specified together")

	// ErrNegativeMemory is returned when memory limit is negative.
	ErrNegativeMemory = errors.New("memory limit cannot be negative")

	// ErrInvalidRestartPolicy is returned when an unrecognized restart policy is provided.
	ErrInvalidRestartPolicy = errors.New("invalid restart policy; must be 'always', 'never', or 'on_failure'")
)
View Source 
var (
	// ErrNotFound is returned when a requested workload is not found in the cluster.
	ErrNotFound = errors.New("workload not found")

	// ErrDaemonUnreachable is returned when the Unix domain socket cannot be reached.
	ErrDaemonUnreachable = errors.New("concord daemon unreachable; ensure the daemon is running")
)

Functions

func DefaultSocketPath 

func DefaultSocketPath() (string, error)

DefaultSocketPath returns the standard Unix domain socket path for Concord.

Types

type Builder 

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

Builder provides a fluent API for constructing and validating a Workload specification.

func NewWorkload 

func NewWorkload() *Builder

NewWorkload initializes a new Workload builder populated with safe default values.

func (*Builder) Build 

func (b *Builder) Build() (Workload, error)

Build validates and returns the final immutable Workload struct.

func (*Builder) CPUShares 

func (b *Builder) CPUShares(shares uint64) *Builder

CPUShares sets the relative CPU weight (default is 1024).

func (*Builder) Command 

func (b *Builder) Command(cmd ...string) *Builder

Command sets the entrypoint and argument list override for the container process. Empty keeps the image default: entrypoint plus cmd resolve at start time.

func (*Builder) DependsOn 

func (b *Builder) DependsOn(ids ...uuid.UUID) *Builder

DependsOn waits for the listed workloads to run on the same node before this one starts. Unknown, removed, or elsewhere-assigned IDs are ignored, never waited on.

func (*Builder) Env 

func (b *Builder) Env(key, value string) *Builder

Env sets an individual environment variable key-value pair.

func (*Builder) Envs 

func (b *Builder) Envs(env map[string]string) *Builder

Envs copies multiple environment variables into the workload.

func (*Builder) File 

func (b *Builder) File(containerPath, digest string, mode uint32) *Builder

File stages a registry artifact into the container: the digest must already be pushed (see fileart.Client.Push); the spec carries only the pointer. Mode 0 means 0600.

func (*Builder) HealthCheck 

func (b *Builder) HealthCheck(path string, action HealthAction) *Builder

HealthCheck sets the HTTP path and action for container health monitoring.

func (*Builder) HealthProbe 

func (b *Builder) HealthProbe(probe HealthProbe, command ...string) *Builder

HealthProbe selects the check type with an optional exec command. An empty probe with no command keeps the default HTTP check.

func (*Builder) Image 

func (b *Builder) Image(image string) *Builder

Image sets the OCI container image reference (e.g. "docker.io/library/nginx:alpine").

func (*Builder) MemoryMB 

func (b *Builder) MemoryMB(mb int64) *Builder

MemoryMB sets the maximum memory limit in megabytes (0 = unlimited).

func (*Builder) MustBuild 

func (b *Builder) MustBuild() Workload

MustBuild validates and returns the Workload struct, panicking if invalid.

func (*Builder) Port 

func (b *Builder) Port(hostPort, containerPort uint16) *Builder

Port configures port forwarding between host and container.

func (*Builder) QoS 

func (b *Builder) QoS(qos QoS) *Builder

QoS sets the compute allocation class: best-effort gives way to everything, guaranteed gives way to nothing.

func (*Builder) Resources 

func (b *Builder) Resources(res Resources) *Builder

Resources sets compute constraints (CPU shares and memory in MB).

func (*Builder) Restart 

func (b *Builder) Restart(policy RestartPolicy) *Builder

Restart sets the container restart policy.

func (*Builder) StopTimeout 

func (b *Builder) StopTimeout(d time.Duration) *Builder

StopTimeout sets the graceful shutdown grace period before SIGKILL.

func (*Builder) StopTimeoutSeconds 

func (b *Builder) StopTimeoutSeconds(seconds int) *Builder

StopTimeoutSeconds sets the graceful shutdown grace period in seconds.

func (*Builder) Validate 

func (b *Builder) Validate() error

Validate verifies that the workload configuration satisfies all invariants.

type Client 

type Client interface {
	// Submit submits a workload specification to be committed to the cluster journal.
	Submit(ctx context.Context, w Workload) (uuid.UUID, error)

	// Stop stops and removes a workload by committing a tombstone event.
	Stop(ctx context.Context, id uuid.UUID) error

	// Get retrieves a workload specification by its unique ID.
	Get(ctx context.Context, id uuid.UUID) (*Workload, error)

	// List returns all active workloads currently recorded in the cluster view.
	List(ctx context.Context) ([]Workload, error)

	// Stats returns live utilization for one running workload.
	Stats(ctx context.Context, id uuid.UUID) (*WorkloadStats, error)

	// Metrics returns sampler state in Prometheus text exposition format.
	Metrics(ctx context.Context) (string, error)

	// Trail returns our recorded positions since boot, oldest-first.
	// Bounded by the 720-point ring; full history lives in track.jsonl.
	Trail(ctx context.Context) ([]TrailPoint, error)

	// Logs returns one workload's captured output lines oldest-first.
	// Tail caps the result to the last N lines; zero or negative means all.
	Logs(ctx context.Context, id uuid.UUID, tail int) ([]LogLine, error)

	// UpdateImage bumps a live workload to a new image keeping its ID,
	// assignment, and history. The node restarts the container on the
	// new image; rollback is another bump.
	UpdateImage(ctx context.Context, id uuid.UUID, image string) error

	// SetPosition applies one live position fix: persisted for reboot,
	// gossiped to the fleet, and recorded to trail and track log.
	SetPosition(ctx context.Context, lat, lon float64) error

	// Nodes lists all known cluster nodes and their network status.
	Nodes(ctx context.Context) ([]Node, error)

	// Close closes the client transport.
	Close() error
}

Client provides an interface for interacting with a Concord node.

func Dial 

func Dial(socketPath ...string) (Client, error)

Dial creates a new Concord SDK client connected to the local daemon's Unix socket. If socketPath is omitted, it defaults to ~/.config/concord/concord.sock.

type FileRef 

type FileRef struct {
	Path   string `json:"path"`
	Digest string `json:"digest"`
	Mode   uint32 `json:"mode,omitempty"`
}

FileRef points at one file's content in the registry: the container path, the blob digest, and the file mode (0 means 0600).

type HealthAction 

type HealthAction int

HealthAction defines what action to take when a container fails health checks. 

const (
	// HealthActionRestart restarts the container process upon failed health checks.
	HealthActionRestart HealthAction = 0

	// HealthActionSignal sends a notification signal when health check fails.
	HealthActionSignal HealthAction = 1
)

type HealthProbe 

type HealthProbe string

HealthProbe selects how the fast beat checks a workload. Empty means HTTP, preserving every old spec's behavior. 

const (
	// HealthProbeHTTP checks an HTTP endpoint on the mapped host port.
	HealthProbeHTTP HealthProbe = "http"
	// HealthProbeTCP dials the mapped host port and checks the connect.
	HealthProbeTCP HealthProbe = "tcp"
	// HealthProbeExec runs a command inside the container and checks for
	// exit code zero.
	HealthProbeExec HealthProbe = "exec"
)

type ImageUpdate 

type ImageUpdate struct {
	Image string `json:"image"`
}

ImageUpdate carries a new image reference for a live workload. Single field, named so both sides share one definition instead of two anonymous structs.

type LogLine 

type LogLine struct {
	At     time.Time `json:"at"`
	Stream string    `json:"stream"`
	Line   string    `json:"line"`
}

LogLine is one captured container output line with its timestamp and stream ("stdout" or "stderr").

type Node 

type Node struct {
	ID                 uuid.UUID `json:"id"`
	Address            string    `json:"address"`
	State              string    `json:"state"`
	WireGuardPublicKey string    `json:"wireguard_public_key,omitempty"`
	CPUPercent         uint8     `json:"cpu_percent,omitempty"`
	MemPercent         uint8     `json:"mem_percent,omitempty"`
	DiskPercent        uint8     `json:"disk_percent,omitempty"`
	Lat                float64   `json:"lat,omitempty"`
	Lon                float64   `json:"lon,omitempty"`
	Anchor             bool      `json:"anchor,omitempty"`
}

Node represents a cluster member node and its current health state.

type NodeStatus 

type NodeStatus struct {
	ID          uuid.UUID `json:"id"`
	CPUPercent  uint8     `json:"cpu_percent"`
	MemPercent  uint8     `json:"mem_percent"`
	DiskPercent uint8     `json:"disk_percent"`
}

NodeStatus is a node's identity plus CPU, memory, and disk utilization as 0-100 percents.

type Position 

type Position struct {
	Lat float64 `json:"lat"`
	Lon float64 `json:"lon"`
}

Position is one position fix in decimal degrees. It is the wire format for the self-position setter, shared by client and server so the endpoint body has exactly one definition.

type QoS 

type QoS string

QoS is a workload's compute allocation class: who places first and who gives way. Empty means best-effort. This ranks compute, not packets: ROS-style DDS QoS governs message delivery, this governs placement. See docs/qos. 

const (
	// QoSBestEffort runs when room allows and gives way to everything.
	QoSBestEffort QoS = "besteffort"
	// QoSBurstable preempts best-effort and yields to guaranteed.
	QoSBurstable QoS = "burstable"
	// QoSGuaranteed places first and is never preempted.
	QoSGuaranteed QoS = "guaranteed"
)

type Resources 

type Resources struct {
	CPUShares uint64 `json:"cpu_shares"` // Relative CPU weight (default 1024).
	MemoryMB  int64  `json:"memory_mb"`  // Maximum memory in MB (0 = unlimited).
}

Resources specifies compute limits for a container workload.

type RestartPolicy 

type RestartPolicy string

RestartPolicy defines the container restart behavior on process exit. 

const (
	// RestartNever indicates the container should never restart once terminated.
	RestartNever RestartPolicy = "never"

	// RestartAlways indicates the container should always be restarted upon termination.
	RestartAlways RestartPolicy = "always"

	// RestartOnFailure indicates the container should be restarted only on non-zero exit codes.
	RestartOnFailure RestartPolicy = "on_failure"
)

type TrailPoint 

type TrailPoint struct {
	At  time.Time `json:"at"`
	Lat float64   `json:"lat"`
	Lon float64   `json:"lon"`
}

TrailPoint is one recorded position with its timestamp.

type Workload 

type Workload struct {
	ID                 uuid.UUID         `json:"id,omitempty"`
	Image              string            `json:"image"`
	Command            []string          `json:"command,omitempty"`
	Env                map[string]string `json:"env,omitempty"`
	Resources          Resources         `json:"resources"`
	Restart            RestartPolicy     `json:"restart"`
	HostPort           uint16            `json:"host_port,omitempty"`
	ContainerPort      uint16            `json:"container_port,omitempty"`
	StopTimeoutSeconds int               `json:"stop_timeout_seconds,omitempty"`
	HealthAction       HealthAction      `json:"health_action,omitempty"`
	HealthPath         string            `json:"health_path,omitempty"`
	HealthProbe        HealthProbe       `json:"health_probe,omitempty"`
	HealthCommand      []string          `json:"health_command,omitempty"`
	DependsOn          []uuid.UUID       `json:"depends_on,omitempty"`
	QoS                QoS               `json:"qos,omitempty"`
	Files              []FileRef         `json:"files,omitempty"`
}

Workload defines the complete specification of a container workload in Concord.

type WorkloadStats 

type WorkloadStats struct {
	CPUPercent    uint8      `json:"cpu_percent"`
	MemPercent    uint8      `json:"mem_percent"`
	MemUsageMB    uint64     `json:"mem_usage_mb"`
	MemLimitMB    uint64     `json:"mem_limit_mb"`
	AvgCPUPercent uint8      `json:"avg_cpu_percent"`
	AvgMemPercent uint8      `json:"avg_mem_percent"`
	Node          NodeStatus `json:"node"`
}

WorkloadStats reports live utilization for one running workload. These are sampled readings, not desired state: they never enter the journal and never appear on submit. MemLimitMB is 0 when unlimited. Node carries the local node's identity and pressure trio as context: stats exist only where the workload runs, so the local node is always the relevant one.

Source Files

View all Source files

Directories

Path Synopsis
Package fileart pushes and pulls file artifacts through any OCI distribution registry, including Concord's embedded registry.
 Package fileart pushes and pulls file artifacts through any OCI distribution registry, including Concord's embedded registry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.