relay

README

Relay

Relay is a small go HTTP server that knows how to run a remote command and proxy IO to this command over a TCP connection.

Getting Started

Relay communicates over TLS, you'll need to add the included certificate ca.cert.pem and trust as root in order for the client to work properly:

To add certificate to your keychain on OSX:

make cert

Overview

1. Start a container by posting to the relay service.

POST /containers
{"image":"phusion/baseimage", "command":"/bin/bash", "env": { "TERM":"x-term"}, "attach":true}

201 Created
{"attachURL":"rendezvous://rendez.empire.com:5000/<token>"}

2. The relay service will run the equivalent of the following via the docker remote api:

docker pull phusion/baseimage
docker run --name run.<token> -e TERM=x-term phusion/baseimage /bin/bash

3. Client connects to relay's tcp port

The relay service is listening on rendez.empire.com:5000, after a tls handshake with a client, it waits to receive the "token" from the client, after which it tries to attach to the docker container named the same as the token, and begins pipeing stdin,stdout,stderr over tcp to the client.

If the container has already finished running, it will send any logged output to the client, and remove the container.

Spec

Clients connect over tls.

• When the client connects, it sends a secret followed by a \r\n sequence. The secret is the session identifier.
• \0x03 and \0x1C represent SIGINT and SIGQUIT respectively. Rendezvous closes the tcp connection if these characters are received.
• Rendezvous will echo back what it receives from the connection, back to the sender.

Documentation

Index

• Variables
• func Decode(r *http.Request, v interface{}) error
• func Encode(w http.ResponseWriter, v interface{}) error
• func Error(w http.ResponseWriter, err error, status int) error
• func NewDockerManager(socket, certPath string, auth *docker.AuthConfigurations) (*dockerManager, error)
• func NewHTTPHandler(r *Relay) http.Handler
• func NewTCPHandler(r *Relay) tcp.Handler
• type Container
• type ContainerManager
• type DockerOptions
• type ErrorResource
  • func (e *ErrorResource) Error() string
• type Options
• type PostContainers
  • func (h *PostContainers) ServeHTTPContext(ctx context.Context, w http.ResponseWriter, r *http.Request) error
• type PostContainersForm
• type Relay
  • func New(options Options) *Relay
  • func (r *Relay) AttachToContainer(ctx context.Context, name string, in io.Reader, out io.Writer) error
  • func (r *Relay) CreateContainer(ctx context.Context, c *Container) error
  • func (r *Relay) GenContainerName(s string) string
  • func (r *Relay) PurgeContainer(ctx context.Context, name string) (err error)
  • func (r *Relay) RegisterContainer(name string, c *Container)
  • func (r *Relay) StartContainer(ctx context.Context, name string) error
  • func (r *Relay) UnregisterContainer(name string)
  • func (r *Relay) WaitContainer(ctx context.Context, name string) (int, error)
• type TcpOptions

Variables

var (
	// DefaultContainerNameFunc is the default implementation for generating container names.
	DefaultContainerNameFunc = func(s string) string { return fmt.Sprintf("%s.%s", s, uuid.New()) }
)

var ErrInvalidRepo = errors.New("registry: not a valid docker repo")

ErrInvalidRepo is returned by parseRepo when the repo is not a valid repo.

var RepoPattern = regexp.MustCompile(`(\S+\/)?(\S+\/\S+):(\S+)`)

RepoPattern matches strings like `quay.io/remind101/acme-inc:latest` or `remind101/acme-inc:latest`

Functions

func Decode

func Decode(r *http.Request, v interface{}) error

func Encode

func Encode(w http.ResponseWriter, v interface{}) error

func Error

func Error(w http.ResponseWriter, err error, status int) error

Error is used to respond with errors in the heroku error format, which is specified at https://devcenter.heroku.com/articles/platform-api-reference#errors

If an ErrorResource is provided as the error, and it provides a non-zero status, that will be used as the response status code.

func NewDockerManager

