microvm

package
v1.16.0 Latest Latest
Warning

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

 Go to latest Published: Jul 7, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package microvm provides AppTheory's constrained AWS Lambda MicroVM runtime primitives.

Index

Constants

View Source 
const (
	// ErrorCodeInvalidControllerRequest reports a malformed controller request envelope.
	ErrorCodeInvalidControllerRequest = "m15.microvm.invalid_controller_request"
	// ErrorCodeControllerCommandFailed reports a sanitized client command failure.
	ErrorCodeControllerCommandFailed = "m15.microvm.controller_command_failed"
)
View Source 
const (
	// KindLifecycle is the lifecycle contract kind.
	KindLifecycle ContractKind = "lifecycle"
	// KindControllerSession is the controller/session contract kind.
	KindControllerSession ContractKind = "controller_session"

	// ControllerAuthDefaultDeny is the only controller auth default AppTheory accepts.
	ControllerAuthDefaultDeny = "deny"

	// ErrorCodeUnauthenticatedController reports a controller contract or request that does not fail closed.
	ErrorCodeUnauthenticatedController = "m15.microvm.unauthenticated_controller"
	// ErrorCodeControllerIncomplete reports an incomplete controller contract.
	ErrorCodeControllerIncomplete = "m15.microvm.controller_incomplete"
	// ErrorCodeSessionRegistryIncomplete reports an incomplete session registry contract.
	ErrorCodeSessionRegistryIncomplete = "m15.microvm.session_registry_incomplete"
)
View Source 
const (
	// ErrorCodeInvalidContract reports an unsupported or malformed MicroVM contract.
	ErrorCodeInvalidContract = "m15.microvm.invalid_contract"
	// ErrorCodeRawSDKEscapeHatch reports a forbidden raw AWS SDK escape hatch.
	ErrorCodeRawSDKEscapeHatch = "m15.microvm.raw_sdk_escape_hatch"
	// ErrorCodeLifecycleBypass reports a forbidden raw lifecycle hook bypass.
	ErrorCodeLifecycleBypass = "m15.microvm.lifecycle_bypass" //nolint:gosec // Contract error code, not a credential.
	// ErrorCodeLifecycleIncomplete reports an incomplete lifecycle contract.
	ErrorCodeLifecycleIncomplete = "m15.microvm.lifecycle_incomplete"
	// ErrorCodeForbiddenField reports a field that AppTheory refuses to persist or echo.
	ErrorCodeForbiddenField = "m15.microvm.forbidden_field"
	// ErrorCodeInvalidLifecycleEvent reports a malformed lifecycle event.
	ErrorCodeInvalidLifecycleEvent = "m15.microvm.invalid_lifecycle_event"
	// ErrorCodeLifecycleHookFailed reports a lifecycle hook handler failure.
	ErrorCodeLifecycleHookFailed = "m15.microvm.lifecycle_hook_failed"
)
View Source 
const (
	// ContractName is the only supported AppTheory MicroVM contract name.
	ContractName = "apptheory.lambda_microvm"
	// ContractVersion is the M15 MicroVM contract version implemented by this package.
	ContractVersion = "m15.microvm/v1"
)
View Source 
const (
	// ContractVersionM16 is the corrective real Lambda MicroVM contract version.
	ContractVersionM16 = "m16.microvm/v1"

	// ErrorCodeOperationContractIncomplete reports an incomplete real MicroVM operation contract.
	ErrorCodeOperationContractIncomplete = "m16.microvm.operation_contract_incomplete"
	// ErrorCodeRouteContractIncomplete reports an incomplete or unsafe real MicroVM HTTP route contract.
	ErrorCodeRouteContractIncomplete = "m16.microvm.route_contract_incomplete"
	// ErrorCodeProviderStateMappingIncomplete reports an incomplete provider-state mapping contract.
	ErrorCodeProviderStateMappingIncomplete = "m16.microvm.provider_state_mapping_incomplete"
	// ErrorCodeTokenSafetyViolation reports an unsafe MicroVM token issuance surface.
	ErrorCodeTokenSafetyViolation = "m16.microvm.token_safety_violation" //nolint:gosec // Contract error code, not a credential.
	// ErrorCodeTenantBindingViolation reports a cross-tenant MicroVM access contract violation.
	ErrorCodeTenantBindingViolation = "m16.microvm.tenant_binding_violation"
	// ErrorCodeRealLifecycleIncomplete reports an incomplete real MicroVM lifecycle contract.
	ErrorCodeRealLifecycleIncomplete = "m16.microvm.lifecycle_incomplete"
)
View Source 
const (
	// ErrorCodeProviderRequestInvalid reports a malformed constrained provider request.
	ErrorCodeProviderRequestInvalid = "m16.microvm.provider_request_invalid"
	// ErrorCodeProviderOperationUnsupported reports an operation outside the M16 real provider vocabulary.
	ErrorCodeProviderOperationUnsupported = "m16.microvm.provider_operation_unsupported"
	// ErrorCodeProviderOperationFailed reports a sanitized provider call failure.
	ErrorCodeProviderOperationFailed = "m16.microvm.provider_operation_failed"
)
View Source 
const (
	// EnvSessionRegistryTableName names the TableTheory table used for durable MicroVM session records.
	EnvSessionRegistryTableName = "APPTHEORY_MICROVM_SESSION_REGISTRY_TABLE"
	// DefaultSessionRegistryTableName is the default durable MicroVM session registry table name.
	DefaultSessionRegistryTableName = "apptheory-microvm-sessions"
)
View Source 
const (
	// DefaultSessionProviderID is the provider id used by deterministic AppTheory registry clients.
	DefaultSessionProviderID = "apptheory.microvm.registry"
	// AWSLambdaMicroVMProviderID is the provider id for the official AWS Lambda MicroVM provider.
	AWSLambdaMicroVMProviderID = "aws.lambda.microvm"
)
View Source 
const (
	// EnvExecutionRoleArn names the optional IAM role ARN passed to AWS Lambda MicroVMs during execution.
	EnvExecutionRoleArn = "APPTHEORY_MICROVM_EXECUTION_ROLE_ARN"
)

Variables

This section is empty.

Functions

func IsTerminalState 

func IsTerminalState(state LifecycleState) bool

IsTerminalState reports whether a state is terminal under the M15 contract.

func RegisterControllerRoutes added in v1.15.0 

func RegisterControllerRoutes(app *apptheory.App, controller *Controller) (*apptheory.App, error)

RegisterControllerRoutes registers the canonical M16 MicroVM controller HTTP routes on an AppTheory app.

func RegisterMicroVMControllerRoutes added in v1.15.0 

func RegisterMicroVMControllerRoutes(app *apptheory.App, controller *Controller) (*apptheory.App, error)

RegisterMicroVMControllerRoutes is an explicit alias for RegisterControllerRoutes.

func RequiredForbiddenOperationFields added in v1.15.0 

func RequiredForbiddenOperationFields() []string

RequiredForbiddenOperationFields returns field names that must never be accepted or emitted by MicroVM contracts.

func SessionRegistryPartitionKey 

func SessionRegistryPartitionKey(tenantID, namespace string) string

SessionRegistryPartitionKey derives the TableTheory partition key for a tenant-bound namespace.

func SessionRegistrySortKey 

func SessionRegistrySortKey(sessionID string) string

SessionRegistrySortKey derives the TableTheory sort key for a session.

func SessionRegistryTableName 

func SessionRegistryTableName() string

SessionRegistryTableName returns the configured registry table name.

func ValidateControllerContract 

