retainedprovider

package
v1.0.34 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ConfigProtocolVersion = "retained-provider.config.v1"
	GitHubPluginID        = "workflow-plugin-github"

	MaxProviderProbeLabels = 64
)
View Source 
const (
	ActiveStateProtocolVersion        = "retained-provider.active.v1"
	TransactionJournalProtocolVersion = "retained-provider.transaction.v1"
	StatusProtocolVersion             = "retained-provider.status.v1"
)
View Source 
const (
	LifecycleJournalProtocolVersion = "retained-provider.lifecycle-transaction.v1"
)
View Source 
const MaxStateFileBytes = 1 << 20

Variables

View Source 
var ErrInstallLocked = errors.New("retained provider install is already locked")

Functions

func AtomicWriteJSON 

func AtomicWriteJSON(path string, value any) (returnErr error)

func CloneRegularTree 

func CloneRegularTree(source, destination string, limits CloneLimits) (returnErr error)

func IsCanonicalSafeAbsolutePath 

func IsCanonicalSafeAbsolutePath(value string) bool

IsCanonicalSafeAbsolutePath reports whether value is safe to pass unchanged to filesystem and process boundaries.

func ReadStrictJSONFile 

func ReadStrictJSONFile(path string, target any) error

func ValidateUserPath 

func ValidateUserPath(home, path string, requireExisting bool) error

ValidateUserPath enforces a lexical user-home boundary and rejects symlinks or untrusted ownership and writability in every existing component.

func WriteInstallMaterial 

func WriteInstallMaterial(paths LifecyclePaths, material InstallMaterial) error

func WriteStatus 

func WriteStatus(writer io.Writer, status Status) error

Types

type ActiveState 

type ActiveState struct {
	ProtocolVersion string          `json:"protocol_version"`
	Current         ImageSelection  `json:"current"`
	Previous        *ImageSelection `json:"previous,omitempty"`
	UpdatedAt       time.Time       `json:"updated_at"`
}

func RecoverActiveState 

func RecoverActiveState(journal TransactionJournal) (ActiveState, error)

func (ActiveState) Validate 

func (state ActiveState) Validate() error

func (ActiveState) ValidateForConfig 

func (state ActiveState) ValidateForConfig(config Config) error

type CloneLimits 

type CloneLimits struct {
	MaxFiles int
	MaxBytes int64
}

type Command 

type Command struct {
	Path  string
	Args  []string
	Env   []string
	Dir   string
	Stdin []byte
}

type CommandRunner 

type CommandRunner interface {
	Run(context.Context, Command) ([]byte, error)
	Exec(Command) error
}

type Config 

type Config struct {
	ProtocolVersion        string   `json:"protocol_version"`
	WorkerID               string   `json:"worker_id"`
	ProfileID              string   `json:"profile_id"`
	PluginID               string   `json:"plugin_id"`
	ComponentID            string   `json:"component_id"`
	ComputeAgentPath       string   `json:"compute_agent_path"`
	SupervisorConfigPath   string   `json:"supervisor_config_path"`
	LocalStatusPath        string   `json:"local_status_path"`
	ProviderMarkerPath     string   `json:"provider_marker_path"`
	InstallRoot            string   `json:"install_root"`
	SystemdDir             string   `json:"systemd_dir"`
	AgentUnit              string   `json:"agent_unit"`
	PodmanPath             string   `json:"podman_path"`
	SystemctlPath          string   `json:"systemctl_path"`
	LoginctlPath           string   `json:"loginctl_path"`
	ProviderURL            string   `json:"provider_url"`
	StableContainer        string   `json:"stable_container"`
	CandidateContainer     string   `json:"candidate_container"`
	ContainerNetwork       string   `json:"container_network"`
	Organization           string   `json:"organization"`
	Repository             string   `json:"repository"`
	Workflow               string   `json:"workflow"`
	Ref                    string   `json:"ref"`
	RunnerName             string   `json:"runner_name"`
	RunnerGroup            string   `json:"runner_group"`
	Labels                 []string `json:"labels"`
	RefreshIntervalSeconds int      `json:"refresh_interval_seconds"`
}

Config is the non-secret, versioned retained-provider installation contract.

