domainsockets

README

domainsockets

DO NOT USE! No where even close to prime time.

Documentation

Overview

Package domainsockets implements an OS level procedure calling service based on the Unix Domain Sockets IPC.

This implementation is simplistic in that it does not try to duplicate more complex communication mechansims, such as message splitting (into packets), assembly of disjointed messages, etc...

Instead a client sends an entire message across the socket and receives a response. Calls are syncronous. The client can send multiple messages simultaneously (calls are thread safe).

At this point, local security is a concern, as there is not authorization control against users on the same OS. This may be a concern depending on if the OS is shared between untrusted users or if the tmp directory is exposed to other containers instead of being container local only.

Finally, compatibility is only currently guarenteed between client and servers using the same version of code. Some of the underlying mechansims may be changed in the future. Once this is completely settled, this warning will go away.

Package domainsockets prvoides for a unix domain socket server, similar to an RPC server like Grpc except that it is intended to only connect unix processes on the same device.

Usage

Usage is fairly simple:

s, err := NewServer()
if err != nil {
  // Do something
}

s.Register(header, handler)

if err := s.Start(); err != nil {
  // Do something
}

Index

• Constants
• Variables
• func SetupDecode(r io.Reader) (string, error)
• func SetupEncode(uid string, w io.Writer) error
• type Client
  • func DialServer(uid string) (*Client, error)
  • func (c *Client) Call(ctx context.Context, call string, msg *ClientMsg) (*ServerMsg, error)
• type ClientMsg
  • func (m *ClientMsg) Decode(r io.ByteReader) error
  • func (m *ClientMsg) Encode(w io.Writer) error
• type Handler
• type Server
  • func NewServer(setupSocket string) (*Server, error)
  • func (s *Server) Close()
  • func (s *Server) Register(name string, h Handler) error
  • func (s *Server) Start()
• type ServerMsg
  • func (m *ServerMsg) Decode(r io.ByteReader) error
  • func (m *ServerMsg) Encode(w io.Writer) error

Constants

const (
	// ClientKeepAlive indicates that the client is still alive.
	ClientKeepAlive = 0

	// ClientData indicates that the client is making a request to the server.
	ClientData = 1
)

const (
	// ServerError indicates there was an error and that Data will be a string
	// message of why.
	ServerError = 0

	// ServerData indicates that the server is returning data.
	ServerData = 1
)

const (
	MiB = 1048576
)

MiB is a Mebibyte (sometimes called a Megabyte).

Variables

var (
	KeepAlive = byte(011)
	LenTotal  = 36
)

Functions

func SetupDecode

func SetupDecode(r io.Reader) (string, error)

SetupDecode decodes a setup message into a UUIDv4 identifer. This ID is the unix socket in os.TempDir that the remote side is listening on.

func SetupEncode

func SetupEncode(uid string, w io.Writer) error

SetupEncode encodes the uid (a UUIDv4 ID) into a message to be sent for setup. This ID is the socket name inside os.TempDir() that the process is listening on.

Types

type Client

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

Client provides a client to a Domain Socket server.

func DialServer

func DialServer(uid string) (*Client, error)

DialServer dials a Unix Domain Socket where a server is listening and returns a client to the server.

func (*Client) Call

func (c *Client) Call(ctx context.Context, call string, msg *ClientMsg) (*ServerMsg, error)

Call makes a call to the remote procedure "call" with arguments in "msg". It returns the server's response or error. TODO(jdoak): Signal the far side of a context cancel.

type ClientMsg

type ClientMsg struct {
	ID      uint64
	Type    uint64
	Data    []byte
	Handler string
}

ClientMsg represents the data to be sent on the wire from the client to the server.

func (*ClientMsg) Decode

func (m *ClientMsg) Decode(r io.ByteReader) error

Decodes a byte encoded message into Message.

func (*ClientMsg) Encode

func (m *ClientMsg) Encode(w io.Writer) error

Encode encodes the message in the following []byte format: [TotalSize][ID][Type][handler length][handler][data length][data]

type Handler

type Handler func(req *ClientMsg) (*ServerMsg, error)

Handler provides a function that answers a request from a client and returns a response. The ServerMsg returned must have the same ID as req.

type Server

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

Server provides a Unix Domain Socket procedure calling service.

func NewServer

func NewServer(setupSocket string) (*Server, error)

New is the constructor for Server.

func (*Server) Close

func (s *Server) Close()

Close closes all connections. This server object cannot be reused.

func (*Server) Register

func (s *Server) Register(name string, h Handler) error

Register registers a handler. This should only be called before Start(), otherwise the results are undetermined.

func (*Server) Start

func (s *Server) Start()

type ServerMsg

type ServerMsg struct {
	ID   uint64
	Type uint64
	Data []byte
}

ServerMsg represents a message returned by the message handler.

func (*ServerMsg) Decode

func (m *ServerMsg) Decode(r io.ByteReader) error

Decodes a byte encoded message into Message.

func (*ServerMsg) Encode

func (m *ServerMsg) Encode(w io.Writer) error

Encode encodes the message in the following []byte format: [TotalLen][ID][Type][data length][data]