api

Documentation

Overview

Package api defines the API cc-proxy exposes to clients, processes connecting to the proxy AF_UNIX socket.

Index

• func ReadFd(c *net.UnixConn) (int, error)
• func ReadMessage(reader io.Reader, msg interface{}) error
• func WriteFd(c *net.UnixConn, fd int) error
• func WriteMessage(writer io.Writer, msg interface{}) error
• type AllocateIo
• type AllocateIoResult
• type Attach
• type Bye
• type Client
  • func NewClient(conn *net.UnixConn) *Client
  • func (client *Client) AllocateIo(nStreams int) (ioBase uint64, ioFile *os.File, err error)
  • func (client *Client) Attach(containerID string) error
  • func (client *Client) Bye(containerID string) error
  • func (client *Client) Close()
  • func (client *Client) Hello(containerID, ctlSerial, ioSerial string) error
  • func (client *Client) Hyper(hyperName string, hyperMessage interface{}) error
• type Hello
• type Hyper
• type Request
• type Response

Functions

func ReadFd

func ReadFd(c *net.UnixConn) (int, error)

ReadFd reads a fd file descriptor written with WriteFd.

func ReadMessage

func ReadMessage(reader io.Reader, msg interface{}) error

ReadMessage reads a message from reader. A message is either a Request or a Response

func WriteFd

func WriteFd(c *net.UnixConn, fd int) error

WriteFd passes the fd file descriptor through the c AF_UNIX socket using out of band data. Along with the file descriptor, WriteFd will write the single byte 'F' to the socket as stream sockets need some data to actually unblock the read at the other end.

func WriteMessage

func WriteMessage(writer io.Writer, msg interface{}) error

WriteMessage writes a message into writer. A message is either a Request for a Response

Types

type AllocateIo

type AllocateIo struct {
	NStreams int `json:"nStreams"`
}

The AllocateIo payload asks the proxy to allocate IO stream sequence numbers for use with the execcmd hyperstart command.

A stream sequence number is a globally unique number identifying a data stream between hyperstart and clients. This is used to multiplex stdin, stdout and stderr of several processes onto a single channel. Sequence numbers are associated with a process running on the VM and used by the proxy to route I/O data to and from the corresponding client.

One can allocate up to two streams with allocateIO. stdin and stdout use the same sequence number as they can be differentiated by the direction of the data. If wanting stderr as its own stream, a second sequence number needs to be allocated.

The result of an allocateIO operation is encoded as an AllocateIoResult.

{
  "id": "allocateIO",
  "data": {
    "nStreams": 2
  }
}

type AllocateIoResult

type AllocateIoResult struct {
	IoBase uint64 `json:"ioBase"`
}

AllocateIoResult is the result from a successful allocateIO.

The sequence numbers allocated are:

ioBase, ioBase + 1, ..., ioBase + nStreams - 1

Those sequence numbers should then be used by a client to populate an "execcmd" hyperstart command.

The AllocateIOResult response is followed by a file descriptor. This file descriptor is sent through the out of band data mechanism of AF_UNIX sockets along with a single byte, 'F'.

The proxy will route the I/O streams with the sequence numbers allocated by this operation between that file descriptor and hyperstart.

{
  "success": true,
  "data": {
    "ioBase": 1234
  }
}

type Attach

type Attach struct {
	ContainerID string `json:"containerId"`
}

The Attach payload can be used to associate clients to an already known VM. attach cannot be issued if a hello for this container hasn't been issued beforehand.

{
  "id": "attach",
  "data": {
    "containerId": "756535dc6e9ab9b560f84c8..."
  }
}

type Bye

type Bye struct {
	ContainerID string `json:"containerId"`
}

The Bye payload does the opposite of what hello does, indicating to the proxy it should release resources created by hello for the container identified by containerId.

{
  "id": "bye",
  "data": {
    "containerId": "756535dc6e9ab9b560f84c8..."
  }
}

type Client

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

The Client struct can be used to issue proxy API calls with a convenient high level API.

func NewClient

func NewClient(conn *net.UnixConn) *Client

NewClient creates a new client object to communicate with the proxy using the connection conn. The user should call Close() once finished with the client object to close conn.

func (*Client) AllocateIo

func (client *Client) AllocateIo(nStreams int) (ioBase uint64, ioFile *os.File, err error)

AllocateIo wraps the AllocateIo payload (see payload description for more details)

func (*Client) Attach

func (client *Client) Attach(containerID string) error

Attach wraps the Attach payload (see payload description for more details)

func (*Client) Bye

func (client *Client) Bye(containerID string) error

Bye wraps the Bye payload (see payload description for more details)

func (*Client) Close

func (client *Client) Close()

Close a client, closing the underlying AF_UNIX socket.

func (*Client) Hello

func (client *Client) Hello(containerID, ctlSerial, ioSerial string) error

Hello wraps the Hello payload (see payload description for more details)

func (*Client) Hyper

func (client *Client) Hyper(hyperName string, hyperMessage interface{}) error

Hyper wraps the Hyper payload (see payload description for more details)

type Hello

type Hello struct {
	ContainerID string `json:"containerId"`
	CtlSerial   string `json:"ctlSerial"`
	IoSerial    string `json:"ioSerial"`
}

The Hello payload is issued first after connecting to the proxy socket. It is used to let the proxy know about a new container on the system along with the paths go hyperstart's command and I/O channels (AF_UNIX sockets).

{
  "id": "hello",
  "data": {
    "containerId": "756535dc6e9ab9b560f84c8...",
    "ctlSerial": "/tmp/sh.hyper.channel.0.sock",
    "ioSerial": "/tmp/sh.hyper.channel.1.sock"
  }
}

type Hyper

type Hyper struct {
	HyperName string          `json:"hyperName"`
	Data      json.RawMessage `json:"data,omitempty"`
}

The Hyper payload will forward an hyperstart command to hyperstart.

{
  "id": "hyper",
  "data": {
    "hyperName": "startpod",
    "data": {
      "hostname": "clearlinux",
      "containers": [],
      "shareDir": "rootfs"
    }
  }
}

type Request

type Request struct {
	ID   string          `json:"id"`
	Data json.RawMessage `json:"data,omitempty"`
}

A Request is a JSON message sent from a client to the proxy. This message embed a payload identified by "id". A payload can have data associated with it. It's useful to think of Request as an RPC call with "id" as function name and "data" as arguments.

The list of possible payloads are documented in this package.

Each Request has a corresponding Response message sent back from the proxy.

type Response

type Response struct {
	Success bool                   `json:"success"`
	Error   string                 `json:"error,omitempty"`
	Data    map[string]interface{} `json:"data,omitempty"`
}

A Response is a JSON message sent back from the proxy to a client after a Request has been issued. The Response holds the result of the Request, including its success state and optional data. It's useful to think of Response as the result of an RPC call with ("success", "error") describing if the call has been successul and "data" holding the optional results.