relay

Documentation

Overview

Package relay contains relaying interfaces for external use.

These interfaces are currently unstable, and aren't covered by the API backwards-compatibility guarantee.

Index

• type CallFrame
• type CallStats
• type Conn
• type Hosts
• type Peer
• type Stats
  • func NewNoopStats() Stats

Types

type CallFrame

type CallFrame interface {
	// Caller is the name of the originating service.
	Caller() []byte
	// Service is the name of the destination service.
	Service() []byte
	// Method is the name of the method being called.
	Method() []byte
	// RoutingDelegate is the name of the routing delegate, if any.
	RoutingDelegate() []byte
	// RoutingKey may refer to an alternate traffic group instead of the
	// traffic group identified by the service name.
	RoutingKey() []byte
}

CallFrame is an interface that abstracts access to the call req frame.

type CallStats

type CallStats interface {
	// SetPeer is called once a peer has been selected for this call.
	// Note: This may not be called if a call fails before peer selection.
	SetPeer(Peer)

	// The call succeeded (possibly after retrying).
	Succeeded()
	// The RPC failed.
	Failed(reason string)
	// End stats collection for this RPC. Will be called exactly once.
	End()
}

CallStats is a reporter for per-request stats. The Succeeded, Failed, and End methods should be safe for concurrent use.

Because call res frames don't include the OK bit, we can't wait until the last frame of a relayed RPC to decide whether or not the RPC succeeded. Instead, we mark the call successful or failed as we see the relevant frame, but we wait to end any timers until the last frame of the response.

type Conn

type Conn interface {
	// RemoteProcessPrefixMatches checks whether the remote peer's process name
	// matches a preconfigured list of prefixes specified in the connection
	// options. It's the caller's responsibility to match indices between the two
	// slices. Callers shouldn't mutate the returned slice.
	RemoteProcessPrefixMatches() []bool

	// RemoteHostPort returns the host:port of the remote peer.
	RemoteHostPort() string
}

Conn is an interface that exposes a bit of information about the underlying connection.

type Hosts

type Hosts interface {
	// Get returns the peer to forward the given call to.
	// If a SystemError is returned, the error is forwarded. Otherwise
	// a Declined error is returned to the caller.
	Get(CallFrame, Conn) (Peer, error)
}

Hosts allows external wrappers to inject peer selection logic for relaying.

type Peer

type Peer struct {
	// HostPort of the peer that was selected.
	HostPort string

	// Pool allows the peer selection to specify a pool that this Peer belongs
	// to, which may be useful when reporting stats.
	Pool string

	// Zone allows the peer selection to specify the zone that this Peer belongs
	// to, which is also useful for stats.
	Zone string
}

Peer represents the destination selected for a call.

type Stats

type Stats interface {
	Begin(CallFrame) CallStats
}

Stats is a CallStats factory.

func NewNoopStats

func NewNoopStats() Stats

NewNoopStats returns a no-op implementation of Stats.