func ValidateControllerContract(contract ControllerContract) error

ValidateControllerContract validates the controller contract vocabulary.

func ValidateEscapeHatches 

func ValidateEscapeHatches(escapeHatches EscapeHatches) error

ValidateEscapeHatches fails closed when a contract enables a raw SDK or lifecycle bypass.

func ValidateLifecycleContract 

func ValidateLifecycleContract(contract LifecycleContract) error

ValidateLifecycleContract validates the lifecycle contract and returns a safe error on failure.

func ValidateOperationContract added in v1.15.0 

func ValidateOperationContract(contract OperationContract) error

ValidateOperationContract validates the real MicroVM operation, route, token, provider-state, and tenant contract.

func ValidateProviderListInput added in v1.15.0 

func ValidateProviderListInput(input ProviderListInput) error

ValidateProviderListInput validates a safe AppTheory list/recovery provider request.

func ValidateProviderRunInput added in v1.15.0 

func ValidateProviderRunInput(input ProviderRunInput) error

ValidateProviderRunInput validates a safe AppTheory run request.

func ValidateProviderSession added in v1.15.0 

func ValidateProviderSession(session ProviderSession) error

ValidateProviderSession validates a sanitized provider session response.

func ValidateProviderSessionInput added in v1.15.0 

func ValidateProviderSessionInput(operation Operation, input ProviderSessionInput) error

ValidateProviderSessionInput validates a safe AppTheory bound-session provider request.

func ValidateProviderToken added in v1.15.0 

func ValidateProviderToken(token ProviderToken) error

ValidateProviderToken validates sanitized token issuance metadata.

func ValidateProviderTokenInput added in v1.15.0 

func ValidateProviderTokenInput(operation Operation, input ProviderTokenInput) error

ValidateProviderTokenInput validates a safe AppTheory token provider request.

func ValidateRealLifecycleContract added in v1.15.0 

func ValidateRealLifecycleContract(contract LifecycleContract) error

ValidateRealLifecycleContract validates the M16 real lifecycle vocabulary without accepting synthetic start/stop hooks.

func ValidateSessionRecord 

func ValidateSessionRecord(record SessionRecord) error

ValidateSessionRecord fails closed when a session record is incomplete or contains forbidden metadata.

func ValidateSessionRegistryContract 

func ValidateSessionRegistryContract(registry SessionRegistryContract) error

ValidateSessionRegistryContract validates the session registry contract vocabulary.

func ValidateSessionRegistryRecord 

func ValidateSessionRegistryRecord(record SessionRegistryRecord) error

ValidateSessionRegistryRecord fails closed when a durable registry item is incomplete, unsafe, or its derived TableTheory keys do not match its tenant/session identity.

func ValidateSessionStatus 

func ValidateSessionStatus(status SessionStatus) error

ValidateSessionStatus fails closed when a status response is incomplete.

func ValidateSessionTokenMetadata added in v1.15.0 

func ValidateSessionTokenMetadata(token SessionTokenMetadata, requestID string) error

ValidateSessionTokenMetadata fails closed if token metadata is incomplete or carries token plaintext.

Types

type AWSLambdaMicroVMProvider added in v1.15.0 

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

AWSLambdaMicroVMProvider is the official AWS SDK-backed constrained provider adapter.

The raw AWS SDK client and loaded AWS configuration remain private implementation details.

func NewAWSLambdaMicroVMProvider added in v1.15.0 

func NewAWSLambdaMicroVMProvider(ctx context.Context, opts ...AWSLambdaMicroVMProviderOption) (*AWSLambdaMicroVMProvider, error)

NewAWSLambdaMicroVMProvider creates an official AWS SDK-backed constrained provider adapter.

AWS credentials and the raw SDK client are loaded and retained internally; callers receive only the AppTheory Provider interface implemented by the returned adapter.

func (*AWSLambdaMicroVMProvider) CreateAuthToken added in v1.15.0 

func (p *AWSLambdaMicroVMProvider) CreateAuthToken(ctx context.Context, input ProviderTokenInput) (ProviderToken, error)

CreateAuthToken maps a safe AppTheory auth-token request to the official AWS token operation.

func (*AWSLambdaMicroVMProvider) CreateShellToken added in v1.15.0 

func (p *AWSLambdaMicroVMProvider) CreateShellToken(ctx context.Context, input ProviderTokenInput) (ProviderToken, error)

CreateShellToken maps a safe AppTheory shell-token request to the official AWS token operation.

func (*AWSLambdaMicroVMProvider) Get added in v1.15.0 

func (p *AWSLambdaMicroVMProvider) Get(ctx context.Context, input ProviderSessionInput) (ProviderSession, error)

Get maps a safe AppTheory get request to the official AWS GetMicrovm operation.

func (*AWSLambdaMicroVMProvider) List added in v1.15.0 

func (p *AWSLambdaMicroVMProvider) List(ctx context.Context, input ProviderListInput) (ProviderListOutput, error)

List maps a tenant-bound AppTheory list request to the official AWS ListMicrovms operation.

func (*AWSLambdaMicroVMProvider) Resume added in v1.15.0 

func (p *AWSLambdaMicroVMProvider) Resume(ctx context.Context, input ProviderSessionInput) (ProviderSession, error)

Resume maps a safe AppTheory resume request to the official AWS ResumeMicrovm operation.

func (*AWSLambdaMicroVMProvider) Run added in v1.15.0 

func (p *AWSLambdaMicroVMProvider) Run(ctx context.Context, input ProviderRunInput) (ProviderSession, error)

Run maps a safe AppTheory run request to the official AWS RunMicrovm operation.

func (*AWSLambdaMicroVMProvider) Suspend added in v1.15.0 

func (p *AWSLambdaMicroVMProvider) Suspend(ctx context.Context, input ProviderSessionInput) (ProviderSession, error)

Suspend maps a safe AppTheory suspend request to the official AWS SuspendMicrovm operation.

func (*AWSLambdaMicroVMProvider) Terminate added in v1.15.0 

func (p *AWSLambdaMicroVMProvider) Terminate(ctx context.Context, input ProviderSessionInput) (ProviderSession, error)

Terminate maps a safe AppTheory terminate request to the official AWS TerminateMicrovm operation.

type AWSLambdaMicroVMProviderOption added in v1.15.0 

type AWSLambdaMicroVMProviderOption func(*awsLambdaMicroVMProviderConfig)

AWSLambdaMicroVMProviderOption configures the official AWS Lambda MicroVM provider adapter.

func WithAWSLambdaMicroVMClock added in v1.15.0 

func WithAWSLambdaMicroVMClock(clock Clock) AWSLambdaMicroVMProviderOption

WithAWSLambdaMicroVMClock sets the clock used for sanitized token metadata.

func WithAWSLambdaMicroVMRegion added in v1.15.0 

func WithAWSLambdaMicroVMRegion(region string) AWSLambdaMicroVMProviderOption

WithAWSLambdaMicroVMRegion sets the AWS region used by the official provider adapter.

type AuthContext 

type AuthContext struct {
	Subject      string            `json:"subject"`
	TenantID     string            `json:"tenant_id"`
	Namespace    string            `json:"namespace,omitempty"`
	Entitlements []string          `json:"entitlements,omitempty"`
	Metadata     map[string]string `json:"metadata,omitempty"`
}

AuthContext is the sanitized authenticated principal context required by controller requests.

type Client 