func DecodeConfig 

func DecodeConfig(reader io.Reader, home string) (Config, error)

func ReadConfigFile 

func ReadConfigFile(path, home string) (Config, error)

func (Config) Validate 

func (config Config) Validate(home string) error

type Credentials 

type Credentials struct {
	GitHubToken   string
	ProviderToken string
}

type ImageSelection 

type ImageSelection struct {
	Update      VerifiedUpdate `json:"update"`
	ImageID     string         `json:"image_id"`
	ImageRef    string         `json:"image_ref"`
	ActivatedAt time.Time      `json:"activated_at"`
}

func (ImageSelection) Validate 

func (selection ImageSelection) Validate() error

type InstallLock 

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

func AcquireInstallLock 

func AcquireInstallLock(path string) (*InstallLock, error)

func (*InstallLock) Release 

func (lock *InstallLock) Release() error

type InstallMaterial 

type InstallMaterial struct {
	ProviderEnv    []byte
	ProbeEnv       []byte
	AgentEnv       []byte
	ContainersConf []byte
	CACert         []byte
	CAKey          []byte
	ServerCert     []byte
	ServerKey      []byte
}

func GenerateInstallMaterial 

func GenerateInstallMaterial(config Config, credentials Credentials, random io.Reader, now time.Time) (InstallMaterial, error)

type Installer 

type Installer struct {
	Runner         CommandRunner
	ExecutablePath func() (string, error)
	UserID         func() (string, error)
	Random         io.Reader
	Now            func() time.Time
	Sleep          func(context.Context, time.Duration) error
	Refresh        func(context.Context, Config) (Status, error)
	ProbeActive    func(context.Context, Config) error
}

func (Installer) Install 

func (installer Installer) Install(ctx context.Context, home string, config Config, credentials Credentials) (status Status, returnErr error)

func (Installer) Recover 

func (installer Installer) Recover(ctx context.Context, home string, config Config, confirmation string) (status Status, returnErr error)

func (Installer) Status 

func (installer Installer) Status(ctx context.Context, home string, config Config) (Status, error)

func (Installer) Uninstall 

func (installer Installer) Uninstall(ctx context.Context, home string, config Config, purge bool) (status Status, returnErr error)

type JournalPhase 

type JournalPhase string
const (
	JournalStaging           JournalPhase = "staging"
	JournalPrepared          JournalPhase = "prepared"
	JournalStatePromoting    JournalPhase = "state_promoting"
	JournalStateDetached     JournalPhase = "state_detached"
	JournalStatePromoted     JournalPhase = "state_promoted"
	JournalActivated         JournalPhase = "activated"
	JournalCommitted         JournalPhase = "committed"
	JournalRollbackRestoring JournalPhase = "rollback_restoring"
	JournalRollbackRestored  JournalPhase = "rollback_restored"
	JournalRollbackCleaned   JournalPhase = "rollback_cleaned"
)

type LifecycleAuditEvent 

type LifecycleAuditEvent struct {
	EventID        string             `json:"event_id"`
	Sequence       uint64             `json:"sequence"`
	Timestamp      time.Time          `json:"timestamp"`
	TransactionID  string             `json:"transaction_id"`
	WorkerID       string             `json:"worker_id"`
	Operation      LifecycleOperation `json:"operation"`
	Phase          LifecyclePhase     `json:"phase"`
	Kind           LifecycleAuditKind `json:"kind"`
	Outcome        LifecycleOutcome   `json:"outcome,omitempty"`
	ProviderEffect ProviderEffect     `json:"provider_effect,omitempty"`
	Purge          *bool              `json:"purge,omitempty"`
	Disposition    string             `json:"disposition,omitempty"`
	ErrorClass     string             `json:"error_class,omitempty"`
	Count          uint64             `json:"count,omitempty"`
	FirstSeen      time.Time          `json:"first_seen,omitempty"`
	LastSeen       time.Time          `json:"last_seen,omitempty"`
	Digest         string             `json:"digest,omitempty"`
	Offset         *int64             `json:"offset,omitempty"`
}

func (LifecycleAuditEvent) Validate 

func (event LifecycleAuditEvent) Validate() error

