runtime

Documentation

Overview

Package runtime implements the internal execution engine that backs the public gbash API.

Index

• type Config
• type ExecutionRequest
• type ExecutionResult
• type FileSystemConfig
  • func CustomFileSystem(factory gbfs.Factory, workingDir string) FileSystemConfig
  • func HostProjectFileSystem(root string, opts HostProjectOptions) FileSystemConfig
  • func InMemoryFileSystem() FileSystemConfig
  • func MountableFileSystem(opts MountableFileSystemOptions) FileSystemConfig
  • func ReadWriteDirectoryFileSystem(root string, opts ReadWriteDirectoryOptions) FileSystemConfig
  • func SeededInMemoryFileSystem(files gbfs.InitialFiles) FileSystemConfig
• type HostProjectOptions
• type InteractiveRequest
• type InteractiveResult
• type LogCallback
• type LogEvent
• type LogKind
• type MountableFileSystemOptions
• type Option
  • func WithBaseEnv(env map[string]string) Option
  • func WithConfig(cfg *Config) Option
  • func WithFileSystem(cfg FileSystemConfig) Option
  • func WithLogger(callback LogCallback) Option
  • func WithNetworkClient(client network.Client) Option
  • func WithNetworkConfig(cfg *network.Config) Option
  • func WithPolicy(p policy.Policy) Option
  • func WithRegistry(registry commands.CommandRegistry) Option
  • func WithTracing(cfg TraceConfig) Option
• type ReadWriteDirectoryOptions
• type Runtime
  • func New(opts ...Option) (*Runtime, error)
  • func (r *Runtime) NewSession(ctx context.Context) (*Session, error)
  • func (r *Runtime) Run(ctx context.Context, req *ExecutionRequest) (*ExecutionResult, error)
• type Session
  • func (s *Session) Exec(ctx context.Context, req *ExecutionRequest) (*ExecutionResult, error)
  • func (s *Session) FileSystem() gbfs.FileSystem
  • func (s *Session) Interact(ctx context.Context, req *InteractiveRequest) (*InteractiveResult, error)
• type TraceConfig
• type TraceMode

Types

type Config

type Config struct {
	FileSystem    FileSystemConfig
	Registry      commands.CommandRegistry
	Policy        policy.Policy
	BaseEnv       map[string]string
	Network       *network.Config
	NetworkClient network.Client
	Tracing       TraceConfig
	Logger        LogCallback
}

type ExecutionRequest

type ExecutionRequest struct {
	Name            string
	Interpreter     string
	PassthroughArgs []string
	ScriptPath      string
	Script          string
	Command         []string
	Args            []string
	StartupOptions  []string
	StartupHome     string
	Env             map[string]string
	WorkDir         string
	Timeout         time.Duration
	ReplaceEnv      bool
	Interactive     bool
	Stdin           io.Reader
	Stdout          io.Writer
	Stderr          io.Writer
}

type ExecutionResult

type ExecutionResult struct {
	ExitCode        int
	ShellExited     bool
	Stdout          string
	Stderr          string
	ControlStderr   string
	FinalEnv        map[string]string
	StartedAt       time.Time
	FinishedAt      time.Time
	Duration        time.Duration
	Events          []trace.Event
	StdoutTruncated bool
	StderrTruncated bool
}

type FileSystemConfig

type FileSystemConfig struct {
	Factory    gbfs.Factory
	WorkingDir string
}

FileSystemConfig describes how a runtime session gets its sandbox filesystem and what working directory it should start in.

func CustomFileSystem

func CustomFileSystem(factory gbfs.Factory, workingDir string) FileSystemConfig

CustomFileSystem wires an arbitrary filesystem factory into the runtime.

func HostProjectFileSystem

func HostProjectFileSystem(root string, opts HostProjectOptions) FileSystemConfig

HostProjectFileSystem mounts root as a read-only project tree underneath an in-memory overlay and starts the session in that mounted directory.

func InMemoryFileSystem

func InMemoryFileSystem() FileSystemConfig

InMemoryFileSystem returns the default session filesystem setup.

func MountableFileSystem

