sandbox

README

Sandbox Service

The sandbox service is responsible for spinning up Docker containers to manage a single match. The containers it creates are:

• A container for the game server which manages the game (e.g., Tron server)
• A separate container for each agent.

The server will spin up a local server, and all the agents will be configured to connect to it, and the game will kick-off.

Results curated by the sandbox service will be sent to the scoreboard service.

Running Scripts

The sandbox looks for a 'run.sh' script in the source directory for each client and server. A default is provided that will look for typical run files in each language, however this script can be overwritten by a custom one inside the source directory provided by the user. So in case the default run.sh does not meet your needs, you can provide a custom one.

Usage

$ cd server/

$ ./build.sh && ./run.sh

This will start an HTTP server listening on port 8080.

Documentation

Index

• Constants
• func ArchiveToTar(a Archive) (io.Reader, error)
• func BadClients(cli *client.Client, serverId string) ([]string, error)
• func BuildImage(cli *client.Client, path, name string) ([]byte, error)
• func ClientsConnected(cli *client.Client, serverId string) ([]string, error)
• func ContainerLogs(cli *client.Client, id string) ([]byte, error)
• func DestroySandbox(cli *client.Client, network string, containers []string) error
• func GameHistory(cli *client.Client, serverId string) ([]interface{}, error)
• func GameResult(cli *client.Client, serverId string) ([]int, error)
• func GenerateSecrets(n int) ([]string, error)
• func SetupClient(cli *client.Client, netId, serverIP, secret string, archive Archive) (string, error)
• func SetupClients(cli *client.Client, netId, serverIp string, secrets []string, ...) ([]string, error)
• func SetupNetwork(cli *client.Client) (string, error)
• func SetupServer(cli *client.Client, ids, secrets []string, archive Archive) (string, error)
• func StartClient(cli *client.Client, netId, clientId string) error
• func StartClients(cli *client.Client, netId string, clientIds []string) error
• func StartServer(cli *client.Client, netId, servId string) (string, error)
• func Wait(cli *client.Client, serverId string) error
• type Archive
  • func OpenArchive(r io.Reader) (Archive, error)
• type ArchiveFile
• type MatchRequest
  • func FromHttp(r *http.Request) (*MatchRequest, error)
• type TarArchive
  • func OpenTar(r *bytes.Reader) (*TarArchive, error)
  • func (t *TarArchive) Files() ([]*ArchiveFile, error)
• type ZipArchive
  • func OpenZip(r *bytes.Reader) (*ZipArchive, error)
  • func (z *ZipArchive) Files() ([]*ArchiveFile, error)

Constants

const (
	MimeDetectLen      = 512 // bytes
	MimeTypeZip        = "application/zip"
	MimeTypeTar        = "application/x-tar"
	MimeTypeGZip       = "application/x-gzip"
	MimeTypeRar        = "application/x-rar-compressed"
	ArchivePermissions = 0555
)

const ClientDropDir = "/botbox-client"

const ClientImageName = "botbox-sandbox-client"

const ClientSecretEnvVar = "BOTBOX_SECRET"

const ClientServerEnvVar = "BOTBOX_SERVER"

const ClientUser = "sandbox"

const ConnectLogFile = "connect.log"

const DisconnectLogFile = "disconnect.log"

const EnvListSep = " "

const ResultLogFile = "result.log"

const SecretLength = 64

const ServerDropDir = "/botbox-server"

const ServerIdsEnvVar = "BOTBOX_IDS"

const ServerImageName = "botbox-sandbox-server"

const ServerSecretEnvVar = "BOTBOX_SECRETS"

const ServerUser = "sandbox"

const SetupMemUsage = 100000 // bytes

const StateLogFile = "state.log"

Functions

func ArchiveToTar

func ArchiveToTar(a Archive) (io.Reader, error)

Convert an opened archive to a tar stream. Handy since Docker likes everything to be a Tar stream.

func BadClients

func BadClients(cli *client.Client, serverId string) ([]string, error)

Get the list of clients who committed a sin from the disconnect.log file inside the container.

func BuildImage

func BuildImage(cli *client.Client, path, name string) ([]byte, error)

