waddell

package module
v0.0.0-...-8ce2c05 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 21, 2015 License: Apache-2.0 Imports: 13 Imported by: 5

README

waddell Travis CI Status Coverage Status GoDoc

waddell provides a simple signaling TCP-based signaling service. It includes a server API for implementing a server, as well as a client API for talking to waddell servers. The server optionally supports running with TLS, using pk and cert files specified at the command-line.

To install:

go get github.com/getlantern/waddell

For docs:

godoc github.com/getlantern/waddell

Documentation

Overview

package waddell implements a low-latency signaling server that allows peers to exchange small messages (up to around 64kB) over TCP. It is named after William B. Waddell, one of the founders of the Pony Express.

Peers are identified by randomly assigned peer ids (type 4 UUIDs), which are used to address messages to the peers. For the scheme to work, peers must have some out-of-band mechanism by which they can exchange peer ids. Note that as soon as one peer contacts another via waddell, the 2nd peer will have the 1st peer's address and be able to reply using it.

Peers can obtain new ids simply by reconnecting to waddell, and depending on security requirements it may be a good idea to do so periodically.

Here is an example exchange between two peers:

peer 1 -> waddell server : connect

waddell server -> peer 1 : send newly assigned peer id

peer 2 -> waddell server : connect

waddell server -> peer 2 : send newly assigned peer id

(out of band)            : peer 1 lets peer 2 know about its id

peer 2 -> waddell server : send message to peer 1