func NewDockerManager(socket, certPath string, auth *docker.AuthConfigurations) (*dockerManager, error)

func NewHTTPHandler

func NewHTTPHandler(r *Relay) http.Handler

func NewTCPHandler

func NewTCPHandler(r *Relay) tcp.Handler

Types

type Container

type Container struct {
	Image     string            `json:"image"`
	Name      string            `json:"name"`
	Command   string            `json:"command"`
	State     string            `json:"state"`
	Env       map[string]string `json:"env"`
	Attach    bool              `json:"attach"`
	AttachURL string            `json:"attach_url"`
}

Container represents a docker container to run.

type ContainerManager

type ContainerManager interface {
	Pull(*Container) error
	Create(*Container) error
	Attach(string, io.Reader, io.Writer) error
	Start(string) error
	Wait(string) (int, error)
	Stop(string) error
	Remove(string) error
}

ContainerManager defines an interface for managing containers.

type DockerOptions

type DockerOptions struct {
	// The default docker organization to use.
	Organization string

	// The unix socket to connect to the docker api.
	Socket string

	// Path to a certificate to use for TLS connections.
	CertPath string

	// A set of docker registry credentials.
	Auth *docker.AuthConfigurations
}

DockerOptions is a set of options to configure a docker api client.

type ErrorResource

type ErrorResource struct {
	Status  int    `json:"-"`
	ID      string `json:"id"`
	Message string `json:"message"`
	URL     string `json:"url"`
}

ErrorResource represents the error response format that we return.

func (*ErrorResource) Error

func (e *ErrorResource) Error() string

Error implements error interface.

type Options

type Options struct {
	ContainerNameFunc func(string) string
	Tcp               TcpOptions
	Docker            DockerOptions
}

Options is the main set of options to configure relay.

type PostContainers

type PostContainers struct {
	*Relay
}

func (*PostContainers) ServeHTTPContext

func (h *PostContainers) ServeHTTPContext(ctx context.Context, w http.ResponseWriter, r *http.Request) error

type PostContainersForm

type PostContainersForm struct {
	User    string            `json:"user"`
	Image   string            `json:"image"`
	Command string            `json:"command"`
	Env     map[string]string `json:"env"`
	Attach  bool              `json:"attach"`
}

type Relay

type Relay struct {
	sync.Mutex

	// The rendezvous host.
	Host string
	// contains filtered or unexported fields
}

func New

func New(options Options) *Relay

New returns a new Relay instance with sensible defaults.

func (*Relay) AttachToContainer

func (r *Relay) AttachToContainer(ctx context.Context, name string, in io.Reader, out io.Writer) error

AttachToContainer attaches IO to an existing container.

func (*Relay) CreateContainer

func (r *Relay) CreateContainer(ctx context.Context, c *Container) error

CreateContainer creates a new container instance, but doesn't start it.

func (*Relay) GenContainerName

func (r *Relay) GenContainerName(s string) string

GenContainerName generates a new container name.

func (*Relay) PurgeContainer

func (r *Relay) PurgeContainer(ctx context.Context, name string) (err error)

PurgeContainer stops, deletes and unregisters a container.

func (*Relay) RegisterContainer

func (r *Relay) RegisterContainer(name string, c *Container)

RegisterContainer registers a new container, ready to be started over a TCP session.

func (*Relay) StartContainer

func (r *Relay) StartContainer(ctx context.Context, name string) error

StartContainer starts a container. This should be called after creating and attaching to a container.

func (*Relay) UnregisterContainer

func (r *Relay) UnregisterContainer(name string)

UnregisterContainer unregisters a container.

func (*Relay) WaitContainer

func (r *Relay) WaitContainer(ctx context.Context, name string) (int, error)

WaitContainer blocks until a container has finished runnning.

type TcpOptions

type TcpOptions struct {
	// Host that the tcp server is running on.
	Host string

	// Port that the tcp server is running on.
	Port string
}

TcpOptions is a set of options to configure the tcp server.