wire

Documentation

Overview

Package wire contains the basic wire communication infrastructure like wire message en- and decoding. The actual (de)serialization functions are found in package pkg/io.

Index

• func Encode(msg Msg, w io.Writer) error
• func RegisterDecoder(t Type, decoder func(io.Reader) (Msg, error))
• func RegisterExternalDecoder(t Type, decoder func(io.Reader) (Msg, error), name string)
• func TestMsg(t *testing.T, msg Msg)
• type Account
• type Address
  • func DecodeAddress(r stdio.Reader) (Address, error)
• type Addresses
• type AddressesWithLen
• type AuthResponseMsg
  • func (m *AuthResponseMsg) Decode(r io.Reader) (err error)
  • func (m *AuthResponseMsg) Encode(w io.Writer) error
  • func (m *AuthResponseMsg) Type() Type
• type Bus
• type Cache
  • func (c *Cache) Cache(ctx context.Context, p Predicate)
  • func (c *Cache) Flush()
  • func (c *Cache) Get(p Predicate) []*Envelope
  • func (c *Cache) Put(e *Envelope) bool
  • func (c *Cache) Size() int
• type Cacher
• type Consumer
• type Envelope
  • func (env *Envelope) Decode(r io.Reader) (err error)
  • func (env *Envelope) Encode(w io.Writer) error
• type LocalBus
  • func NewLocalBus() *LocalBus
  • func (h *LocalBus) Publish(ctx context.Context, e *Envelope) error
  • func (h *LocalBus) SubscribeClient(c Consumer, receiver Address) error
• type Msg
  • func Decode(r io.Reader) (Msg, error)
  • func NewAuthResponseMsg(_ Account) Msg
• type PingMsg
  • func NewPingMsg() *PingMsg
  • func (m *PingMsg) Decode(reader io.Reader) error
  • func (m PingMsg) Encode(writer io.Writer) error
  • func (m *PingMsg) Type() Type
• type PongMsg
  • func NewPongMsg() *PongMsg
  • func (m *PongMsg) Decode(reader io.Reader) error
  • func (m PongMsg) Encode(writer io.Writer) error
  • func (m *PongMsg) Type() Type
• type Predicate
• type Publisher
• type Receiver
  • func NewReceiver() *Receiver
  • func (r *Receiver) Next(ctx context.Context) (*Envelope, error)
  • func (r *Receiver) Put(e *Envelope)
• type Relay
  • func NewRelay() *Relay
  • func (p *Relay) Cache(ctx context.Context, predicate Predicate)
  • func (p *Relay) Close() error
  • func (p *Relay) Put(e *Envelope)
  • func (p *Relay) SetDefaultMsgHandler(handler func(*Envelope))
  • func (p *Relay) Subscribe(c Consumer, predicate Predicate) error
• type ShutdownMsg
  • func (m *ShutdownMsg) Decode(r io.Reader) error
  • func (m *ShutdownMsg) Encode(w io.Writer) error
  • func (m *ShutdownMsg) Type() Type
• type Subscriber
• type Type
  • func (t Type) String() string
  • func (t Type) Valid() bool

Functions

func Encode

func Encode(msg Msg, w io.Writer) error

Encode encodes a message into an io.Writer. It also encodes the message type whereas the Msg.Encode implementation is assumed not to write the type.

func RegisterDecoder

func RegisterDecoder(t Type, decoder func(io.Reader) (Msg, error))

RegisterDecoder sets the decoder of messages of Type `t`.

func RegisterExternalDecoder

func RegisterExternalDecoder(t Type, decoder func(io.Reader) (Msg, error), name string)

RegisterExternalDecoder sets the decoder of messages of external type `t`. This is like RegisterDecoder but for message types not part of the Perun wire protocol and thus not known natively. This can be used by users of the framework to create additional message types and send them over the same peer connection. It also comes in handy to register types for testing.

func TestMsg

func TestMsg(t *testing.T, msg Msg)

TestMsg performs generic tests on a wire.Msg object.

Types

type Account

type Account = wallet.Account

Account is a node's permanent Perun identity, which is used to establish authenticity within the Perun peer-to-peer network. For now, it is just a stub.

type Address

type Address = wallet.Address

Address is a Perun node's public Perun address, which is used as a permanent identity within the Perun peer-to-peer network. For now, it is just a stub.

func DecodeAddress

func DecodeAddress(r stdio.Reader) (Address, error)

DecodeAddress decodes a peer address.

type Addresses

type Addresses = wallet.Addresses

