urpc

Documentation

Overview

Package urpc provides a minimal RPC package based on unet.

RPC requests are _not_ concurrent and methods must be explicitly registered. However, files may be send as part of the payload.

Index

• Variables
• type Client
  • func NewClient(socket *unet.Socket) *Client
  • func (c *Client) Call(method string, arg any, result any) error
  • func (c *Client) Close() error
• type FilePayload
  • func (f *FilePayload) ReleaseFD(index int) (*fd.FD, error)
• type RemoteError
  • func (r RemoteError) Error() string
• type Server
  • func NewServer() *Server
  • func NewServerWithCallback(afterRPCCallback func()) *Server
  • func (s *Server) Handle(client *unet.Socket) error
  • func (s *Server) Register(obj any)
  • func (s *Server) StartHandling(client *unet.Socket)
  • func (s *Server) Stop(timeout time.Duration)
• type Stopper

Variables

var ErrTooManyFiles = errors.New("too many files")

ErrTooManyFiles is returned when too many file descriptors are mapped.

var ErrUnknownMethod = errors.New("unknown method")

ErrUnknownMethod is returned when a method is not known.

Types

type Client

type Client struct {

	// Socket is the underlying socket for this client.
	//
	// This _must_ be provided and must be closed manually by calling
	// Close.
	Socket *unet.Socket
	// contains filtered or unexported fields
}

Client is a urpc client.

func NewClient

func NewClient(socket *unet.Socket) *Client

NewClient returns a new client.

func (*Client) Call

func (c *Client) Call(method string, arg any, result any) error

Call calls a function.

func (*Client) Close

func (c *Client) Close() error

Close closes the underlying socket.

Further calls to the client may result in undefined behavior.

type FilePayload

type FilePayload struct {
	Files []*os.File `json:"-"`
}

FilePayload may be _embedded_ in another type in order to send or receive a file as a result of an RPC. These are not actually serialized, rather they are sent via an accompanying SCM_RIGHTS message (plumbed through the unet package).

When embedding a FilePayload in an argument struct, the argument type _must_ be a pointer to the struct rather than the struct type itself. This is because the urpc package defines pointer methods on FilePayload.

func (*FilePayload) ReleaseFD

func (f *FilePayload) ReleaseFD(index int) (*fd.FD, error)

ReleaseFD releases the FD at the specified index.

type RemoteError

type RemoteError struct {
	// Message is the result of calling Error() on the remote error.
	Message string
}

RemoteError is an error returned by the remote invocation.

This indicates that the RPC transport was correct, but that the called function itself returned an error.

func (RemoteError) Error

func (r RemoteError) Error() string

Error returns the remote error string.

type Server

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

Server is an RPC server.

func NewServer

func NewServer() *Server

NewServer returns a new server.

func NewServerWithCallback

func NewServerWithCallback(afterRPCCallback func()) *Server

NewServerWithCallback returns a new server, who upon completion of each RPC calls the given function.

func (*Server) Handle

func (s *Server) Handle(client *unet.Socket) error

Handle synchronously handles a single client over a connection.

func (*Server) Register

func (s *Server) Register(obj any)

Register registers the given object as an RPC receiver.

This functions is the same way as the built-in RPC package, but it does not tolerate any object with non-conforming methods. Any non-confirming methods will lead to an immediate panic, instead of being skipped or an error. Panics will also be generated by anonymous objects and duplicate entries.

func (*Server) StartHandling

func (s *Server) StartHandling(client *unet.Socket)

StartHandling creates a goroutine that handles a single client over a connection.

func (*Server) Stop

func (s *Server) Stop(timeout time.Duration)

Stop safely terminates outstanding clients.

No new requests should be initiated after calling Stop. Existing clients will be closed after completing any pending RPCs. This method will block until all clients have disconnected.

timeout is the time for clients to complete pending RPCs. After timeout expires, all clients are drained (i.e. their ongoing RPC is allowed to complete) and closed. Any new RPCs will not be processed. Note that ongoing RPCs are *not* interrupted or cancelled.

type Stopper

type Stopper interface {
	Stop()
}

Stopper is an optional interface, that when implemented, allows an object to have a callback executed when the server is shutting down.