Overview

The protocol is based on JSON and Spread. The idea is simple: Spread creates a unified message bus for distributed applications; SpreadRPC manages the spread messages and creates a really simple RPC implementation for these distributed applications. Any message from/to the applications is JSON.

The SpreadRPC mechanism doesn't use two peers but a spread ring. There is not a client and a server, but a list of distribuited applications that could implement the same methods or, the same methods with different parameters. For that reason, for any request, SpreadRPC has to expect 0, or N responses.

Call Requests

A normal request is a JSON object like this:

{ 
  "version" : "0.1",
  "id" : {
    "id" : "client abc",
    "pid" : 1
  },
  "type" : "CALL",
  "method" : "echo",
  "params" : [ 
    { "var 1" : "hello world!" },
    { "var 2" : true }
  ]
}

This object always contains a version attribute about the protocol release. It is a string (default: 0.1).

Another part of this the "id": a JSON object with the ID of the client (string) and the pid (progress Id), a unique numeric value. This JSON object must be part of the response.

The type string contains a description of the request. This request calls a method and the type is "CALL".

The method string is the method name.

Params is an array of object. Any object is a key/value where the "key" is the name of the variable and the value is a JSON value for that variable. Params can be empty.

Call Responses

A normal response for a call request is a JSON object like this:

{ 
  "version" : "0.1",
  "id" : {
    "id" : "client abc",
    "pid" : 1
  },
  "type" : "RESPONSE",
  "params" : [
    { "var 1" : "hello world!" },
  ]
}

This object always contains a version attribute about the protocol release. It is a string (default: 0.1).

The object "id" is from the call request.

Type contains "RESPONSE".

Params is an array of object. Any object is a key/value where the "key" is the name of the variable and the value is a JSON value for that variable. Params can be empty.

"Exists" Requests

The "Exists" request is useful to know if a method exists or not.

{
  "version" : "0.1",
  "id" : {
    "id" : "client abc",
    "pid" : 1
  },
  "type" : "EXIST",
  "method" : "echo"
}

The format is the same of the call requests but the type is "EXIST" and there is not params.

"Exists" Responses

A normal response for this request is a JSON object like this:

{ 
  "version" : "0.1",
  "id" : {
    "id" : "client abc",
    "pid" : 1
  },
  "type" : "RESPONSE",
  "params" : [
    { "exists" : true }
  ]
}

The responses will have a standard format like the "call responses" but the params will contain only 1 value: exists, boolean always "true". Only the applications with that method will response.

List Requests

This request returns the list of the methods for application.

{
  "version" : "0.1",
  "id" : {
    "id" : "client abc",
    "pid" : 1
  },
  "type" : "LIST"
}

The format is the same of the call requests but the type is "LIST" and there is not params and method.

List Responses

A normal response for this request is a JSON object like this:

{ 
  "version" : "0.1",
  "id" : {
    "id" : "client abc",
    "pid" : 1
  },
  "type" : "RESPONSE",
  "params" : [
    {
      "method_name" : {
        "description" : "description",
        "params" : [
	  { "variable name" : "variable value" }
	 ]
      }
    }
  ]
}

The params will contain objects. Any object has a item called as the method and the values is an object for the description of it. The description object contains: description (a string), params (array of key/value for the variables).

"Params" Requests

This request returns a list of params for a method.

{
  "version" : "0.1",
  "id" : {
    "id" : "client abc",
    "pid" : 1
  },
  "type" : "PARAMS",
  "method" : "echo"

}

It has only the method name and the type to "PARAMS".

"Params" Responses

A normal response for this request is a JSON object like this:

{ 
  "version" : "0.1",
  "id" : {
    "id" : "client abc",
    "pid" : 1
  },
  "type" : "RESPONSE",
  "params" : [
    { "variable" : "value" },
    { "variable" : "value" }
  ]
}

The params will key/value for the variables.