iris

Documentation

Overview

Package iris implements the iris communication primitives on top of scribe.

Index

• Variables
• type Connection
  • func (c *Connection) Broadcast(cluster string, msg []byte) error
  • func (c *Connection) Close() error
  • func (c *Connection) Publish(topic string, msg []byte) error
  • func (c *Connection) Request(cluster string, req []byte, timeout time.Duration) ([]byte, error)
  • func (c *Connection) Subscribe(topic string, handler SubscriptionHandler) error
  • func (c *Connection) Tunnel(cluster string, timeout time.Duration) (*Tunnel, error)
  • func (c *Connection) Unregister() error
  • func (c *Connection) Unsubscribe(topic string) error
• type ConnectionHandler
• type Overlay
  • func New(overId string, key *rsa.PrivateKey) *Overlay
  • func (o *Overlay) Boot() (int, error)
  • func (o *Overlay) Connect(cluster string, handler ConnectionHandler) (*Connection, error)
  • func (o *Overlay) HandleBalance(src *big.Int, topic string, msg *proto.Message)
  • func (o *Overlay) HandleDirect(src *big.Int, msg *proto.Message)
  • func (o *Overlay) HandlePublish(src *big.Int, topic string, msg *proto.Message)
  • func (o *Overlay) Shutdown() error
• type SubscriptionHandler
• type Tunnel
  • func (t *Tunnel) Close() error
  • func (t *Tunnel) Recv(timeout time.Duration) (int, []byte, error)
  • func (t *Tunnel) Send(size int, chunk []byte) error

Variables

var ErrNotSubscribed = errors.New("not subscribed")

var ErrSubscribed = errors.New("already subscribed")

var ErrTerminating = errors.New("terminating")

Iris specific errors

var ErrTimeout = errors.New("timeout")

Types

type Connection

type Connection struct {
	// contains filtered or unexported fields
}

Connection through which to interact with other iris clients.

func (*Connection) Broadcast

func (c *Connection) Broadcast(cluster string, msg []byte) error

Broadcasts asynchronously a message to all members of an iris cluster. No guarantees are made that all nodes receive the message (best effort).

func (*Connection) Close

func (c *Connection) Close() error

Gracefully terminates the connection, all subscriptions and all tunnels.

func (*Connection) Publish

func (c *Connection) Publish(topic string, msg []byte) error

Publishes an event asynchronously to topic. No guarantees are made that all subscribers receive the message.

func (*Connection) Request

func (c *Connection) Request(cluster string, req []byte, timeout time.Duration) ([]byte, error)

Executes a synchronous request to cluster (load balanced between all active), and returns the received reply, or an error if a timeout is reached.

func (*Connection) Subscribe

func (c *Connection) Subscribe(topic string, handler SubscriptionHandler) error

Subscribes to topic, using handler as the callback for arriving events. An error is returned if subscription fails.

func (*Connection) Tunnel

func (c *Connection) Tunnel(cluster string, timeout time.Duration) (*Tunnel, error)

Opens a direct tunnel to a member of cluster, allowing pairwise-exclusive and order-guaranteed message passing between them. The method blocks until either the newly created tunnel is set up, or a timeout is reached.

func (*Connection) Unregister

func (c *Connection) Unregister() error

Closes the service aspect of the connection, but leave the client alive.

func (*Connection) Unsubscribe

func (c *Connection) Unsubscribe(topic string) error

Unsubscribes from topic, receiving no more event notifications for it.

type ConnectionHandler

type ConnectionHandler interface {
	// Handles a message broadcast to all applications of the local type.
	HandleBroadcast(msg []byte)

	// Handles the request, returning the reply that should be forwarded back to
	// the caller. If the method crashes, nothing is returned and the caller will
	// eventually time out.
	HandleRequest(req []byte, timeout time.Duration) ([]byte, error)

	// Handles the request to open a direct tunnel.
	HandleTunnel(tun *Tunnel)
}

Handler for the connection scope events: application requests, application broadcasts and tunneling requests.

type Overlay

type Overlay struct {
	// contains filtered or unexported fields
}

The overlay implementation, receiving the overlay events and processing them according to the iris protocol.

func New

func New(overId string, key *rsa.PrivateKey) *Overlay

Creates a new iris overlay.

func (*Overlay) Boot

func (o *Overlay) Boot() (int, error)

Boots the overlay, returning the number of remote peers.

func (*Overlay) Connect

func (o *Overlay) Connect(cluster string, handler ConnectionHandler) (*Connection, error)

Connects to the iris overlay. The parameters can be either both specified, in the case of a service registration, or both skipped in the case of a client connection. Others combinations will fail.

func (*Overlay) HandleBalance

func (o *Overlay) HandleBalance(src *big.Int, topic string, msg *proto.Message)

Implements proto.iris.ConnectionCallback.HandlePublish. Extracts the data from the Iris envelope and calls the appropriate handler.

func (*Overlay) HandleDirect

func (o *Overlay) HandleDirect(src *big.Int, msg *proto.Message)

Implements proto.scribe.ConnectionCallback.HandleDirect. Extracts the data from the Iris envelope and calls the appropriate handler.

func (*Overlay) HandlePublish

func (o *Overlay) HandlePublish(src *big.Int, topic string, msg *proto.Message)

Implements proto.iris.ConnectionCallback.HandlePublish. Extracts the data from the Iris envelope and calls the appropriate handler.

func (*Overlay) Shutdown

func (o *Overlay) Shutdown() error

Terminates the overlay and all lower layer network primitives.

type SubscriptionHandler

type SubscriptionHandler interface {
	// Handles an event published to the subscribed topic.
	HandleEvent(msg []byte)
}

Subscription handler receiving events from a single subscribed topic.

type Tunnel

type Tunnel struct {
	// contains filtered or unexported fields
}

Communication stream between the local app and a remote endpoint. Ordered message delivery is guaranteed.

func (*Tunnel) Close

func (t *Tunnel) Close() error

Closes the tunnel connection.

func (*Tunnel) Recv

func (t *Tunnel) Recv(timeout time.Duration) (int, []byte, error)

Retrieves a message waiting in the local queue. If none is available, the call blocks until either one arrives or a timeout is reached.

func (*Tunnel) Send

func (t *Tunnel) Send(size int, chunk []byte) error

Sends an asynchronous message to the remote pair. Not reentrant (order).