runtime

package
v0.0.0-...-c82e7e9 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package runtime owns backend-neutral module authority and lifecycle.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrModuleNotInstalled  = runtimeError(codes.NotFound, "MODULE_NOT_INSTALLED")
	ErrModuleAlreadyActive = runtimeError(codes.AlreadyExists, "MODULE_ALREADY_ACTIVE")
)

Functions

func IntersectResourceScopes

func IntersectResourceScopes(a, b []*wire.ResourceScope) []*wire.ResourceScope

IntersectResourceScopes returns fresh selectors, never aliases of input grants.

func ResourceScopesSubset

func ResourceScopesSubset(scopes, ceiling []*wire.ResourceScope) bool

func ValidateResourceScope

func ValidateResourceScope(scope *wire.ResourceScope, resourceFree bool) error

Types

type AccessRequest

type AccessRequest struct {
	Backend   string
	Operation string
	Scopes    []*wire.ResourceScope
}

type Admission

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

Admission is an operation-scoped authority lease, never wire identity. Its context is canceled at expiry, drain expiry or terminal failure.

func AdmissionFromContext

func AdmissionFromContext(ctx context.Context) (*Admission, error)

AdmissionFromContext returns the last admitted operation in this real RPC.

func (*Admission) CapabilityGrant

func (a *Admission) CapabilityGrant() (*wire.CapabilityGrant, error)

CapabilityGrant returns the immutable actual operation grant, including registered backend constraints, only while this admission is still valid.

func (*Admission) Context

func (a *Admission) Context() context.Context

func (*Admission) Principal

func (a *Admission) Principal() InstancePrincipal

func (*Admission) Release

func (a *Admission) Release()

type Authorizer

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

func (*Authorizer) Authorize

func (a *Authorizer) Authorize(ctx context.Context, req AccessRequest) (InstancePrincipal, error)

func (*Authorizer) AwaitOperation

func (a *Authorizer) AwaitOperation(ctx context.Context, backend, operation string) (InstancePrincipal, error)

AwaitOperation permits only bounded, trusted, readonly relationship lookup. It cannot authorize a mutation or credential/file lease and creates neither an admission nor another control-RPC slot. Authorize must subsequently check the complete resolved target list and recheck current operation eligibility.

type BackendBinding

type BackendBinding struct{ Grant *wire.BackendGrant }

type BackendConfig

type BackendConfig struct {
	Major         uint32            `json:"major"`
	Config        json.RawMessage   `json:"config"`
	SecretSources map[string]string `json:"secret_sources"`
}

type BackendCredentialHandle

type BackendCredentialHandle interface{ BackendCredentialHandle() }

BackendCredentialHandle is implemented by a backend-private secret-store key. Raw strings and tokens cannot satisfy this interface.

type BackendEvent

type BackendEvent struct {
	BackendID    string
	BackendMajor uint32
	EventType    string
	Operation    string
	Scope        *wire.ResourceScope
	ReceivedAt   time.Time
	Recipient    func(InstancePrincipal) bool
	Project      func(context.Context, InstancePrincipal) (*anypb.Any, error)
}

type BackendPreparation

type BackendPreparation struct {
	Requirement *wire.BackendRequirement
	Approved    *wire.BackendGrant
}

type BackendRegistration

type BackendRegistration struct {
	ID                        string
	Major                     uint32
	Adapter                   BackendAdapter
	Register                  func(InstanceServices) (core.HelperRegistrar, error)
	Operations                []OperationPolicy
	Events                    []EventPolicy
	ValidateSelector          func(*wire.ResourceSelector) error
	ValidateConstraints       func(*wire.CapabilityGrant) error
	ValidateConstraintsSubset func(actual, ceiling *wire.CapabilityGrant) error
}

Register is called before helper Serve; Prepare must never register services.

type CleanupPhase

type CleanupPhase uint8

CleanupPhase identifies an existing teardown step, not an operation result or a new retry policy. String returns only fixed diagnostic identifiers.