type LifecycleAuditKind 

type LifecycleAuditKind string
const (
	AuditPhase    LifecycleAuditKind = "phase"
	AuditRecovery LifecycleAuditKind = "recovery"
	AuditError    LifecycleAuditKind = "error"
	AuditOverflow LifecycleAuditKind = "overflow"
)

type LifecycleAuditQueue 

type LifecycleAuditQueue struct {
	NextSequence uint64                `json:"next_sequence"`
	Safety       []LifecycleAuditEvent `json:"safety,omitempty"`
	Diagnostics  []LifecycleAuditEvent `json:"diagnostics,omitempty"`
}

func (*LifecycleAuditQueue) EnqueueDiagnostic 

func (queue *LifecycleAuditQueue) EnqueueDiagnostic(event LifecycleAuditEvent) error

func (*LifecycleAuditQueue) EnqueueSafety 

func (queue *LifecycleAuditQueue) EnqueueSafety(event LifecycleAuditEvent) error

func (LifecycleAuditQueue) Validate 

func (queue LifecycleAuditQueue) Validate() error

type LifecycleFileAttestation 

type LifecycleFileAttestation struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
}

func (LifecycleFileAttestation) Validate 

func (attestation LifecycleFileAttestation) Validate() error

type LifecycleIdentity 

type LifecycleIdentity struct {
	WorkerID    string `json:"worker_id"`
	ProfileID   string `json:"profile_id"`
	PluginID    string `json:"plugin_id"`
	ComponentID string `json:"component_id"`
}

func (LifecycleIdentity) Validate 

func (identity LifecycleIdentity) Validate() error

type LifecycleJournal 

type LifecycleJournal struct {
	ProtocolVersion     string                        `json:"protocol_version"`
	TransactionID       string                        `json:"transaction_id"`
	Operation           LifecycleOperation            `json:"operation"`
	Phase               LifecyclePhase                `json:"phase"`
	Outcome             LifecycleOutcome              `json:"outcome,omitempty"`
	ProviderEffect      ProviderEffect                `json:"provider_effect"`
	Identity            LifecycleIdentity             `json:"identity"`
	Recovery            LifecycleRecoveryAuthority    `json:"recovery"`
	ProviderTransaction *LifecycleProviderTransaction `json:"provider_transaction,omitempty"`
	Unchanged           *LifecycleUnchangedProvenance `json:"unchanged,omitempty"`
	Uninstall           *LifecycleUninstallPayload    `json:"uninstall,omitempty"`
	Snapshots           []managedFileSnapshot         `json:"snapshots,omitempty"`
	WiringIntent        []LifecycleManagedFileIntent  `json:"wiring_intent,omitempty"`
	PreviousUnits       map[string]systemdUnitState   `json:"previous_units,omitempty"`
	Activation          systemdActivation             `json:"activation,omitempty"`
	AgentUnitIntended   *LifecycleSystemdSignature    `json:"agent_unit_intended,omitempty"`
	Audit               LifecycleAuditQueue           `json:"audit"`
	StartedAt           time.Time                     `json:"started_at"`
	UpdatedAt           time.Time                     `json:"updated_at"`
}

func (LifecycleJournal) Validate 

func (journal LifecycleJournal) Validate(home string, paths LifecyclePaths) error

type LifecycleManagedFileIntent 

type LifecycleManagedFileIntent struct {
	Path     string      `json:"path"`
	Present  bool        `json:"present"`
	Mode     os.FileMode `json:"mode,omitempty"`
	SHA256   string      `json:"sha256,omitempty"`
	Contents []byte      `json:"contents,omitempty"`
}

type LifecycleOperation 

type LifecycleOperation string
const (
	LifecycleInstall         LifecycleOperation = "install"
	LifecycleUninstall       LifecycleOperation = "uninstall"
	LifecycleRefresh         LifecycleOperation = "refresh"
	LifecycleRefreshRecovery LifecycleOperation = "refresh_recovery"
)

type LifecycleOutcome 

type LifecycleOutcome string
const (
	LifecycleCommit   LifecycleOutcome = "commit"
	LifecycleRollback LifecycleOutcome = "rollback"
)

type LifecyclePaths 

