runtime

type ExecOpts struct {
	Cmd     []string          `json:"cmd"`
	Env     map[string]string `json:"env,omitempty"`
	WorkDir string            `json:"workdir,omitempty"`
	Timeout time.Duration     `json:"timeout,omitempty"`
	Stdin   io.Reader         `json:"-"`
}

type ExecResult struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
}

type ExecStream interface {
	// Recv returns the next message from the stream.
	// Returns io.EOF when the stream is finished.
	Recv() (ExecStreamMessage, error)
	// Close terminates the stream.
	Close() error
}

type ExecStreamMessage struct {
	Type string `json:"type"` // "stdout", "stderr", "exit"
	Data string `json:"data"`
}

type FileInfo struct {
	Name    string    `json:"name"`
	Path    string    `json:"path"`
	Size    int64     `json:"size"`
	Mode    string    `json:"mode"`
	ModTime time.Time `json:"mod_time"`
	IsDir   bool      `json:"is_dir"`
}

type PortMapping struct {
	SandboxPort int    `json:"sandbox_port"`
	HostPort    int    `json:"host_port"`
	Protocol    string `json:"protocol,omitempty"` // "tcp" (default) or "udp"
}

type Runtime interface {
	// Ping verifies connectivity to the runtime backend.
	Ping(ctx context.Context) error

	// Lifecycle
	Create(ctx context.Context, id string, cfg SandboxConfig) error
	Start(ctx context.Context, id string) error
	Stop(ctx context.Context, id string, timeout time.Duration) error
	Remove(ctx context.Context, id string) error
	Info(ctx context.Context, id string) (*SandboxInfo, error)
	List(ctx context.Context) ([]SandboxInfo, error)

	// Execution
	Exec(ctx context.Context, id string, opts ExecOpts) (*ExecResult, error)
	ExecStream(ctx context.Context, id string, opts ExecOpts) (ExecStream, error)

	// File operations
	ReadFile(ctx context.Context, id string, path string) ([]byte, error)
	WriteFile(ctx context.Context, id string, path string, content []byte) error
	ListDir(ctx context.Context, id string, path string) ([]FileInfo, error)
	MkDir(ctx context.Context, id string, path string) error
	RemoveFile(ctx context.Context, id string, path string) error

	// Snapshots
	Snapshot(ctx context.Context, id string, name string) (*SnapshotInfo, error)
	Restore(ctx context.Context, snapshotID string) (string, error)
	ListSnapshots(ctx context.Context, sandboxID string) ([]SnapshotInfo, error)
	RemoveSnapshot(ctx context.Context, snapshotID string) error

	// Stats
	Stats(ctx context.Context, id string) (*SandboxStats, error)

	// Resource management
	UpdateMemoryLimit(ctx context.Context, id string, memoryBytes int64) error
}

type S3SyncConfig struct {
	Endpoint  string     `json:"endpoint,omitempty"`
	Bucket    string     `json:"bucket"`
	Prefix    string     `json:"prefix,omitempty"`
	Region    string     `json:"region,omitempty"`
	AccessKey string     `json:"access_key,omitempty"`
	SecretKey string     `json:"secret_key,omitempty"`
	Mode      S3SyncMode `json:"mode"`
	MountPath string     `json:"mount_path,omitempty"` // FUSE: "/mnt/s3"
	SyncPath  string     `json:"sync_path,omitempty"`  // Hooks: local path to sync
}

type S3SyncMode string

type SandboxConfig struct {
	Image      string            `json:"image"`
	Env        map[string]string `json:"env,omitempty"`
	WorkDir    string            `json:"workdir,omitempty"`
	Cmd        []string          `json:"cmd,omitempty"`
	CPU        int64             `json:"cpu,omitempty"`        // NanoCPUs (1e9 = 1 core)
	Memory     int64             `json:"memory,omitempty"`     // bytes
	DiskLimit  int64             `json:"disk_limit,omitempty"` // bytes
	PidLimit   int64             `json:"pid_limit,omitempty"`
	Timeout    time.Duration     `json:"timeout,omitempty"`
	Ports      []PortMapping     `json:"ports,omitempty"`
	Labels     map[string]string `json:"labels,omitempty"`
	NetworkID  string            `json:"-"`
	ReadOnlyFS bool              `json:"readonly_fs,omitempty"`
	Storage    *StorageConfig    `json:"storage,omitempty"`
	TmpfsMap   map[string]string `json:"-"` // Computed by engine from storage config + defaults
}

type SandboxInfo struct {
	ID        string            `json:"id"`
	Name      string            `json:"name"`
	Image     string            `json:"image"`
	Status    SandboxStatus     `json:"status"`
	CreatedAt time.Time         `json:"created_at"`
	Ports     []PortMapping     `json:"ports,omitempty"`
	Labels    map[string]string `json:"labels,omitempty"`
	Pid       int               `json:"pid,omitempty"`
}

type SandboxStats struct {
	CPUPercent    float64   `json:"cpu_percent"`
	MemoryUsage   int64     `json:"memory_usage"` // bytes
	MemoryLimit   int64     `json:"memory_limit"` // bytes
	MemoryPercent float64   `json:"memory_percent"`
	NetworkRx     int64     `json:"network_rx"` // bytes
	NetworkTx     int64     `json:"network_tx"` // bytes
	DiskRead      int64     `json:"disk_read"`  // bytes
	DiskWrite     int64     `json:"disk_write"` // bytes
	PidCount      int64     `json:"pid_count"`
	Timestamp     time.Time `json:"timestamp"`
}

type SandboxStatus string

type SnapshotInfo struct {
	ID        string    `json:"id"`
	SandboxID string    `json:"sandbox_id"`
	Name      string    `json:"name"`
	ImageID   string    `json:"image_id"`
	CreatedAt time.Time `json:"created_at"`
	Size      int64     `json:"size"`
}

type StorageConfig struct {
	Volumes []VolumeMount `json:"volumes,omitempty"`
	Tmpfs   []TmpfsMount  `json:"tmpfs,omitempty"`
	S3      *S3SyncConfig `json:"s3,omitempty"`
}

type TmpfsMount struct {
	Path    string `json:"path"`
	Size    string `json:"size"`              // "256m", "1g"
	Options string `json:"options,omitempty"` // "rw,noexec,nosuid"
}

type VolumeMount struct {
	Name      string `json:"name"`
	MountPath string `json:"mount_path"`
	ReadOnly  bool   `json:"read_only,omitempty"`
}