resprot

README

Go utilities for communicating with RES Services
Synchronize Your Clients

---

Package resprot provides low level structs and methods for communicating with services using the RES Service Protocol over NATS server.

Installation

go get github.com/jirenius/go-res/resprot

Example usage

Make a request

conn, _ := nats.Connect("nats://127.0.0.1:4222")
response := resprot.SendRequest(conn, "call.example.ping", nil, time.Second)

Get a model

response := resprot.SendRequest(conn, "get.example.model", nil, time.Second)

var model struct {
	Message string `json:"message"`
}
_, err := response.ParseModel(&model)

Call a method

response := resprot.SendRequest(conn, "call.math.add", resprot.Request{Params: struct {
	A float64 `json:"a"`
	B float64 `json:"b"`
}{5, 6}}, time.Second)

var result struct {
	Sum float64 `json:"sum"`
}
err := response.ParseResult(&result)

Documentation

Overview

Package resprot provides low level structs and methods for communicating with services using the RES Service Protocol over NATS server.

https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md

Usage

Make a request:

conn, _ := nats.Connect("nats://127.0.0.1:4222")
response := resprot.SendRequest(conn, "call.example.ping", nil, time.Second)

Get a model:

response := resprot.SendRequest(conn, "get.example.model", nil, time.Second)

var model struct {
	Message string `json:"message"`
}
_, err := response.ParseModel(&model)

Call a method:

response := resprot.SendRequest(conn, "call.math.add", resprot.Request{Params: struct {
	A float64 `json:"a"`
	B float64 `json:"b"`
}{5, 6}}, time.Second)

var result struct {
	Sum float64 `json:"sum"`
}
err := response.ParseResult(&result)

Index

• func MarshalDataValue(v interface{}) ([]byte, error)
• func UnmarshalDataValue(data []byte, v interface{}) error
• type AccessResult
• type AddEvent
• type ChangeEvent
• type EventEntry
• type GetResult
• type QueryEvent
• type QueryRequest
• type QueryResult
• type RemoveEvent
• type Request
• type ResetEvent
• type Response
  • func ParseResponse(data []byte) Response
  • func SendRequest(nc res.Conn, subject string, req interface{}, timeout time.Duration, ...) Response
  • func (r Response) AccessResult() (bool, string, error)
  • func (r Response) HasError() bool
  • func (r Response) HasResource() bool
  • func (r Response) HasResult() bool
  • func (r Response) ParseCollection(collection interface{}) (string, error)
  • func (r Response) ParseModel(model interface{}) (string, error)
  • func (r Response) ParseResult(v interface{}) error
• type TokenEvent

Functions

func MarshalDataValue

func MarshalDataValue(v interface{}) ([]byte, error)

MarshalDataValue returns the JSON encoding of v, similar to json.Marshal.

If v encodes into a JSON object or array, MarshalDataValue will wrap the value in a data object, where the value is stored under the key "data".

MarshalDataValue(42)                        // Returns []byte(`42`)
MarshalDataValue("foo"), v)                 // Returns []byte(`"foo"`)
MarshalDataValue([]string{"foo", "bar"})    // Returns []byte(`{"data":["foo","bar"]}`)
MarshalDataValue(map[string]int{"foo": 42}) // Returns []byte(`{"data":{"foo":42}}`)

MarshalDataValue can be used to implement the json.Marshaler interface:

func (t T) MarshalJSON() ([]byte, error)
	return MarshalDataValue(t)
}

See: https://github.com/resgateio/resgate/blob/master/docs/res-protocol.md#data-values

func UnmarshalDataValue

func UnmarshalDataValue(data []byte, v interface{}) error

UnmarshalDataValue parses the JSON-encoded data and stores the result in the value pointed to by v, similar to json.Unmarshal.

If the JSON data starts with an object, UnmarshalDataValue will use the value of the object key "data" to store in v, or will return an error if the object key "data" does not exist.

If the JSON data start with an array, UnmarshalDataValue will return an error.

UnmarshalDataValue([]byte(`42`), v)                     // sets v to 42
UnmarshalDataValue([]byte(`"foo"`), v)                  // sets v to "foo"
UnmarshalDataValue([]byte(`{"data":true}`), v)          // sets v to true
UnmarshalDataValue([]byte(`{"data":["foo","bar"]}`), v) // sets v to []string{"foo", "bar"}
UnmarshalDataValue([]byte(`{"foo":"bar"}`), v)          // returns error
UnmarshalDataValue([]byte(`[1,2,3]`), v)                // returns error

UnmarshalDataValue can be used to implement the json.Unmarshaler interface:

func (t *T) UnmarshalJSON([]byte) error
	return UnmarshalDataValue(data, t)
}

See: https://github.com/resgateio/resgate/blob/master/docs/res-protocol.md#data-values

Types

type AccessResult

type AccessResult struct {
	Get  bool   `json:"get,omitempty"`
	Call string `json:"call,omitempty"`
}

AccessResult is the result of an access request.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#access-request

type AddEvent

type AddEvent struct {
	Value interface{} `json:"value"`
	Idx   int         `json:"idx"`
}

AddEvent is the payload of a collection add event.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#collection-add-event

type ChangeEvent

