core

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Aug 17, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package core defines the abstract interfaces for Platform Factory's domain.

Package core defines the abstract interfaces for Platform Factory's domain.

Index

Constants

View Source 
const (
	PipelineAPIVersion            = "platform-factory.dev/v1"
	PipelineLegacyAPIVersion      = "secure-oci.dev/v1"
	PipelineBetaAPIVersion        = "platform-factory.dev/v1beta1"
	PipelineBetaLegacyAPIVersion  = "secure-oci.dev/v1beta1"
	PipelineAlphaAPIVersion       = "platform-factory.dev/v1alpha1"
	PipelineAlphaLegacyAPIVersion = "secure-oci.dev/v1alpha1"
	// APIVersion aliases the oldest accepted wire identifier for internal tests
	// and fixtures. Domain validation accepts all compatibility versions.
	APIVersion       = PipelineAlphaAPIVersion
	LegacyAPIVersion = PipelineAlphaLegacyAPIVersion
)

Variables

View Source 
var ErrOperationIndeterminate = errors.New("operation outcome is indeterminate; re-observe external state")

ErrOperationIndeterminate means a mutation may have happened but no durable terminal observation exists. Callers must observe external state before any retry.

Functions

func CanTransition 

func CanTransition(from, to Phase) bool

CanTransition reports whether from -> to is an allowed transition.

func DeriveID 

func DeriveID(domain string, parts ...string) string

DeriveID returns a domain-separated, deterministic identity. Domain names are versioned by callers; NUL framing prevents ambiguous part boundaries.

func IsValidCapability 

func IsValidCapability(capability string) bool

IsValidCapability is a convenience function that returns true if the capability is valid.

func ValidOperationID 

func ValidOperationID(id OperationID) bool

ValidOperationID rejects values that cannot safely identify a journal record. The same validation applies to every journal adapter.

func ValidateCapability 

func ValidateCapability(capability string) error

ValidateCapability checks if a capability string is valid for use in a manifest. This is exported for use by other packages that need to validate capabilities.

Types

type ArtifactDeclaration 

type ArtifactDeclaration struct {
	Name string `json:"name"`
	Path string `json:"path"`
}

type ArtifactDescriptor 

type ArtifactDescriptor struct {
	Digest ArtifactDigest `json:"digest,omitempty"`
}

func (ArtifactDescriptor) Validate 

func (a ArtifactDescriptor) Validate() error

type ArtifactDigest 

type ArtifactDigest string

type ArtifactReference 

type ArtifactReference struct {
	Stage  string `json:"stage"`
	Name   string `json:"name"`
	Target string `json:"target,omitempty"`
}

type BuildPlan 

type BuildPlan struct {
	WorkloadID WorkloadID `json:"workload_id,omitempty"`
}

func (BuildPlan) Validate 

func (p BuildPlan) Validate() error

type CacheMount 

type CacheMount struct {
	ID     string `json:"id"`
	Target string `json:"target"`
}

type CacheStageKeyInputs 

type CacheStageKeyInputs struct {
	EngineVersion string
	Stage         Stage
	BaseDigest    string
	InputDigests  []string
	Platform      string
}

CacheStageKeyInputs is the core-owned input to deterministic stage-key computation. Concrete cache implementations consume this contract without leaking their types back into the domain.

type CacheStore 

type CacheStore interface {
	// Put streams content into the cache and returns a descriptor.
	// Identical content is deduplicated.
	Put(r io.Reader) (Descriptor, error)

	// Get retrieves cached content by digest.
	// Returns nil reader if not found.
	Get(digest string) (io.ReadCloser, error)

	// StageKey computes a deterministic cache key for a stage's inputs.
	StageKey(inputs CacheStageKeyInputs) (string, error)

	// GetRecord retrieves a cached record by key.
	GetRecord(key string, out any) (bool, error)

	// PutRecord stores a record under a key.
	PutRecord(key string, value any) error

	// Verify checks that a cached blob's content matches its digest.
	Verify(digest string) error
}

CacheStore is the interface that pipeline stages use to store and retrieve content-addressed build artifacts. It abstracts the concrete implementation in internal/cache, allowing internal/executor to depend only on this interface.

type CapabilitySet 

type CapabilitySet struct {
	Capabilities []string `json:"capabilities,omitempty"`
}

type Command 

type Command struct {
	Executable string   `json:"executable"`
	Args       []string `json:"args,omitempty"`
	WorkingDir string   `json:"working_dir,omitempty"`
}

type DeploymentSpec 

type DeploymentSpec struct {
	Runtime RuntimeSpec `json:"runtime,omitempty"`
}

func (DeploymentSpec) Validate 

func (d DeploymentSpec) Validate() error

type Descriptor 

type Descriptor struct {
	Digest string `json:"digest"`
	Size   int64  `json:"size"`
}

Descriptor identifies a stored blob by its content digest and size.

type EvidenceBundle 

type EvidenceBundle struct {
	Artifacts []ArtifactDescriptor `json:"artifacts,omitempty"`
}