const (
	CleanupBackendDrain CleanupPhase = iota + 1
	CleanupLaunchJoin
	CleanupCallbackJoin
	CleanupStopHook
	CleanupHelperClose
	CleanupHostTerminate
	CleanupBackend
	CleanupFiles
	CleanupCredentials
	CleanupPluginJoin
	CleanupConnectJoin
	CleanupControls
	CleanupTransport
	CleanupHostRelease
)

func CleanupFailurePhases

func CleanupFailurePhases(err error) []CleanupPhase

CleanupFailurePhases returns a deduplicated, fixed-order list from the current Stop cleanup wrappers and errors.Join aggregates. It deliberately does not inspect opaque backend causes, their text, or their arbitrary unwrap chains. errors.Is/errors.As still reach those original causes through Unwrap.

func (CleanupPhase) String

func (phase CleanupPhase) String() string

type Config

type Config struct {
	SchemaVersion    int                        `json:"schema_version"`
	Host             HostConfig                 `json:"host"`
	Backends         map[string]BackendConfig   `json:"backends"`
	ResourceProfiles map[string]ResourceProfile `json:"resource_profiles"`
	Defaults         Defaults                   `json:"defaults"`
	Limits           Limits                     `json:"limits"`
	Modules          []ModuleSpec               `json:"-"`
}

func DecodeConfig

func DecodeConfig(raw []byte) (Config, error)

DecodeConfig rejects unknown and duplicate fields; module JSON bytes are kept exact. The caller bounds the host document while reading it; no secret source is expanded.

func (Config) Validate

func (c Config) Validate() error

type CoreServer

type CoreServer struct {
	wire.UnimplementedCoreServer
	Authorizer *Authorizer
}

func (*CoreServer) GetConfig

func (s *CoreServer) GetConfig(ctx context.Context, _ *emptypb.Empty) (*wire.JSONValue, error)

type CredentialBinding

type CredentialBinding struct {
	BackendID     string
	Purpose       string
	Resource      *wire.ResourceSelector
	ExpiresAt     time.Time
	BackendHandle BackendCredentialHandle
}

type CredentialLease

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

func (*CredentialLease) Context

func (l *CredentialLease) Context() context.Context

func (*CredentialLease) Handle

Handle is host-only; canceled leases never reveal the backend key.

func (*CredentialLease) Release

func (l *CredentialLease) Release()

type CredentialRegistry

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

func (*CredentialRegistry) Acquire

func (*CredentialRegistry) Issue

func (*CredentialRegistry) RevokeInstance

func (v *CredentialRegistry) RevokeInstance(ctx context.Context, owner InstancePrincipal) error

type CredentialRequirement

type CredentialRequirement struct {
	BackendID string
	Purpose   string
	Resource  *wire.ResourceSelector
}

type Defaults

type Defaults struct {
	StartupDeadline  Duration `json:"startup_deadline"`
	DrainDeadline    Duration `json:"drain_deadline"`
	EventQueueEvents int      `json:"event_queue_events"`
	EventQueueBytes  int64    `json:"event_queue_bytes"`
}

type Dispatcher

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

func (*Dispatcher) Admit

func (d *Dispatcher) Admit(ctx context.Context, event BackendEvent) error

func (*Dispatcher) FailBackend

func (d *Dispatcher) FailBackend(ctx context.Context, backend, reason string) error

FailBackend is reserved for an unattributable fatal backend decode or state integrity fault, not an ordinary API failure or an unowned route. It fails actual and preparing participants, without making core-only modules depend on every backend whose helper services were merely pre-registered.

func (*Dispatcher) FailEvent

func (d *Dispatcher) FailEvent(ctx context.Context, backend, eventType, reason string) error

FailEvent handles a known malformed event for which trustworthy target facts cannot be recovered. It never fabricates a scope, projects a payload, issues credentials or queues an event. Only RUNNING holders of that registered event's actual capability are failed. Unknown events produce a diagnostic. reason must be a fixed trusted code, never source JSON or an error body.

