direct

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Apr 3, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package direct implements DirectSandboxControl, which manages raw EC2 instances as agent execution environments. Multiple agents share one instance without isolation. This is the "D2: EC2 Lightweight Sandbox" shape from the cloud-sandbox-providers shaping doc.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInstanceNotFound indicates the sandbox ID does not correspond to a
	// known managed instance.
	ErrInstanceNotFound = errors.New("direct: instance not found")

	// ErrProcessNotFound indicates the process ID does not correspond to a
	// known launched process on the given instance.
	ErrProcessNotFound = errors.New("direct: process not found")

	// ErrInstanceNotReady indicates the instance exists but is not in a state
	// where operations can be performed (e.g., stopped, pending).
	ErrInstanceNotReady = errors.New("direct: instance not ready")

	// ErrInstanceReadyTimeout indicates the instance did not reach "running"
	// state within Config.InstanceReadyTimeout.
	ErrInstanceReadyTimeout = errors.New("direct: instance ready timeout")

	// ErrProcessReadyTimeout indicates a launched process did not pass its
	// health check within Config.ProcessReadyTimeout.
	ErrProcessReadyTimeout = errors.New("direct: process ready timeout")

	// ErrSSMUnavailable indicates the SSM agent on the instance is not
	// responding or not registered.
	ErrSSMUnavailable = errors.New("direct: ssm agent unavailable")

	// ErrSSMTimeout indicates an SSM command did not complete within the
	// allowed time.
	ErrSSMTimeout = errors.New("direct: ssm command timeout")

	// ErrProcessLaunchFailed indicates the process launch command failed
	// (e.g., binary not found, port in use, permission denied).
	ErrProcessLaunchFailed = errors.New("direct: process launch failed")

	// ErrResourcesExceedMaximum indicates the requested resources exceed the
	// largest supported instance type mapping.
	ErrResourcesExceedMaximum = errors.New("direct: resources exceed maximum supported")

	// ErrDirectClosed indicates the adapter is shutting down and cannot
	// accept new CreateSandbox calls.
	ErrDirectClosed = errors.New("direct: adapter is closed")
)

Functions

This section is empty.

Types

type Config

type Config struct {
	// AMIID is the AMI to launch instances from. Should have flexagent pre-installed.
	AMIID string

	// DefaultInstanceType is the EC2 instance type used when Resources is
	// zero-valued (e.g., "t3.medium", "m5.xlarge").
	DefaultInstanceType string

	// SubnetID is the VPC subnet for instance placement.
	SubnetID string

	// SecurityGroupIDs are the security groups to attach to instances.
	SecurityGroupIDs []string

	// InstanceProfileARN is the IAM instance profile for SSM access and
	// any AWS API calls from the instance.
	InstanceProfileARN string

	// KeyPairName is the SSH key pair for SSH fallback (optional; SSM is primary).
	KeyPairName string

	// RootVolumeSizeGB is the EBS root volume size in GiB (default 50).
	RootVolumeSizeGB int

	// RootVolumeType is the EBS volume type (default "gp3").
	RootVolumeType string

	// UserDataTemplate is a Go text/template script executed on instance boot.
	// Used to configure workspace directory, install dependencies, etc.
	UserDataTemplate string

	// Tags are applied to all resources created by this adapter. The adapter
	// always adds {"ManagedBy": "flex-agent-runtime", "adapter": "direct"}
	// in addition to any user-provided tags.
	Tags map[string]string

	// IPSelectionMode controls which IP address is used for connectivity.
	// Valid values: "public" (default), "private", "auto" (public if
	// available, else private).
	IPSelectionMode string

	// TerminateOnClose controls whether Close() terminates all managed
	// instances. When false (default), instances are left running for
	// potential recovery after restart.
	TerminateOnClose bool

	// InstanceReadyTimeout is the maximum time to wait for an instance to
	// reach "running" state and SSM registration (default 3 minutes).
	InstanceReadyTimeout time.Duration

	// ProcessReadyTimeout is the maximum time to wait for a launched process
	// to pass its health check (default 30 seconds).
	ProcessReadyTimeout time.Duration
}

Config configures the DirectSandboxControl adapter.

type DirectSandboxControl

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

