candaceos

Documentation

Overview

Package candaceos contains the small, durable domain model shared by CandaceOS controllers and user-facing applications.

The package deliberately contains no scheduler, persistence, or transport concerns. Placement is a pure decision over an authoritative cluster snapshot, and receipts can only be appended to a ReceiptLog.

Index

• Variables
• func DefaultAppSourceLimits() *candaceosv1.AppSourceLimits
• func DigestAppSource(ctx context.Context, root string) (string, error)
• func DigestAppSourceWithLimits(ctx context.Context, root string, limits *candaceosv1.AppSourceLimits) (string, error)
• func MaterializeGitAppSource(ctx context.Context, gitBin string, repositoryRoot string, revision string, ...) (string, error)
• func MaterializeGitAppSourceWithLimits(ctx context.Context, gitBin string, repositoryRoot string, revision string, ...) (string, error)
• func ResolvePlacement(deployment Deployment, snapshot ClusterSnapshot) ([]*candaceosv1.Node, error)
• type AppRevision
  • func (revision AppRevision) Validate() error
• type Approval
  • func (approval Approval) Validate() error
• type ApprovalDecision
• type ClusterSnapshot
  • func (snapshot ClusterSnapshot) Validate() error
• type Deployment
  • func (deployment Deployment) Validate() error
• type DesiredState
• type ExactNodePlacement
• type LeaderPlacement
• type MatchLabelsPlacement
• type Placement
  • func (placement Placement) Validate() error
• type Receipt
  • func (receipt Receipt) Validate() error
• type ReceiptKind
• type ReceiptLog
  • func NewReceiptLog(runID string) (*ReceiptLog, error)
  • func RestoreReceiptLog(runID string, receipts []Receipt) (*ReceiptLog, error)
  • func (log *ReceiptLog) Append(receipt Receipt) error
  • func (log *ReceiptLog) Entries() []Receipt
  • func (log *ReceiptLog) Len() int
• type Run
  • func (run Run) Validate() error
• type RunStatus

Variables

var (
	// ErrInvalidNode reports a malformed node description.
	ErrInvalidNode = errors.New("candaceos: invalid node")
	// ErrInvalidAppRevision reports a mutable or malformed application revision.
	ErrInvalidAppRevision = errors.New("candaceos: invalid app revision")
	// ErrInvalidPlacement reports a malformed placement policy.
	ErrInvalidPlacement = errors.New("candaceos: invalid placement")
	// ErrInvalidDeployment reports a malformed desired deployment.
	ErrInvalidDeployment = errors.New("candaceos: invalid deployment")
	// ErrInvalidRun reports a malformed execution run.
	ErrInvalidRun = errors.New("candaceos: invalid run")
	// ErrInvalidApproval reports a malformed approval request or decision.
	ErrInvalidApproval = errors.New("candaceos: invalid approval")
	// ErrInvalidReceipt reports a malformed receipt.
	ErrInvalidReceipt = errors.New("candaceos: invalid receipt")
	// ErrInvalidClusterSnapshot reports a malformed cluster snapshot.
	ErrInvalidClusterSnapshot = errors.New("candaceos: invalid cluster snapshot")
	// ErrNotAuthoritative reports that Warden has not supplied an authoritative
	// cluster view from which mutations may be planned.
	ErrNotAuthoritative = errors.New("candaceos: cluster snapshot is not authoritative")
	// ErrNoQuorum reports that a placement decision cannot safely be made.
	ErrNoQuorum = errors.New("candaceos: cluster has no quorum")
	// ErrLeaderUnavailable reports that the elected leader is absent or dead.
	ErrLeaderUnavailable = errors.New("candaceos: cluster leader is unavailable")
	// ErrPlacementUnsatisfied reports that too few suitable alive nodes exist.
	ErrPlacementUnsatisfied = errors.New("candaceos: placement cannot be satisfied")
	// ErrReceiptAppend reports an attempt to alter receipt history instead of
	// extending it with the next event.
	ErrReceiptAppend = errors.New("candaceos: receipt append rejected")
)

Functions

func DefaultAppSourceLimits

func DefaultAppSourceLimits() *candaceosv1.AppSourceLimits

DefaultAppSourceLimits returns the per-revision materialization policy.

func DigestAppSource

func DigestAppSource(ctx context.Context, root string) (string, error)

DigestAppSource returns the canonical digest binding an approval to the regular files materialized by a node agent.

func DigestAppSourceWithLimits

func DigestAppSourceWithLimits(
	ctx context.Context,
	root string,
	limits *candaceosv1.AppSourceLimits,
) (string, error)

DigestAppSourceWithLimits returns the canonical digest under an explicit per-revision resource policy.

func MaterializeGitAppSource

