ordersync

Documentation

Overview

Package ordersync contains the ordersync protocol, which is used for sharing existing orders between two peers, typically during initialization. The protocol consists of a requester (the peer requesting orders) and a provider (the peer providing them).

Index

• Constants
• Variables
• type FirstRequestsForSubprotocols
• type NoMatchingSubprotocolsError
  • func (e NoMatchingSubprotocolsError) Error() string
• type Request
• type Response
• type Service
  • func New(ctx context.Context, node *p2p.Node, subprotocols []Subprotocol) *Service
  • func (s *Service) GetMatchingSubprotocol(rawReq *rawRequest) (Subprotocol, int, error)
  • func (s *Service) GetOrders(ctx context.Context, minPeers int) error
  • func (s *Service) HandleStream(stream network.Stream)
  • func (s *Service) PeriodicallyGetOrders(ctx context.Context, minPeers int, approxDelay time.Duration) error
• type Subprotocol

Constants

const (
	// TypeRequest is used to identify a JSON message as an ordersync request.
	TypeRequest = "Request"
	// TypeResponse is used to identify a JSON message as an ordersync response.
	TypeResponse = "Response"
)

const (
	// ID is the ID for the ordersync protocol.
	ID = protocol.ID("/0x-mesh/order-sync/version/0")
)

Variables

var (
	// ErrNoOrders is returned whenever the orders we are looking for cannot be
	// found anywhere on the network. This can mean that we aren't connected to any
	// peers on the same topic, that there are no orders for the topic throughout
	// the entire network, or that there are peers that have the orders we're
	// looking for, but they are refusing to give them to us.
	ErrNoOrders = errors.New("no orders where received from any known peers")
	// ErrNoOrderFromPeer is returned when a peer returns no orders during ordersync.
	ErrNoOrdersFromPeer = errors.New("no orders received from peer")
)

Types

type FirstRequestsForSubprotocols

type FirstRequestsForSubprotocols struct {
	MetadataForSubprotocol []json.RawMessage `json:"metadata"`
}

type NoMatchingSubprotocolsError

type NoMatchingSubprotocolsError struct {
	Requested []string
	Supported []string
}

NoMatchingSubprotocolsError is returned whenever two peers attempting to use the ordersync protocol cannot agree on a subprotocol to use.

func (NoMatchingSubprotocolsError) Error

func (e NoMatchingSubprotocolsError) Error() string

type Request

type Request struct {
	RequesterID peer.ID     `json:"requesterID"`
	Metadata    interface{} `json:"metadata"`
}

Request represents a high-level ordersync request. It abstracts away some of the details of subprotocol negotiation and encoding/decoding.

type Response

type Response struct {
	ProviderID peer.ID               `json:"providerID"`
	Orders     []*zeroex.SignedOrder `json:"orders"`
	Complete   bool                  `json:"complete"`
	Metadata   interface{}           `json:"metadata"`
}

Response represents a high-level ordersync response. It abstracts away some of the details of subprotocol negotiation and encoding/decoding.

type Service

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

Service is the main entrypoint for running the ordersync protocol. It handles responding to and sending ordersync requests.

func New

func New(ctx context.Context, node *p2p.Node, subprotocols []Subprotocol) *Service

New creates and returns a new ordersync service, which is used for both requesting orders from other peers and providing orders to peers who request them. New expects an array of subprotocols which the service will support, in the order of preference. The service will automatically pick the most preferred protocol that is supported by both peers for each request/response.

func (*Service) GetMatchingSubprotocol

func (s *Service) GetMatchingSubprotocol(rawReq *rawRequest) (Subprotocol, int, error)

GetMatchingSubprotocol returns the most preferred subprotocol to use based on the given request.

func (*Service) GetOrders

func (s *Service) GetOrders(ctx context.Context, minPeers int) error

GetOrders iterates through every peer the node is currently connected to and attempts to perform the ordersync protocol. It keeps trying until ordersync has been completed with minPeers, using an exponential backoff strategy between retries.

func (*Service) HandleStream

func (s *Service) HandleStream(stream network.Stream)

HandleStream is a stream handler that is used to handle incoming ordersync requests.

func (*Service) PeriodicallyGetOrders

func (s *Service) PeriodicallyGetOrders(ctx context.Context, minPeers int, approxDelay time.Duration) error

PeriodicallyGetOrders periodically calls GetOrders. It waits a minimum of approxDelay (with some random jitter) between each call. It will block until there is a critical error or the given context is canceled.

type Subprotocol

type Subprotocol interface {
	// Name is the name of the subprotocol. Must be unique.
	Name() string
	// HandleOrderSyncRequest returns a Response based on the given Request. It is the
	// implementation for the "provider" side of the subprotocol.
	HandleOrderSyncRequest(context.Context, *Request) (*Response, error)
	// HandleOrderSyncResponse handles a response (e.g. typically by saving orders to
	// the database), returns the number of valid orders that were received,
	// and, if needed, creates and returns the next request that should be sent.
	// If nextRequest is nil, the ordersync protocol is considered finished.
	// HandleOrderSyncResponse is the implementation for the "requester" side
	// of the subprotocol.
	HandleOrderSyncResponse(context.Context, *Response) (nextRequest *Request, numValidOrders int, err error)
	// ParseRequestMetadata converts raw request metadata into a concrete type
	// that the subprotocol expects.
	ParseRequestMetadata(metadata json.RawMessage) (interface{}, error)
	// ParseResponseMetadata converts raw response metadata into a concrete type
	// that the subprotocol expects.
	ParseResponseMetadata(metadata json.RawMessage) (interface{}, error)
	// GenerateFirstRequestMetadata generates the metadata for the first request
	// that should be made with this subprotocol.
	GenerateFirstRequestMetadata() (json.RawMessage, error)
}

Subprotocol is a lower-level protocol which defines the details for the request/response metadata. While the ordersync protocol supports sending requests and responses in order to synchronize orders between two peers in general, a subprotocol defines exactly what those requests and responses should look like and how each peer is expected to respond to them.