type Client interface {
	Create(context.Context, CreateSessionInput) (SessionRecord, error)
	Start(context.Context, SessionCommandInput) (SessionRecord, error)
	Stop(context.Context, SessionCommandInput) (SessionRecord, error)
	Status(context.Context, SessionQueryInput) (SessionStatus, error)
	Session(context.Context, SessionQueryInput) (SessionRecord, error)
}

Client is the constrained MicroVM client surface. It deliberately exposes no raw AWS SDK client.

type Clock 

type Clock interface {
	Now() time.Time
}

Clock supplies controller timestamps.

type Command 

type Command string

Command names a constrained MicroVM controller command. 

const (
	CommandCreate  Command = "create"
	CommandStart   Command = "start"
	CommandStop    Command = "stop"
	CommandStatus  Command = "status"
	CommandSession Command = "session"

	CommandRun            Command = "run"
	CommandGet            Command = "get"
	CommandList           Command = "list"
	CommandSuspend        Command = "suspend"
	CommandResume         Command = "resume"
	CommandTerminate      Command = "terminate"
	CommandAuthToken      Command = "auth-token"
	CommandShellAuthToken Command = "shell-auth-token" //nolint:gosec // Contract command name, not a credential.
	// CommandShellToken is a compatibility alias for the canonical shell-auth-token command.
	CommandShellToken Command = CommandShellAuthToken
	// CommandLegacyShellToken is accepted only as a compatibility input alias.
	CommandLegacyShellToken Command = "shell-token"
)

type ContractKind 

type ContractKind string

ContractKind identifies a MicroVM contract vocabulary kind.

type Controller 

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

Controller handles constrained MicroVM control-plane commands.

func NewController 

func NewController(client Client, opts ...ControllerOption) (*Controller, error)

NewController creates a fail-closed MicroVM controller.

func NewRealController added in v1.15.0 

func NewRealController(provider Provider, registry SessionRegistry, opts ...ControllerOption) (*Controller, error)

NewRealController creates the canonical M16 provider-backed MicroVM controller.

func (*Controller) Handle 

func (c *Controller) Handle(ctx context.Context, request ControllerRequest) (ControllerResponse, error)

Handle executes a controller request after authenticated, tenant-bound envelope validation.

type ControllerAuthContract 

type ControllerAuthContract struct {
	Required bool   `json:"required"`
	Default  string `json:"default"`
}

ControllerAuthContract describes controller authentication requirements.

type ControllerCommandContract 

type ControllerCommandContract struct {
	Name           Command  `json:"name"`
	Method         string   `json:"method"`
	Path           string   `json:"path"`
	RequestFields  []string `json:"request_fields"`
	ResponseFields []string `json:"response_fields"`
}

ControllerCommandContract describes a single controller command.

type ControllerContract 

type ControllerContract struct {
	Auth     ControllerAuthContract      `json:"auth"`
	Envelope ControllerEnvelopeContract  `json:"envelope"`
	Commands []ControllerCommandContract `json:"commands"`
}

ControllerContract is the AppTheory MicroVM controller vocabulary.

func DefaultControllerContract 

func DefaultControllerContract() ControllerContract

DefaultControllerContract returns the M15 controller command and envelope vocabulary.

type ControllerEnvelopeContract 

type ControllerEnvelopeContract struct {
	RequiredFields  []string `json:"required_fields"`
	SafeErrorFields []string `json:"safe_error_fields"`
	ForbiddenFields []string `json:"forbidden_fields"`
}

ControllerEnvelopeContract describes the safe controller envelope vocabulary.

type ControllerOption 

type ControllerOption func(*Controller)

ControllerOption configures a Controller.

func WithControllerClock 

func WithControllerClock(clock Clock) ControllerOption

WithControllerClock sets the controller clock. Nil restores the real clock.

func WithControllerExecutionRoleArn added in v1.15.2 

func WithControllerExecutionRoleArn(executionRoleArn string) ControllerOption

WithControllerExecutionRoleArn sets the optional IAM role ARN passed to provider RunMicrovm requests.

func WithControllerID 

func WithControllerID(controllerID string) ControllerOption

WithControllerID sets the controller_id written into session records.

func WithControllerIDGenerator 

func WithControllerIDGenerator(ids IDGenerator) ControllerOption

WithControllerIDGenerator sets the controller session ID generator. Nil restores the default generator.

func WithControllerProviderID added in v1.15.0 

func WithControllerProviderID(providerID string) ControllerOption

WithControllerProviderID sets the provider id written into real provider-backed session records.

func WithControllerSessionTTL added in v1.15.0 

func WithControllerSessionTTL(ttl time.Duration) ControllerOption

WithControllerSessionTTL configures the TTL applied to real provider-backed session records.

type ControllerRequest 

type ControllerRequest struct {
	Command                     Command             `json:"command"`
	RequestID                   string              `json:"request_id"`
	TenantID                    string              `json:"tenant_id"`
	Namespace                   string              `json:"namespace"`
	AuthContext                 AuthContext         `json:"auth_context"`
	SessionID                   string              `json:"session_id,omitempty"`
	ImageRef                    string              `json:"image_ref,omitempty"`
	ImageVersion                string              `json:"image_version,omitempty"`
	NetworkConnectorRef         string              `json:"network_connector_ref,omitempty"`
	IngressNetworkConnectorRefs []string            `json:"ingress_network_connector_refs,omitempty"`
	EgressNetworkConnectorRefs  []string            `json:"egress_network_connector_refs,omitempty"`
	SessionSpec                 SessionSpec         `json:"session_spec,omitempty"`
	IdlePolicy                  *ProviderIdlePolicy `json:"idle_policy,omitempty"`
	MaximumDurationSeconds      int32               `json:"maximum_duration_seconds,omitempty"`
	TTLSeconds                  int32               `json:"ttl_seconds,omitempty"`
	AllowedPortScope            []ProviderPortScope `json:"allowed_port_scope,omitempty"`
	MaxResults                  int32               `json:"max_results,omitempty"`
}

ControllerRequest is the single AppTheory MicroVM control-plane request envelope.

type ControllerResponse 

type ControllerResponse struct {
	Command           Command           `json:"command"`
	RequestID         string            `json:"request_id"`
	TenantID          string            `json:"tenant_id,omitempty"`
	Namespace         string            `json:"namespace,omitempty"`
	SessionID         string            `json:"session_id,omitempty"`
	State             LifecycleState    `json:"state,omitempty"`
	DesiredState      LifecycleState    `json:"desired_state,omitempty"`
	LifecycleState    LifecycleState    `json:"lifecycle_state,omitempty"`
	Endpoint          string            `json:"endpoint,omitempty"`
	MicroVMID         string            `json:"microvm_id,omitempty"`
	ProviderMicroVMID string            `json:"provider_microvm_id,omitempty"`
	ProviderState     string            `json:"provider_state,omitempty"`
	LastAction        Command           `json:"last_action,omitempty"`
	LastTransition    time.Time         `json:"last_transition,omitempty"`
	RegistryVersion   int64             `json:"registry_version,omitempty"`
	Sessions          []ProviderSession `json:"sessions,omitempty"`
	RecoveryCursor    string            `json:"recovery_cursor,omitempty"`
	TokenID           string            `json:"token_id,omitempty"`
	TokenType         string            `json:"token_type,omitempty"`
	ExpiresAt         time.Time         `json:"expires_at,omitempty"`
	Scope             []string          `json:"scope,omitempty"`
	Error             *SafeError        `json:"error,omitempty"`
}

ControllerResponse is the safe controller response envelope.

type CreateSessionInput 

