Documentation ¶
Overview ¶
Package resprot provides low level structs and methods for communicating with services using the RES Service Protocol over NATS server.
https://gitlab.com/apconsulting/pkgs/res/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 (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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MarshalDataValue ¶
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://gitlab.com/apconsulting/pkgs/res/resgate/blob/master/docs/res-protocol.md#data-values
func UnmarshalDataValue ¶
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://gitlab.com/apconsulting/pkgs/res/resgate/blob/master/docs/res-protocol.md#data-values
Types ¶
type AccessResult ¶
AccessResult is the result of an access request.
type AddEvent ¶
type AddEvent struct { Value interface{} `json:"value"` Idx int `json:"idx"` }
AddEvent is the payload of a collection add event.
type ChangeEvent ¶
type ChangeEvent struct {
Values map[string]interface{} `json:"values"`
}
ChangeEvent is the payload of a 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.
type QueryEvent ¶
type QueryEvent struct {
Subject string `json:"subject"`
}
QueryEvent is the payload of a query event.
type QueryRequest ¶
type QueryRequest struct {
Query string `json:"query"`
}
QueryRequest is a query request.
type QueryResult ¶
type QueryResult struct {
Events []EventEntry `json:"events"`
}
QueryResult is the result of a query request.
type RemoveEvent ¶
type RemoveEvent struct {
Idx int `json:"idx"`
}
RemoveEvent is the payload of a 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://gitlab.com/apconsulting/pkgs/res/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.
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://gitlab.com/apconsulting/pkgs/res/resgate/blob/master/docs/res-service-protocol.md#response
func ParseResponse ¶
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://gitlab.com/apconsulting/pkgs/res/resgate/blob/master/docs/res-service-protocol.md#pre-response
func (Response) AccessResult ¶
AccessResult returns the get and call values from the response of a successful access request.
func (Response) HasResource ¶
HasResource returns true if the response is a resource response.
func (Response) HasResult ¶
HasResult returns true if the response is a successful a result response.
func (Response) ParseCollection ¶
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 ¶
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 ¶
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.