type Duration

type Duration time.Duration

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(raw []byte) error

type Error

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

Error is a fixed runtime failure with a machine-readable reason and status.

func (*Error) Error

func (e *Error) Error() string

func (*Error) GRPCStatus

func (e *Error) GRPCStatus() *status.Status

func (*Error) Reason

func (e *Error) Reason() string

type EventPolicy

type EventPolicy struct {
	EventType      string
	Operation      string
	PayloadTypeURL string
}

BackendEvent contains trusted resolved resource facts and a credential-safe projector. Project must be bounded, in-process and must not invoke modules or perform remote lookups. Only registered typed events may reach this entrypoint. Recipient applies backend-owned route/command ownership before projection.

type FileTransferFactory

type FileTransferFactory func(InstanceServices) (core.HelperRegistrar, error)

type HostConfig

type HostConfig struct {
	DockerEndpoint      string        `json:"docker_endpoint"`
	DockerEngineVersion string        `json:"docker_engine_version"`
	RunscRuntimeName    string        `json:"runsc_runtime_name"`
	RunscVersion        string        `json:"runsc_version"`
	RunscSHA256         string        `json:"runsc_sha256"`
	ManagementDirectory string        `json:"management_directory"`
	StorageRoot         string        `json:"storage_root"`
	IPCRoot             string        `json:"ipc_root"`
	QuotaBackend        string        `json:"quota_backend"`
	Network             NetworkConfig `json:"network"`
}

type Instance

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

Instance has one authoritative lock for lifecycle, authority, queues and leases. All externally visible protobuf values are immutable copies.

func (*Instance) Principal

func (i *Instance) Principal() InstancePrincipal

func (*Instance) Snapshot

func (i *Instance) Snapshot() InstanceSnapshot

type InstanceCleanup

type InstanceCleanup func(context.Context, InstancePrincipal) error

type InstanceID

type InstanceID string

type InstancePrincipal

type InstancePrincipal struct {
	ModuleID   ModuleID
	InstanceID InstanceID
}

func PrincipalFromContext

func PrincipalFromContext(ctx context.Context) (InstancePrincipal, error)

type InstanceServices

type InstanceServices struct {
	Principal           InstancePrincipal
	Authorizer          *Authorizer
	Credentials         *CredentialRegistry
	Limits              Limits
	ManagementDirectory string
	CredentialBindings  []ProvisionedCredentialBinding
}

type InstanceSnapshot

type InstanceSnapshot struct {
	Principal        InstancePrincipal
	State            RuntimeState
	FailureReason    string
	CleanupComplete  bool
	CleanupError     error
	RetainedEvents   int
	RetainedBytes    int64
	IncompleteEvents int
	Grants           *wire.Grants
}

type Limits

type Limits struct {
	TerminationDeadline       Duration `json:"termination_deadline"`
	DockerAPIDeadline         Duration `json:"docker_api_deadline"`
	HookRPCDeadline           Duration `json:"hook_rpc_deadline"`
	ReadinessPollInterval     Duration `json:"readiness_poll_interval"`
	ControlMessageMaxBytes    int      `json:"control_message_max_bytes"`
	ConfigMaxBytes            int      `json:"config_max_bytes"`
	ControlRPCsPerInstance    int      `json:"control_rpcs_per_instance"`
	CredentialRefsPerInstance int      `json:"credential_refs_per_instance"`
	CredentialRefMaxTTL       Duration `json:"credential_ref_max_ttl"`
	PersistentInodeLimit      int64    `json:"persistent_inode_limit"`
	ScratchInodeLimit         int64    `json:"scratch_inode_limit"`
	LogBufferBytes            int64    `json:"log_buffer_bytes"`
	LogFileMaxBytes           int64    `json:"log_file_max_bytes"`
	LogRetainedFiles          int      `json:"log_retained_files"`
	UploadRecordsPerInstance  int      `json:"upload_records_per_instance"`
	UploadRecordsPerHost      int      `json:"upload_records_per_host"`
	UploadFileNameMaxBytes    int      `json:"upload_file_name_max_bytes"`
	UploadContentTypeMaxBytes int      `json:"upload_content_type_max_bytes"`
	UploadDeadline            Duration `json:"upload_deadline"`
}