type CreateSessionInput struct {
	RequestID           string      `json:"request_id"`
	TenantID            string      `json:"tenant_id"`
	Namespace           string      `json:"namespace"`
	SessionID           string      `json:"session_id"`
	ImageRef            string      `json:"image_ref"`
	NetworkConnectorRef string      `json:"network_connector_ref"`
	SessionSpec         SessionSpec `json:"session_spec"`
	ControllerID        string      `json:"controller_id"`
	AuthSubject         string      `json:"auth_subject"`
	Now                 time.Time   `json:"now"`
}

CreateSessionInput is the safe client input for creating a session.

type EscapeHatches 

type EscapeHatches struct {
	RawAWSSDK              bool `json:"raw_aws_sdk"`
	RawLifecycleHookBypass bool `json:"raw_lifecycle_hook_bypass"`
}

EscapeHatches captures forbidden extension points that must remain disabled.

type IDGenerator 

type IDGenerator interface {
	NewID() string
}

IDGenerator supplies controller-created session identifiers.

type LifecycleAdapter 

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

LifecycleAdapter executes MicroVM lifecycle hooks through the contract vocabulary.

func NewLifecycleAdapter 

func NewLifecycleAdapter(opts ...LifecycleOption) (*LifecycleAdapter, error)

NewLifecycleAdapter creates a lifecycle adapter that fails closed when its contract is incomplete.

func (*LifecycleAdapter) Handle 

func (a *LifecycleAdapter) Handle(ctx context.Context, event LifecycleEvent) (LifecycleResult, error)

Handle executes one lifecycle hook. Handler errors are sanitized and translated to failed state.

type LifecycleContract 

type LifecycleContract struct {
	Hooks          []LifecycleHookSpec   `json:"hooks"`
	States         []LifecycleState      `json:"states"`
	TerminalStates []LifecycleState      `json:"terminal_states"`
	Transitions    []LifecycleTransition `json:"transitions"`
}

LifecycleContract is the AppTheory MicroVM lifecycle vocabulary.

func DefaultLifecycleContract 

func DefaultLifecycleContract() LifecycleContract

DefaultLifecycleContract returns the M15 MicroVM lifecycle contract vocabulary.

func DefaultRealLifecycleContract added in v1.15.0 

func DefaultRealLifecycleContract() LifecycleContract

DefaultRealLifecycleContract returns the M16 real MicroVM lifecycle vocabulary.

type LifecycleEvent 

