Documentation
¶
Overview ¶
Package runtime owns backend-neutral module authority and lifecycle.
Index ¶
- Variables
- func IntersectResourceScopes(a, b []*wire.ResourceScope) []*wire.ResourceScope
- func ResourceScopesSubset(scopes, ceiling []*wire.ResourceScope) bool
- func ValidateResourceScope(scope *wire.ResourceScope, resourceFree bool) error
- type AccessRequest
- type Admission
- type Authorizer
- type BackendAdapter
- type BackendBinding
- type BackendConfig
- type BackendCredentialHandle
- type BackendEvent
- type BackendPreparation
- type BackendRegistration
- type CleanupPhase
- type Config
- type CoreServer
- type CredentialBinding
- type CredentialLease
- type CredentialRegistry
- func (v *CredentialRegistry) Acquire(ctx context.Context, ref *wire.CredentialRef, want CredentialRequirement) (*CredentialLease, error)
- func (v *CredentialRegistry) Issue(ctx context.Context, owner InstancePrincipal, b CredentialBinding) (*wire.CredentialRef, error)
- func (v *CredentialRegistry) RevokeInstance(ctx context.Context, owner InstancePrincipal) error
- type CredentialRequirement
- type Defaults
- type Dispatcher
- type Duration
- type Error
- type EventPolicy
- type FileTransferFactory
- type HostConfig
- type Instance
- type InstanceCleanup
- type InstanceID
- type InstancePrincipal
- type InstanceServices
- type InstanceSnapshot
- type Limits
- type Manager
- func (m *Manager) Credentials() *CredentialRegistry
- func (m *Manager) Dispatcher() *Dispatcher
- func (m *Manager) Instance(id ModuleID) (*Instance, bool)
- func (m *Manager) Launch(ctx context.Context, spec ModuleSpec) (result *Instance, launchErr error)
- func (m *Manager) Reconcile(ctx context.Context) error
- func (m *Manager) Stop(ctx context.Context, id ModuleID) error
- type ManagerOptions
- type ModuleID
- type ModuleSpec
- type NetworkConfig
- type OperationClass
- type OperationPolicy
- type ProvisionedCredentialBinding
- type ResourceProfile
- type RuntimeState
Constants ¶
This section is empty.
Variables ¶
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 ¶
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) Principal ¶
func (a *Admission) Principal() InstancePrincipal
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 BackendAdapter ¶
type BackendAdapter interface {
Prepare(context.Context, InstancePrincipal, BackendPreparation) (*BackendBinding, error)
Activate(context.Context, InstancePrincipal) error
Drain(context.Context, InstancePrincipal) error
Cleanup(context.Context, InstancePrincipal) error
}
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 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 ¶
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.
type CoreServer ¶
type CoreServer struct {
wire.UnimplementedCoreServer
Authorizer *Authorizer
}
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 ¶
func (l *CredentialLease) Handle() (BackendCredentialHandle, error)
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 (v *CredentialRegistry) Acquire(ctx context.Context, ref *wire.CredentialRef, want CredentialRequirement) (*CredentialLease, error)
func (*CredentialRegistry) Issue ¶
func (v *CredentialRegistry) Issue(ctx context.Context, owner InstancePrincipal, b CredentialBinding) (*wire.CredentialRef, error)
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 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 ¶
func (*Duration) UnmarshalJSON ¶
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) GRPCStatus ¶
type EventPolicy ¶
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
type ManagerOptions ¶
type ManagerOptions struct {
Host *host.Client
Backends []BackendRegistration
FileTransfer FileTransferFactory
FileCleanup InstanceCleanup
}
type ModuleSpec ¶
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 ResourceProfile ¶
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" )