Addresses is a helper type for encoding and decoding address slices in situations where the length of the slice is known.

type AddressesWithLen

type AddressesWithLen = wallet.AddressesWithLen

AddressesWithLen is a helper type for encoding and decoding address slices of unknown length.

type AuthResponseMsg

type AuthResponseMsg struct {
}

AuthResponseMsg is the response message in the peer authentication protocol.

This will be expanded later to contain signatures.

func (*AuthResponseMsg) Decode

func (m *AuthResponseMsg) Decode(r io.Reader) (err error)

Decode decodes an AuthResponseMsg from an io.Reader.

func (*AuthResponseMsg) Encode

func (m *AuthResponseMsg) Encode(w io.Writer) error

Encode encodes this AuthResponseMsg into an io.Writer.

func (*AuthResponseMsg) Type

func (m *AuthResponseMsg) Type() Type

Type returns AuthResponse.

type Bus

type Bus interface {
	Publisher

	// SubscribeClient should route all messages with clientAddr as recipient to
	// the provided Consumer. Every address may only be subscribed to once.
	SubscribeClient(c Consumer, clientAddr Address) error
}

A Bus is a central message bus over which all clients of a channel network communicate. It is used as the transport layer abstraction for the client.Client.

type Cache

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

Cache is a message cache. The default value is a valid empty cache.

func (*Cache) Cache

func (c *Cache) Cache(ctx context.Context, p Predicate)

Cache is a message cache. The default value is a valid empty cache.

func (*Cache) Flush

func (c *Cache) Flush()

Flush empties the message cache and removes all predicates.

func (*Cache) Get

func (c *Cache) Get(p Predicate) []*Envelope

Get retrieves all messages from the cache that match the predicate. They are removed from the Cache.

func (*Cache) Put

func (c *Cache) Put(e *Envelope) bool

Put puts the message into the cache if it matches any active predicate. If it matches several predicates, it is still only added once to the cache.

func (*Cache) Size

func (c *Cache) Size() int

Size returns the number of messages held in the message cache.

type Cacher

type Cacher interface {
	// Cache should enable the caching of messages
	Cache(context.Context, Predicate)
}

A Cacher has the Cache method to enable caching of messages.

type Consumer

type Consumer interface {
	// The producer calls OnClose() to unregister the Consumer after it is
	// closed.
	sync.OnCloser
	// Put is called by the emitter when relaying a message.
	Put(*Envelope)
}

Consumer consumes messages fed into it via Put().

type Envelope

type Envelope struct {
	Sender    Address // Sender of the message.
	Recipient Address // Recipient of the message.
	// Msg contained in this Envelope. Not embedded so Envelope doesn't implement Msg.
	Msg Msg
}

An Envelope encapsulates a message with routing information, that is, the sender and intended recipient.

func (*Envelope) Decode

func (env *Envelope) Decode(r io.Reader) (err error)

Decode decodes an Envelope from an io.Reader.

func (*Envelope) Encode

func (env *Envelope) Encode(w io.Writer) error

Encode encodes an Envelope into an io.Writer.

type LocalBus

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

LocalBus is a bus that only sends message in the same process.

func NewLocalBus

func NewLocalBus() *LocalBus

NewLocalBus creates a new local bus, which only targets receivers that lie within the same process.

func (*LocalBus) Publish

func (h *LocalBus) Publish(ctx context.Context, e *Envelope) error

Publish implements wire.Bus.Publish. It returns only once the recipient received the message or the context times out.

func (*LocalBus) SubscribeClient

func (h *LocalBus) SubscribeClient(c Consumer, receiver Address) error

SubscribeClient implements wire.Bus.SubscribeClient. There can only be one subscription per receiver address. When the Consumer closes, its subscription is removed.

type Msg

type Msg interface {
	// Type returns the message's type.
	Type() Type
	// encoding of payload. Type byte should not be encoded.
	perunio.Encoder
}

Msg is the top-level abstraction for all messages sent between Perun nodes.

func Decode

func Decode(r io.Reader) (Msg, error)

Decode decodes a message from an io.Reader.

func NewAuthResponseMsg

func NewAuthResponseMsg(_ Account) Msg

NewAuthResponseMsg creates an authentication response message.

type PingMsg

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

PingMsg is a ping request. It contains the time at which it was sent, so that the recipient can also measure the time it took to transmit the ping request.

func NewPingMsg

func NewPingMsg() *PingMsg

NewPingMsg creates a new Ping message.

func (*PingMsg) Decode

