service

Documentation

Index

• Constants
• Variables
• type CallFunc
• type Context
• type Error
  • func NewError(err error, msg string, code int) Error
• type Hook
• type Hooks
• type Options
• type RawStreamFunc
• type Service
  • func New(opts *Options) (Service, error)
• type Session
• type TypedRStream
• type TypedRStreamFunc
• type TypedRWStream
• type TypedRWStreamFunc
• type TypedStreamCloser
• type TypedWStream
• type TypedWStreamFunc

Constants

const (
	NoMaxSizeLimit = -1
	DefaultMaxSize = -2

	DefaultTimeout = 0
	NoTimeout      = -1
)

Variables

var (
	// ErrClosed defines the error if a stream, session or service is closed.
	ErrClosed = errors.New("closed")

	// ErrInvalidVersion defines the error if the version of both peers do not match
	// during the version exchange.
	ErrInvalidVersion = errors.New("invalid version")

	// ErrCatchedPanic defines the error if a panic has been catched while executing user code.
	ErrCatchedPanic = errors.New("catched panic")
)

Types

type CallFunc

type CallFunc func(ctx Context, arg []byte) (ret interface{}, err 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

	// Header returns the raw header byte slice defined by the key. Returns nil if not present.
	Header(key string) []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 service context which extends the context.Context interface.

type Error

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

	// Msg returns a textual explanation of the error and should
	// NOT contain sensitive information about the application.
	Msg() string

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

An Error offers a way for handler functions of rpc calls to determine the information passed to the client, in case an error occurs. That way, sensitive information that may be contained in a standard error, can be hidden from the client. Instead, a Msg and a code can be sent back to give a non-sensitive explanation of the error and a code that is easy to check, to allow handling common errors.

func NewError

func NewError(err error, msg string, code int) Error

NewError constructs and returns a type that satisfies the Error interface from the given parameters.

type Hook

type Hook interface {
	// Close is called if the service 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.
	// If err == nil, then the stream completed successfully.
	OnStreamClosed(ctx Context, id string, err error)
}

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 {
	// ListenAddr specifies the listen address for the server. This value is passed to the transport backend.
	ListenAddr 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 (NoTimeout) for no timeout.
	CallTimeout time.Duration

	// HandshakeTimeout specifies the timeout for the initial handshake.
	HandshakeTimeout time.Duration

	// AcceptConnWorkers specifies the routines accepting new connections.
	AcceptConnWorkers int

	// SessionIDLen specifies the length of each session ID.
	SessionIDLen uint

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

	// SendInternalErrors sends all errors to the client, even if the Error interface is not satisfied.
	SendInternalErrors 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 RawStreamFunc

type RawStreamFunc func(ctx Context, stream transport.Stream)

type Service

type Service interface {
	closer.Closer

	// RegisterCall registers a synchronous call send over the shared stream.
	// Do not call after Run() was called.
	// Set timeout to DefaultTimeout for the default timeout.
	// Set timeout to NoTimeout for not timeout.
	RegisterCall(id string, f CallFunc, timeout time.Duration)

	// RegisterAsyncCall registers an asynchronous call using its own stream.
	// Do not call after Run() was called.
	// Set timeout to DefaultTimeout for the default timeout.
	// Set timeout to NoTimeout for not timeout.
	// 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.
	RegisterAsyncCall(id string, f CallFunc, timeout time.Duration, maxArgSize, maxRetSize int)

	// RegisterStream registers the callback for the incoming stream specified by the id.
	// Do not call after Run() was called.
	RegisterStream(id string, f RawStreamFunc)

	// RegisterTypedRStream registers the callback for the incoming typed read stream
	// specified by the id.
	// Do not call after Run() was called.
	// See RegisterAsyncCall() for the usage of maxArgSize.
	RegisterTypedRStream(id string, f TypedRStreamFunc, maxArgSize int)

	// RegisterTypedWStream registers the callback for the incoming typed write stream
	// specified by the id.
	// Do not call after Run() was called.
	// See RegisterAsyncCall() for the usage of maxRetSize.
	RegisterTypedWStream(id string, f TypedWStreamFunc, maxRetSize int)

	// RegisterTypedRWStream registers the callback for the incoming typed read write stream
	// specified by the id.
	// Do not call after Run() was called.
	// See RegisterAsyncCall() for the usage of maxArgSize & maxRetSize.
	RegisterTypedRWStream(id string, f TypedRWStreamFunc, maxArgSize, maxRetSize int)

	// Run the service and start accepting requests.
	Run() error
}

func New

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

type Session

type Session interface {
	closer.Closer

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

type TypedRStream

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

type TypedRStreamFunc

type TypedRStreamFunc func(ctx Context, stream TypedRStream) error

type TypedRWStream

type TypedRWStream interface {
	TypedRStream
	TypedWStream
}

type TypedRWStreamFunc

type TypedRWStreamFunc func(ctx Context, stream TypedRWStream) error

type TypedStreamCloser

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

type TypedWStream

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

type TypedWStreamFunc

type TypedWStreamFunc func(ctx Context, stream TypedWStream) error