func MaterializeGitAppSource(
	ctx context.Context,
	gitBin string,
	repositoryRoot string,
	revision string,
	relativePath string,
	destination string,
) (string, error)

MaterializeGitAppSource extracts one app subtree from an exact Git commit into an existing empty directory and returns its canonical content digest.

func MaterializeGitAppSourceWithLimits

func MaterializeGitAppSourceWithLimits(
	ctx context.Context,
	gitBin string,
	repositoryRoot string,
	revision string,
	relativePath string,
	destination string,
	limits *candaceosv1.AppSourceLimits,
) (string, error)

MaterializeGitAppSourceWithLimits applies an explicit resource policy before archive bytes reach disk.

func ResolvePlacement

func ResolvePlacement(deployment Deployment, snapshot ClusterSnapshot) ([]*candaceosv1.Node, error)

ResolvePlacement returns the complete target set for a deployment. Running placements fail closed without quorum and never return a partial replica set. Returned nodes are independent copies sorted by stable node ID.

Types

type AppRevision

type AppRevision struct {
	ID          string `json:"id" yaml:"id"`
	AppID       string `json:"app_id" yaml:"app_id"`
	Source      string `json:"source" yaml:"source"`
	Revision    string `json:"revision" yaml:"revision"`
	Digest      string `json:"digest" yaml:"digest"`
	ComposePath string `json:"compose_path" yaml:"compose_path"`
}

AppRevision is a content-addressed application source snapshot. Revision is a full Git object ID rather than a mutable branch or tag, and Digest covers the materialized source used for the deployment.

func (AppRevision) Validate

func (revision AppRevision) Validate() error

Validate ensures the revision names immutable source and a safe, repository-relative Compose file.

type Approval

type Approval struct {
	ID          string           `json:"id" yaml:"id"`
	RunID       string           `json:"run_id" yaml:"run_id"`
	Action      string           `json:"action" yaml:"action"`
	Decision    ApprovalDecision `json:"decision" yaml:"decision"`
	RequestedAt time.Time        `json:"requested_at" yaml:"requested_at"`
	DecidedAt   *time.Time       `json:"decided_at,omitempty" yaml:"decided_at,omitempty"`
	DecidedBy   string           `json:"decided_by,omitempty" yaml:"decided_by,omitempty"`
	Reason      string           `json:"reason,omitempty" yaml:"reason,omitempty"`
}

Approval is a human decision about a named action in a run. Reason is optional operator context and is retained with either terminal decision.

func (Approval) Validate

func (approval Approval) Validate() error

Validate checks the request and ensures terminal decisions have complete, chronologically valid attribution.

type ApprovalDecision

type ApprovalDecision string

ApprovalDecision captures both an open request and its terminal decision.

const (
	ApprovalPending  ApprovalDecision = "pending"
	ApprovalApproved ApprovalDecision = "approved"
	ApprovalDenied   ApprovalDecision = "denied"
)

type ClusterSnapshot

type ClusterSnapshot struct {
	Nodes         []*candaceosv1.Node `json:"nodes" yaml:"nodes"`
	LeaderNodeID  string              `json:"leader_node_id,omitempty" yaml:"leader_node_id,omitempty"`
	Authoritative bool                `json:"authoritative" yaml:"authoritative"`
	HasQuorum     bool                `json:"has_quorum" yaml:"has_quorum"`
}

ClusterSnapshot is the minimum authoritative Warden state needed for a pure placement decision. ResolvePlacement never probes or mutates nodes.

func (ClusterSnapshot) Validate

func (snapshot ClusterSnapshot) Validate() error

Validate checks node identity uniqueness and any supplied leader identity.

type Deployment

type Deployment struct {
	ID            string       `json:"id" yaml:"id"`
	AppRevisionID string       `json:"app_revision_id" yaml:"app_revision_id"`
	DesiredState  DesiredState `json:"desired_state" yaml:"desired_state"`
	Placement     Placement    `json:"placement" yaml:"placement"`
	Stateful      bool         `json:"stateful" yaml:"stateful"`
}

Deployment is desired state. AppRevisionID points to one immutable AppRevision; changing source creates another revision instead of mutating it.

func (Deployment) Validate

func (deployment Deployment) Validate() error

Validate checks the desired-state contract. Stateful workloads must remain pinned to an exact node so leader changes or label ordering cannot move data.

type DesiredState

type DesiredState string

DesiredState is the operator's intended deployment state.

const (
	DesiredStateRunning DesiredState = "running"
	DesiredStateStopped DesiredState = "stopped"
)

type ExactNodePlacement

type ExactNodePlacement struct {
	NodeID string `json:"node_id" yaml:"node_id"`
}

ExactNodePlacement pins one deployment replica to one durable node identity.

type LeaderPlacement

type LeaderPlacement struct{}

