Remod JSON RPC draft

Remod implementation based on JSON-RPC 2.0 version. Network part implemented in plain sockets and because of that there no support of https protocol.

• Remod server can listen incoming JSON connection
• Remod server can establish outcoming JSON connections
• Remote clients can subscribe to remod events

Incoming JSON connection

Setup

Configuration parameters in server-init.cfg

jsonrpc 1
jsonport 8082
jsonauth kdhgkjhstyda56s75d634
jsonauth fjkhkj65o73498623fhgs

• jsonrpc - 0 or 1 enable incoming JSON-RPC connections
• jsonport - TCP port to listen
• jsonauth - user defined token to access server RPC, if in config file no jsonauth command then anonymous connections allowed;

Authentication

At first remote client should authorize, if in config not single jsonauth that mean remod JSON act in anonymous mode and accept any connections.

POST / HTTP/1.1
Content-Type: application/json-rpc
Content-Length: ...

{
    "jsonrpc": "2.0",
    "method": "authenticate",
    "params": {
        "token": "kdhgkjhstyda56s75d634"
    },
    "id": 0
}

If match match to any jsonauth or remod JSON act in anonymous mode then answer is successful

HTTP/1.1 200 OK
Server: Remod
Content-Type: application/json-rpc
Content-Length: ...

{
    "jsonrpc": "2.0",
    "result": 1,
    "error": null,
    "id": 0
}

If token not match then server return authorization failure

HTTP/1.1 403 OK
Server: Remod
Content-Type: application/json-rpc
Content-Length: ...

{
    "jsonrpc": "2.0",
    "result": null,
    "error": "Authentication failure",
    "id": 0
}

Simple communication

After successful authentication remod can recive commands and execute it as cubescript.

Next example show how to get list of all client numbers on server.

Client request

{
    "jsonrpc": "2.0",
    "method": "listclients",
    "params": [],
    "id": 1
}

Server answer

{
    "jsonrpc": "2.0",
    "result": "1 2 3 5 7 13",
    "error": null,
    "id": 1
}

Next example show how to create custom function which return data.

At start in any .cfg file create following cubescript function

jsonrpc_test_params = [
    ret = (format "RPC test: arg1=%1, arg2=%2" $arg1 $arg2)
    result $ret
]

After that our server able to execute that code and return result string. On local machine we can execute that code with follow line test = (jsonrpc_test_params "a1" "a2") and get in $test variable value RPC test: arg1=a1, arg2=a2. The code before is equivalent next JSON-RPC request

{
    "jsonrpc": "2.0",
    "method": "jsonrpc_test_params",
    "params": [
        "a1",
        "a2"
    ],
    "id": 2
}

Server anser

{
    "jsonrpc": "2.0",
    "result": "RPC test: arg1=a1, arg2=a2",
    "error": null,
    "id": 2
}

Outcoming JSON connections

For work with other server or web application at first you need establish connection and authenticate

For create connection you need to use follow cubescript code

handle = (jsonconnect "http://api.server.org:8082/remod/rpc" "kdhgkjhstyda56s75d634")

handle is handler of established connection, if handler below 0 it mean some error.

handle value is:

• above 0 - no error
• -1 - connection error
• -2 - authentication error)

Code above do follow http requests:

POST /remod/rpc HTTP/1.1
Host: api.server.org:8082
Content-Type: application/json-rpc
Content-Length: ...

{
    "jsonrpc": "2.0",
    "method": "authenticate",
    "params": {
        "token": "kdhgkjhstyda56s75d634"
    },
    "id": 0
}

Then we get answer about successful authentication:

HTTP/1.1 200 OK
Content-Type: application/json-rpc
Content-Length: ...

{
    "jsonrpc": "2.0",
    "result": 1,
    "error": null,
    "id": 0
}

After successful authentication we can send JSON-RPC request with follow cubescript code:

jsonsend $handle 0 "updateStatus" "online" 5 6 8 9 "server 5"

Syntax of jsonsend command is follow:

jsonsend [notification] [handle] [method] [params]

• notification - can be 0 or 1, if notification is 1 then to request will be added id field, it mean that response from remote client is necessarily, otherwise there no response from remote client.
• handle - connection handler, created by jsonconnect command.
• method - method name to put in request
• params - list of parameters to put in request

Code above will produce next JSON code:

POST /remod/rpc HTTP/1.1
Host: api.server.org:8082
Content-Type: application/json-rpc
Content-Length: ...

{
    "jsonrpc": "2.0",
    "method": "updateStatus",
    "params": [ "online", "5", "6", "8", "9", "server 5" ]
}

Subscribe to events