envexec

Documentation

Overview

Package envexec provides utility function to run program in restricted environments through container and cgroup.

Cmd

Cmd defines single program to run, including copyin files before exec, run the program and copy out files after exec

Single

Single defines single Cmd with Environment and Cgroup Pool

Group

Group defines multiple Cmd with Environment and Cgroup Pool, together with Pipe mapping between different Cmd

Index

• type Cmd
• type Environment
• type EnvironmentPool
• type ExecveParam
• type Group
  • func (r *Group) Run(ctx context.Context) ([]Result, error)
• type Limit
• type Pipe
• type PipeCollector
• type PipeIndex
• type Process
• type Result
• type RunnerResult
• type Single
  • func (s *Single) Run(ctx context.Context) (result Result, err error)
• type Size
• type Status
  • func (s Status) String() string
• type Usage

Types

type Cmd

type Cmd struct {
	// argument, environment
	Args []string
	Env  []string

	// fds for exec: can be nil, file.Opener, PipeCollector
	// nil: undefined, will be closed
	// *os.File: will be fd and passed to runner, file will be close after cmd starts
	// file.Opener: will be opened and passed to runner
	// PipeCollector: a pipe write end will be passed to runner and collected as a copyout file
	Files []interface{}
	TTY   bool // use pty as input / output

	// resource limits
	TimeLimit        time.Duration
	MemoryLimit      Size
	StackLimit       Size
	ExtraMemoryLimit Size
	OutputLimit      Size
	ProcLimit        uint64
	CPURateLimit     float64

	// file contents to copyin before exec
	CopyIn map[string]file.File

	// file names to copyout after exec
	CopyOut    []string
	CopyOutMax Size // file size limit

	// CopyOutDir specifies a dir to dump all /w contnet
	CopyOutDir string

	// Waiter is called after cmd starts and it should return
	// once time limit exceeded.
	// return true to as TLE and false as normal exits (context finished)
	Waiter func(context.Context, Process) bool
}

Cmd defines instruction to run a program in container environment

type Environment

type Environment interface {
	Execve(context.Context, ExecveParam) (Process, error)
	WorkDir() *os.File // WorkDir returns opened work directory, should not close after
	// Open open file at work dir with given relative path and flags
	Open(path string, flags int, perm os.FileMode) (*os.File, error)
}

Environment defines the interface to access container execution environment

type EnvironmentPool

type EnvironmentPool interface {
	Get() (Environment, error)
	Put(Environment)
}

EnvironmentPool implements pool of environments

type ExecveParam

type ExecveParam struct {
	// Args holds command line arguments
	Args []string

	// Env specifies the environment of the process
	Env []string

	// Files specifies file descriptors for the child process
	Files []uintptr

	// ExecFile specifies file descriptor for executable file using fexecve
	ExecFile uintptr

	// TTY specifies whether to use TTY
	TTY bool

	// Process Limitations
	Limit Limit
}

ExecveParam is parameters to run process inside environment

type Group

type Group struct {
	// EnvironmentPool defines pool used for runner environment
	EnvironmentPool EnvironmentPool

	// Cmd defines Cmd running in parallel in multiple environments
	Cmd []*Cmd

	// Pipes defines the potential mapping between Cmd.
	// ensure nil is used as placeholder in correspond cmd
	Pipes []*Pipe
}

Group defines the running instruction to run multiple exec in parallel restricted within cgroup

func (*Group) Run

func (r *Group) Run(ctx context.Context) ([]Result, error)

Run starts the cmd and returns exec results

type Limit

type Limit struct {
	Time   time.Duration // Time limit
	Memory Size          // Memory limit
	Proc   uint64        // Process count limit
	Stack  Size          // Stack limit
	Output Size          // Output limit
	Rate   float64       // CPU Rate limit
}

Limit defines the process running resource limits

type Pipe

type Pipe struct {
	In, Out PipeIndex
}

Pipe defines the pipe between parallel Cmd

type PipeCollector

type PipeCollector struct {
	Name      string
	SizeLimit int64
}

PipeCollector can be used in Cmd.Files paramenter

type PipeIndex

type PipeIndex struct {
	Index int
	Fd    int
}

PipeIndex defines the index of cmd and the fd of the that cmd

type Process

type Process interface {
	Done() <-chan struct{} // Done returns a channel for wait process to exit
	Result() RunnerResult  // Result is available after done is closed
	Usage() Usage          // Usage retrieves the process usage during the run time
}

Process reference to the running process group

type Result

type Result struct {
	Status Status

	ExitStatus int

	Error string // error

	Time    time.Duration
	RunTime time.Duration
	Memory  Size // byte

	// Files stores copy out files
	Files map[string]file.File
}

Result defines the running result for single Cmd

type RunnerResult

type RunnerResult = runner.Result

RunnerResult represent process finish result

type Single

type Single struct {
	// EnvironmentPool defines pool used for runner environment
	EnvironmentPool EnvironmentPool

	// Cmd defines Cmd running in parallel in multiple environments
	Cmd *Cmd
}

Single defines the running instruction to run single exec in restricted within cgroup

func (*Single) Run

func (s *Single) Run(ctx context.Context) (result Result, err error)

Run starts the cmd and returns exec results

type Size

type Size = runner.Size

Size represent data size in bytes

type Status

type Status int

Status defines run task Status return status

const (
	// not initialized status (as error)
	StatusInvalid Status = iota

	// exit normally
	StatusAccepted
	StatusWrongAnswer
	StatusPartiallyCorrect

	// exit with error
	StatusMemoryLimitExceeded // MLE
	StatusTimeLimitExceeded   // TLE
	StatusOutputLimitExceeded // OLE
	StatusFileError           // FE
	StatusNonzeroExitStatus   // NZS
	StatusSignalled           // SIG
	StatusDangerousSyscall    // DJS

	// SPJ / interactor error
	StatusJudgementFailed
	StatusInvalidInteraction // interactor signals error

	// internal error including: cgroup init failed, container failed, etc
	StatusInternalError
)

Defines run task Status result status

func (Status) String

func (s Status) String() string

type Usage

type Usage struct {
	Time   time.Duration
	Memory Size
}

Usage defines the peak process resource usage