rpc

Documentation

Overview

Package rpc provides an RPC service for non-specific []byte in and []byte out data. Note that this package is usually used to build higher-level rpc packages and not directly.

A simple client works like:

client, err := New(pathToSocket)
if err != nil {
	// Do something
}

ctx, cancel := context.WitheTimeout(5 * time.Second)
resp := Response{}

retry:
	// req and resp are []byte{}
	if err := client.Call(ctx, "method", req, &resp); err != nil {
		if Retryable(err) {
			// Okay, so you probably should do this in a for loop, but I wanted to use
			// a label for the hell of it.
			goto retry
		}
		// Do something here, cause you have a non-retryable error.
	}

Note: The server only returns errors to clients when something goes wrong. This makes it predictable on the server side when the error is retryable. When the service has an error, I recommend returning the expected response, which should have a dict containing the error code and the error message. This allows your clients to decide if they should retry a request.

Index

• Constants
• func CredFromCtx(ctx context.Context) uds.Cred
• func Errorf(code ErrType, s string, i ...interface{}) error
• func Retryable(err error) bool
• type Client
  • func New(socketAddr string, uid, gid int, fileModes []os.FileMode, options ...Option) (*Client, error)
  • func (c *Client) Call(ctx context.Context, method string, req []byte, resp *[]byte) error
  • func (c *Client) Close() error
• type ErrBadData
  • func (e ErrBadData) Error() string
• type ErrDeadlineExceeded
  • func (e ErrDeadlineExceeded) Error() string
• type ErrMethodNotFound
  • func (e ErrMethodNotFound) Error() string
• type ErrServer
  • func (e ErrServer) Error() string
• type ErrType
• type ErrUnknown
  • func (e ErrUnknown) Error() string
• type Option
  • func MaxSize(size int64) Option
  • func SharedPool(pool *chunk.Pool) Option
• type RequestHandler
• type Server
  • func NewServer(socketAddr string, uid, gid int, fileMode os.FileMode) (*Server, error)
  • func (s *Server) RegisterMethod(method string, handler RequestHandler)
  • func (s *Server) Start() error
  • func (s *Server) Stop(ctx context.Context) error

Constants

const (
	// ETUnknown means to use the ErrUnknown type.
	ETUnknown = 0
	// ETMethodNotFound means to use the ErrMethodNotFound type.
	ETMethodNotFound = 1
	// ETDeadlineExceeded means to use the ErrDeadlineExceeded type.
	ETDeadlineExceeded = 2
	// ETBadData means to use the ErrBadData type.
	ETBadData = 3
	// ETServer means to use the ErrServer type.
	ETServer = 4
)

Functions

func CredFromCtx

func CredFromCtx(ctx context.Context) uds.Cred

CredFromCtx will extract the Cred from the Context object.

func Errorf

func Errorf(code ErrType, s string, i ...interface{}) error

Errorf returns an error specificed by the ErrType containing the error text of fmt.Sprintf(s, i...).

func Retryable

func Retryable(err error) bool

Retryable indicates that the error is retryable.

Types

type Client

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

Client provides an RPC client with []byte in and []byte out.

func New

func New(socketAddr string, uid, gid int, fileModes []os.FileMode, options ...Option) (*Client, error)

New is the constructor for Client. rwc must be a *uds.Client or *uds.Conn.

func (*Client) Call

func (c *Client) Call(ctx context.Context, method string, req []byte, resp *[]byte) error

Call calls the RPC service. If Context timeout is not set, will default to 5 minutes.

func (*Client) Close

func (c *Client) Close() error

Close closes the underyling connection.

type ErrBadData

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

ErrBadData indicates that client sent bad data according to the server.

func (ErrBadData) Error

func (e ErrBadData) Error() string

type ErrDeadlineExceeded

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

ErrDeadlineExceeded indicates call deadline was exceeded.

func (ErrDeadlineExceeded) Error

func (e ErrDeadlineExceeded) Error() string

type ErrMethodNotFound

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

ErrMethodNotFound indicates that the calling method wasn't found on the server.

func (ErrMethodNotFound) Error

func (e ErrMethodNotFound) Error() string

type ErrServer

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

ErrServer indicates the server sent back an error message.

func (ErrServer) Error

func (e ErrServer) Error() string

type ErrType

type ErrType int8

ErrType indicates the type of message to use.

type ErrUnknown

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

ErrUnknown indicates the error type is unknown.

func (ErrUnknown) Error

func (e ErrUnknown) Error() string

type Option

type Option func(c *Client)

Option is an optional argument to New.

func MaxSize

func MaxSize(size int64) Option

MaxSize is the maximum size a read message is allowed to be. If a message is larger than this, Next() will fail and the underlying connection will be closed.

func SharedPool

func SharedPool(pool *chunk.Pool) Option

SharedPool allows the use of a shared pool of buffers between Client instead of a pool per client. This is useful when clients are short lived and have similar message sizes. Client will panic if the pool does not return a *[]byte object.

type RequestHandler

type RequestHandler func(ctx context.Context, req []byte) (resp []byte, err error)

RequestHandler will receive a Context object with a Deadline set and you can retrieve the calling process creds with CredFromCtx. An error returned is a ErrServer that can not be retried. Generally service errors should be in the resp, not as a returned error. See the note in the package intro.

type Server

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

Server provides an json RPC server.

func NewServer

func NewServer(socketAddr string, uid, gid int, fileMode os.FileMode) (*Server, error)

NewServer is the constructor for a Server. rwc must be a *uds.Client or *uds.Conn.

func (*Server) RegisterMethod

func (s *Server) RegisterMethod(method string, handler RequestHandler)

RegisterMethod registers an RPC method with the server.

func (*Server) Start

func (s *Server) Start() error

Start starts the server. This will block until the server stops.

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error

Stop stops the server, which will stop listening for new connections. This should slowly kill off existing calls. Stop will return when all calls have completed or the context deadline is reached(or cancelled). A nil error indicates that all jobs were completed. Note: a Server cannot be reused.