func MountableFileSystem(opts MountableFileSystemOptions) FileSystemConfig

MountableFileSystem returns a multi-mount filesystem configuration.

func ReadWriteDirectoryFileSystem

func ReadWriteDirectoryFileSystem(root string, opts ReadWriteDirectoryOptions) FileSystemConfig

ReadWriteDirectoryFileSystem mounts root as the mutable sandbox root.

This mirrors just-bash's direct read-write host filesystem mode: sandbox paths are rooted at "/", and mutations persist back to the host directory.

func SeededInMemoryFileSystem

func SeededInMemoryFileSystem(files gbfs.InitialFiles) FileSystemConfig

SeededInMemoryFileSystem returns an in-memory filesystem preloaded with the provided files.

type HostProjectOptions

type HostProjectOptions struct {
	VirtualRoot      string
	MaxFileReadBytes int64
}

HostProjectOptions configures the high-level host-project sandbox helper.

type InteractiveRequest

type InteractiveRequest struct {
	Name           string
	Args           []string
	StartupOptions []string
	Env            map[string]string
	WorkDir        string
	ReplaceEnv     bool
	Stdin          io.Reader
	Stdout         io.Writer
	Stderr         io.Writer
}

type InteractiveResult

type InteractiveResult struct {
	ExitCode int
}

type LogCallback

type LogCallback func(context.Context, LogEvent)

type LogEvent

type LogEvent struct {
	Kind        LogKind
	SessionID   string
	ExecutionID string
	Name        string
	WorkDir     string
	ExitCode    int
	Duration    time.Duration
	Output      string
	Truncated   bool
	ShellExited bool
	Error       string
}

type LogKind

type LogKind string

const (
	LogExecStart  LogKind = "exec.start"
	LogStdout     LogKind = "stdout"
	LogStderr     LogKind = "stderr"
	LogExecFinish LogKind = "exec.finish"
	LogExecError  LogKind = "exec.error"
)

type MountableFileSystemOptions

type MountableFileSystemOptions struct {
	Base       gbfs.Factory
	Mounts     []gbfs.MountConfig
	WorkingDir string
}

MountableFileSystemOptions configures a multi-mount sandbox filesystem.

type Option

type Option func(*Config) error

Option configures a runtime before initialization.

func WithBaseEnv

func WithBaseEnv(env map[string]string) Option

func WithConfig

func WithConfig(cfg *Config) Option

WithConfig overlays non-zero values from cfg onto the runtime config.

func WithFileSystem

func WithFileSystem(cfg FileSystemConfig) Option

func WithLogger

func WithLogger(callback LogCallback) Option

func WithNetworkClient

func WithNetworkClient(client network.Client) Option

func WithNetworkConfig

func WithNetworkConfig(cfg *network.Config) Option

func WithPolicy

func WithPolicy(p policy.Policy) Option

func WithRegistry

func WithRegistry(registry commands.CommandRegistry) Option

func WithTracing

func WithTracing(cfg TraceConfig) Option

type ReadWriteDirectoryOptions

type ReadWriteDirectoryOptions struct {
	MaxFileReadBytes int64
}

ReadWriteDirectoryOptions configures a host directory mounted as the mutable sandbox root.

type Runtime

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

func New

func New(opts ...Option) (*Runtime, error)

func (*Runtime) NewSession

func (r *Runtime) NewSession(ctx context.Context) (*Session, error)

func (*Runtime) Run

func (r *Runtime) Run(ctx context.Context, req *ExecutionRequest) (*ExecutionResult, error)

type Session

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

func (*Session) Exec

func (s *Session) Exec(ctx context.Context, req *ExecutionRequest) (*ExecutionResult, error)

func (*Session) FileSystem

func (s *Session) FileSystem() gbfs.FileSystem

func (*Session) Interact

func (s *Session) Interact(ctx context.Context, req *InteractiveRequest) (*InteractiveResult, error)

type TraceConfig

type TraceConfig struct {
	Mode    TraceMode
	OnEvent func(context.Context, trace.Event)
}

type TraceMode

type TraceMode uint8

const (
	TraceOff TraceMode = iota
	TraceRedacted
	TraceRaw
)