waddell server -> peer 1 : deliver message from peer 2 (includes peer 2's id)

peer 1 -> waddell server : send message to peer 2

etc ..

Message structure on the wire (bits):

0-15    Frame Length    - waddell uses github.com/getlantern/framed to
                          frame messages. framed uses the first 16 bits of
                          the message to indicate the length of the frame
                          (Little Endian).

16-79   Address Part 1  - 64-bit integer in Little Endian byte order for
                          first half of peer id identifying recipient (on
                          messages to waddell) or sender (on messages from
                          waddell).

80-143  Address Part 2  - 64-bit integer in Little Endian byte order for
                          second half of peer id

144-159 Topic ID        - 16-bit integer in Little Endian byte order
                          identifying the topic of the communication

160+    Message Body    - whatever data the client sent

Index

Constants

View Source
const (
	PeerIdLength        = buuid.EncodedLength
	TopicIdLength       = 2
	WaddellHeaderLength = PeerIdLength + TopicIdLength
	WaddellOverhead     = framed.FrameHeaderLength + WaddellHeaderLength // bytes of overhead imposed by waddell
	MaxDataLength       = framed.MaxFrameLength - WaddellOverhead

	UnknownTopic = TopicId(0)
)
View Source
const (
	DefaultNumBuffers = 10000
)

Variables

This section is empty.

Functions

func Listen

func Listen(addr string, pkfile string, certfile string) (net.Listener, error)

Listen creates a listener at the given address. pkfile and certfile are optional. If both are specified, connections will be secured with TLS.

Types

type Client

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

Client is a client of a waddell server

func NewClient

func NewClient(cfg *ClientConfig) (*Client, error)

NewClient creates a waddell client, including establishing an initial connection to the waddell server, returning the client and the initial PeerId.

IMPORTANT - clients receive messages on topics. Users of Client are responsible for draining all topics on which the Client may receive a message, otherwise other topics will block.

Note - if the client automatically reconnects, its peer ID will change. You can obtain the new id through providing an OnId callback to the client.

Note - whether or not auto reconnecting is enabled, this method doesn't return until a connection has been established or we've failed trying.

func (*Client) Close

func (c *Client) Close() error

Close closes this client, its topics and associated resources.

WARNING - Close() closes the out topic channels. Attempts to write to these channels after they're closed will result in a panic. So, don't call Close() until you're actually 100% finished using this client.

func (*Client) CurrentId

func (c *Client) CurrentId() PeerId

CurrentId returns the current id (from most recent connection to waddell). To be notified about changes to the id, use the OnId handler.

func (*Client) In

func (c *Client) In(id TopicId) <-chan *MessageIn

In returns the (one and only) channel for receiving from the topic identified by the given id.

func (*Client) Out

func (c *Client) Out(id TopicId) chan<- *MessageOut

Out returns the (one and only) channel for writing to the topic identified by the given id.

func (*Client) SendKeepAlive

func (c *Client) SendKeepAlive() error

SendKeepAlive sends a keep alive message to the server to keep the underlying connection open.

type ClientConfig

type ClientConfig struct {
	// Dial is a function that dials the waddell server
	Dial DialFunc

	// ServerCert: PEM-encoded certificate by which to authenticate the waddell
	// server. If provided, connection to waddell is encrypted with TLS. If not,
	// connection will be made plain-text.
	ServerCert string

	// ReconnectAttempts specifies how many consecutive times to try
	// reconnecting in the event of a connection failure.
	//
	// Note - when auto reconnecting is enabled, the client will never resend
	// messages, it will simply reopen the connection.
	ReconnectAttempts int

	// OnId allows optionally registering a callback to be notified whenever a
	// PeerId is assigned to this client (i.e. on each successful connection to
	// the waddell server).
	OnId func(id PeerId)
}

type ClientMgr

type ClientMgr struct {
	// Dial is a function that dials the waddell server at the given addr.
	Dial func(addr string) (net.Conn, error)

	// ServerCert: PEM-encoded certificate by which to authenticate the waddell
	// server. If provided, connection to waddell is encrypted with TLS. If not,
	// connection will be made plain-text.
	ServerCert string

	// ReconnectAttempts specifies how many consecutive times to try
	// reconnecting in the event of a connection failure. See
	// Client.ReconnectAttempts for more information.
	ReconnectAttempts int

	// OnId allows optionally registering a callback to be notified whenever a
	// PeerId is assigned to the client connected to the indicated addr (i.e. on
	// each successful connection to the waddell server at addr).
	OnId func(addr string, id PeerId)
	// contains filtered or unexported fields
}

ClientMgr provides a mechanism for managing connections to multiple waddell servers.

func (*ClientMgr) ClientTo

func (m *ClientMgr) ClientTo(addr string) (*Client, error)

ClientTo obtains the one (and only) client to the given addr, creating a new one if necessary. This method is safe to call from multiple goroutines.

func (*ClientMgr) Close

func (m *ClientMgr) Close() []error

Close closes this ClientMgr and all managed clients.

type DialFunc

type DialFunc func() (net.Conn, error)

DialFunc is a function for dialing a waddell server.

type MessageIn

type MessageIn struct {
	From PeerId

	Body []byte
	// contains filtered or unexported fields
}

MessageIn is a message to a waddell server

type MessageOut

type MessageOut struct {
	To   PeerId
	Body [][]byte
}

MessageOut is a message to a waddell server

func Message

func Message(to PeerId, body ...[]byte) *MessageOut

Message builds a new message to the given peer with the given body.

type PeerId

type PeerId buuid.ID

PeerId is an identifier for a waddell peer

func PeerIdFromString

func PeerIdFromString(s string) (PeerId, error)

PeerIdFromString constructs a PeerId from the string-encoded version of a uuid.UUID.

func (PeerId) String

func (id PeerId) String() string

type Server

type Server struct {
	// NumBuffers: number of buffers to cache for reading and writing (balances
	// overall memory consumption against CPU usage).  Defaults to 10,000.
	NumBuffers int

	// BufferBytes: size of each buffer (this places a cap on the maxmimum
	// message size that can be transmitted).  Defaults to 65,535.
	BufferBytes int
	// contains filtered or unexported fields
}

Server is a waddell server

func (*Server) Serve

func (server *Server) Serve(listener net.Listener) error

Serve starts the waddell server using the given listener

type TopicId

type TopicId uint16

TopicId identifies a topic for messages.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL