txjason

Description

An interface for writing JSON-RPC 2.0 servers and clients in Twisted.

Features

• JSON-RPC 2.0 compliant (including batch operations for the server).

• Support for Netstrings over TCP transport. (HTTP is not supported)

• Easily extensible for other transports, such as TLS, curvecp, websockets, etc.

Server Usage

Define a factory and handler, and add the handler to the factory:

from twisted.internet import defer
from txjason import handler
from txjason.netstring import JSONRPCServerFactory


class Example(handler.Handler):
    # export the echo2 method as 'echo'
    @handler.exportRPC('echo')
    def echo2(self, param):
        return param

    # exported methods may return a deferred
    @handler.exportRPC()
    def deferred_echo(self, param):
        return defer.succeed(param)

factory = JSONRPCServerFactory()
factory.addHandler(Example(), namespace='main')

The factory can then be used in a .tac, twistd plugin, or anywhere else a server factory is normally found. The RPC methods will be exported as 'main.echo' and 'main.deferred_echo'.

The server can be forced to serve a predefined exception by invoking the service's stopServing method, with the exception class to serve. If no exception class is passed, a ServiceUnavailableError will be used. This method can be used to gracefully suspend the service (e.g., in preparation for shutdown), without destroying in-progress requests.

from txjason.service import JSONRPCError


class CustomError(JSONRPCError):
    code = -32050
    message = 'Custom Error'

...

factory.service.stopServing(CustomError)

Requests to all methods will now receive an error response.

If the timeout parameter is passed to the Factory, a "Timeout Error" will be returned to the client after the specified number of seconds have elapsed:

factory = JSONRPCServerFactory(timeout=2)

At any time, all pending requests may be cancelled:

factory.service.cancelPending()

Client Usage

Given a reactor reactor:

from twisted.internet import endpoints
from txjason.netstring import JSONRPCClientFactory


endpoint = endpoints.TCP4ClientEndpoint(reactor, '127.0.0.1', 7080)
client = JSONRPCClientFactory(endpoint, reactor=reactor)

d = client.callRemote('main.echo', 'foo')
d.addBoth(someFunction)

No connection step is necessary; JSONRPCClientFactory will automatically connect and reconnect when needed. Disconnections are logged with Twisted's logging system.

For a non-twisted/blocking JSON-RPC over Netstrings client, try jsonrpc-ns

Running the Examples

To run the provided examples, first start the example server in a shell:

twistd -noy examples/server.tac

Then run the client:

python examples/client.py

Running the Tests

trial txjason.tests

txjason vs txjsonrpc

Here are some differences between txjason and txjsonrpc:

• txjason only supports JSON-RPC version 2. txjsonrpc only supports JSON-RPC version 1.
• txjsonrpc supports JSON-RPC over HTTP as well as Netstrings. txjason only supports Netstrings.