type LifecycleEvent struct {
	RequestID string            `json:"request_id"`
	TenantID  string            `json:"tenant_id"`
	Namespace string            `json:"namespace"`
	SessionID string            `json:"session_id"`
	Hook      LifecycleHook     `json:"hook"`
	State     LifecycleState    `json:"state"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

LifecycleEvent is the sanitized event passed to lifecycle hook handlers. It intentionally contains no raw Lambda payload and no raw AWS SDK client.

type LifecycleHandler 

type LifecycleHandler func(context.Context, LifecycleEvent) error

LifecycleHandler handles one sanitized lifecycle hook invocation.

type LifecycleHook 

type LifecycleHook string

LifecycleHook names a first-class MicroVM lifecycle hook. 

const (
	HookPrepareImage LifecycleHook = "prepare_image"
	HookStart        LifecycleHook = "start"
	HookReadiness    LifecycleHook = "readiness"
	HookStop         LifecycleHook = "stop"
	HookTeardown     LifecycleHook = "teardown"
	HookFailure      LifecycleHook = "failure"
)
const (
	// HookValidate validates a requested MicroVM before provider run.
	HookValidate LifecycleHook = "validate"
	// HookRun tracks a provider run operation.
	HookRun LifecycleHook = "run"
	// HookReady tracks a provider readiness observation.
	HookReady LifecycleHook = "ready"
	// HookSuspend tracks a provider suspend operation.
	HookSuspend LifecycleHook = "suspend"
	// HookResume tracks a provider resume operation.
	HookResume LifecycleHook = "resume"
	// HookTerminate tracks a provider terminate operation.
	HookTerminate LifecycleHook = "terminate"
)

type LifecycleHookSpec 

type LifecycleHookSpec struct {
	Name         LifecycleHook  `json:"name"`
	Phase        string         `json:"phase"`
	State        LifecycleState `json:"state"`
	SuccessState LifecycleState `json:"success_state"`
	FailureState LifecycleState `json:"failure_state"`
}

LifecycleHookSpec is the contract vocabulary for one lifecycle hook.

type LifecycleOption 

type LifecycleOption func(*LifecycleAdapter)

LifecycleOption configures a LifecycleAdapter.

func WithLifecycleContract 

func WithLifecycleContract(contract LifecycleContract) LifecycleOption

WithLifecycleContract replaces the default M15 lifecycle contract.

func WithLifecycleHandler 

func WithLifecycleHandler(hook LifecycleHook, handler LifecycleHandler) LifecycleOption

WithLifecycleHandler registers a handler for a contract lifecycle hook.

type LifecycleResult 

type LifecycleResult struct {
	RequestID     string            `json:"request_id"`
	TenantID      string            `json:"tenant_id"`
	Namespace     string            `json:"namespace"`
	SessionID     string            `json:"session_id"`
	Hook          LifecycleHook     `json:"hook"`
	PreviousState LifecycleState    `json:"previous_state"`
	State         LifecycleState    `json:"state"`
	Metadata      map[string]string `json:"metadata,omitempty"`
	Error         *SafeError        `json:"error,omitempty"`
}

LifecycleResult is the safe result returned by a lifecycle adapter.

type LifecycleState 

type LifecycleState string

LifecycleState names a contract-defined MicroVM lifecycle state. 

const (
	StateRequested        LifecycleState = "requested"
	StateImagePreparing   LifecycleState = "image_preparing"
	StateImagePrepared    LifecycleState = "image_prepared"
	StateStarting         LifecycleState = "starting"
	StateStarted          LifecycleState = "started"
	StateReadinessProbing LifecycleState = "readiness_probing"
	StateReady            LifecycleState = "ready"
	StateStopping         LifecycleState = "stopping"
	StateStopped          LifecycleState = "stopped"
	StateTearingDown      LifecycleState = "tearing_down"
	StateTerminated       LifecycleState = "terminated"
	StateFailed           LifecycleState = "failed"
)
const (
	StateValidating  LifecycleState = "validating"
	StateValidated   LifecycleState = "validated"
	StateRunning     LifecycleState = "running"
	StateSuspending  LifecycleState = "suspending"
	StateSuspended   LifecycleState = "suspended"
	StateResuming    LifecycleState = "resuming"
	StateTerminating LifecycleState = "terminating"
)

func MapProviderState added in v1.15.0 

func MapProviderState(providerState string) (LifecycleState, bool, error)

MapProviderState maps a provider state string into the AppTheory M16 lifecycle contract.

type LifecycleTransition 

type LifecycleTransition struct {
	From LifecycleState `json:"from"`
	Hook LifecycleHook  `json:"hook"`
	To   LifecycleState `json:"to"`
}

LifecycleTransition is one allowed contract transition.

type MemorySessionRegistry 

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

MemorySessionRegistry is a deterministic in-memory SessionRegistry for tests and local contract runners.

func NewMemorySessionRegistry 

func NewMemorySessionRegistry() *MemorySessionRegistry

NewMemorySessionRegistry creates an empty deterministic session registry.

func (*MemorySessionRegistry) Delete 

func (r *MemorySessionRegistry) Delete(_ context.Context, key SessionKey) error

Delete removes a record from memory by its tenant-bound key.

func (*MemorySessionRegistry) Get 

func (r *MemorySessionRegistry) Get(_ context.Context, key SessionKey) (SessionRecord, error)

Get loads a record from memory by its tenant-bound key.

func (*MemorySessionRegistry) List added in v1.15.0 

func (r *MemorySessionRegistry) List(_ context.Context, input SessionListInput) ([]SessionRecord, error)

List returns records for exactly one tenant and namespace.

func (*MemorySessionRegistry) Put 

func (r *MemorySessionRegistry) Put(_ context.Context, record SessionRecord) (SessionRecord, error)

Put validates and stores a record in memory.

type Operation added in v1.15.0 

type Operation string

Operation names a real AWS Lambda MicroVM control-plane operation. 

const (
	OperationRun       Operation = "run"
	OperationGet       Operation = "get"
	OperationList      Operation = "list"
	OperationSuspend   Operation = "suspend"
	OperationResume    Operation = "resume"
	OperationTerminate Operation = "terminate"
	OperationAuthToken Operation = "auth-token"
	// OperationShellAuthToken is the canonical shell token issuance operation.
	OperationShellAuthToken Operation = "shell-auth-token" //nolint:gosec // Contract operation name, not a credential.
	// OperationShellToken is a compatibility alias for the canonical shell-auth-token operation.
	OperationShellToken Operation = OperationShellAuthToken
	// OperationLegacyShellToken is accepted only as a compatibility input alias.
	OperationLegacyShellToken Operation = "shell-token"
)

func RequiredOperations added in v1.15.0 

func RequiredOperations() []Operation

RequiredOperations returns the complete M16 real MicroVM operation vocabulary.

type OperationContract added in v1.15.0 

type OperationContract struct {
	Operations            []Operation                  `json:"operations"`
	Routes                []OperationHTTPRouteContract `json:"routes"`
	ProviderStateMappings []ProviderStateMapping       `json:"provider_state_mappings"`
	TokenIssuance         []TokenIssuanceContract      `json:"token_issuance"`
	TenantBinding         []TenantBindingRule          `json:"tenant_binding"`
	ForbiddenFields       []string                     `json:"forbidden_fields"`
}

OperationContract is the real MicroVM operation, route, lifecycle mapping, token, and tenant-binding contract.

func DefaultOperationContract added in v1.15.0 

func DefaultOperationContract() OperationContract

DefaultOperationContract returns the M16 real MicroVM operation contract.

type OperationHTTPRouteContract added in v1.15.0 

type OperationHTTPRouteContract struct {
	Operation       Operation `json:"operation"`
	Method          string    `json:"method"`
	Path            string    `json:"path"`
	AuthRequired    bool      `json:"auth_required"`
	DefaultAuth     string    `json:"default_auth"`
	TenantBound     bool      `json:"tenant_bound"`
	Recovery        bool      `json:"recovery,omitempty"`
	RequestFields   []string  `json:"request_fields"`
	ResponseFields  []string  `json:"response_fields"`
	ForbiddenFields []string  `json:"forbidden_fields,omitempty"`
}

OperationHTTPRouteContract pins the canonical HTTP route for one MicroVM operation.

type Provider added in v1.15.0 

type Provider interface {
	Run(context.Context, ProviderRunInput) (ProviderSession, error)
	Get(context.Context, ProviderSessionInput) (ProviderSession, error)
	List(context.Context, ProviderListInput) (ProviderListOutput, error)
	Suspend(context.Context, ProviderSessionInput) (ProviderSession, error)
	Resume(context.Context, ProviderSessionInput) (ProviderSession, error)
	Terminate(context.Context, ProviderSessionInput) (ProviderSession, error)
	CreateAuthToken(context.Context, ProviderTokenInput) (ProviderToken, error)
	CreateShellToken(context.Context, ProviderTokenInput) (ProviderToken, error)
}

Provider is the constrained M16 real MicroVM provider surface.

It deliberately exposes only AppTheory request and response structs. Raw AWS SDK clients, credentials, provider payloads, bearer tokens, and plaintext session tokens are not part of this interface.

type ProviderIdlePolicy added in v1.15.0 

type ProviderIdlePolicy struct {
	AutoResumeEnabled        bool  `json:"auto_resume_enabled"`
	MaxIdleDurationSeconds   int32 `json:"max_idle_duration_seconds"`
	SuspendedDurationSeconds int32 `json:"suspended_duration_seconds"`
}

ProviderIdlePolicy is the safe AppTheory representation of provider idle behavior.

type ProviderListInput added in v1.15.0 

type ProviderListInput struct {
	RequestID     string                   `json:"request_id"`
	TenantID      string                   `json:"tenant_id"`
	Namespace     string                   `json:"namespace"`
	AuthContext   AuthContext              `json:"auth_context"`
	ImageRef      string                   `json:"image_ref,omitempty"`
	ImageVersion  string                   `json:"image_version,omitempty"`
	MaxResults    int32                    `json:"max_results,omitempty"`
	KnownSessions []ProviderSessionBinding `json:"known_sessions,omitempty"`
}

ProviderListInput is the safe AppTheory request for tenant-bound provider list/recovery.

KnownSessions is the safe registry-derived allowlist used by provider adapters to avoid leaking account-wide provider list results across tenants.

type ProviderListOutput added in v1.15.0 

type ProviderListOutput struct {
	Sessions       []ProviderSession `json:"sessions"`
	RecoveryCursor string            `json:"recovery_cursor,omitempty"`
}

ProviderListOutput is the sanitized tenant-bound list/recovery result.

type ProviderPortScope added in v1.15.0 

type ProviderPortScope struct {
	AllPorts  bool  `json:"all_ports,omitempty"`
	Port      int32 `json:"port,omitempty"`
	StartPort int32 `json:"start_port,omitempty"`
	EndPort   int32 `json:"end_port,omitempty"`
}

ProviderPortScope describes the allowed port scope for sanitized auth-token issuance.

type ProviderRunInput added in v1.15.0 

type ProviderRunInput struct {
	RequestID                   string              `json:"request_id"`
	TenantID                    string              `json:"tenant_id"`
	Namespace                   string              `json:"namespace"`
	SessionID                   string              `json:"session_id"`
	AuthContext                 AuthContext         `json:"auth_context"`
	ImageRef                    string              `json:"image_ref"`
	ImageVersion                string              `json:"image_version,omitempty"`
	NetworkConnectorRef         string              `json:"network_connector_ref,omitempty"`
	IngressNetworkConnectorRefs []string            `json:"ingress_network_connector_refs,omitempty"`
	EgressNetworkConnectorRefs  []string            `json:"egress_network_connector_refs,omitempty"`
	SessionSpec                 SessionSpec         `json:"session_spec,omitempty"`
	IdlePolicy                  *ProviderIdlePolicy `json:"idle_policy,omitempty"`
	MaximumDurationSeconds      int32               `json:"maximum_duration_seconds,omitempty"`
	ExecutionRoleArn            string              `json:"execution_role_arn,omitempty"`
}

ProviderRunInput is the safe AppTheory request for the real run operation.

type ProviderSession added in v1.15.0 

type ProviderSession struct {
	TenantID          string         `json:"tenant_id"`
	Namespace         string         `json:"namespace"`
	SessionID         string         `json:"session_id"`
	ProviderMicroVMID string         `json:"provider_microvm_id"`
	State             LifecycleState `json:"state"`
	ProviderState     string         `json:"provider_state"`
	ImageRef          string         `json:"image_ref,omitempty"`
	ImageVersion      string         `json:"image_version,omitempty"`
	StartedAt         time.Time      `json:"started_at,omitempty"`
	TerminatedAt      time.Time      `json:"terminated_at,omitempty"`
	RegistryVersion   int64          `json:"registry_version,omitempty"`
	Terminal          bool           `json:"terminal,omitempty"`
}

ProviderSession is the sanitized provider session shape emitted by AppTheory.

func (ProviderSession) Binding added in v1.15.0 

func (s ProviderSession) Binding() ProviderSessionBinding

Binding returns the safe provider binding for a provider session.

func (ProviderSession) Key added in v1.15.0 

func (s ProviderSession) Key() SessionKey

Key returns the tenant/namespace/session key for a provider session.

type ProviderSessionBinding added in v1.15.0 

type ProviderSessionBinding struct {
	TenantID          string `json:"tenant_id"`
	Namespace         string `json:"namespace"`
	SessionID         string `json:"session_id"`
	ProviderMicroVMID string `json:"provider_microvm_id"`
	RegistryVersion   int64  `json:"registry_version,omitempty"`
}

ProviderSessionBinding binds an AppTheory session to a provider MicroVM identifier.

func (ProviderSessionBinding) Key added in v1.15.0 

func (b ProviderSessionBinding) Key() SessionKey

Key returns the tenant/namespace/session key for a provider session binding.

type ProviderSessionInput added in v1.15.0 

type ProviderSessionInput struct {
	RequestID   string                 `json:"request_id"`
	TenantID    string                 `json:"tenant_id"`
	Namespace   string                 `json:"namespace"`
	AuthContext AuthContext            `json:"auth_context"`
	Binding     ProviderSessionBinding `json:"binding"`
}

ProviderSessionInput is the safe AppTheory request for a bound session operation.

type ProviderStateMapping added in v1.15.0 

type ProviderStateMapping struct {
	ProviderState string         `json:"provider_state"`
	State         LifecycleState `json:"state"`
	Terminal      bool           `json:"terminal"`
}

ProviderStateMapping maps a provider state into the AppTheory lifecycle contract.

func DefaultProviderStateMappings added in v1.15.0 

func DefaultProviderStateMappings() []ProviderStateMapping

DefaultProviderStateMappings returns the minimum provider state mapping required by M16.

type ProviderToken added in v1.15.0 

type ProviderToken struct {
	TenantID          string    `json:"tenant_id"`
	Namespace         string    `json:"namespace"`
	SessionID         string    `json:"session_id"`
	ProviderMicroVMID string    `json:"provider_microvm_id"`
	TokenID           string    `json:"token_id"`
	TokenType         string    `json:"token_type"`
	ExpiresAt         time.Time `json:"expires_at"`
	Scope             []string  `json:"scope"`
}

ProviderToken is the sanitized token issuance metadata AppTheory may expose.

It never contains provider auth header values, bearer tokens, or session token plaintext.

type ProviderTokenInput added in v1.15.0 

type ProviderTokenInput struct {
	RequestID        string                 `json:"request_id"`
	TenantID         string                 `json:"tenant_id"`
	Namespace        string                 `json:"namespace"`
	AuthContext      AuthContext            `json:"auth_context"`
	Binding          ProviderSessionBinding `json:"binding"`
	TTLSeconds       int32                  `json:"ttl_seconds,omitempty"`
	AllowedPortScope []ProviderPortScope    `json:"allowed_port_scope,omitempty"`
}

ProviderTokenInput is the safe AppTheory request for auth-token and shell-token operations.

type ReconstructingSessionRegistry added in v1.15.0 

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

ReconstructingSessionRegistry wraps a registry with a product-owned reconstruction hook.

func NewReconstructingSessionRegistry added in v1.15.0 

func NewReconstructingSessionRegistry(registry SessionRegistry, hook SessionReconstructionHook, opts ...SessionReconstructionOption) (*ReconstructingSessionRegistry, error)

NewReconstructingSessionRegistry creates a registry wrapper that fails closed without a hook.

func (*ReconstructingSessionRegistry) Delete added in v1.15.0 

func (r *ReconstructingSessionRegistry) Delete(ctx context.Context, key SessionKey) error

Delete delegates tenant-bound deletion to the wrapped registry.

func (*ReconstructingSessionRegistry) Get added in v1.15.0 

func (r *ReconstructingSessionRegistry) Get(ctx context.Context, key SessionKey) (SessionRecord, error)

Get returns a fresh tenant-bound record, reconstructing from product truth only when needed.

func (*ReconstructingSessionRegistry) List added in v1.15.0 

func (r *ReconstructingSessionRegistry) List(ctx context.Context, input SessionListInput) ([]SessionRecord, error)

List delegates tenant-bound listing when the wrapped registry exposes a list surface.

func (*ReconstructingSessionRegistry) Put added in v1.15.0 

func (r *ReconstructingSessionRegistry) Put(ctx context.Context, record SessionRecord) (SessionRecord, error)

Put validates and stores a reconstructed or caller-supplied session record.

type RegistryClient 

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

RegistryClient is a deterministic constrained MicroVM client backed by a durable SessionRegistry.

func NewRegistryClient 

func NewRegistryClient(registry SessionRegistry, opts ...RegistryClientOption) (*RegistryClient, error)

NewRegistryClient creates a constrained client that persists sessions through a SessionRegistry.

func (*RegistryClient) Create 

func (c *RegistryClient) Create(ctx context.Context, input CreateSessionInput) (SessionRecord, error)

Create stores a requested durable session record.

func (*RegistryClient) Session 

func (c *RegistryClient) Session(ctx context.Context, input SessionQueryInput) (SessionRecord, error)

Session returns the durable session record.

func (*RegistryClient) Start 

func (c *RegistryClient) Start(ctx context.Context, input SessionCommandInput) (SessionRecord, error)

Start marks a durable session as starting toward started.

func (*RegistryClient) Status 

func (c *RegistryClient) Status(ctx context.Context, input SessionQueryInput) (SessionStatus, error)

Status returns durable status for a session.

func (*RegistryClient) Stop 

func (c *RegistryClient) Stop(ctx context.Context, input SessionCommandInput) (SessionRecord, error)

Stop marks a durable session as stopping toward stopped.

type RegistryClientOption 

type RegistryClientOption func(*RegistryClient)

RegistryClientOption configures a registry-backed constrained client.

func WithRegistryClientTTL 

func WithRegistryClientTTL(ttl time.Duration) RegistryClientOption

WithRegistryClientTTL configures the TTL applied to newly-created durable sessions.

type SafeError 

type SafeError struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id,omitempty"`
}