Build a docker image from a Dockerfile with the given name

func ClientsConnected

func ClientsConnected(cli *client.Client, serverId string) ([]string, error)

Get the list of clients who successfully connected from the connect.log file inside the container.

func ContainerLogs

func ContainerLogs(cli *client.Client, id string) ([]byte, error)

Get container STDIN/STDOUT results

func DestroySandbox

func DestroySandbox(cli *client.Client, network string, containers []string) error

Destroy a sandbox by passing it a list of container ids and the network id. It will disconnect clients from the network, remove the containers, and then remove the network.

func GameHistory

func GameHistory(cli *client.Client, serverId string) ([]interface{}, error)

Get a list of state histories from the state.log file

func GameResult

func GameResult(cli *client.Client, serverId string) ([]int, error)

Get the results for each client from the server.

func GenerateSecrets

func GenerateSecrets(n int) ([]string, error)

Generate a list of n cryptographically secure secrets.

func SetupClient

func SetupClient(cli *client.Client, netId, serverIP, secret string, archive Archive) (string, error)

Setup a client sandbox in an isolated container. Returns the ID of the container if it was created successfully.

func SetupClients

func SetupClients(cli *client.Client, netId, serverIp string, secrets []string, archives []Archive) ([]string, error)

func SetupNetwork

func SetupNetwork(cli *client.Client) (string, error)

Setup a Docker bridge network to connect the server with the clients.

func SetupServer

func SetupServer(
	cli *client.Client,
	ids, secrets []string,
	archive Archive,
) (string, error)

Setup a server sandbox in an isolated container. Returns the ID of the container if it was created successfully.

func StartClient

func StartClient(cli *client.Client, netId, clientId string) error

Start a client container and connect it to the network.

func StartClients

func StartClients(cli *client.Client, netId string, clientIds []string) error

func StartServer

func StartServer(cli *client.Client, netId, servId string) (string, error)

Start the server container and connect it to the network. Return the IP assigned to the server on the network or an error.

func Wait

func Wait(cli *client.Client, serverId string) error

Blocks until the server container stops.

Types

type Archive

type Archive interface {
	Files() ([]*ArchiveFile, error)
}

A generic archive interface that generalizes archive file formats: .zip, .tar.gz, etc. So that they can all be interacted with identically. For the most part, Botbox doesn't care what particular archive is used, so we can abstract the implementation details away.

func OpenArchive

func OpenArchive(r io.Reader) (Archive, error)

Open an arbitrary archive. The particular type is determined using http.DetectContentType on the first 512 bytes.

type ArchiveFile

type ArchiveFile struct {
	Name   string
	Reader io.Reader
}

A file in an archive. It will have a name (which is actually a full URI with directories in the path), and a reader to the file contents.

type MatchRequest

type MatchRequest struct {
	// Passed in the 'server' property
	Server Archive
	// Passed in the 'ids' property
	Ids []string
	// Passed in the 'clients' property
	Clients []Archive
}

A request to start a match with readers to the directories for starting the match. A list of client unique Ids must be passed in the same order as a list of zip files that contain the agent scripts for each id. Each request must be a multipart-form encoded request.

func FromHttp

func FromHttp(r *http.Request) (*MatchRequest, error)

Build the request from an HTTP multipart/form POST request. The request must contain a single server .zip file and a list of client .zip files. Remember to Close() the MatchRequest when you're done with it!

type TarArchive

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

An archive built from a tar file. It is backed by the golang tar.Reader type from the standard lib.

func OpenTar

func OpenTar(r *bytes.Reader) (*TarArchive, error)

Open a tar archive.

func (*TarArchive) Files

func (t *TarArchive) Files() ([]*ArchiveFile, error)

Get a list of files in the tar archive.

type ZipArchive

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

A concrete implementation of the Archive interface for zip archives. It is backed by the golang zip.Reader struct from the standard lib.

func OpenZip

func OpenZip(r *bytes.Reader) (*ZipArchive, error)

Open a zip archive.

func (*ZipArchive) Files

func (z *ZipArchive) Files() ([]*ArchiveFile, error)

Get a list of files in the zip archive.