\= ROME: RPC Over Mangos/MsgPack Encapsulation
image:https://img.shields.io/github/workflow/status/nanomsg/rome/linux?logoColor=grey&logo=ubuntu&label=\[Linux Status,link="https://github.com/nanomsg/rome/actions"\] image:https://img.shields.io/github/workflow/status/nanomsg/rome/windows?logoColor=grey&logo=windows&label=\[Windows Status,link="https://github.com/nanomsg/rome/actions"\] image:https://img.shields.io/github/workflow/status/nanomsg/rome/darwin?logoColor=grey&logo=apple&label=\[Darwin Status,link="https://github.com/nanomsg/rome/actions"\] image:https://img.shields.io/codecov/c/github/nanomsg/rome?logoColor=grey&logo=codecov&label=\[Coverage,link="https://codecov.io/gh/nanomsg/rome"\] image:https://img.shields.io/codacy/grade/619d463a779d4b20bcf653323dee9a73?logoColor=grey&logo=codacy&label=\[Code Quality,link="https://app.codacy.com/gh/nanomsg/rome/dashboard"\] image:https://img.shields.io/badge/godoc-docs-blue.svg?label=&logo=go\[GoDoc,link="https://godoc.org/go.nanomsg.org/rome"\] image:https://img.shields.io/github/license/nanomsg/mangos.svg?logoColor=silver&logo=Open Source Initiative&label=&color=blue[Apache 2.0 License,link="https://github.com/nanomsg/rome/blob/master/LICENSE"\] image:https://img.shields.io/discord/639573728212156478?label=&logo=discord\[Discord,link="https://discord.gg/wewTkby"\]
As with Roman civilization, we hope that this will be a foundation that will enable even greater things to be built.
This is early work at this stage. We expect the API may evolve over the next week or so, as we add functionality, examples, and test coverage.
== Protocol Packaging Format
We are inspired by JSON-RPC v2.0, and use that as the basis for our work. However, JSON-RPC v2.0 offers capabilities that few use, requiring extra complexity, and for which we find little use. Consequently, our approach represents a minimalist subset of JSON-RPC, modified to use msgpack and mangos for transport. We also have made changes intended to allow for higher performance by not requiring that messages be encoded using strings.
=== No Batching
Our protocol does not offer at this time any support for batching requests. Applications that need batching may do so by presenting a batch API at their application layer.
=== No Notifications
Mangos requires a reply, always. We will use other patterns (PUB/SUB, SURVEYOR) when strict one reply to one request is not needed.
=== Use mangos request IDs
Mangos already embeds a request ID at it's layer. So we do not provide support for application supplied request IDs. This prevents us from having to concern ourselves with some of the dodgier parts of the JSON-RPC specification.
The RPC framework builds upon REQ/REP in mangos. This implementation uses separate contexts to provide for concurrency both in the client and in the server. (Server side concurrency is tunable.)
We use context.Context on the client side to provide for request timeouts and cancellation, although note that at present cancellation events are not propagated to the server as the protocol does not have any way to express this.
Messages are sent as an array for performance reasons.
|=== |Index|Field|Description |0|Version|This is an integer and must have the value 1 for this specification. |1|Method|This is the method name, presented as a string. |2|Parameters|This is the parameters for the method. |===
The method name is normally encoded as the name of the enclosing structure concatenated joined with the actual method name using a period. For example, "`MyStructure.MyFunction`". Implementations may override this name. Names beginning with two underscores ("`__`") are reserved for use by this specification. Names beginning with a single underscore are reserved for implementation use.
Applications needing to ensure globally unique names are encouraged to use reverse-DNS style naming, e.g. "`org.nanomsg.go.rome.Accumulator`". (This however comes at a performance cost, and many applications may find it simpler to just use very short names.)
The parameters may be any valid MsgPack value, including `null`, simple data types, maps, and arrays.
|=== |Index|Field|Description |0|Version|As with requests, this is an integer value 1. |1|Success|This boolean indicates whether the call succeeded. |2|Result|This will either be an Error object (if Success is false), or the results from a successful call. |===
==== Error objects
In order to facilitate consistent error handling, we have structure for errors. These error objects are also arrays.
|=== |Index|Field|Description |0|Code|An integer error code representing the error. Some errors are reserved, see below. |1|Message|A string with a human-readable message. |2|Details|Additional information about the error. This is specific to each error, and may be used to convey any payload needed. |===