sandbox

package
v0.1.21 Latest Latest
Warning

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

Go to latest
Published: Sep 28, 2026 License: MIT Imports: 11 Imported by: 0

README

core/sandbox

core/sandbox provides a unified code execution sandbox for AI competition and online judge workloads.

The public API is intentionally small:

runner, err := sandbox.New(sandbox.Options{
    AllowedImages: []string{"python:3.12-slim"},
})
if err != nil {
    return err
}

result, err := runner.Run(ctx, &sandbox.RunRequest{
    SubmissionID: "submission-1",
    Language:     sandbox.LanguagePython,
    Files: []sandbox.File{
        {Path: "main.py", Content: []byte(`print("ok")`)},
    },
})

Docker SDK usage is hidden in core/sandbox/internal/docker; callers must use Sandbox.Run.

Local demo:

go run ./examples/sandbox-demo

Optional local observability stack:

docker compose -f deploy/sandbox/docker-compose.yaml up -d

Jaeger UI: http://127.0.0.1:16686

Documentation

Index

Constants

View Source
const (
	MetricRunTotal     = "sandbox_run_total"
	MetricRunDuration  = "sandbox_run_duration"
	MetricTimeoutTotal = "sandbox_timeout_total"
	MetricMemoryUsage  = "sandbox_memory_usage"
	MetricCPUUsage     = "sandbox_cpu_usage"
)

Variables

View Source
var (
	ErrInvalidRequest  = errors.New("sandbox: invalid request")
	ErrImageNotAllowed = errors.New("sandbox: image not allowed")
	ErrImagePull       = errors.New("sandbox: image pull failed")
	ErrCompileFailed   = errors.New("sandbox: compile failed")
	ErrRuntimeFailed   = errors.New("sandbox: runtime failed")
	ErrTimeout         = errors.New("sandbox: timeout")
	ErrResourceLimit   = errors.New("sandbox: resource limit exceeded")
	ErrCleanup         = errors.New("sandbox: cleanup failed")
)

Functions

func WriteFiles

func WriteFiles(workspace string, files []File) error

Types

type Backend

type Backend interface {
	Run(ctx context.Context, spec *RunSpec) (*RunResult, error)
}

type File

type File struct {
	Path    string
	Content []byte
	Mode    uint32
}

type Language

type Language string
const (
	LanguagePython Language = "python"
	LanguageGo     Language = "golang"
	LanguageCPP    Language = "cpp"
)

type MetricsRecorder

type MetricsRecorder interface {
	RecordRun(ctx context.Context, result *RunResult, err error)
	RecordDuration(ctx context.Context, duration time.Duration)
	RecordTimeout(ctx context.Context)
	RecordMemoryUsage(ctx context.Context, bytes uint64)
	RecordCPUUsage(ctx context.Context, cpu float64)
}

func NoopMetrics

func NoopMetrics() MetricsRecorder

type Options

type Options struct {
	Backend           Backend
	TempDir           string
	CleanupTimeout    time.Duration
	LogLimitBytes     int64
	MaxFileBytes      int64
	MaxTotalFileSize  int64
	MaxFiles          int
	AllowedImages     []string
	DefaultPullPolicy PullPolicy
	Metrics           MetricsRecorder
}

type PrometheusMetrics

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

func NewPrometheusMetrics

func NewPrometheusMetrics(reg prometheus.Registerer) (*PrometheusMetrics, error)

func (*PrometheusMetrics) RecordCPUUsage

func (m *PrometheusMetrics) RecordCPUUsage(ctx context.Context, cpu float64)

func (*PrometheusMetrics) RecordDuration

func (m *PrometheusMetrics) RecordDuration(ctx context.Context, duration time.Duration)

func (*PrometheusMetrics) RecordMemoryUsage

func (m *PrometheusMetrics) RecordMemoryUsage(ctx context.Context, bytes uint64)

func (*PrometheusMetrics) RecordRun

func (m *PrometheusMetrics) RecordRun(ctx context.Context, result *RunResult, err error)

func (*PrometheusMetrics) RecordTimeout

func (m *PrometheusMetrics) RecordTimeout(context.Context)

type PullPolicy

type PullPolicy string
const (
	PullNever        PullPolicy = "never"
	PullIfNotPresent PullPolicy = "if-not-present"
	PullAlways       PullPolicy = "always"
)

type RegistryAuth

type RegistryAuth struct {
	ServerAddress string
	Username      string
	Password      string
	IdentityToken string
}

type RunRequest

type RunRequest struct {
	SubmissionID    string
	Language        Language
	Image           string
	Cmd             []string
	CompileCmd      []string
	RunCmd          []string
	Env             []string
	Files           []File
	Timeout         time.Duration
	CompileTimeout  time.Duration
	RunTimeout      time.Duration
	CPUNano         int64
	MemoryBytes     int64
	PidsLimit       int64
	Ulimits         []Ulimit
	WorkingDir      string
	Stdin           []byte
	NetworkDisabled *bool
	ReadonlyRootfs  *bool
	User            string
	RegistryAuth    *RegistryAuth
	PullPolicy      PullPolicy
}

func (*RunRequest) GetImage

func (r *RunRequest) GetImage() string

func (*RunRequest) GetMemoryBytes

func (r *RunRequest) GetMemoryBytes() int64

func (*RunRequest) GetSubmissionID

func (r *RunRequest) GetSubmissionID() string

func (*RunRequest) GetTimeoutSeconds

func (r *RunRequest) GetTimeoutSeconds() float64

type RunResult

type RunResult struct {
	ExitCode        int
	Stdout          []byte
	Stderr          []byte
	StdoutTruncated bool
	StderrTruncated bool
	Duration        time.Duration
	MemoryUsed      uint64
	CPUUsed         float64
	TimedOut        bool
	ContainerID     string
	Phase           string
}

func (*RunResult) GetCPUUsed

func (r *RunResult) GetCPUUsed() float64

func (*RunResult) GetContainerID

func (r *RunResult) GetContainerID() string

func (*RunResult) GetExitCode

func (r *RunResult) GetExitCode() int

func (*RunResult) GetMemoryUsed

func (r *RunResult) GetMemoryUsed() uint64

func (*RunResult) GetTimedOut

func (r *RunResult) GetTimedOut() bool

type RunSpec

type RunSpec struct {
	Request           *RunRequest
	WorkspaceDir      string
	CleanupTimeout    time.Duration
	LogLimitBytes     int64
	MaxFileBytes      int64
	MaxTotalFileSize  int64
	MaxFiles          int
	AllowedImages     []string
	DefaultPullPolicy PullPolicy
	Metrics           MetricsRecorder
}

type Sandbox

type Sandbox interface {
	Run(ctx context.Context, req *RunRequest) (*RunResult, error)
}

func New

func New(opts Options) (Sandbox, error)

func NewDocker

func NewDocker(opts Options) (Sandbox, error)

type Ulimit

type Ulimit struct {
	Name string
	Soft int64
	Hard int64
}

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

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