client

Documentation

Index

• Constants
• Variables
• type Client
  • func New(opts *Options) (Client, error)
• type Context
• type Error
  • func NewError(code int, msg string) Error
• type Hook
• type Hooks
• type Options
• type Session
• type State
• type TypedRStream
• type TypedRWStream
• type TypedStreamCloser
• type TypedWStream

Constants

const (
	NoMaxSizeLimit = -1
	DefaultMaxSize = -2
)

Variables

var (
	ErrClosed         = errors.New("closed")
	ErrNoData         = errors.New("no data available")
	ErrConnect        = errors.New("connect failed")
	ErrInvalidVersion = errors.New("invalid version")
	ErrCatchedPanic   = errors.New("catched panic")
)

Types

type Client

type Client interface {
	closer.Closer

	// StateChan returns a read-only channel that can be listened on
	// to get notifications about changes of the client's state.
	// This allows to react for example to sudden disconnects.
	StateChan() <-chan State

	// Call performs a call on the shared main stream.
	// Returns ErrConnect if a session connection attempt failed.
	Call(ctx context.Context, id string, arg, ret interface{}) error

	// AsyncCall performs a call on a new stream.
	// If maxArgSize & maxRetSize are set to 0, then the payload must be empty.
	// If maxArgSize & maxRetSize are set to NoMaxSizeLimit, then no limit is set.
	// If maxArgSize & maxRetSize are set to DefaultMaxSize, then the default size is used from the options.
	// Returns ErrConnect if a session connection attempt failed.
	AsyncCall(ctx context.Context, id string, arg, ret interface{}, maxArgSize, maxRetSize int) error

	// Stream opens a new data stream.
	// Returns ErrConnect if a session connection attempt failed.
	Stream(ctx context.Context, id string) (transport.Stream, error)

	// TypedRStream opens a new typed read stream.
	// Returns ErrConnect if a session connection attempt failed.
	// See AsyncCall() for the usage of maxRetSize.
	TypedRStream(ctx context.Context, id string, maxRetSize int) (TypedRStream, error)

	// TypedWStream opens a new typed write stream.
	// Returns ErrConnect if a session connection attempt failed.
	// See AsyncCall() for the usage of maxArgSize.
	TypedWStream(ctx context.Context, id string, maxArgSize int) (TypedWStream, error)

	// TypedRWStream opens a new typed read-write stream.
	// Returns ErrConnect if a session connection attempt failed.
	// See AsyncCall() for the usage of maxArgSize & maxRetSize.
	TypedRWStream(ctx context.Context, id string, maxArgSize, maxRetSize int) (TypedRWStream, error)
}

func New

func New(opts *Options) (Client, error)

type Context

type Context interface {
	context.Context

	// SetContext can be used to wrap the context.Context with additonal deadlines, ...
	SetContext(ctx context.Context)

	// Session returns the current active session.
	Session() Session

	// SetRaw sets the raw header byte slice defined by the key.
	// This data is send to the service.
	SetHeader(key string, data []byte)

	// Data returns the value defined by the key. Returns nil if not present.
	Data(key string) interface{}

	// SetData sets the value defined by the key.
	SetData(key string, v interface{})
}

A Context defines the client context which extends the context.Context interface.

type Error

type Error interface {
	// Embeds the standard go error interface.
	error

	// Code returns an integer that can give a hint about the
	// type of error that occurred.
	Code() int
}

The Error type extends the standard go error by a simple integer code. It is returned in the Call- functions of this package and allows callers that use them to check for common errors via the code.

func NewError

func NewError(code int, msg string) Error

NewError returns a new error with the given message and code.

type Hook

type Hook interface {
	// Close is called if the client closes.
	Close() error

	// OnSession is called if a new client session is connected to the service.
	// RPC and stream routines are handled after this hook.
	// Do not use the stream after returning from this hook.
	// Return an error to close the session and abort the initialization process.
	OnSession(s Session, stream transport.Stream) error

	// OnSessionClosed is called as soon as the session closes.
	OnSessionClosed(s Session)

	// OnCall is called before a call request.
	// Return an error to abort the call.
	OnCall(ctx Context, id string, callKey uint32) error

	// OnCallDone is called after a call request.
	// The context is the same as from the OnCall hook.
	// If err == nil, then the call completed successfully.
	OnCallDone(ctx Context, id string, callKey uint32, err error)

	// OnCallCanceled is called, if a call is canceled.
	// The context is the same as from the OnCall hook.
	OnCallCanceled(ctx Context, id string, callKey uint32)

	// OnStream is called during a new stream setup.
	// Return an error to abort the stream setup.
	OnStream(ctx Context, id string) error

	// OnStreamClosed is called after a stream closes.
	// The context is the same as from the OnStream hook.
	OnStreamClosed(ctx Context, id string)
}

Hook allows third-party code to hook into orbit's logic, to implement for example logging or authentication functionality.

type Hooks

type Hooks []Hook

type Options

type Options struct {
	// Host specifies the destination host address. This value must be set.
	Host string

	// Transport specifies the communication backend. This value must be set.
	Transport transport.Transport

	// Closer defines the closer instance. A default closer will be created if unspecified.
	Closer closer.Closer

	// Codec defines the transport encoding. A default codec will be used if unspecified.
	Codec codec.Codec

	// Hooks specifies the hooks executed during certain actions. The order of the hooks is stricly followed.
	Hooks Hooks

	// Log specifies the default logger backend. A default logger will be used if unspecified.
	Log *zerolog.Logger

	// CallTimeout specifies the default timeout for each call.
	// Set to -1 for no timeout.
	CallTimeout time.Duration

	// ConnectTimeout specifies the timeout duration after a service connect attempt.
	ConnectTimeout time.Duration

	// ConnectThrottleDuration specifies the wait duration between subsequent connection attempts.
	ConnectThrottleDuration time.Duration

	// HandshakeTimeout specifies the connection initialization timeout.
	HandshakeTimeout time.Duration

	// StreamInitTimeout specifies the default timeout for a stream setup.
	StreamInitTimeout time.Duration

	// PrintPanicStackTraces prints stack traces of catched panics.
	PrintPanicStackTraces bool

	// MaxArgSize defines the default maximum argument payload size for RPC calls.
	MaxArgSize int

	// MaxRetSize defines the default maximum return payload size for RPC calls.
	MaxRetSize int

	// MaxHeaderSize defines the maximum header size for calls and streams.
	MaxHeaderSize int
}

type Session

type Session interface {
	closer.Closer

	ID() string
	LocalAddr() net.Addr
	RemoteAddr() net.Addr
}

type State

type State int

const (
	StateConnecting   State = 0
	StateConnected    State = 1
	StateReconnecting State = 2
	StateReconnected  State = 3
	StateDisconnected State = 4
)

type TypedRStream

type TypedRStream interface {
	TypedStreamCloser
	Read(data interface{}) error
}

type TypedRWStream

type TypedRWStream interface {
	TypedRStream
	TypedWStream
}

type TypedStreamCloser

type TypedStreamCloser interface {
	Close() error
	CloseWithErr(error) error
	ClosedChan() <-chan struct{}
	IsClosed() bool
}

type TypedWStream

type TypedWStream interface {
	TypedStreamCloser
	Write(data interface{}) error
}