type Manager

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

func NewManager

func NewManager(config Config, options ManagerOptions) (*Manager, error)

func (*Manager) Credentials

func (m *Manager) Credentials() *CredentialRegistry

func (*Manager) Dispatcher

func (m *Manager) Dispatcher() *Dispatcher

func (*Manager) Instance

func (m *Manager) Instance(id ModuleID) (*Instance, bool)

func (*Manager) Launch

func (m *Manager) Launch(ctx context.Context, spec ModuleSpec) (result *Instance, launchErr error)

func (*Manager) Reconcile

func (m *Manager) Reconcile(ctx context.Context) error

func (*Manager) Stop

func (m *Manager) Stop(ctx context.Context, id ModuleID) error

type ManagerOptions

type ManagerOptions struct {
	Host         *host.Client
	Backends     []BackendRegistration
	FileTransfer FileTransferFactory
	FileCleanup  InstanceCleanup
}

type ModuleID

type ModuleID string

type ModuleSpec

type ModuleSpec struct {
	ModuleID                         ModuleID
	ImageDigest                      string
	Entrypoint, Args                 []string
	UID, GID                         uint32
	Config                           *wire.JSONValue
	Approval                         *wire.Grants
	CredentialBindings               []ProvisionedCredentialBinding
	ConfigRevision, ApprovalRevision string
}

type NetworkConfig

type NetworkConfig struct {
	FirewallBackend        string   `json:"firewall_backend"`
	IPv4                   bool     `json:"ipv4"`
	IPv6                   bool     `json:"ipv6"`
	Resolvers              []string `json:"resolvers"`
	HostPublicAddresses    []string `json:"host_public_addresses"`
	InternalPrefixes       []string `json:"internal_prefixes"`
	InfrastructurePrefixes []string `json:"infrastructure_prefixes"`
	MetadataDestinations   []string `json:"metadata_destinations"`
}

type OperationClass

type OperationClass uint8
const (
	FiniteOperation OperationClass = iota + 1
	LongLivedOperation
	OwnerCleanupOperation
)

type OperationPolicy

type OperationPolicy struct {
	Backend      string
	Operation    string
	Capability   string
	InitSafe     bool
	ResourceFree bool
	DrainSafe    bool
	Class        OperationClass
}

type ProvisionedCredentialBinding

type ProvisionedCredentialBinding struct {
	Name      string                 `json:"name"`
	BackendID string                 `json:"backend_id"`
	SecretID  string                 `json:"secret_id"`
	Purpose   string                 `json:"purpose"`
	Resource  *wire.ResourceSelector `json:"resource"`
}

type ResourceProfile

type ResourceProfile struct {
	CPUMillicores   uint32 `json:"cpu_millicores"`
	MemoryBytes     uint64 `json:"memory_bytes"`
	MaxPids         uint32 `json:"max_pids"`
	PersistentBytes uint64 `json:"persistent_bytes"`
	ScratchBytes    uint64 `json:"scratch_bytes"`
}

type RuntimeState

type RuntimeState string
const (
	Starting     RuntimeState = "STARTING"
	Initializing RuntimeState = "INITIALIZING"
	Ready        RuntimeState = "READY"
	Running      RuntimeState = "RUNNING"
	Draining     RuntimeState = "DRAINING"
	Stopped      RuntimeState = "STOPPED"
	Failed       RuntimeState = "FAILED"
)

Directories

Path Synopsis
Package upload implements the backend-neutral, instance-owned core file store.
Package upload implements the backend-neutral, instance-owned core file store.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL