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 CmdCopyOutFile
• type Environment
• type ExecveParam
• type File
  • func NewFileCollector(name string, limit Size, pipe bool) File
  • func NewFileInput(p string) File
  • func NewFileOpened(f *os.File) File
  • func NewFileReader(r io.Reader) File
  • func NewFileWriter(w io.Writer, limit Size) File
• type FileCollector
• type FileError
• type FileErrorType
  • func (t FileErrorType) MarshalJSON() ([]byte, error)
  • func (t FileErrorType) String() string
  • func (t *FileErrorType) UnmarshalJSON(b []byte) error
• type FileInput
• type FileOpened
• type FileReader
• type FileStreamIn
  • func NewFileStreamIn() FileStreamIn
• type FileStreamOut
  • func NewFileStreamOut() FileStreamOut
• type FileWriter
• type Group
  • func (r *Group) Run(ctx context.Context) ([]Result, error)
• type Limit
• type NewStoreFile
• type Pipe
• 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 StringToStatus(s string) (Status, error)
  • func (s Status) String() string
• type TerminalSize
• type Usage

Functions

func FileToReader

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

FileToReader get a Reader from underlying file the reader need to be closed by caller explicitly

Types

type Cmd

type Cmd struct {
	Environment Environment

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

	// symbolic link to be created before exec
	SymLinks map[string]string

	// 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
	OpenFileLimit    uint64
	CPURateLimit     uint64
	CPUSetLimit      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

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

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

	// additional memory option
	AddressSpaceLimit bool
	DataSegmentLimit  bool
}

Cmd defines instruction to run a program in container environment

type CmdCopyOutFile

type CmdCopyOutFile struct {
	Name     string // Name is the file out to copyOut
	Optional bool   // Optional ignores the file if not exists
}

CmdCopyOutFile defines the file to be copy out after cmd execution

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)
	// Make dir creates directory inside the container
	MkdirAll(path string, perm os.FileMode) error
	// Make symbolic link for a file / directory
	Symlink(oldName, newName string) 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 NewFileCollector

func NewFileCollector(name string, limit Size, pipe bool) File

NewFileCollector creates file output which will be collected through pipe

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 NewFileReader

func NewFileReader(r io.Reader) File

NewFileReader creates File input which can be fully read before exec. If pipe is required, use the FileStream to get the write end of pipe instead

func NewFileWriter

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

NewFileWriter create File which will be piped out from exec

type FileCollector

type FileCollector struct {
	Name  string
	Limit Size
	Pipe  bool
}

FileCollector represent pipe output which will be collected through pipe

type FileError

type FileError struct {
	Name    string        `json:"name"`
	Type    FileErrorType `json:"type"`
	Message string        `json:"message,omitempty"`
}

FileError defines the location, file name and the detailed message for a failed file operation

type FileErrorType

type FileErrorType int

FileErrorType defines the location that file operation fails

const (
	ErrCopyInOpenFile FileErrorType = iota
	ErrCopyInCreateDir
	ErrCopyInCreateFile
	ErrCopyInCopyContent
	ErrCopyOutOpen
	ErrCopyOutNotRegularFile
	ErrCopyOutSizeExceeded
	ErrCopyOutCreateFile
	ErrCopyOutCopyContent
	ErrCollectSizeExceeded
	ErrSymlink
)

FileError enums

func (FileErrorType) MarshalJSON

func (t FileErrorType) MarshalJSON() ([]byte, error)

MarshalJSON encodes file error into json string

func (FileErrorType) String

func (t FileErrorType) String() string

func (*FileErrorType) UnmarshalJSON

func (t *FileErrorType) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes file error from json string

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

type FileStreamIn interface {
	File
	io.WriteCloser
	SetSize(*TerminalSize) error
}

FileStreamIn represent a input streaming pipe and the streamer is able to write to the write end of the pipe after pipe created. It is the callers responsibility to close the WritePipe

func NewFileStreamIn

func NewFileStreamIn() FileStreamIn

type FileStreamOut

type FileStreamOut interface {
	File
	io.ReadCloser
}

FileStreamOut represent a out streaming pipe and the streamer is able to read to the read end of the pipe after pipe created. It is the callers responsibility to close the ReadPipe

func NewFileStreamOut

func NewFileStreamOut() FileStreamOut

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

	// NewStoreFile defines interface to create stored file
	NewStoreFile NewStoreFile
}

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         uint64        // CPU Rate limit
	OpenFile     uint64        // Number of open files
	CPUSet       string        // CPU set limit
	DataSegment  bool          // Use stricter memory limit (e.g. rlimit)
	AddressSpace bool          // rlimit address space
}

Limit defines the process running resource limits

type NewStoreFile

type NewStoreFile func() (*os.File, error)

NewStoreFile creates a new file in storage

type Pipe

type Pipe struct {
	// In, Out defines the pipe input source and output destination
	In, Out PipeIndex

	// Name defines copy out entry name if it is not empty and proxy is enabled
	Name string

	// Limit defines maximum bytes copy out from proxy and proxy will still
	// copy data after limit exceeded
	Limit Size

	// Proxy creates 2 pipe and connects them by copying data
	Proxy bool
}

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 Result

type Result struct {
	Status Status

	ExitStatus int

	Error string // error

	Time     time.Duration
	RunTime  time.Duration
	Memory   Size   // byte
	ProcPeak uint64 // maximum processes ever running

	// Files stores copy out files
	Files map[string]*os.File

	// FileError stores file errors details
	FileError []FileError
}

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

	// NewStoreFile defines interface to create stored file
	NewStoreFile NewStoreFile
}

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)

StringToStatus convert string to Status

func (Status) String

func (s Status) String() string

type TerminalSize

type TerminalSize struct {
	Rows uint16 // ws_row: Number of rows (in cells).
	Cols uint16 // ws_col: Number of columns (in cells).
	X    uint16 // ws_xpixel: Width in pixels.
	Y    uint16 // ws_ypixel: Height in pixels.
}

TerminalSize controls the size of the terminal if TTY is enabled

type Usage

type Usage struct {
	Time   time.Duration
	Memory Size
}

Usage defines the peak process resource usage