SafeError is the MicroVM-safe error envelope exposed by lifecycle and controller adapters. It carries only code, message, and request_id so callers cannot leak raw provider errors, bearer tokens, AWS credentials, or lifecycle payloads through AppTheory primitives.

func (SafeError) Error 

func (e SafeError) Error() string

type SessionCommandInput 

type SessionCommandInput struct {
	RequestID    string         `json:"request_id"`
	TenantID     string         `json:"tenant_id"`
	Namespace    string         `json:"namespace"`
	SessionID    string         `json:"session_id"`
	ControllerID string         `json:"controller_id"`
	AuthSubject  string         `json:"auth_subject"`
	DesiredState LifecycleState `json:"desired_state"`
	Now          time.Time      `json:"now"`
}

SessionCommandInput is the safe client input for start/stop commands.

type SessionKey 

type SessionKey struct {
	TenantID  string `json:"tenant_id"`
	Namespace string `json:"namespace"`
	SessionID string `json:"session_id"`
}

SessionKey identifies a MicroVM session by tenant, namespace, and session_id.

type SessionListInput added in v1.15.0 

type SessionListInput struct {
	RequestID   string `json:"request_id"`
	TenantID    string `json:"tenant_id"`
	Namespace   string `json:"namespace"`
	AuthSubject string `json:"auth_subject,omitempty"`
}

