libchan

README

libchan: like Go channels over the network

Libchan is an ultra-lightweight networking library which lets network services communicate in the same way that goroutines communicate using channels:

• Simple message passing
• Synchronization for concurrent programming
• Nesting: channels can send channels

Libchan supports the following transports out of the box:

• In-memory Go channel
• Unix socket
• Raw TCP
• TLS
• HTTP2/SPDY
• Websocket

This provides great flexibility in scaling an application by breaking it down into loosely coupled concurrent services. The same application could be composed of goroutines communicating over in-memory channels; then transition to separate unix processes, each assigned to a processor core, and communicating over high-performance IPC; then to a cluster of machines communicating over authenticated TLS sessions. All along it benefits from the concurrency model which has made Go so popular.

Not all transports have the same semantics. In-memory Go channels guarantee exactly-once delivery; TCP, TLS, and the various HTTP socket families do not guarantee delivery. Messages arrive in order but may be arbitrarily delayed or lost. There are no ordering invariants across channels.

An explicit goal of libchan is simplicity of implementation and clarity of spec. Porting it to any language should be as effortless as humanly possible.

Focused on not reinventing the wheel

Because remote libchan sessions are regular HTTP2 over TLS sessions, they can be used in combination with any standard proxy or authentication middleware. This means libchan, when configured properly, can be safely exposed on the public Internet. It can also be embedded in an existing rest API using an http1 and websocket fallback.

How is it different from RPC or REST?

Modern micro-services are not a great fit for classical RPC or REST protocols because they often rely heavily on events, bi-directional communication, stream multiplexing, and some form of data synchronization. Sometimes these services have a component which requires raw socket access, either for performance (file transfer, event firehose, database access) or simply because they have their own protocol (dns, smtp, sql, ssh, zeromq, etc). These components typically need a separate set of tools because they are outside the scope of the REST and RPC tools. If there is also a websocket or ServerEvents transport, those require yet another layer of tools.

Instead of a clunky patchwork of tools, libchan implements in a single minimalistic library all the primitives needed by modern micro-services:

• Request/response with arbitrary structured data

• Asynchronous events flowing in real-time in both directions

• Requests and responses can flow in any direction, and can be arbitrarily nested, for example to implement a self-registering worker model

• Any message serialization format can be plugged in: json, msgpack, xml, protobuf.

• Raw file descriptors can be "attached" to any message, and passed under the hood using the best method available to each transport. The Go channel transport just passes os.File pointers around. The unix socket transport uses fd passing which makes it suitable for high-performance IPC. The tcp transport uses dedicated http2 streams. And as a bonus extension, a built-in tcp gateway can be used to proxy raw network sockets without extra overhead. That means libchan services can be used as smart gateways to a sql database, ssh or file transfer service, with unified auth, discovery and tooling and without performance penalty.

Example usage

Here's an example implementing basic RPC-style request/response. We gloss over error handling to tersely demonstrate the core concepts.

On the client:

var ch libchan.Sender

// Send a message, indicate that we want a return channel to be automatically created
ret1, err := ch.Send(&libchan.Message{Data: []byte("request 1!"), Ret: libchan.RetPipe})

// Send another message on the same channel
ret2, err := ch.Send(&libchan.Message{Data: []byte("request 2!"), Ret: libchan.RetPipe})

// Wait for an answer from the first request.  Set flags to zero
// to indicate we don't want a nested return channel.
msg, err := ret1.Receive(0)

On the server:

var ch libchan.Receiver

// Wait for messages in a loop
// Set the return channel flag to indicate that we
// want to receive nested channels (if any).
// Note: we don't send a nested return channel, but we could.
for {
	msg, err := ch.Receive(libchan.Ret)
	msg.Ret.Send(&libchan.Message{Data: []byte("this is an extremely useful response")});
}

Creators

Solomon Hykes

• http://twitter.com/solomonstre
• http://github.com/shykes

Additional Implementations

Java

• https://github.com/ndeloof/jchan

Javascript / Node.js

• https://github.com/GraftJS/jschan

Copyright and license

Code and documentation copyright 2013-2014 Docker, inc. Code released under the Apache 2.0 license. Docs released under Creative commons.

Documentation

Index

• Variables
• func BufferedPipe(n int) (Receiver, Sender)
• func Copy(w Sender, r Receiver) (int, error)
• func Pipe() (Receiver, Sender)
• type Receiver
• type ReceiverFrom
• type Sender
• type SenderTo
• type Transport

Variables

var (
	// ErrIncompatibleSender is used when an object cannot support
	// SendTo for its given argument.
	ErrIncompatibleSender = errors.New("incompatible sender")
	// ErrIncompatibleReceiver is used when an object cannot support
	// ReceiveFrom for its given argument.
	ErrIncompatibleReceiver = errors.New("incompatible receiver")
)

Functions

func BufferedPipe

func BufferedPipe(n int) (Receiver, Sender)

BufferedPipe returns an inmemory buffered pipe.

func Copy

func Copy(w Sender, r Receiver) (int, error)

Copy copies from a receiver to a sender until an EOF is received. The number of copies made is returned along with any error that may have halted copying prior to an EOF.

func Pipe

func Pipe() (Receiver, Sender)

Pipe returns an inmemory Sender/Receiver pair.

Types

type Receiver

type Receiver interface {
	// Receive receives a message sent across the channel from
	// a sender on the other side of the underlying transport.
	// Receive is expected to receive the same object that was
	// sent by the Sender, any differences between the
	// receive and send type should be handled carefully.  It is
	// up to the application to determine type compatibility, if
	// the receive object is incompatible, Receiver will
	// throw an error.
	Receive(message interface{}) error
}

Receiver is a channel which can receive messages of any content including other channels and bytestreams.

type ReceiverFrom

type ReceiverFrom interface {
	// ReceiveFrom receives object from the given receiver. If the given
	// receiver is not a supported type, this function should return
	// ErrIncompatibleReceiver.
	ReceiveFrom(Receiver) (int, error)
}

ReceiverFrom defines a type which can directly receive objects from a receiver.

type Sender

type Sender interface {
	// Send sends a message across the channel to a receiver on the
	// other side of the underlying transport.
	Send(message interface{}) error

	// Close closes the channel.
	Close() error
}

Sender is a channel which sent messages of any content including other channels and bytestreams.

type SenderTo

type SenderTo interface {
	// SendTo sends object to the given sender. If the given
	// sender is not a supported type, this function should return
	// ErrIncompatibleSender.
	SendTo(Sender) (int, error)
}

SenderTo defines a type which can directly send objects from a sender.

type Transport

type Transport interface {
	// NewSendChannel creates and returns a new send channel.  The receive
	// end will get picked up on the remote end of the transport through
	// the remote calling WaitReceiveChannel.
	NewSendChannel() (Sender, error)

	// WaitReceiveChannel waits for a new channel be created by the
	// remote end of the transport calling NewSendChannel.
	WaitReceiveChannel() (Receiver, error)
}

Transport represents a connection which can multiplex channels and bytestreams.