rpc

Documentation

Overview

Package rpc provides the canonical NATS request/reply RPC mechanism for all internal Loom service-to-service communication.

Subject Convention

loom.rpc.{serviceType}.{instanceID}.{method}

Callers that want any instance of a service type use a wildcard:

loom.rpc.agent-coder.*.task.assign

Usage (caller)

var resp MyResponse
err := rpc.Call(ctx, nc, "loom.rpc.agent-coder.*.task.assign", callerID, payload, &resp)

Usage (handler)

rpc.Register(nc, "loom.rpc.agent-coder.inst123.task.assign", func(req *rpc.Request) *rpc.Response {
    // process req.Payload
    return rpc.OK(responsePayload)
})

Index

• func Call(ctx context.Context, nc *nats.Conn, subject, callerID, method string, ...) error
• func Register(nc *nats.Conn, subject string, handler func(*Request) *Response) (*nats.Subscription, error)
• func Subject(serviceType, instanceID, method string) string
• func WildcardSubject(serviceType, method string) string
• type Request
• type Response
  • func Err(err error) *Response
  • func OK(payload interface{}) *Response

Functions

func Call

func Call(ctx context.Context, nc *nats.Conn, subject, callerID, method string, payload, out interface{}) error

Call sends a NATS request to the given subject and decodes the response payload into out (which must be a pointer). Uses defaultTimeout if ctx has no deadline.

func Register

func Register(nc *nats.Conn, subject string, handler func(*Request) *Response) (*nats.Subscription, error)

Register subscribes nc to subject and calls handler for each incoming request. The handler's returned *Response is serialised and sent as the NATS reply. subject should be the fully-qualified instance subject, e.g.:

loom.rpc.agent-coder.inst123.task.assign

func Subject

func Subject(serviceType, instanceID, method string) string

Subject returns the canonical RPC subject for a given service type, instance ID, and method.

func WildcardSubject

func WildcardSubject(serviceType, method string) string

WildcardSubject returns a subject that matches any instance of the given service type and method.

Types

type Request

type Request struct {
	Method   string          `json:"method"`
	CallerID string          `json:"caller_id"`
	Payload  json.RawMessage `json:"payload,omitempty"`
	TraceID  string          `json:"trace_id,omitempty"`
}

Request is the canonical envelope for a NATS RPC call.

type Response

type Response struct {
	OK      bool            `json:"ok"`
	Payload json.RawMessage `json:"payload,omitempty"`
	Error   string          `json:"error,omitempty"`
}

Response is the canonical reply envelope for a NATS RPC call.

func Err

func Err(err error) *Response

Err constructs an error Response.

func OK

func OK(payload interface{}) *Response

OK constructs a successful Response with the given payload marshalled to JSON.