DirectSandboxControl manages raw EC2 instances as agent environments. Multiple agents share one instance without isolation.

Shutdown safety: The closing flag and inflightWg WaitGroup protect against orphaned instances during Close(). CreateSandbox checks closing before starting work. Close() sets closing, then waits on inflightWg for all in-flight CreateSandbox operations to complete before cleanup.

func NewDirectSandboxControl

func NewDirectSandboxControl(provisioner instance.InstanceProvisioner, ssmClient SSMAPI, cfg Config, opts ...Option) (*DirectSandboxControl, error)

NewDirectSandboxControl creates a DirectSandboxControl with the given provisioner, SSM client, and configuration. Constructor-time recovery is fail-fast on ListInstances errors to avoid silently leaking orphaned instances.

func (*DirectSandboxControl) Capabilities

Capabilities returns the sandbox provider capabilities for the Direct adapter. Direct does not support snapshots or rollback (no ZFS). Pause is supported via EC2 stop/start, but is lossy -- all processes are killed and only EBS volumes survive.

func (*DirectSandboxControl) Close

func (d *DirectSandboxControl) Close() error

Close shuts down the adapter. It blocks until in-flight CreateSandbox calls finish. If TerminateOnClose is set, managed instances are terminated.

func (*DirectSandboxControl) CreateSandbox

CreateSandbox provisions a new EC2 instance and returns it as a sandbox.

func (*DirectSandboxControl) DestroySandbox

func (d *DirectSandboxControl) DestroySandbox(ctx context.Context, sandboxID string) error

DestroySandbox terminates the underlying EC2 instance and removes the sandbox from in-memory tracking.

func (*DirectSandboxControl) GetProcessStatus

GetProcessStatus returns the current status of a launched process.

func (*DirectSandboxControl) KillProcess

KillProcess terminates a launched process using SSM.

func (*DirectSandboxControl) LaunchProcess

LaunchProcess starts a long-running process inside an existing sandbox using SSM.

func (*DirectSandboxControl) PauseSandbox

func (d *DirectSandboxControl) PauseSandbox(ctx context.Context, sandboxID string) error

PauseSandbox stops the backing EC2 instance. This is a lossy pause: processes do not survive and are marked exited.

func (*DirectSandboxControl) Recover

func (d *DirectSandboxControl) Recover(ctx context.Context) error

Recover rebuilds in-memory instance/process state from cloud inventory.

func (*DirectSandboxControl) ResumeSandbox

func (d *DirectSandboxControl) ResumeSandbox(ctx context.Context, sandboxID string) error

ResumeSandbox starts a previously stopped EC2 instance, waits for cloud and SSM readiness, refreshes IPs, and clears process state.

type Option

type Option func(*DirectSandboxControl)

Option configures a DirectSandboxControl.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets the structured logger for the adapter.

type SSMAPI

type SSMAPI interface {
	SendCommand(ctx context.Context, input *ssm.SendCommandInput, opts ...func(*ssm.Options)) (*ssm.SendCommandOutput, error)
	GetCommandInvocation(ctx context.Context, input *ssm.GetCommandInvocationInput, opts ...func(*ssm.Options)) (*ssm.GetCommandInvocationOutput, error)
	DescribeInstanceInformation(ctx context.Context, input *ssm.DescribeInstanceInformationInput, opts ...func(*ssm.Options)) (*ssm.DescribeInstanceInformationOutput, error)
}

SSMAPI wraps the subset of SSM SDK methods used by this adapter for remote process management. This is the remaining EC2-specific piece -- instance lifecycle is provider-neutral via InstanceProvisioner. In the future, this could be abstracted behind a RemoteExec interface to support non-AWS providers.

type UserDataTemplateData

type UserDataTemplateData struct {
	// SandboxID is a placeholder ("direct:pending"). The actual sandbox ID
	// depends on the EC2 instance ID and is not known until after launch.
	// Use EC2 instance metadata if the startup script needs self-identification.
	SandboxID    string
	Labels       map[string]string // labels from the CreateSandbox request
	WorkspaceDir string            // workspace directory path (default "/workspace")
}

UserDataTemplateData provides typed fields for UserData template rendering.

Jump to

Keyboard shortcuts

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