gomq

package module
v0.0.0-...-0cfdede Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2021 License: MPL-2.0 Imports: 9 Imported by: 0

README

GoMQ Build Status Doc Status

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func BindServer 

func BindServer(s Server, endpoint string) (net.Addr, error)

BindServer accepts a Server interface and an endpoint in the format <proto>://<address>:<port>. It then attempts to bind to the endpoint.

func ConnectClient 

func ConnectClient(c Client, endpoint string) error

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 

func ConnectDealer(d Dealer, endpoint string) error

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.

func NewDealer 

func NewDealer(mechanism zmtp.SecurityMechanism, id string) Dealer

NewDealer accepts a zmtp.SecurityMechanism and an ID. It returns a DealerSocket as a gomq.Dealer interface.

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

func (*ServerSocket) Bind 

func (s *ServerSocket) Bind(endpoint string) (net.Addr, error)

Bind accepts a zeromq endpoint and binds the server socket to it. Currently the only transport supported is TCP. The endpoint string should be in the format "tcp://<address>:<port>".

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) Recv 

func (s *Socket) Recv() ([]byte, error)

Recv receives a message from the Socket's message channel and returns it.

func (*Socket) RecvChannel 

func (s *Socket) RecvChannel() chan *zmtp.Message

RecvChannel returns the Socket's receive channel used for receiving messages.

func (*Socket) RecvMultipart 

func (s *Socket) RecvMultipart() ([][]byte, error)

func (*Socket) RemoveConnection 

func (s *Socket) RemoveConnection(uuid string)

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 

func (s *Socket) RetryInterval() time.Duration

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) Send 

func (s *Socket) Send(b []byte) error

Send sends to all conn a message. FIXME should use a channel.

func (*Socket) SendMultipart 

func (s *Socket) SendMultipart(b [][]byte) error

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.

Source Files

View all Source files

Directories

Path Synopsis
internal
test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.