type ChangeEvent struct {
	Values map[string]interface{} `json:"values"`
}

ChangeEvent is the payload of a model change event.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#model-change-event

type EventEntry

type EventEntry struct {
	Event string      `json:"event"`
	Data  interface{} `json:"data"`
}

EventEntry is a single event entry in a response to a query request.

type GetResult

type GetResult struct {
	Model      json.RawMessage `json:"model,omitempty"`
	Collection json.RawMessage `json:"collection,omitempty"`
	Query      string          `json:"query,omitempty"`
}

GetResult is the result of a get request.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#get-request

type QueryEvent

type QueryEvent struct {
	Subject string `json:"subject"`
}

QueryEvent is the payload of a query event.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#query-event

type QueryRequest

type QueryRequest struct {
	Query string `json:"query"`
}

QueryRequest is a query request.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#query-request

type QueryResult

type QueryResult struct {
	Events []EventEntry `json:"events"`
}

QueryResult is the result of a query request.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#query-request

type RemoveEvent

type RemoveEvent struct {
	Idx int `json:"idx"`
}

RemoveEvent is the payload of a collection remove event.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#collection-remove-event

type Request

type Request struct {

	// CID is the requesting clients connection ID.
	//
	// Valid for access, call, and auth requests. May be omitted on
	// inter-service requests.
	CID string `json:"cid,omitempty"`

	// Params is the requests parameters.
	//
	// Valid for call and auth requests. May be omitted.
	Params interface{} `json:"params,omitempty"`

	// Token is the RES client's access token.
	//
	// Valid for access, call, and auth requests. May be omitted.
	Token interface{} `json:"token,omitempty"`

	// Header is the request HTTP headers of the client, provided on connect.
	// connect.
	//
	// Valid for auth requests. May be omitted on inter-service requests.
	Header map[string][]string `json:"header,omitempty"`

	// Host is the host on which the URL is sought by the client. Per RFC 2616,
	// this is either the value of the "Host" header or the host name given in
	// the URL itself.
	//
	// Valid for auth requests. May be omitted on inter-service requests. The
	// format is not specified.
	Host string `json:"host,omitempty"`

	// RemoteAddr is the network address of the client, provided on connect.
	//
	// Valid for auth requests. May be omitted on inter-service requests.
	RemoteAddr string `json:"remoteAddr,omitempty"`

	// URI is the unmodified Request-URI of the Request-Line (RFC 2616,
	// Section 5.1) as provided by the client on connect.
	//
	// Valid for auth requests. May be omitted on inter-service requests.
	URI string `json:"uri,omitempty"`

	// Query is the query part of the resource ID without the question mark
	// separator.
	//
	// Valid for access, get, call, auth, and query requests. May be omitted,
	// except for on query requests.
	Query string `json:"query,omitempty"`
}

Request represents the payload of a request.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#requests

type ResetEvent

type ResetEvent struct {
	Resources []string `json:"resources,omitempty"`
	Access    []string `json:"access,omitempty"`
}

ResetEvent is the payload of a system reset event.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#system-reset-event

type Response

type Response struct {

	// Result is the successful result of a request.
	Result json.RawMessage `json:"result"`

	// Resource is a reference to a resource.
	//
	// Valid for responses to call and auth requests.
	Resource res.Ref `json:"resource"`

	// Error is the request error.
	Error *res.Error `json:"error"`
}

Response represents the response to a request.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#response

func ParseResponse

func ParseResponse(data []byte) Response

ParseResponse unmarshals a JSON encoded RES response.

If the response is not valid, the Error field will be set to a *res.Error with code system.internalError.

func SendRequest

func SendRequest(nc res.Conn, subject string, req interface{}, timeout time.Duration, onTimeoutExtend ...func(time.Duration)) Response

SendRequest sends a request over NATS and unmarshals the response before returning it.

If any error is encountered, the Error field will be set.

if req is nil, an empty json object, {}, will be sent as payload instead.

SendRequest handles pre-responses that may extend timeout. See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#pre-response

func (Response) AccessResult

func (r Response) AccessResult() (bool, string, error)

AccessResult returns the get and call values from the response of a successful access request.

func (Response) HasError

func (r Response) HasError() bool

HasError returns true if the response has an error.

func (Response) HasResource

func (r Response) HasResource() bool

HasResource returns true if the response is a resource response.

func (Response) HasResult

func (r Response) HasResult() bool

HasResult returns true if the response is a successful a result response.

func (Response) ParseCollection

func (r Response) ParseCollection(collection interface{}) (string, error)

ParseCollection unmarshals the collection from the response of a successful collection get request.

On success, the get response query value is returned, if one was set.

func (Response) ParseModel

func (r Response) ParseModel(model interface{}) (string, error)

ParseModel unmarshals the model from the response of a successful model get request.

On success, the get response query value is returned, if one was set.

func (Response) ParseResult

func (r Response) ParseResult(v interface{}) error

ParseResult unmarshals the result from the response of a successful request.

type TokenEvent

type TokenEvent struct {
	Token interface{} `json:"token"`
}

TokenEvent is the payload of a connection token event.

See: https://github.com/resgateio/resgate/blob/master/docs/res-service-protocol.md#connection-token-event