runtime

Documentation

Overview

Package runtime provide the runtime environment to execute the bblfsh drivers

The runtime is based on libcontainer allowing to the runtime run the drivers inside of a isolated lightweight container.

Index

• Variables
• func Bootstrap()
• func ContainerConfigFactory(containerID string) *configs.Config
• func NewULID() ulid.ULID
• func ParseImageName(imgName string) (types.ImageReference, error)
• func UnpackImage(src types.Image, target string) error
• func WriteImageConfig(config *ImageConfig, path string) error
• type Command
• type ConfigFactory
• type Container
• type Digest
  • func ComputeDigest(input ...string) Digest
  • func NewDigest(s string) Digest
  • func (d Digest) IsZero() bool
  • func (d Digest) String() string
• type DriverImage
  • func NewDriverImage(imageRef string) (DriverImage, error)
• type DriverImageStatus
• type ImageConfig
  • func ReadImageConfig(path string) (*ImageConfig, error)
• type Process
• type Runtime
  • func NewRuntime(path string) *Runtime
  • func (r *Runtime) Container(id string, d DriverImage, p *Process, f ConfigFactory) (Container, error)
  • func (r *Runtime) Init() error
  • func (r *Runtime) InstallDriver(d DriverImage, update bool) (*DriverImageStatus, error)
  • func (r *Runtime) ListDrivers() ([]*DriverImageStatus, error)
  • func (r *Runtime) RemoveDriver(d DriverImage) error

Variables

var (
	ErrDirtyDriverStorage = errors.NewKind("dirty driver storage")
	ErrDriverNotInstalled = errors.NewKind("driver not installed")
	ErrMalformedDriver    = errors.NewKind("malformed driver, missing manifest.toml")
)

var ErrInvalidImageName = errors.NewKind("invalid image name %q: %s")

Functions

func Bootstrap

func Bootstrap()

Bootstrap perform the init process of a container. This function should be called at the init function of the application.

Because containers are spawned in a two step process you will need a binary that will be executed as the init process for the container. In libcontainer, we use the current binary (/proc/self/exe) to be executed as the init process, and use arg "init", we call the first step process "bootstrap", so you always need a "init" function as the entry of "bootstrap".

In addition to the go init function the early stage bootstrap is handled by importing nsenter.

https://github.com/opencontainers/runc/blob/master/libcontainer/README.md

func ContainerConfigFactory

func ContainerConfigFactory(containerID string) *configs.Config

ContainerConfigFactory is the default container config factory, is returns a config.Config, with the default setup.

func NewULID

func NewULID() ulid.ULID

NewULID returns a new ULID, which is a lexically sortable UUID.

func ParseImageName

func ParseImageName(imgName string) (types.ImageReference, error)

ParseImageName converts a URL-like image name to a types.ImageReference.

func UnpackImage

func UnpackImage(src types.Image, target string) error

func WriteImageConfig

func WriteImageConfig(config *ImageConfig, path string) error

Types

type Command

type Command interface {
	// Run starts the specified command and waits for it to complete.
	Run() error
	// Start starts the specified command but does not wait for it to complete.
	// The Wait method will return the exit code and release associated
	// resources once the command exits.
	Start() error
	// Wait waits for the command to exit. It must have been started by Start.
	Wait() error
	// Stop kills the container.
	Stop() error
}

Command represents the main command of a container.

type ConfigFactory

type ConfigFactory func(containerID string) *configs.Config

type Container

type Container interface {
	// Returns the ID of the container
	ID() string
	// Returns the current status of the container.
	Status() (libcontainer.Status, error)
	// State returns the current container's state information.
	State() (*libcontainer.State, error)
	// Returns the PIDs inside this container. The PIDs are in the namespace of the calling process.
	Processes() ([]int, error)
	// Signal sends the provided signal code to the running process in the container.
	Signal(sig os.Signal) error
	// Returns the current config of the container.
	Config() configs.Config
	Command
}

Container represent a container created from a driver image.

type Digest

type Digest []byte

func ComputeDigest

func ComputeDigest(input ...string) Digest

func NewDigest

func NewDigest(s string) Digest

func (Digest) IsZero

func (d Digest) IsZero() bool

func (Digest) String

func (d Digest) String() string

type DriverImage

type DriverImage interface {
	Name() string
	Digest() (Digest, error)
	Inspect() (*types.ImageInspectInfo, error)
	WriteTo(path string) error
}

DriverImage represents a docker image of a driver

func NewDriverImage

func NewDriverImage(imageRef string) (DriverImage, error)

NewDriverImage returns a new DriverImage from an image reference. For Docker use `docker://bblfsh/rust-driver:latest`.

type DriverImageStatus

type DriverImageStatus struct {
	Reference string
	Digest    Digest
	Manifest  *manifest.Manifest
}

DriverImageStatus represents the status of an installed driver image on disk.

type ImageConfig

type ImageConfig struct {
	// ImageRef is the original image reference used to retrieve the image.
	ImageRef string `json:"image_ref"`
	v1.Image
}

ImageConfig describes some basic information about the image.

func ReadImageConfig

func ReadImageConfig(path string) (*ImageConfig, error)

type Process

type Process libcontainer.Process

Process defines the process to be executed inside of a container.

type Runtime

type Runtime struct {
	ContainerConfigFactory ConfigFactory
	Root                   string
	// contains filtered or unexported fields
}

func NewRuntime

func NewRuntime(path string) *Runtime

NewRuntime create a new runtime using as storage the given path.

func (*Runtime) Container

func (r *Runtime) Container(id string, d DriverImage, p *Process, f ConfigFactory) (Container, error)

Container returns a container for the given DriverImage and Process

func (*Runtime) Init

func (r *Runtime) Init() error

Init initialize the runtime.

func (*Runtime) InstallDriver

func (r *Runtime) InstallDriver(d DriverImage, update bool) (*DriverImageStatus, error)

InstallDriver installs a DriverImage extracting his content to the storage, only one version per image can be stored, update is required to overwrite a previous image if already exists otherwise, Install fails if an previous image already exists.

func (*Runtime) ListDrivers

func (r *Runtime) ListDrivers() ([]*DriverImageStatus, error)

ListDrivers lists all the driver images installed on the storage.

func (*Runtime) RemoveDriver

func (r *Runtime) RemoveDriver(d DriverImage) error

RemoveDriver removes a given DriverImage from the image storage.