LeaderPlacement follows the current authoritative cluster leader.

type MatchLabelsPlacement

type MatchLabelsPlacement struct {
	Labels   map[string]string `json:"labels" yaml:"labels"`
	Replicas int               `json:"replicas" yaml:"replicas"`
}

MatchLabelsPlacement selects a deterministic number of alive nodes whose labels contain every exact key/value match.

type Placement

type Placement struct {
	ExactNode   *ExactNodePlacement   `json:"exact_node,omitempty" yaml:"exact_node,omitempty"`
	Leader      *LeaderPlacement      `json:"leader,omitempty" yaml:"leader,omitempty"`
	MatchLabels *MatchLabelsPlacement `json:"match_labels,omitempty" yaml:"match_labels,omitempty"`
}

Placement is a closed, user-facing choice. Exactly one variant must be set. Pointer variants make invalid combinations detectable at configuration boundaries without an interface-backed union that is awkward to encode.

func (Placement) Validate

func (placement Placement) Validate() error

Validate checks that exactly one complete placement variant is selected.

type Receipt

type Receipt struct {
	ID       string      `json:"id" yaml:"id"`
	RunID    string      `json:"run_id" yaml:"run_id"`
	Sequence uint64      `json:"sequence" yaml:"sequence"`
	Kind     ReceiptKind `json:"kind" yaml:"kind"`
	At       time.Time   `json:"at" yaml:"at"`
	Summary  string      `json:"summary" yaml:"summary"`
}

Receipt is one immutable observation in a run's append-only history.

func (Receipt) Validate

func (receipt Receipt) Validate() error

Validate checks the shape of one receipt independently of a log.

type ReceiptKind

type ReceiptKind string

ReceiptKind is an extensible, machine-readable event name. The common run lifecycle names below are conveniences; daemons may add names in the same lowercase dotted form without changing this package.

const (
	ReceiptRunQueued         ReceiptKind = "run.queued"
	ReceiptApprovalRequested ReceiptKind = "approval.requested"
	ReceiptApprovalApproved  ReceiptKind = "approval.approved"
	ReceiptApprovalDenied    ReceiptKind = "approval.denied"
	ReceiptRunStarted        ReceiptKind = "run.started"
	ReceiptRunSucceeded      ReceiptKind = "run.succeeded"
	ReceiptRunFailed         ReceiptKind = "run.failed"
	ReceiptRunCanceled       ReceiptKind = "run.canceled"
)

type ReceiptLog

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

ReceiptLog owns one run's ordered receipt history. Its entries are private, Entries returns a copy, and Append is the only operation that changes it.

func NewReceiptLog

func NewReceiptLog(runID string) (*ReceiptLog, error)

NewReceiptLog starts an empty append-only log for one run.

func RestoreReceiptLog

func RestoreReceiptLog(runID string, receipts []Receipt) (*ReceiptLog, error)

RestoreReceiptLog validates ordered durable history before accepting it.

func (*ReceiptLog) Append

func (log *ReceiptLog) Append(receipt Receipt) error

Append extends history with exactly the next sequence number. It rejects replacement, insertion, cross-run events, duplicate IDs, and time reversal.

func (*ReceiptLog) Entries

func (log *ReceiptLog) Entries() []Receipt

Entries returns an independent snapshot of the receipt history.

func (*ReceiptLog) Len

func (log *ReceiptLog) Len() int

Len reports the number of appended receipts.

type Run

type Run struct {
	ID            string     `json:"id" yaml:"id"`
	DeploymentID  string     `json:"deployment_id" yaml:"deployment_id"`
	AppRevisionID string     `json:"app_revision_id" yaml:"app_revision_id"`
	NodeID        string     `json:"node_id" yaml:"node_id"`
	Status        RunStatus  `json:"status" yaml:"status"`
	RequestedAt   time.Time  `json:"requested_at" yaml:"requested_at"`
	StartedAt     *time.Time `json:"started_at,omitempty" yaml:"started_at,omitempty"`
	FinishedAt    *time.Time `json:"finished_at,omitempty" yaml:"finished_at,omitempty"`
}

Run captures one attempt against the exact application revision selected when it was queued, so later desired-state edits cannot rewrite history.

func (Run) Validate

func (run Run) Validate() error

Validate checks identity, lifecycle fields, and timestamp ordering.

type RunStatus

type RunStatus string

RunStatus is the lifecycle of one concrete deployment attempt on one node.

const (
	RunStatusQueued           RunStatus = "queued"
	RunStatusAwaitingApproval RunStatus = "awaiting_approval"
	RunStatusRunning          RunStatus = "running"
	RunStatusSucceeded        RunStatus = "succeeded"
	RunStatusFailed           RunStatus = "failed"
	RunStatusCanceled         RunStatus = "canceled"
)