Documentation
¶
Overview ¶
Package vmexec defines the provider-neutral contract for running one job in an isolated virtual machine.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BoundedSink ¶
type BoundedSink struct {
// contains filtered or unexported fields
}
BoundedSink synchronizes forwarding and rejects the chunk that would exceed a shared stdout/stderr byte limit. Since OutputSink methods intentionally do not return errors, engines inspect Err and should use cancel to stop the job.
func Bound ¶
func Bound(sink OutputSink, limit int64, cancel func()) *BoundedSink
Bound returns a synchronized, aggregate-output-limited sink.
func (*BoundedSink) BytesForwarded ¶
func (s *BoundedSink) BytesForwarded() int64
BytesForwarded returns the aggregate number of forwarded bytes.
func (*BoundedSink) Err ¶
func (s *BoundedSink) Err() error
Err returns the first output-limit error, if any.
func (*BoundedSink) Stderr ¶
func (s *BoundedSink) Stderr(chunk []byte)
func (*BoundedSink) Stdout ¶
func (s *BoundedSink) Stdout(chunk []byte)
type ContextError ¶
type ContextError struct {
Cause error
}
ContextError gives cancellation and deadline failures a stable typed form.
func NewContextError ¶
func NewContextError(err error) *ContextError
NewContextError converts a context terminal error to the vmexec typed form.
func (*ContextError) Error ¶
func (e *ContextError) Error() string
func (*ContextError) Unwrap ¶
func (e *ContextError) Unwrap() error
type DiscardSink ¶
type DiscardSink struct{}
DiscardSink ignores all output.
func (DiscardSink) Stderr ¶
func (DiscardSink) Stderr([]byte)
func (DiscardSink) Stdout ¶
func (DiscardSink) Stdout([]byte)
type Engine ¶
type Engine interface {
Run(ctx context.Context, spec RunSpec, sink OutputSink) (RunResult, error)
}
Engine runs one job. A nonzero guest exit is represented in RunResult with a nil error; errors represent infrastructure, output-limit, or context failure.
type EngineConfig ¶
type EngineConfig struct {
MaxOutputBytes int64 `json:"max_output_bytes"`
MaxConcurrentJobs int `json:"max_concurrent_jobs"`
BootTimeout time.Duration `json:"boot_timeout"`
ShutdownTimeout time.Duration `json:"shutdown_timeout"`
DurationIncludesBoot bool `json:"duration_includes_boot"`
}
EngineConfig contains the provider-neutral resource and lifecycle limits every engine must configure explicitly. There are intentionally no defaults for output, concurrency, or lifecycle timeouts.
func NewEngineConfig ¶
func NewEngineConfig() EngineConfig
NewEngineConfig constructs a config with the billing default required by the execution-plane contract. Callers must still set every other field.
func (EngineConfig) Validate ¶
func (c EngineConfig) Validate() error
Validate rejects omitted or invalid required limits.
type InfrastructureError ¶
type InfrastructureError struct {
Phase InfrastructurePhase
Err error
}
InfrastructureError indicates that the VM execution plane, rather than the guest command, failed.
func (*InfrastructureError) Error ¶
func (e *InfrastructureError) Error() string
func (*InfrastructureError) Unwrap ¶
func (e *InfrastructureError) Unwrap() error
type InfrastructurePhase ¶
type InfrastructurePhase string
InfrastructurePhase identifies the lifecycle stage that failed.
const ( PhaseBoot InfrastructurePhase = "boot" PhaseHandshake InfrastructurePhase = "handshake" PhaseTeardown InfrastructurePhase = "teardown" )
type OutputLimitError ¶
OutputLimitError indicates that output exceeded the configured aggregate stdout/stderr byte limit.
func (*OutputLimitError) Error ¶
func (e *OutputLimitError) Error() string
type OutputSink ¶
OutputSink receives arbitrary binary chunks. Implementations must not assume that chunks are line-oriented or retained after the call returns.
type ResultStatus ¶
type ResultStatus uint8
ResultStatus distinguishes a successful command from a command that ran and exited unsuccessfully. Infrastructure failures are returned as errors.
const ( ResultSucceeded ResultStatus = iota ResultGuestCommandFailed )
type RunResult ¶
type RunResult struct {
ExitCode int
Duration time.Duration
Status ResultStatus
}
RunResult is returned after the guest command and VM teardown have finished. Duration excludes teardown. Whether acquisition and boot are included is controlled by EngineConfig.DurationIncludesBoot.
func (RunResult) GuestCommandFailed ¶
GuestCommandFailed reports whether the guest ran the command and it exited unsuccessfully.
type RunSpec ¶
type RunSpec struct {
Cmd string
Args []string
Env map[string]string
Stdin io.Reader
StdinBytes []byte
WorkingDir string
User string
}
RunSpec describes one guest command. Cancellation and deadlines are supplied exclusively through the context passed to Engine.Run.
type SynchronizedSink ¶
type SynchronizedSink struct {
// contains filtered or unexported fields
}
SynchronizedSink serializes stdout and stderr forwarding to the wrapped sink.
func Synchronize ¶
func Synchronize(sink OutputSink) *SynchronizedSink
Synchronize returns a sink that forwards at most one call at a time.
func (*SynchronizedSink) Stderr ¶
func (s *SynchronizedSink) Stderr(chunk []byte)
func (*SynchronizedSink) Stdout ¶
func (s *SynchronizedSink) Stdout(chunk []byte)
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fake provides a scriptable vmexec engine for adapter and driver tests.
|
Package fake provides a scriptable vmexec engine for adapter and driver tests. |
|
Package protocol implements the versioned NDJSON protocol shared by VM hosts and the cascadia guest agent.
|
Package protocol implements the versioned NDJSON protocol shared by VM hosts and the cascadia guest agent. |