func (EvidenceBundle) Validate 

func (e EvidenceBundle) Validate() error

type ImageReference 

type ImageReference struct {
	Reference string `json:"reference"`
	Digest    string `json:"digest"`
	Platform  string `json:"platform,omitempty"`
}

type Input 

type Input struct {
	ID     string `json:"id"`
	Kind   string `json:"kind"`
	Source string `json:"source"`
	Digest string `json:"digest,omitempty"`
}

type Mount 

type Mount struct {
	Source   string `json:"source"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"read_only,omitempty"`
}

type NetworkPolicy 

type NetworkPolicy string
const (
	NetworkNone    NetworkPolicy = "none"
	NetworkResolve NetworkPolicy = "resolve"
	NetworkFull    NetworkPolicy = "full"
)

type NetworkRelay 

type NetworkRelay interface {
	// ServeRelay exchanges length-prefixed DNS datagrams over a connected,
	// message-oriented transport. It is the host side of the resolve-only
	// sandbox data plane.
	ServeRelay(ctx context.Context, conn net.Conn) error

	// GetUpstream returns the configured upstream resolver address.
	GetUpstream() netip.AddrPort
	// GetTimeout returns the configured timeout for DNS operations.
	GetTimeout() int64
	// GetMaxInflight returns the maximum number of concurrent DNS requests.
	GetMaxInflight() int
}

NetworkRelay is the interface for network forwarding capabilities. It abstracts the concrete DNSForwarder implementation in internal/networking, allowing internal/executor to depend only on this interface.

type OperationID 

type OperationID string

type OperationJournal 

type OperationJournal interface {
	Lookup(OperationID) (OperationRecord, bool)
	Start(OperationID, string) (bool, error)
	Complete(OperationID) error
	Fail(OperationID) error
}

OperationJournal is the single idempotency persistence port. Start is an atomic claim: exactly one caller may receive started=true for an ID/scope.

type OperationRecord 

type OperationRecord struct {
	ID     OperationID
	Status OperationStatus
	Scope  string
}

OperationRecord contains only replay-safe identity and state. Plugin output and provider errors are deliberately excluded because both may contain secrets or other untrusted data.

type OperationStatus 

type OperationStatus string

OperationStatus is the durable state of a logical mutation. 

const (
	OperationStarted   OperationStatus = "started"
	OperationCompleted OperationStatus = "completed"
	OperationFailed    OperationStatus = "failed"
)

type Output 

type Output struct {
	Name     string `json:"name"`
	Stage    string `json:"stage"`
	Artifact string `json:"artifact"`
}

type Phase 

type Phase string

Phase is the canonical workload state shared by every backend. 

const (
	PhaseDeclared   Phase = "Declared"
	PhasePlanned    Phase = "Planned"
	PhaseBuilding   Phase = "Building"
	PhaseBuilt      Phase = "Built"
	PhasePublishing Phase = "Publishing"
	PhasePublished  Phase = "Published"
	PhaseDeploying  Phase = "Deploying"
	PhaseRunning    Phase = "Running"
	PhaseStopping   Phase = "Stopping"
	PhaseStopped    Phase = "Stopped"
	PhaseDeleting   Phase = "Deleting"
	PhaseDeleted    Phase = "Deleted"
	PhaseFailed     Phase = "Failed"
	// PhaseUnknown is not a terminal or working state - it means the
	// authoritative external system (containerd/KubeVirt/Kubernetes)
	// could not be reached to confirm what the real state is. A caller
	// observing Unknown must re-query rather than assume the last phase.
	PhaseUnknown Phase = "Unknown"
)

type Pipeline 

type Pipeline struct {
	APIVersion           string   `json:"api_version"`
	Name                 string   `json:"name"`
	RequiredCapabilities []string `json:"required_capabilities,omitempty"`
	Inputs               []Input  `json:"inputs,omitempty"`
	Stages               []Stage  `json:"stages"`
	Outputs              []Output `json:"outputs,omitempty"`
}

Pipeline is the private canonical model consumed by pipeline domain services. Public API versions are wire DTOs and are converted at composition boundaries.

type PluginFamily 

type PluginFamily string

PluginFamily groups plugins for discovery; routing uses capabilities. 

const (
	PluginFamilyLanguage   PluginFamily = "language"
	PluginFamilyAnalyzer   PluginFamily = "analyzer"
	PluginFamilyBuild      PluginFamily = "build"
	PluginFamilyRuntime    PluginFamily = "runtime"
	PluginFamilyDeployment PluginFamily = "deployment"
	PluginFamilyCapability PluginFamily = "capability"
)

type PluginID 

type PluginID string

type PluginManifest 

type PluginManifest struct {
	ID              PluginID          `json:"id" yaml:"id"`
	Version         string            `json:"version" yaml:"version"`
	ProtocolVersion int               `json:"protocol_version" yaml:"protocol_version"`
	Family          PluginFamily      `json:"family" yaml:"family"`
	Capabilities    []string          `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`
	Permissions     PluginPermissions `json:"permissions,omitempty" yaml:"permissions,omitempty"`
}