SessionListInput identifies a tenant-bound registry list operation.

type SessionQueryInput 

type SessionQueryInput struct {
	RequestID   string `json:"request_id"`
	TenantID    string `json:"tenant_id"`
	Namespace   string `json:"namespace"`
	SessionID   string `json:"session_id"`
	AuthSubject string `json:"auth_subject"`
}

SessionQueryInput is the safe client input for status/session queries.

type SessionReconstructionHook added in v1.15.0 

type SessionReconstructionHook func(context.Context, SessionReconstructionRequest) (SessionRecord, error)

SessionReconstructionHook reconstructs operational MicroVM registry state from product truth.

The hook is caller-owned. AppTheory never infers unknown account-wide AWS MicroVM state and never passes raw SDK clients, credentials, provider errors, pagination tokens, or token values.

type SessionReconstructionOption added in v1.15.0 

type SessionReconstructionOption func(*ReconstructingSessionRegistry)

SessionReconstructionOption configures a reconstructing registry wrapper.

func WithSessionReconstructionClock added in v1.15.0 

func WithSessionReconstructionClock(clock Clock) SessionReconstructionOption

WithSessionReconstructionClock sets the clock used for stale-record checks.

func WithSessionReconstructionStaleAfter added in v1.15.0 

func WithSessionReconstructionStaleAfter(staleAfter time.Duration) SessionReconstructionOption

WithSessionReconstructionStaleAfter reconstructs records older than the configured observation window.

type SessionReconstructionRequest added in v1.15.0 

type SessionReconstructionRequest struct {
	RequestID   string         `json:"request_id"`
	TenantID    string         `json:"tenant_id"`
	Namespace   string         `json:"namespace"`
	SessionID   string         `json:"session_id"`
	AuthSubject string         `json:"auth_subject,omitempty"`
	Now         time.Time      `json:"now"`
	Existing    *SessionRecord `json:"existing,omitempty"`
}

SessionReconstructionRequest is the fail-closed request sent to product-owned registry truth.

type SessionRecord 

type SessionRecord struct {
	TenantID                    string                 `json:"tenant_id"`
	Namespace                   string                 `json:"namespace"`
	SessionID                   string                 `json:"session_id"`
	State                       LifecycleState         `json:"state"`
	DesiredState                LifecycleState         `json:"desired_state"`
	Endpoint                    string                 `json:"endpoint,omitempty"`
	MicroVMID                   string                 `json:"microvm_id,omitempty"`
	ProviderID                  string                 `json:"provider_id"`
	ProviderMicroVMID           string                 `json:"provider_microvm_id,omitempty"`
	ProviderState               string                 `json:"provider_state"`
	AWSLifecycleState           string                 `json:"aws_lifecycle_state"`
	ImageRef                    string                 `json:"image_ref"`
	ImageVersion                string                 `json:"image_version,omitempty"`
	NetworkConnectorRef         string                 `json:"network_connector_ref"`
	IngressNetworkConnectorRefs []string               `json:"ingress_network_connector_refs,omitempty"`
	EgressNetworkConnectorRefs  []string               `json:"egress_network_connector_refs,omitempty"`
	ControllerID                string                 `json:"controller_id"`
	CreatedAt                   time.Time              `json:"created_at"`
	UpdatedAt                   time.Time              `json:"updated_at"`
	LastObservedAt              time.Time              `json:"last_observed_at"`
	ProviderStartedAt           time.Time              `json:"provider_started_at,omitempty"`
	ProviderTerminatedAt        time.Time              `json:"provider_terminated_at,omitempty"`
	ExpiresAt                   time.Time              `json:"expires_at"`
	Generation                  int64                  `json:"generation"`
	LastAction                  Command                `json:"last_action"`
	LastCommandID               string                 `json:"last_command_id"`
	AuthSubject                 string                 `json:"auth_subject"`
	ReasonMetadata              map[string]string      `json:"reason_metadata,omitempty"`
	StatusMetadata              map[string]string      `json:"status_metadata,omitempty"`
	TokenMetadata               []SessionTokenMetadata `json:"token_metadata,omitempty"`
	Metadata                    map[string]string      `json:"metadata,omitempty"`
}

SessionRecord is the safe durable-session shape AppTheory exposes to clients and registries.

func ReconstructSessionRecord added in v1.15.0 

func ReconstructSessionRecord(ctx context.Context, request SessionReconstructionRequest, hook SessionReconstructionHook) (SessionRecord, error)

ReconstructSessionRecord invokes a product-owned hook and validates the returned operational state.

func SessionRecordFromRegistryRecord 

func SessionRecordFromRegistryRecord(record SessionRegistryRecord) (SessionRecord, error)

SessionRecordFromRegistryRecord converts a durable registry item into the safe session record shape.

func (SessionRecord) Key 

func (r SessionRecord) Key() SessionKey

Key returns the tenant/namespace/session key for a session record.

type SessionRegistry 

type SessionRegistry interface {
	Put(context.Context, SessionRecord) (SessionRecord, error)
	Get(context.Context, SessionKey) (SessionRecord, error)
	Delete(context.Context, SessionKey) error
}

SessionRegistry stores canonical durable MicroVM session records.

type SessionRegistryContract 

type SessionRegistryContract struct {
	Pattern         string   `json:"pattern"`
	TenantBinding   []string `json:"tenant_binding"`
	RequiredFields  []string `json:"required_fields"`
	StateValues     []string `json:"state_values"`
	ForbiddenFields []string `json:"forbidden_fields"`
}

SessionRegistryContract is the TableTheory-patterned session record vocabulary.

func DefaultSessionRegistryContract 

func DefaultSessionRegistryContract() SessionRegistryContract

DefaultSessionRegistryContract returns the M15 session registry vocabulary.

type SessionRegistryLister added in v1.15.0 

type SessionRegistryLister interface {
	List(context.Context, SessionListInput) ([]SessionRecord, error)
}

SessionRegistryLister is the optional tenant-bound list surface required by real controller list routes.

type SessionRegistryRecord 