type LifecyclePaths struct {
	Root                  string
	ConfigFile            string
	Launcher              string
	ActiveState           string
	Journal               string
	InstallLock           string
	InstallJournal        string
	LifecycleJournal      string
	LifecycleTransactions string
	LifecycleAudit        string
	LifecycleAuditLock    string
	ProviderState         string
	PackagesRoot          string
	CandidatesRoot        string
	ProviderEnv           string
	ProbeEnv              string
	AgentEnv              string
	CAKey                 string
	TLSRoot               string
	CAFile                string
	ServerCert            string
	ServerKey             string
	ContainersConf        string
	ProviderUnit          string
	RefreshUnit           string
	PathUnit              string
	TimerUnit             string
	AgentDropIn           string
}

func LifecyclePathsFor 

func LifecyclePathsFor(config Config) LifecyclePaths

func (LifecyclePaths) CandidateState 

func (paths LifecyclePaths) CandidateState(digest string) string

func (LifecyclePaths) LifecycleTransactionRoot 

func (paths LifecyclePaths) LifecycleTransactionRoot(transactionID string) string

func (LifecyclePaths) PackageBinary 

func (paths LifecyclePaths) PackageBinary(digest string) string

func (LifecyclePaths) PackageDir 

func (paths LifecyclePaths) PackageDir(digest string) string

func (LifecyclePaths) PreviousState 

func (paths LifecyclePaths) PreviousState(digest string) string

type LifecyclePhase 

type LifecyclePhase string
const (
	LifecycleIntent    LifecyclePhase = "intent"
	LifecycleAdopting  LifecyclePhase = "adopting"
	LifecycleFencing   LifecyclePhase = "fencing"
	LifecycleFenced    LifecyclePhase = "fenced"
	LifecycleReady     LifecyclePhase = "ready"
	LifecycleReleasing LifecyclePhase = "releasing"
	LifecycleCommitted LifecyclePhase = "committed"
)

type LifecycleProviderTransaction 

type LifecycleProviderTransaction struct {
	TransactionID       string `json:"transaction_id"`
	ProfileID           string `json:"profile_id"`
	Digest              string `json:"digest"`
	LegacyJournalSHA256 string `json:"legacy_journal_sha256,omitempty"`
}

func (LifecycleProviderTransaction) Validate 

func (binding LifecycleProviderTransaction) Validate(identity LifecycleIdentity) error

type LifecycleRecoveryAuthority 

type LifecycleRecoveryAuthority struct {
	Config           Config                    `json:"config"`
	ComputeAgent     LifecycleFileAttestation  `json:"compute_agent"`
	SupervisorConfig LifecycleFileAttestation  `json:"supervisor_config"`
	Podman           LifecycleFileAttestation  `json:"podman"`
	Systemctl        LifecycleFileAttestation  `json:"systemctl"`
	Loginctl         LifecycleFileAttestation  `json:"loginctl"`
	AgentUnitBefore  LifecycleSystemdSignature `json:"agent_unit_before"`
}

func (LifecycleRecoveryAuthority) Reattest 

func (authority LifecycleRecoveryAuthority) Reattest() error

func (LifecycleRecoveryAuthority) Validate 

func (authority LifecycleRecoveryAuthority) Validate(home string, identity LifecycleIdentity) error

type LifecycleSystemdSignature 

type LifecycleSystemdSignature struct {
	Fragment         LifecycleFileAttestation   `json:"fragment"`
	DropIns          []LifecycleFileAttestation `json:"drop_ins,omitempty"`
	ExecStart        string                     `json:"exec_start"`
	EnvironmentFiles []LifecycleFileAttestation `json:"environment_files,omitempty"`
}

func (LifecycleSystemdSignature) Reattest 

func (signature LifecycleSystemdSignature) Reattest() error

func (LifecycleSystemdSignature) Validate 

func (signature LifecycleSystemdSignature) Validate(home string) error

type LifecycleUnchangedProvenance 

type LifecycleUnchangedProvenance struct {
	Active        ImageSelection `json:"active"`
	Candidate     VerifiedUpdate `json:"candidate"`
	StableProbeAt time.Time      `json:"stable_probe_at,omitempty"`
}

func (LifecycleUnchangedProvenance) Validate 

func (provenance LifecycleUnchangedProvenance) Validate(identity LifecycleIdentity, requireProbe bool) error

type LifecycleUninstallPayload 

type LifecycleUninstallPayload struct {
	Purge bool `json:"purge"`
}

type OSCommandRunner 

type OSCommandRunner struct {
	MaxOutputBytes int
}

func (OSCommandRunner) Exec 

func (runner OSCommandRunner) Exec(command Command) error

func (OSCommandRunner) Run 

func (runner OSCommandRunner) Run(ctx context.Context, command Command) ([]byte, error)

type ProviderEffect 

type ProviderEffect string
const (
	ProviderChanged       ProviderEffect = "changed"
	ProviderUnchanged     ProviderEffect = "unchanged"
	ProviderNotApplicable ProviderEffect = "not_applicable"
)

type Refresher 

type Refresher struct {
	Runner         CommandRunner
	ExecutablePath func() (string, error)
	Random         io.Reader
	Now            func() time.Time
	Sleep          func(context.Context, time.Duration) error
	// contains filtered or unexported fields
}

func (Refresher) Refresh 

func (refresher Refresher) Refresh(ctx context.Context, config Config) (status Status, returnErr error)

func (Refresher) RestartAndProbeActive 

func (refresher Refresher) RestartAndProbeActive(ctx context.Context, config Config) error

RestartAndProbeActive revalidates the stable service even when the package digest did not change, as happens during credential rotation.

func (Refresher) ServeActive 

func (refresher Refresher) ServeActive(ctx context.Context, config Config) error

type Status 

type Status struct {
	ProtocolVersion string    `json:"protocol_version"`
	Installed       bool      `json:"installed"`
	ServiceActive   bool      `json:"service_active"`
	CurrentVersion  string    `json:"current_version,omitempty"`
	CurrentSHA256   string    `json:"current_sha256,omitempty"`
	ObservedAt      time.Time `json:"observed_at,omitempty"`
}

Status deliberately contains only redacted, local lifecycle observations.

type SystemdUnits 

type SystemdUnits struct {
	ProviderService string
	RefreshService  string
	RefreshPath     string
	RefreshTimer    string
	AgentDropIn     string
}

func RenderSystemdUnits 

func RenderSystemdUnits(config Config, paths LifecyclePaths) (SystemdUnits, error)

type TransactionJournal 

type TransactionJournal struct {
	ProtocolVersion    string         `json:"protocol_version"`
	ID                 string         `json:"id"`
	Phase              JournalPhase   `json:"phase"`
	RollbackFrom       JournalPhase   `json:"rollback_from,omitempty"`
	DeferredCommit     bool           `json:"deferred_commit,omitempty"`
	RuntimeRepair      bool           `json:"runtime_repair,omitempty"`
	OuterTransactionID string         `json:"outer_transaction_id,omitempty"`
	ProfileID          string         `json:"profile_id,omitempty"`
	Previous           *ActiveState   `json:"previous,omitempty"`
	Candidate          ImageSelection `json:"candidate"`
	StartedAt          time.Time      `json:"started_at"`
	UpdatedAt          time.Time      `json:"updated_at"`
}

func (TransactionJournal) Validate 

func (journal TransactionJournal) Validate() error

func (TransactionJournal) ValidateForConfig 

func (journal TransactionJournal) ValidateForConfig(config Config) error

type VerifiedUpdate 

type VerifiedUpdate struct {
	WorkerID    string `json:"worker_id"`
	DirectiveID string `json:"directive_id"`
	CampaignID  string `json:"campaign_id"`
	Component   string `json:"component"`
	PluginID    string `json:"plugin_id"`
	ComponentID string `json:"component_id"`
	Version     string `json:"version"`
	Format      string `json:"format"`
	Path        string `json:"path"`
	SHA256      string `json:"sha256"`
}

func VerifyCurrentUpdate 

func VerifyCurrentUpdate(ctx context.Context, config Config, runner CommandRunner) (VerifiedUpdate, error)

func (VerifiedUpdate) Validate 

func (update VerifiedUpdate) Validate() error

Source Files

View all Source files

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.