README
¶
GoMQ
![Doc Status](https://godoc.org/github.com/zeromq/gomq?status.png)
Introduction
A pure Go implementation of the ZeroMQ Message Transport Protocol. Danger Will Robinson, Danger! This code is very young. There will be false starts, APIs will change and things will break. If you are looking to use ZeroMQ with Go in a production project, we suggest using GoCZMQ, which depends on the CZMQ C API.
Problem Statement
We want to use ZeroMQ in Go projects. While GoCZMQ provides a way to do this, dealing with C dependencies while writing Go is not fun - and we like fun.
Proposed Solution
GoMQ will be a pure Go implementation of a subset of ZMTP, wrapped with a friendly API. GoMQ will only implement ZMTP version 3.x and greater, and will not be backwards compatible with previous versions of ZMTP. The initial implementation aims to support the following ZMTP features:
- ZMQ_CLIENT / ZMQ_SERVER sockets
- ZMQ_RADAR / ZMQ_DISH sockets
- The NULL security mechanism
- The PLAIN security mechanism
- The CURVE securty mechanism
Contribution Guidelines
GoMQ adheres to the Collective Code Construction Contract. For details, see CONTRIBUTING.md. We believe that building a community is an essential component of succesful open source software, and not just a side effect. People before code!
Setting Up Your Development Environment
While the end goal of GoMQ is a pure Go implementation of ZeroMQ with no dependencies on cgo, we currently require cgo for our test suite. The friction this creates in getting started is unfortunate but we feel it's the best way to test interoperability between our implemenation and the reference implementation of the protocol. Assuming that you already have a working Go development environment ( see: The Go Programming Language: Getting Started ) you will additionally need the following libraries:
Because we are implementing ZeroMQ socket types that are not yet included in a stable release, we are developing against git master checkouts of libzmq and czmq. These build instructions were tested on Ubuntu 15.10. If someone would like to provide guides for getting started on Windows, that would be great!
Linux & OSX
Note: Each of these libraries need you to run sudo ldconfig
if you are on Linux. You can skip it if you are on OSX.
Install libsodium
wget https://download.libsodium.org/libsodium/releases/libsodium-1.0.8.tar.gz
wget https://download.libsodium.org/libsodium/releases/libsodium-1.0.8.tar.gz.sig
wget https://download.libsodium.org/jedi.gpg.asc
gpg --import jedi.gpg.asc
gpg --verify libsodium-1.0.8.tar.gz.sig libsodium-1.0.8.tar.gz
tar zxvf libsodium-1.0.8.tar.gz
cd libsodium-1.0.8
./configure; make check
sudo make install
sudo ldconfig
On OSX, verify that, the output of ls -al /usr/local/lib/libsodium.dylib
is:
lrwxr-xr-x 1 root admin 18B Feb 21 10:35 /usr/local/lib/libsodium.dylib@ -> libsodium.18.dylib
Building libzmq from master
git clone git@github.com:zeromq/libzmq.git
cd libzmq
./autogen.sh
./configure --with-libsodium
make check
sudo make install
sudo ldconfig
On OSX, verify that, the output of ls -al /usr/local/lib/libzmq.dylib
is:
lrwxr-xr-x 1 dhanush admin 29B Feb 21 15:55 /usr/local/lib/libzmq.dylib@ -> /usr/local/lib/libzmq.5.dylib
Building czmq from master
git clone git@github.com:zeromq/czmq.git
cd libzmq
./autogen.sh
./configure
make check
sudo make install
sudo ldconfig
On OSX, verify that, the output of ls -al /usr/local/lib/libczmq.dylib
is:
lrwxr-xr-x 1 root admin 15B Feb 21 15:57 /usr/local/lib/libczmq.dylib@ -> libczmq.3.dylib
Note: if for some reason libzmq or czmq do not build properly or have failing tests, don't panic! This is an excellent opportunity to get involved in the community. If you can figure out the problem on you own and fix it, send us a pull request. If you're stumped, feel free to hop on the ZeroMQ mailing list and describe the problem you're running into.
Getting Started
You should now be ready to get started. Fork gomq, clone it, and make sure the tests now work in your environment:
go test -v
=== RUN TestNewClient
--- PASS: TestNewClient (0.00s)
socket_test.go:60: server received: "HELLO"
socket_test.go:32: client received: "WORLD"
socket_test.go:70: server received: "GOODBYE"
=== RUN TestExternalServer
--- PASS: TestExternalServer (0.25s)
socket_test.go:94: client received: "WORLD"
PASS
ok github.com/zeromq/gomq 0.255s
Now you're ready. Remember: pull requests should always be simple solutions to minimal problems. If you're stuck, want to discuss ideas or just want to say hello, some of us are usually lurking in the #zeromq channel on the gophers slack.
Helpful Reference Material
Documentation
¶
Index ¶
- func BindServer(s Server, endpoint string) (net.Addr, error)
- func ConnectClient(c Client, endpoint string) error
- func ConnectDealer(d Dealer, endpoint string) error
- type Client
- type ClientSocket
- type Connection
- type Dealer
- type DealerSocket
- type ErrBadProto
- type PullSocket
- type PushSocket
- type Server
- type ServerSocket
- type Socket
- func (s *Socket) AddConnection(conn *Connection)
- func (s *Socket) Close()
- func (s *Socket) GetConnection(uuid string) (*Connection, error)
- func (s *Socket) Recv() ([]byte, error)
- func (s *Socket) RecvChannel() chan *zmtp.Message
- func (s *Socket) RecvMultipart() ([][]byte, error)
- func (s *Socket) RemoveConnection(uuid string)
- func (s *Socket) RetryInterval() time.Duration
- func (s *Socket) SecurityMechanism() zmtp.SecurityMechanism
- func (s *Socket) Send(b []byte) error
- func (s *Socket) SendMultipart(b [][]byte) error
- func (s *Socket) SocketIdentity() zmtp.SocketIdentity
- func (s *Socket) SocketType() zmtp.SocketType
- type ZeroMQSocket
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BindServer ¶
BindServer accepts a Server interface and an endpoint in the format <proto>://<address>:<port>. It then attempts to bind to the endpoint.
func ConnectClient ¶
ConnectClient accepts a Client interface and an endpoint in the format <proto>://<address>:<port>. It then attempts to connect to the endpoint and perform a ZMTP handshake.
func ConnectDealer ¶
ConnectDealer accepts a Dealer interface and an endpoint in the format <proto>://<address>:<port>. It then attempts to connect to the endpoint and perform a ZMTP handshake.
Types ¶
type Client ¶
type Client interface { ZeroMQSocket Connect(endpoint string) error }
Client is a gomq interface used for client sockets. It implements the Socket interface along with a Connect method for connecting to endpoints.
func NewClient ¶
func NewClient(mechanism zmtp.SecurityMechanism) Client
NewClient accepts a zmtp.SecurityMechanism and returns a ClientSocket as a gomq.Client interface.
type ClientSocket ¶
type ClientSocket struct {
*Socket
}
ClientSocket is a ZMQ_CLIENT socket type. See: http://rfc.zeromq.org/spec:41
func (*ClientSocket) Connect ¶
func (c *ClientSocket) Connect(endpoint string) error
Connect accepts a zeromq endpoint and connects the client socket to it. Currently the only transport supported is TCP. The endpoint string should be in the format "tcp://<address>:<port>".
type Connection ¶
type Connection struct {
// contains filtered or unexported fields
}
Connection is a gomq connection. It holds both the net.Conn transport as well as the zmtp connection information.
func NewConnection ¶
func NewConnection(netConn net.Conn, zmtpConn *zmtp.Connection) *Connection
NewConnection accepts a net.Conn, a *zmtp.Connection and returns a *gomq.Connection.
func (*Connection) Send ¶
func (c *Connection) Send(b []byte) error
Send sends a message. FIXME should use a channel.
func (*Connection) SendMultipart ¶
func (c *Connection) SendMultipart(b [][]byte) error
SendMultipart ...
type Dealer ¶
type Dealer interface { ZeroMQSocket Connect(endpoint string) error }
Dealer is a gomq interface used for dealer sockets. It implements the Socket interface along with a Connect method for connecting to endpoints.
type DealerSocket ¶
type DealerSocket struct {
*Socket
}
DealerSocket is a ZMQ_DEALER socket type. See: https://rfc.zeromq.org/spec:28
func (*DealerSocket) Connect ¶
func (d *DealerSocket) Connect(endpoint string) error
Connect accepts a zeromq endpoint and connects the dealer socket to it. Currently the only transport supported is TCP. The endpoint string should be in the format "tcp://<address>:<port>".
type ErrBadProto ¶
type ErrBadProto string
func (ErrBadProto) Error ¶
func (e ErrBadProto) Error() string
type PullSocket ¶
type PullSocket struct {
*Socket
}
PullSocket is a ZMQ_PULL socket type. See: http://rfc.zeromq.org/spec:41
func NewPull ¶
func NewPull(mechanism zmtp.SecurityMechanism) *PullSocket
NewPull accepts a zmtp.SecurityMechanism and returns a PullSocket as a gomq.Pull interface.
func (*PullSocket) Bind ¶
func (s *PullSocket) Bind(endpoint string) (net.Addr, error)
Bind accepts a zeromq endpoint and binds the push socket to it. Currently the only transport supported is TCP. The endpoint string should be in the format "tcp://<address>:<port>".
func (*PullSocket) Connect ¶
func (c *PullSocket) Connect(endpoint string) error
Connect accepts a zeromq endpoint and connects the pull socket to it. Currently the only transport supported is TCP. The endpoint string should be in the format "tcp://<address>:<port>".
type PushSocket ¶
type PushSocket struct {
*Socket
}
PushSocket is a ZMQ_PUSH socket type. See: http://rfc.zeromq.org/spec:41
func NewPush ¶
func NewPush(mechanism zmtp.SecurityMechanism) *PushSocket
NewPush accepts a zmtp.SecurityMechanism and returns a PushSocket as a gomq.Push interface.
func (*PushSocket) Bind ¶
func (s *PushSocket) Bind(endpoint string) (net.Addr, error)
Bind accepts a zeromq endpoint and binds the push socket to it. Currently the only transport supported is TCP. The endpoint string should be in the format "tcp://<address>:<port>".
func (*PushSocket) Connect ¶
func (s *PushSocket) Connect(endpoint string) error
Connect accepts a zeromq endpoint and connects the client socket to it. Currently the only transport supported is TCP. The endpoint string should be in the format "tcp://<address>:<port>".
type Server ¶
type Server interface { ZeroMQSocket Bind(endpoint string) (net.Addr, error) }
Server is a gomq interface used for server sockets. It implements the Socket interface along with a Bind method for binding to endpoints.
func NewServer ¶
func NewServer(mechanism zmtp.SecurityMechanism) Server
NewServer accepts a zmtp.SecurityMechanism and returns a ServerSocket as a gomq.Server interface.
type ServerSocket ¶
type ServerSocket struct {
*Socket
}
ServerSocket is a ZMQ_SERVER socket type. See: http://rfc.zeromq.org/spec:41
type Socket ¶
type Socket struct {
// contains filtered or unexported fields
}
Socket is the base GoMQ socket type. It should probably not be used directly. Specifically typed sockets such as ClientSocket, ServerSocket, etc embed this type.
func NewSocket ¶
func NewSocket(asServer bool, sockType zmtp.SocketType, sockID zmtp.SocketIdentity, mechanism zmtp.SecurityMechanism) *Socket
NewSocket accepts an asServer boolean, zmtp.SocketType, a socket identity and a zmtp.SecurityMechanism and returns a *Socket.
func (*Socket) AddConnection ¶
func (s *Socket) AddConnection(conn *Connection)
AddConnection adds a gomq.Connection to the socket. It is goroutine safe.
func (*Socket) Close ¶
func (s *Socket) Close()
Close closes all underlying transport connections for the socket.
func (*Socket) GetConnection ¶
func (s *Socket) GetConnection(uuid string) (*Connection, error)
GetConnection returns the connection by identity
func (*Socket) RecvChannel ¶
RecvChannel returns the Socket's receive channel used for receiving messages.
func (*Socket) RecvMultipart ¶
func (*Socket) RemoveConnection ¶
RemoveConnection accepts the uuid of a connection and removes that gomq.Connection from the socket if it exists. FIXME will bomb if uuid does not exist in map
func (*Socket) RetryInterval ¶
RetryInterval returns the retry interval used for asyncronous bind / connect.
func (*Socket) SecurityMechanism ¶
func (s *Socket) SecurityMechanism() zmtp.SecurityMechanism
SecurityMechanism returns the Socket's zmtp.SecurityMechanism.
func (*Socket) SendMultipart ¶
func (*Socket) SocketIdentity ¶
func (s *Socket) SocketIdentity() zmtp.SocketIdentity
SocketIdentity returns the Socket's zmtp.SocketIdentity.
func (*Socket) SocketType ¶
func (s *Socket) SocketType() zmtp.SocketType
SocketType returns the Socket's zmtp.SocketType.
type ZeroMQSocket ¶
type ZeroMQSocket interface { Recv() ([]byte, error) Send([]byte) error RetryInterval() time.Duration SocketType() zmtp.SocketType SocketIdentity() zmtp.SocketIdentity SecurityMechanism() zmtp.SecurityMechanism AddConnection(*Connection) RemoveConnection(string) RecvChannel() chan *zmtp.Message SendMultipart([][]byte) error RecvMultipart() ([][]byte, error) Close() }
ZeroMQSocket is the base gomq interface.