type SessionRegistryRecord struct {
	PK                          string                 `theorydb:"pk,attr:pk" json:"pk"`
	SK                          string                 `theorydb:"sk,attr:sk" json:"sk"`
	TenantID                    string                 `theorydb:"attr:tenant_id" json:"tenant_id"`
	Namespace                   string                 `theorydb:"attr:namespace" json:"namespace"`
	SessionID                   string                 `theorydb:"attr:session_id" json:"session_id"`
	State                       LifecycleState         `theorydb:"attr:state" json:"state"`
	DesiredState                LifecycleState         `theorydb:"attr:desired_state" json:"desired_state"`
	Endpoint                    string                 `theorydb:"attr:endpoint,omitempty" json:"endpoint,omitempty"`
	MicroVMID                   string                 `theorydb:"attr:microvm_id,omitempty" json:"microvm_id,omitempty"`
	ProviderID                  string                 `theorydb:"attr:provider_id" json:"provider_id"`
	ProviderMicroVMID           string                 `theorydb:"attr:provider_microvm_id,omitempty" json:"provider_microvm_id,omitempty"`
	ProviderState               string                 `theorydb:"attr:provider_state" json:"provider_state"`
	AWSLifecycleState           string                 `theorydb:"attr:aws_lifecycle_state" json:"aws_lifecycle_state"`
	ImageRef                    string                 `theorydb:"attr:image_ref" json:"image_ref"`
	ImageVersion                string                 `theorydb:"attr:image_version,omitempty" json:"image_version,omitempty"`
	NetworkConnectorRef         string                 `theorydb:"attr:network_connector_ref" json:"network_connector_ref"`
	IngressNetworkConnectorRefs []string               `theorydb:"attr:ingress_network_connector_refs,omitempty" json:"ingress_network_connector_refs,omitempty"`
	EgressNetworkConnectorRefs  []string               `theorydb:"attr:egress_network_connector_refs,omitempty" json:"egress_network_connector_refs,omitempty"`
	ControllerID                string                 `theorydb:"attr:controller_id" json:"controller_id"`
	CreatedAt                   time.Time              `theorydb:"attr:created_at" json:"created_at"`
	UpdatedAt                   time.Time              `theorydb:"attr:updated_at" json:"updated_at"`
	LastObservedAt              time.Time              `theorydb:"attr:last_observed_at" json:"last_observed_at"`
	ProviderStartedAt           time.Time              `theorydb:"attr:provider_started_at,omitempty" json:"provider_started_at,omitempty"`
	ProviderTerminatedAt        time.Time              `theorydb:"attr:provider_terminated_at,omitempty" json:"provider_terminated_at,omitempty"`
	ExpiresAt                   time.Time              `theorydb:"attr:expires_at" json:"expires_at"`
	TTL                         int64                  `theorydb:"ttl,attr:ttl" json:"ttl"`
	Generation                  int64                  `theorydb:"attr:generation" json:"generation"`
	Version                     int64                  `theorydb:"version,attr:version" json:"version"`
	LastAction                  Command                `theorydb:"attr:last_action" json:"last_action"`
	LastCommandID               string                 `theorydb:"attr:last_command_id" json:"last_command_id"`
	AuthSubject                 string                 `theorydb:"attr:auth_subject" json:"auth_subject"`
	ReasonMetadata              map[string]string      `theorydb:"attr:reason_metadata,omitempty" json:"reason_metadata,omitempty"`
	StatusMetadata              map[string]string      `theorydb:"attr:status_metadata,omitempty" json:"status_metadata,omitempty"`
	TokenMetadata               []SessionTokenMetadata `theorydb:"attr:token_metadata,omitempty" json:"token_metadata,omitempty"`
	Metadata                    map[string]string      `theorydb:"attr:metadata,omitempty" json:"metadata,omitempty"`
}

SessionRegistryRecord is the canonical TableTheory/DynamoDB-shaped durable MicroVM session item.

PK and SK are derived from tenant_id/namespace/session_id. ValidateSessionRegistryRecord fails closed if those keys do not match the bound tenant/session identity or if metadata contains forbidden fields.

func SessionRecordToRegistryRecord 

func SessionRecordToRegistryRecord(record SessionRecord) (SessionRegistryRecord, error)

SessionRecordToRegistryRecord converts a safe session record into the canonical durable registry item.

func (SessionRegistryRecord) TableName 

func (SessionRegistryRecord) TableName() string

TableName returns the configured durable MicroVM session registry table name.

type SessionSpec 

type SessionSpec struct {
	Metadata map[string]string `json:"metadata,omitempty"`
}

SessionSpec is the safe session specification accepted by the controller.

type SessionStatus 

type SessionStatus struct {
	TenantID        string         `json:"tenant_id"`
	Namespace       string         `json:"namespace"`
	SessionID       string         `json:"session_id"`
	State           LifecycleState `json:"state"`
	DesiredState    LifecycleState `json:"desired_state"`
	LifecycleState  LifecycleState `json:"lifecycle_state"`
	Endpoint        string         `json:"endpoint,omitempty"`
	MicroVMID       string         `json:"microvm_id,omitempty"`
	LastAction      Command        `json:"last_action"`
	LastTransition  time.Time      `json:"last_transition"`
	RegistryVersion int64          `json:"registry_version"`
}

SessionStatus is the safe controller status response from a constrained client.

func (SessionStatus) Key 

func (s SessionStatus) Key() SessionKey

Key returns the tenant/namespace/session key for a status record.

type SessionTokenMetadata added in v1.15.0 

type SessionTokenMetadata struct {
	TokenID   string    `json:"token_id"`
	TokenType string    `json:"token_type"`
	ExpiresAt time.Time `json:"expires_at"`
	Scope     []string  `json:"scope"`
}

SessionTokenMetadata is the only token information a MicroVM registry record may persist.

It deliberately contains no plaintext token, bearer token, X-aws-proxy-auth header value, provider credential, raw SDK object, or provider pagination token.

func SessionTokenMetadataFromProviderToken added in v1.15.0 

func SessionTokenMetadataFromProviderToken(token ProviderToken) (SessionTokenMetadata, error)

SessionTokenMetadataFromProviderToken converts sanitized provider token output into registry-safe metadata.

type TableTheorySessionRegistry 

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

TableTheorySessionRegistry stores MicroVM session registry records through the blessed TableTheory DB path.

func NewTableTheorySessionRegistry 

func NewTableTheorySessionRegistry(db tablecore.DB) (*TableTheorySessionRegistry, error)

NewTableTheorySessionRegistry creates a TableTheory-backed durable MicroVM session registry.

func (*TableTheorySessionRegistry) Delete 

func (r *TableTheorySessionRegistry) Delete(ctx context.Context, key SessionKey) error

Delete removes a tenant-bound session record through TableTheory.

func (*TableTheorySessionRegistry) Get 

func (r *TableTheorySessionRegistry) Get(ctx context.Context, key SessionKey) (SessionRecord, error)

Get retrieves a tenant-bound session record through TableTheory.

func (*TableTheorySessionRegistry) List added in v1.15.0 

func (r *TableTheorySessionRegistry) List(ctx context.Context, input SessionListInput) ([]SessionRecord, error)

List retrieves tenant-bound session records through TableTheory.

func (*TableTheorySessionRegistry) Put 

func (r *TableTheorySessionRegistry) Put(ctx context.Context, record SessionRecord) (SessionRecord, error)

Put validates and upserts a session record through TableTheory.

type TenantBindingRule added in v1.15.0 

type TenantBindingRule struct {
	Operation        Operation `json:"operation"`
	RequestTenantID  string    `json:"request_tenant_id"`
	RequestNamespace string    `json:"request_namespace"`
	RecordTenantID   string    `json:"record_tenant_id"`
	RecordNamespace  string    `json:"record_namespace"`
	Recovery         bool      `json:"recovery,omitempty"`
	Allowed          bool      `json:"allowed"`
}

TenantBindingRule pins whether one MicroVM access attempt is allowed for a tenant/namespace binding.

type TokenIssuanceContract added in v1.15.0 

type TokenIssuanceContract struct {
	Operation       Operation `json:"operation"`
	ResultFields    []string  `json:"result_fields"`
	ForbiddenFields []string  `json:"forbidden_fields"`
	Sanitized       bool      `json:"sanitized"`
	TenantBound     bool      `json:"tenant_bound"`
	SessionBound    bool      `json:"session_bound"`
	MaxTTLSeconds   int       `json:"max_ttl_seconds"`
}

TokenIssuanceContract describes the only safe token issuance result shape.

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.