Simple Remote Procedure Call - Batch

SRPC-Batch is an extension to SRPC. The batch-mode carries multiple remote procedure calls in a single transaction. The global "Method" indicates the batch mode. Individual RPCs are prefixed by an index, e.g. "1:Method=...".

Example:

1. C: Method=Batch
2. C: 0:Method=GetQuote
3. C: 0:Symbol=GOOG
4. C: 1:Method=GetQuote
5. C: 1:Symbol=APPL

1. S: Status=1
2. S: 0:Status=1
3. S: 0:Average=123
4. S: 0:Low=121
5. S: 0:High=125
6. S: 1:Status=1
7. S: 1:Average=456
8. S: 1:Low=455
9. S: 1:High=457

Rationale:

In rare cases clients want to execute not just one, but multiple commands. This saves network bandwidth and roundtrip time, especially on SSL connections. It also allows a batch of RPCs to be executed consecutively. We are using batch commands also to store them in the database and execute multiple commands on request.

Details:

• the request has a "Method=Batch",
• the request contains multiple remote procedure calls,
• parameters of individual RPCs are prefixed by an index N and a colon: "N:", e.g. "1:",
• the index indicates individual RPCs,
• all parameters of an individual RPC have the same index,
• the index starts with "0" (zero),
• each RPC has a "Method" parameter (1:Method=...),
• meta parameters as usual: "1:Symbol/Encoding=cstring",
• the response has a "Status=..." (0/1) indicating success of the batch-parser,
• the response carries a "Status" for each individual request,
• result parameters use the same syntax as the requests (1:Status=...),
• RPC results have the the same index as the corresponding request,
• the receiver executes ALL commands and returns their result even if some fail.
  

Comments:

• the batch-extension is optional. It is not required for receivers. Better ask your server if it is supported,
• in additon to "Method", the request may have additional "global" parameters.
  

VPTN 2 und 3

Endlich am Wochenende auf dem Barcamp Köln die Spezifikation für "Virtual Presence User Data" fertiggestellt. Zusammen mit "Vitual Presence Location Mapping" die Grundlage für ein globales, verteiltes und chatsystemübergreifendes VP-System. 

OpenID und FOAF sind sehr eng verwandt mit VP-Identity und können vermutlich sinnvoll integriert werden. OpenID hat ein Konzept für selektive Veröffentlichung. Das fehlt bisher bei VP-Identity und FOAF. FOAF gibt es schon lange. Es ist ziemlich weit entwickelt, hat aber nie den Mainstream erreicht. OpenID ist sehr jung, aber auf dem Weg zum Mainstream. OpenID Services könnten als VP-Identity Item integriert werden, FOAF ebenfalls. Vor allem FOAF hätte auch das Potential als VP-Identity Format. Dafür müsste man FOAF erweitern um Features, wie VP-Identity Digest. VP-Identity ist eine gute Grundlage. Mal sehen was noch kommt. 

_happy_coding()

Simple Remote Procedure Call

In my projects we often use remote procedure calls. We use various kinds, SOAP, XMLRPC, REST, JSON, conveyed by different protocols (HTTP, XMPP, even SMTP). We use whatever is appropriate in the situation, be it client-server, server-service, client-p2p, and depending on the code environment C++, C#, JScript, PHP.
With SOAP and XMLRPC you don't want to generate or parse SOAP-XML by hand. That's an avoidable error source. Rather you use a library, which does the RPC-encoding/decoding job. To do that you have to get used to the lib's API, modes of operations, and its quirks.
This is significant work until you are really in "complete advanced control" of the functionality. Especially, if there is only a method name with paramaters to exchange. Even more bothersome is the fact, that most such libraries need megabytes, have their own XML parser, their own network components. Stuff, we already have in our software for other purposes.
What we really need is a simple way to execute remote procedure calls

• with an encoding so easy and fail safe, that it needs no library to en/decode,
• that is so obvious, that we do not need an industry standard like SOAP, just to tell other
  developers what the RPC means.

The solution is a list of key-value pairs. This is Simple RPC (SRPC):

• request and response are lists of key-value pairs,
• each parameter is key=value
• parameters separated by line feed
• request as HTTP-POST body or HTTP-GET with query
• response as HTTP response body
• Content-type text/plain
• all UTF-8
• values must be single line (must not contain line feeds)
• request method as Method=

Example (I love stock quote examples):
HTTP-POST request body:

1. C: POST /srpc.php HTTP/1.1
2. C: Content-type: text/plain; charset=UTF-8
3. C: Content-length: 43
4. C:
5. C: Method=GetQuote
6. C: Symbol=GOOG
7. C: Date=1969-07-21

HTTP response body:

1. S: HTTP/1.1 200 OK
2. S: Content-type: text/plain; charset=UTF-8
3. S:
4. S: Status=1
5. S: Average=123
6. S: Low=121
7. S: High=125

Additional options:
1. Multiline Values:
Of course, there are sometimes line feeds in RPC arguments and results. Line feeds must be encoded using HTTP-URL encoding (%0A) or a better readable "cstring" encoding (\n). The encoding is specified as meta parameter:

1. News=Google%20Introduces%20New...%0AAnalyst%20says...
2. News/Encoding=URL

or:

1. News=Google Introduces New...\nAnalyst says...
2. News/Encoding=cstring

The "cstring" encoding replaces carriage-return (\n), line-feed (\r), and back-slash (\\). The "cstring" encoding indication, e.g. "News/Encoding=cstring" may be omitted.
2. Binary Values:
Binary values in requests and responses are base64 encoded. An optional "Type" uses MIME types to indicate the data type in case of e.g. image data.

1. Chart=R0lGODlhkAH6AIAAAOfo7by/wCH5BA... (base64 encoded GIF)
2. Chart/Encoding=base64
3. Chart/Type=image/gif

3. The Query Variant:
Even complex result values, such as XML data, must be single line. Following the scheme above, this can be done by using "base64" or "cstring" encoding. Both are not easily readable in case of XML. SRPC offers a simpler way to return a single result value: if the request is HTTP-GET with query then the result value comes as response body with Content-type. It's a normal HTTP request, but SRPC conform.
HTTP query:

1. C: GET /srpc.php?Method=GetPrices&Symbol=GOOG&Date=1969-07-21 HTTP/1.1

HTTP response (with a sample xml as a single result value):

1. S: HTTP/1.1 200 OK
2. S: Content-type: text/xml
3. S:
4. S: <?xml version="1.0"?>
5. S: <prices>
6. S: <price time="09:00">121.10</price>
7. S: <price time="09:05">121.20</price>
8. S: </prices>

4. Special Keys
There are 3 special keys defined:

• request "Method=FunctionName" (RPC method)
• response "Status=1" (1=OK, 0=error)
• response "Message=An explanation" (an accompanying explanation for Status=0 or 1)

This Simple RPC specifies exactly how RPC requests are encoded. It's just lists of key=value pairs. But still powerful enough for all RPCs we need.
happy_coding()