func (m *PingMsg) Decode(reader io.Reader) error

func (PingMsg) Encode

func (m PingMsg) Encode(writer io.Writer) error

func (*PingMsg) Type

func (m *PingMsg) Type() Type

Type returns Ping.

type PongMsg

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

PongMsg is the response to a ping message. It contains the time at which it was sent, so that the recipient knows how long the ping request took to be transmitted, and how quickly the response was sent.

func NewPongMsg

func NewPongMsg() *PongMsg

NewPongMsg creates a new Pong message.

func (*PongMsg) Decode

func (m *PongMsg) Decode(reader io.Reader) error

func (PongMsg) Encode

func (m PongMsg) Encode(writer io.Writer) error

func (*PongMsg) Type

func (m *PongMsg) Type() Type

Type returns Pong.

type Predicate

type Predicate = func(*Envelope) bool

A Predicate defines a message filter.

type Publisher

type Publisher interface {
	// Publish should return nil when the message was delivered (outgoing) or is
	// guaranteed to be eventually delivered (cached), depending on the goal of the
	// implementation.
	Publish(context.Context, *Envelope) error
}

A Publisher allows to publish a message in a messaging network.

type Receiver

type Receiver struct {
	sync.Closer
	// contains filtered or unexported fields
}

Receiver is a helper object that can subscribe to different message categories from multiple peers. Receivers must only be used by a single execution context at a time. If multiple contexts need to access a peer's messages, then multiple receivers have to be created.

func NewReceiver

func NewReceiver() *Receiver

NewReceiver creates a new receiver.

func (*Receiver) Next

func (r *Receiver) Next(ctx context.Context) (*Envelope, error)

Next returns a channel to the next message.

func (*Receiver) Put

func (r *Receiver) Put(e *Envelope)

Put puts a new message into the queue.

type Relay

type Relay struct {
	sync.Closer
	// contains filtered or unexported fields
}

Relay handles (un)registering Consumers for a message Relay's messages.

func NewRelay

func NewRelay() *Relay

NewRelay returns a new Relay which logs unhandled messages.

func (*Relay) Cache

func (p *Relay) Cache(ctx context.Context, predicate Predicate)

Cache enables caching of messages that don't match any consumer. They are only cached if they match the given predicate, within the given context.

func (*Relay) Close

func (p *Relay) Close() error

Close closes the relay.

func (*Relay) Put

func (p *Relay) Put(e *Envelope)

Put puts an Envelope in the relay.

func (*Relay) SetDefaultMsgHandler

func (p *Relay) SetDefaultMsgHandler(handler func(*Envelope))

SetDefaultMsgHandler sets the default message handler.

func (*Relay) Subscribe

func (p *Relay) Subscribe(c Consumer, predicate Predicate) error

Subscribe adds a Consumer to the subscriptions. If the Consumer is already subscribed, Subscribe panics. If the producer is closed, Subscribe returns an error. Otherwise, Subscribe returns nil.

type ShutdownMsg

type ShutdownMsg struct {
	Reason string
}

ShutdownMsg is sent when orderly shutting down a connection.

func (*ShutdownMsg) Decode

func (m *ShutdownMsg) Decode(r io.Reader) error

Decode implements msg.Decode.

func (*ShutdownMsg) Encode

func (m *ShutdownMsg) Encode(w io.Writer) error

Encode implements msg.Encode.

func (*ShutdownMsg) Type

func (m *ShutdownMsg) Type() Type

Type implements msg.Type.

type Subscriber

type Subscriber interface {
	// Subscribe adds a Consumer to the subscriptions.
	// If the Consumer is already subscribed, Subscribe panics.
	Subscribe(Consumer, Predicate) error
}

A Subscriber allows to subscribe Consumers, which will receive messages that match a predicate.

type Type

type Type uint8

Type is an enumeration used for (de)serializing messages and identifying a message's Type.

const (
	Ping Type = iota
	Pong
	Shutdown
	AuthResponse
	LedgerChannelProposal
	ChannelProposalAcc
	ChannelProposalRej
	ChannelUpdate
	ChannelUpdateAcc
	ChannelUpdateRej
	ChannelSync
	LastType // upper bound on the message types of the Perun wire protocol
)

Enumeration of message categories known to the Perun framework.

func (Type) String

func (t Type) String() string

String returns the name of a message type if it is valid and name known or otherwise its numerical representation.

func (Type) Valid

func (t Type) Valid() bool

Valid checks whether a decoder is known for the type.