sandbox

type AuditEvent struct {
	// Timestamp when the event occurred
	Timestamp time.Time `json:"timestamp"`

	// EventType categorizes the audit event
	EventType AuditEventType `json:"event_type"`

	// ExecutionID is the unique identifier for the sandbox execution
	ExecutionID string `json:"execution_id"`

	// Runtime is the sandbox runtime used
	Runtime sandboxv1.Runtime `json:"runtime"`

	// Command being executed (first element only for security)
	Command string `json:"command,omitempty"`

	// CommandArgs is the number of arguments (not the args themselves)
	CommandArgCount int `json:"command_arg_count,omitempty"`

	// WorkspaceDir is the workspace directory if specified
	WorkspaceDir string `json:"workspace_dir,omitempty"`

	// NetworkMode indicates the network configuration
	NetworkMode string `json:"network_mode,omitempty"`

	// FilesystemMode indicates the filesystem access mode
	FilesystemMode string `json:"filesystem_mode,omitempty"`

	// User running the sandbox (UID:GID)
	User string `json:"user,omitempty"`

	// ExitCode if the execution completed
	ExitCode *int32 `json:"exit_code,omitempty"`

	// Duration of the execution
	DurationMs int64 `json:"duration_ms,omitempty"`

	// Error message if the event represents a failure
	Error string `json:"error,omitempty"`

	// SecurityEvent indicates if this is a security-relevant event
	SecurityEvent bool `json:"security_event,omitempty"`

	// FilteredEnvVars lists environment variables that were filtered
	FilteredEnvVars []string `json:"filtered_env_vars,omitempty"`

	// PolicyDenied indicates if a policy denied the operation
	PolicyDenied bool `json:"policy_denied,omitempty"`

	// PolicyName is the name of the policy that denied the operation
	PolicyName string `json:"policy_name,omitempty"`
}

type AuditEventType string

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

type CommandSafety int

type Config struct {
	// DefaultRuntime is the preferred runtime if not specified in the request.
	DefaultRuntime sandboxv1.Runtime

	// FallbackRuntimes are tried in order if the preferred runtime is unavailable.
	FallbackRuntimes []sandboxv1.Runtime

	// DefaultMode is the filesystem mode if not specified.
	DefaultMode sandboxv1.Mode

	// DefaultNetworkMode is the network mode if not specified.
	DefaultNetworkMode sandboxv1.NetworkMode

	// DefaultLimits are applied when limits are not specified in the request.
	DefaultLimits *sandboxv1.ResourceLimits

	// DefaultImage is the container image to use if not specified.
	DefaultImage string

	// PolicyPaths are paths to policy files for sandbox evaluation.
	PolicyPaths []string
}

type ExecuteResult struct {
	// ExecutionID is the unique identifier for this execution.
	ExecutionID string

	// ExitCode is the process exit code.
	// 0 indicates success, non-zero indicates failure.
	ExitCode int32

	// Stdout is the captured standard output.
	Stdout []byte

	// Stderr is the captured standard error.
	Stderr []byte

	// Error is set if execution failed.
	Error error

	// Duration is how long the execution took.
	DurationMs int64
}

type ExecutionError struct {
	Message     string
	Code        string
	IsFatal     bool
	IsRetriable bool
}

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

type IsolatingRuntimeConfig struct {
	// Mode determines isolation strategy (snapshot, overlay, etc.)
	Mode sandboxv1.WorkspaceIsolationMode

	// OriginalPath is the host workspace path.
	OriginalPath string

	// ReviewBeforeCommit enables change review workflow.
	ReviewBeforeCommit bool

	// PreserveAfterExecution keeps the isolated workspace for debugging.
	PreserveAfterExecution bool

	// SetupTimeout limits time spent setting up isolation.
	SetupTimeout time.Duration

	// FileMask configuration for hiding sensitive files.
	FileMask *sandboxv1.FileMaskConfig
}

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

type ManagerOption func(*Manager)

type ResourceDefaults struct {
	// MemoryLimit is the default memory limit (e.g., "512m", "1g")
	MemoryLimit string

	// CPULimit is the default CPU limit (e.g., "1.0", "0.5")
	CPULimit string

	// MaxPIDs is the maximum number of processes
	MaxPIDs int32

	// MaxOpenFiles is the maximum number of open file descriptors
	MaxOpenFiles int32

	// MaxFileSizeBytes is the maximum file size that can be created
	MaxFileSizeBytes int64
}

type Runtime interface {
	// Name returns the runtime identifier (e.g., RUNTIME_DOCKER).
	Name() sandboxv1.Runtime

	// Info returns metadata about the runtime.
	// Returns availability status, version, and capabilities.
	Info(ctx context.Context) (*sandboxv1.RuntimeInfo, error)

	// Available returns true if the runtime can be used.
	// This checks if required binaries exist and services are running.
	// For example, Docker runtime checks if docker daemon is accessible.
	Available(ctx context.Context) bool

	// Version returns the runtime version string.
	// Returns empty string if version cannot be determined.
	Version(ctx context.Context) string

	// Capabilities returns what this runtime supports.
	// Used for runtime selection and feature negotiation.
	Capabilities() *sandboxv1.RuntimeCapabilities

	// Execute runs a command in the sandbox and streams events.
	//
	// The returned iterator yields events as execution proceeds:
	//   - StartedEvent: Execution has begun
	//   - OutputEvent: stdout/stderr output
	//   - CompletedEvent: Execution finished successfully
	//   - ErrorEvent: An error occurred
	//
	// Callers should iterate until the sequence is exhausted or an error occurs.
	// Context cancellation will terminate the sandbox execution.
	//
	// Example:
	//
	//	for event, err := range runtime.Execute(ctx, req) {
	//	    if err != nil {
	//	        log.Printf("execution error: %v", err)
	//	        break
	//	    }
	//	    // Handle event based on type
	//	}
	Execute(ctx context.Context, req *sandboxv1.ExecuteRequest) iter.Seq2[*sandboxv1.ExecuteEvent, error]

	// Cleanup releases resources associated with an execution.
	// Should be called after Execute completes to clean up containers, temp files, etc.
	// It is safe to call Cleanup multiple times.
	Cleanup(ctx context.Context, executionID string) error
}

type RuntimeError struct {
	Runtime     sandboxv1.Runtime
	Message     string
	Remediation string
}

type RuntimeInfoLister interface {
	RuntimeInfos(ctx context.Context, includeUnavailable bool) ([]*sandboxv1.RuntimeInfo, error)
}

type RuntimeOption func(any)

type RuntimeRegistry interface {
	// Register adds a runtime to the registry.
	Register(runtime Runtime)

	// Get returns a runtime by name, or nil if not found.
	Get(name sandboxv1.Runtime) Runtime

	// List returns all registered runtimes.
	List() []Runtime

	// Available returns runtimes that are currently usable.
	Available(ctx context.Context) []Runtime

	// Default returns the default runtime to use.
	// Returns nil if no runtimes are available.
	Default(ctx context.Context) Runtime
}