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 EncodeMsg(msg Msg, w io.Writer) error
• func IndexOfAddr(addrs []Address, addr Address) int
• func RegisterDecoder(t Type, decoder func(io.Reader) (Msg, error))
• func RegisterExternalDecoder(t Type, decoder func(io.Reader) (Msg, error), name string)
• func SetNewAddressFunc(f NewAddressFunc)
• type Account
• type AddrKey
  • func Key(a Address) AddrKey
• type Address
  • func NewAddress() Address
• type Addresses
  • func (a Addresses) Decode(r stdio.Reader) error
  • func (a Addresses) Encode(w stdio.Writer) error
• type AddressesWithLen
  • func (a *AddressesWithLen) Decode(r stdio.Reader) error
  • func (a AddressesWithLen) Encode(w stdio.Writer) error
• 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
  • func NewHybridBus(buses ...Bus) Bus
• type Cache
  • func MakeCache() Cache
  • func (c *Cache) Cache(p *Predicate)
  • func (c *Cache) Flush()
  • func (c *Cache) Messages(p Predicate) []*Envelope
  • func (c *Cache) Put(e *Envelope) bool
  • func (c *Cache) Release(p *Predicate)
  • func (c *Cache) Size() int
• type Cacher
• type Consumer
• type Envelope
• type EnvelopeSerializer
• 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 DecodeMsg(r io.Reader) (Msg, error)
  • func NewAuthResponseMsg(acc Account) (Msg, error)
• type NewAddressFunc
• type PingMsg
  • func NewPingMsg() *PingMsg
  • func (m *PingMsg) Type() Type
• type PingPongMsg
  • func (m *PingPongMsg) Decode(reader io.Reader) error
  • func (m PingPongMsg) Encode(writer io.Writer) error
• type PongMsg
  • func NewPongMsg() *PongMsg
  • 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(predicate *Predicate)
  • func (p *Relay) Close() error
  • func (p *Relay) Put(e *Envelope)
  • func (p *Relay) ReleaseCache(predicate *Predicate)
  • 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 EncodeMsg

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

EncodeMsg 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 IndexOfAddr

func IndexOfAddr(addrs []Address, addr Address) int

IndexOfAddr returns the index of the given address in the address slice, or -1 if it is not part of the slice.

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 SetNewAddressFunc

func SetNewAddressFunc(f NewAddressFunc)

SetNewAddressFunc sets the address generator function.

Types

type Account

type Account interface {
	// Address used by this account.
	Address() Address

	// Sign signs the given message with this account's private key.
	Sign(msg []byte) ([]byte, error)
}

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

type AddrKey

type AddrKey string

AddrKey is a non-human readable representation of an `Address`. It can be compared and therefore used as a key in a map.

func Key

func Key(a Address) AddrKey

Key returns the `AddrKey` corresponding to the passed `Address`. The `Address` can be retrieved with `FromKey`. Panics when the `Address` can't be encoded.

type Address

type Address interface {
	// BinaryMarshaler marshals the address to binary.
	encoding.BinaryMarshaler
	// BinaryUnmarshaler unmarshals an address from binary.
	encoding.BinaryUnmarshaler
	// Equal returns wether the two addresses are equal.
	Equal(Address) bool
	// Cmp compares the byte representation of two addresses. For `a.Cmp(b)`
	// returns -1 if a < b, 0 if a == b, 1 if a > b.
	Cmp(Address) int
	// Verify verifies a message signature.
	// It returns an error if the signature is invalid.
	Verify(msg []byte, sig []byte) error
}

Address is a Perun node's network address, which is used as a permanent identity within the Perun peer-to-peer network. For now, it is based on type wallet.Address.

func NewAddress

func NewAddress() Address

NewAddress returns a new address.

type Addresses

type Addresses []Address

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

func (Addresses) Decode

func (a Addresses) Decode(r stdio.Reader) error

Decode decodes wallet addresses.

func (Addresses) Encode

func (a Addresses) Encode(w stdio.Writer) error

Encode encodes wire addresses.

type AddressesWithLen

type AddressesWithLen []Address

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

func (*AddressesWithLen) Decode

func (a *AddressesWithLen) Decode(r stdio.Reader) error

Decode decodes a wallet address slice of unknown length.

func (AddressesWithLen) Encode

func (a AddressesWithLen) Encode(w stdio.Writer) error

Encode encodes wire addresses with length.

type AuthResponseMsg

type AuthResponseMsg struct {
	Signature []byte
}

AuthResponseMsg is the response message in the peer authentication protocol.

func (*AuthResponseMsg) Decode

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

Decode decodes an AuthResponseMsg from an io.Reader. It reads the signature from the reader.

func (*AuthResponseMsg) Encode

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

Encode encodes this AuthResponseMsg into an io.Writer. It writes the signature to the 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.

func NewHybridBus

func NewHybridBus(buses ...Bus) Bus

NewHybridBus creates a hybrid bus that sends and receives messages over multiple buses. Publishing a message over a hybrid bus will attempt to publish it over all its sub-buses simultaneously. Subscribing a client to the hybrid bus will subscribe it to all its sub-buses. The sub-buses can still be accessed independently for more fine-grained control.

Once any bus indicates success in publishing a message, the publishing operations on all other buses are cancelled. This bus is best used with a LocalBus and one network bus, otherwise, with multiple non-instantaneous buses, messages might get sent multiple times. Buses that indicate success immediately (such as when caching outbound messages) can also cause problems if they cancel non-immediate buses.

type Cache

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

Cache is a message cache.

func MakeCache

func MakeCache() Cache

MakeCache creates a new cache.

func (*Cache) Cache

func (c *Cache) Cache(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) Messages

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

Messages 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) Release

func (c *Cache) Release(p *Predicate)

Release releases the cache predicate.

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(*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.

type EnvelopeSerializer

type EnvelopeSerializer interface {
	Encode(w io.Writer, env *Envelope) error
	Decode(r io.Reader) (*Envelope, error)
}

EnvelopeSerializer serializes/deserializes envelopes into/from streams.

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
}

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

func DecodeMsg

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

DecodeMsg decodes a message from an io.Reader.

func NewAuthResponseMsg

func NewAuthResponseMsg(acc Account) (Msg, error)

NewAuthResponseMsg creates an authentication response message.

type NewAddressFunc

type NewAddressFunc = func() Address

NewAddressFunc is an address generator function.

type PingMsg

type PingMsg struct {
	PingPongMsg
}

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

func (m *PingMsg) Type() Type

Type returns Ping.

type PingPongMsg

type PingPongMsg struct {
	Created time.Time
}

PingPongMsg is the common message type used by ping and pong msgs, since both the messages are essentially the same.

func (*PingPongMsg) Decode

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

Decode implements msg.Decode.

func (PingPongMsg) Encode

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

Encode implements msg.Encode.

type PongMsg

type PongMsg struct {
	PingPongMsg
}

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) 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(predicate *Predicate)

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

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

func (p *Relay) ReleaseCache(predicate *Predicate)

ReleaseCache disable caching for the given predicate.

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.

Reason should be a UTF-8 encodable string.

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
	LedgerChannelProposalAcc
	SubChannelProposal
	SubChannelProposalAcc
	VirtualChannelProposal
	VirtualChannelProposalAcc
	ChannelProposalRej
	ChannelUpdate
	VirtualChannelFundingProposal
	VirtualChannelSettlementProposal
	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.