jsonFrame
A jsonrpc 2.0 implementation supporting both TCP and HTTP transports. The TCP implementation uses persistent connections and frames each jsonrpc request/response object with a length prefix, which specifies the length in bytes of the actual message; hence the name jsonFrame. Both the client and server must agree on a length prefix.
Why length-prefixing?
TCP is a stream-oriented protocol as opposed to a message-oriented protocol like HTTP. Data is treated as a continuous flow of data and there are no self-delimiting patterns to determine where one message ends and another starts. A few solutions exist to approach this problem:
- Process a stream of JSON-encoded strings by reading each character, counting and matching
}
, and eventually parsing usingJSON.parse
. Writing a hand-coded JSON parser is ought to be slower than the nativeJSON.parse
method. - Using a delimiter like
\n
to delimit each JSON-encoded message. However, one must also deal with the delimiter appearing in the message itself. For e.g.,{"method":"sendMessage","params":["Hello, \n jsonrpc"],"jsonrpc":"2.0"}\n
- In Length-prefixing, each message is sent by prefixing it with the number of bytes contained in the message. This allows an application to receive a message by first reading the length-prefix and then reading as many bytes as the value of length-prefix. It requires the client and server to agree on a length-prefix.
Package
- JSON-RPC TCP server and client
- Connect middleware for HTTP
application/json-*
POST requests - jQuery function plugin for HTTP transport
jsonTransformer
: A node.js streams2 Transform implementation that reads length-prefixed messages built usingjsonFrame.build(message)
Usage
var methods = { return Arrayprototypeslice; } var jFrame = jsonFrame = rpcServer = jsonFrame //TcpJsonRpcServerrpcClient = jsonFrame; //TcpJsonRpcClient rpcServer;
Simple requests
rpcClient; //Parameters for methods taking arrays as arguments rpcClient; //Error handling with appropriate jsonrpc 2.0 error codes and messages rpcClient; //Method with no parameters rpcClient; rpcClient;
Batch requests
A batch invoke operation receives a batch callback. Request objects are added to batch using add
and notify
.
The batch builder received in callback is chainable and has a fluent interface allowing calls of the form:
batch
Response handler is invoked with as many arguments as the no. of non-notification requests, in the order in which they were add
ed to batch. Each of the response object has either a response property or an error property for failed requests.
rpcClient;
Notifications
JSON-RPC notifications signify the client's lack of interest in the corresponding response object. As such, they do not receive a response object and an invocation must not pass a callback.
rpcClient; rpcClient; rpcClient;
JSON-RPC Connect Middleware
A Connect Middleware for handling JSON-RPC requests. The middleware must be configured with an object containing the methods you wish to invoke. The middleware depends on bodyParser
middleware and must be configured after it.
Example
var jsonFrame = ;//... other middlewares app; //or express.bodyParser() using express app;
jsonTransformer
A streams 2 Transform implementation that can be pipe
d to any stream.Readable
stream . You'd never have to explicitly use it for serving jsonrpc clients. It can be used for applications that want to process a stream of JSON-encoded strings with each string prefixed with a length, in bytes, of the JSON message.
For each JSON-encoded string, jsonTransformer emits a data
event with the parsed JSON. Malformed JSON strings that are not valid according to the JSON grammar receive a parse error
event.
Example
var jsonFrame = jsonTransformer = jsonFrame; someReadable; jsonTransformer ; var socket = net; socket; jsonTransformer; net;
jQuery JSON-RPC Function Plugin
HTTP counterpart of TcpJsonRpcClient
; supports the same methods: invoke
, notify
var $jsonrpc = $; $jsonrpc; $jsonrpc; $jsonrpc;