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

• func FileToReader(f File) (io.ReadCloser, error)
• type Cmd
• type Environment
• type ExecveParam
• type File
  • func NewFileInput(p string) File
  • func NewFileOpened(f *os.File) File
  • func NewFilePipeCollector(name string, limit Size) File
  • func NewFileReader(r io.Reader, s bool) File
  • func NewFileWriter(w io.Writer, limit Size) File
• type FileInput
• type FileOpened
• type FilePipeCollector
• type FileReader
• type FileWriter
• type Group
  • func (r *Group) Run(ctx context.Context) ([]Result, error)
• type Limit
• type Pipe
• type PipeIndex
• type Process
• type ReaderTTY
• type Result
• type RunnerResult
• type Single
  • func (s *Single) Run(ctx context.Context) (result Result, err error)
• type Size
• type Status
  • func StringToStatus(s string) (Status, error)
  • func (s Status) String() string
• type Usage

Functions

func FileToReader

func FileToReader(f File) (io.ReadCloser, error)

FileToReader get a ReadCloser from underlying file

Types

type Cmd

type Cmd struct {
	Environment Environment

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

	// exec argument, environment
	Args []string
	Env  []string

	// Files for the executing command
	Files []File
	TTY   bool // use pty as input / output

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

	// 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

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

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

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 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 File

type File interface {
	// contains filtered or unexported methods
}

File defines interface of envexec files

func NewFileInput

func NewFileInput(p string) File

NewFileInput creates file input which will be opened in read-only mode

func NewFileOpened

func NewFileOpened(f *os.File) File

NewFileOpened creates file that contains already opened file and it will be closed

func NewFilePipeCollector

func NewFilePipeCollector(name string, limit Size) File

NewFilePipeCollector creates file output which will be collected through pipe

func NewFileReader

func NewFileReader(r io.Reader, s bool) File

NewFileReader creates File input which can be fully read before exec or piped into exec

func NewFileWriter

func NewFileWriter(w io.Writer, limit Size) File

NewFileWriter create File which will be piped out from exec

type FileInput

type FileInput struct {
	Path string
}

FileInput represent file input which will be opened in read-only mode

type FileOpened

type FileOpened struct {
	File *os.File
}

FileOpened represent file that is already opened

type FilePipeCollector

type FilePipeCollector struct {
	Name  string
	Limit Size
}

FilePipeCollector represent pipe output which will be collected through pipe

type FileReader

type FileReader struct {
	Reader io.Reader
	Stream bool
}

FileReader represent file input which can be fully read before exec or piped into exec

type FileWriter

type FileWriter struct {
	Writer io.Writer
	Limit  Size
}

FileWriter represent pipe output which will be piped out from exec

type Group

type Group struct {
	// 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
	StrictMemory bool          // Use stricter memory limit (e.g. rlimit)
}

Limit defines the process running resource limits

type Pipe

type Pipe struct {
	In, Out PipeIndex
}

Pipe defines the pipe between parallel Cmd

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 wait until done and returns RunnerResult
	Usage() Usage          // Usage retrieves the process usage during the run time
}

Process reference to the running process group

type ReaderTTY

type ReaderTTY interface {
	TTY(*os.File)
}

ReaderTTY will be asserts when File Reader is provided and TTY is enabled and then TTY will be called with pty file

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][]byte
}

Result defines the running result for single Cmd

type RunnerResult

type RunnerResult = runner.Result

RunnerResult represent process finish result

type Single

type Single struct {
	// 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 StringToStatus

func StringToStatus(s string) (Status, error)

Convert string to 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