server

Documentation

Index

• Variables
• func ErrorResponse(req mercury.Request, err error) mercury.Response
• func SetDefaultMiddleware(middleware []ServerMiddleware)
• type Endpoint
  • func (e Endpoint) Handle(req mercury.Request) (mercury.Response, error)
• type Handler
• type Server
  • func NewServer(name string) Server
• type ServerMiddleware

Variables

var (
	ErrAlreadyRunning  error = terrors.InternalService("", "Server is already running", nil) // empty dotted code so impl details don't leak outside
	ErrTransportClosed error = terrors.InternalService("", "Transport closed", nil)
)

Functions

func ErrorResponse

func ErrorResponse(req mercury.Request, err error) mercury.Response

ErrorResponse constructs a response for the given request, with the given error as its contents. Mercury clients know how to unmarshal these errors.

func SetDefaultMiddleware

func SetDefaultMiddleware(middleware []ServerMiddleware)

Types

type Endpoint

type Endpoint struct {
	// Name is the Endpoint's unique name, and is used to route requests to it.
	Name string
	// Handler is a function to be invoked upon receiving a request, to generate a response.
	Handler Handler
	// Request is a "template" object for the Endpoint's request format.
	Request interface{}
	// Response is a "template" object for the Endpoint's response format.
	Response interface{}
}

An Endpoint represents a handler function bound to a particular endpoint name.

func (Endpoint) Handle

func (e Endpoint) Handle(req mercury.Request) (mercury.Response, error)

Handle takes an inbound Request, unmarshals it, dispatches it to the handler, and serialises the result as a Response. Note that the response may be nil.

type Handler

type Handler func(req mercury.Request) (mercury.Response, error)

type Server

type Server interface {
	// Name returns the service name. It must be set at construction time and is immutable.
	Name() string
	// AddEndpoints registers new Endpoint. If any name conflicts with an existing endpoint, the old endpoint(s) will be
	// removed. Errors raised as panics.
	AddEndpoints(eps ...Endpoint)
	// RemoveEndpoints removes the Endpoints given (if they are registered).
	RemoveEndpoints(eps ...Endpoint)
	// Endpoint returns a registered endpoint (if there is one) for the given Name.
	Endpoint(name string) (Endpoint, bool)
	// Endpoints returns all Endpoints registered.
	Endpoints() []Endpoint
	// Start starts the server on the given transport, and returns once the server is ready for work. The server will
	// continue until purposefully stopped, or until a terminal error occurs. The transport should be pre-initialised.
	Start(trans transport.Transport) error
	// Run starts the server and blocks until it stops. As this function is intended to support the main run loop of a
	// service, an error results in a panic.
	Run(trans transport.Transport)
	// Stop forcefully stops the server. It does not terminate the underlying transport.
	Stop()

	// Middleware returns a copy of the ServerMiddleware stack currently installed.
	//
	// Server middleware is used to act upon or transform a handler's input or output. Middleware is applied in order
	// during the request phase, and in reverse order during the response phase.
	Middleware() []ServerMiddleware
	// SetMiddleware replaces the server's ServerMiddleware stack.
	SetMiddleware([]ServerMiddleware)
	// AddMiddleware appends the given ServerMiddleware to the stack.
	AddMiddleware(ServerMiddleware)
}

A Server provides Endpoint RPC functionality atop a typhon Transport.

func NewServer

func NewServer(name string) Server

type ServerMiddleware

type ServerMiddleware interface {
	// ProcessServerRequest is called on each inbound request, before it is routed to an Endpoint. If a response or an
	// error is returned, Mercury does not bother calling any other request middleware. It will apply response
	// middleware and respond to the caller with the result.
	//
	// If an error is to be returned, use `ErrorResponse`.
	ProcessServerRequest(req mercury.Request) (mercury.Request, mercury.Response)
	// ProcessServerResponse is called on all responses before they are returned to a caller. Unlike request middleware,
	// response middleware is always called. If an error is returned, it will be marshaled to a response and will
	// continue to other response middleware.
	//
	// Nil responses MUST be handled. If an error is to be returned, use `ErrorResponse`.
	//
	// Note that response middleware are applied in reverse order.
	ProcessServerResponse(rsp mercury.Response, req mercury.Request) mercury.Response
}