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 ¶
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) )
const (
DefaultNumBuffers = 10000
)
Variables ¶
This section is empty.
Functions ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
type MessageOut ¶
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 ¶
PeerId is an identifier for a waddell peer
func PeerIdFromString ¶
PeerIdFromString constructs a PeerId from the string-encoded version of a uuid.UUID.
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