PluginManifest declares a plugin's identity, protocol, capabilities, and permissions.

func (PluginManifest) HasCapability 

func (m PluginManifest) HasCapability(capability string) bool

HasCapability reports whether the manifest declares it can perform capability. The core asks this - never a plugin-identity check - to decide whether to route an operation to a plugin at all.

func (PluginManifest) SupportsProtocol 

func (m PluginManifest) SupportsProtocol(hostSupported ...int) bool

SupportsProtocol reports whether the manifest's declared protocol version is one the host negotiating against it understands. Hosts should refuse a protocol version they do not support.

func (PluginManifest) Validate 

func (m PluginManifest) Validate() error

Validate checks the manifest is well-formed: every required field is present, the declared family is one this codebase recognizes, and there are no duplicate capability entries (a duplicate is always either a copy-paste mistake or an attempt to make a capability look more heavily supported than it is - reject it rather than silently dedup, so the author sees the mistake).

type PluginPermissions 

type PluginPermissions struct {
	Network    []string `json:"network,omitempty" yaml:"network,omitempty"`
	Filesystem []string `json:"filesystem,omitempty" yaml:"filesystem,omitempty"`
	Secrets    []string `json:"secrets,omitempty" yaml:"secrets,omitempty"`
}

PluginPermissions is the least-privilege declaration a manifest makes: every capability accessed outside the plugin's own confined workspace must be named here, not assumed. An empty PluginPermissions is the correct declaration for a plugin that needs none of these - the zero value is deliberately the most restrictive one, not "unspecified."

type PolicyDecision 

type PolicyDecision struct {
	Allowed bool `json:"allowed"`
}

type RecordIndex 

type RecordIndex map[string]map[string]Descriptor

RecordIndex maps stage keys to their output descriptors.

type ResourceLimits 

type ResourceLimits struct {
	CPUMilli  int64 `json:"cpu_milli,omitempty"`
	MemoryMiB int64 `json:"memory_mib,omitempty"`
	PIDs      int64 `json:"pids,omitempty"`
}

type RuntimeSpec 

type RuntimeSpec struct {
	Kind string `json:"kind,omitempty"`
}

func (RuntimeSpec) Validate 

func (r RuntimeSpec) Validate() error

type RuntimeState 

type RuntimeState struct {
	Phase Phase `json:"phase,omitempty"`
}

RuntimeState is a workload's canonical state - see statemachine.go for the Phase values it may hold and the transitions between them. This is the single state every backend (containerd, KubeVirt, Kubernetes, Docker, Podman) translates its own native state into; none of them invent their own meaning for what "running" means.

func (RuntimeState) TransitionTo 

func (s RuntimeState) TransitionTo(to Phase) (RuntimeState, error)

TransitionTo returns a new RuntimeState with Phase set to to, if the move from s.Phase is allowed. s itself is never mutated. An empty s.Phase is treated as PhaseDeclared's starting point implicitly only when to is PhaseDeclared itself (a freshly-declared workload has no prior phase to transition from); every other case requires an explicit, valid current phase.

type SandboxPolicy 

type SandboxPolicy struct {
	ReadOnlyRoot bool `json:"read_only_root"`
	NonRoot      bool `json:"non_root"`
}

type SecretReference 

type SecretReference struct {
	ID     string `json:"id"`
	Target string `json:"target"`
}

type Stage 

type Stage struct {
	ID        string                `json:"id"`
	DependsOn []string              `json:"depends_on,omitempty"`
	Base      *ImageReference       `json:"base,omitempty"`
	Command   Command               `json:"command"`
	Env       map[string]string     `json:"env,omitempty"`
	Mounts    []Mount               `json:"mounts,omitempty"`
	Secrets   []SecretReference     `json:"secrets,omitempty"`
	Caches    []CacheMount          `json:"caches,omitempty"`
	Inputs    []ArtifactReference   `json:"inputs,omitempty"`
	Outputs   []ArtifactDeclaration `json:"outputs,omitempty"`
	Network   NetworkPolicy         `json:"network,omitempty"`
	Resources ResourceLimits        `json:"resources,omitempty"`
	Sandbox   SandboxPolicy         `json:"sandbox,omitempty"`
}

type TransitionRule 

type TransitionRule struct {
	From         Phase
	To           Phase
	Idempotent   bool
	Compensation string
}

TransitionRule documents one allowed state change: whether it's safe to repeat verbatim after a crash (Idempotent), and what a caller must do to compensate for a partial attempt before it may retry (Compensation, empty when no cleanup is needed).

func LookupTransition 

func LookupTransition(from, to Phase) (TransitionRule, bool)

LookupTransition returns the rule governing from -> to, if that transition is allowed.

type WorkloadID 

type WorkloadID string

type WorkloadSpec 

type WorkloadSpec struct {
	ID      WorkloadID `json:"id,omitempty"`
	Version string     `json:"version,omitempty"`
}

func (WorkloadSpec) Validate 

func (s WorkloadSpec) 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.