Transports

Transports are somewhat low level interface concerned with transporting messages across through different means. “Messages” in this case are simple strings. All transports need to support two different interfaces:

class tinyrpc.transports.ServerTransport

Base class for all server transports.

receive_message()

Receive a message from the transport.

Blocks until another message has been received. May return a context opaque to clients that should be passed on send_reply() to identify the client later on.

Returns:A tuple consisting of (context, message).
send_reply(context, reply)

Sends a reply to a client.

The client is usually identified by passing context as returned from the original receive_message() call.

Messages must be strings, it is up to the sender to convert the beforehand. A non-string value raises a TypeError.

Parameters:
  • context – A context returned by receive_message().
  • reply – A string to send back as the reply.
class tinyrpc.transports.ClientTransport

Base class for all client transports.

send_message(message, expect_reply=True)

Send a message to the server and possibly receive a reply.

Sends a message to the connected server.

Messages must be strings, it is up to the sender to convert the beforehand. A non-string value raises a TypeError.

This function will block until one reply has been received.

Parameters:message – A string to send.
Returns:A string containing the server reply.

Note that these transports are of relevance when using tinyrpc-built in facilities. They can be coopted for any other purpose, if you simply need reliable server-client message passing as well.

Also note that the client transport interface is not designed for asynchronous use. For simple use cases (sending multiple concurrent requests) monkey patching with gevent may get the job done.

Transport implementations

A few transport implementations are included with tinyrpc:

0mq

Based on zmq, supports 0mq based sockets. Highly recommended:

class tinyrpc.transports.zmq.ZmqServerTransport(socket)

Server transport based on a zmq.ROUTER socket.

Parameters:socket – A zmq.ROUTER socket instance, bound to an endpoint.
classmethod create(zmq_context, endpoint)

Create new server transport.

Instead of creating the socket yourself, you can call this function and merely pass the zmq.core.context.Context instance.

By passing a context imported from zmq.green, you can use green (gevent) 0mq sockets as well.

Parameters:
  • zmq_context – A 0mq context.
  • endpoint – The endpoint clients will connect to.
receive_message()

Receive a message from the transport.

Blocks until another message has been received. May return a context opaque to clients that should be passed on send_reply() to identify the client later on.

Returns:A tuple consisting of (context, message).
send_reply(context, reply)

Sends a reply to a client.

The client is usually identified by passing context as returned from the original receive_message() call.

Messages must be strings, it is up to the sender to convert the beforehand. A non-string value raises a TypeError.

Parameters:
  • context – A context returned by receive_message().
  • reply – A string to send back as the reply.
class tinyrpc.transports.zmq.ZmqClientTransport(socket)

Client transport based on a zmq.REQ socket.

Parameters:socket – A zmq.REQ socket instance, connected to the server socket.
classmethod create(zmq_context, endpoint)

Create new client transport.

Instead of creating the socket yourself, you can call this function and merely pass the zmq.core.context.Context instance.

By passing a context imported from zmq.green, you can use green (gevent) 0mq sockets as well.

Parameters:
  • zmq_context – A 0mq context.
  • endpoint – The endpoint the server is bound to.
send_message(message, expect_reply=True)

Send a message to the server and possibly receive a reply.

Sends a message to the connected server.

Messages must be strings, it is up to the sender to convert the beforehand. A non-string value raises a TypeError.

This function will block until one reply has been received.

Parameters:message – A string to send.
Returns:A string containing the server reply.

HTTP

There is only an HTTP client, no server (use WSGI instead).

class tinyrpc.transports.http.HttpPostClientTransport(endpoint, post_method=None, **kwargs)

HTTP POST based client transport.

Requires requests. Submits messages to a server using the body of an HTTP POST request. Replies are taken from the responses body.

Parameters:
  • endpoint – The URL to send POST data to.
  • post_method – allows to replace requests.post with another method, e.g. the post method of a requests.Session() instance.
  • kwargs – Additional parameters for requests.post().
send_message(message, expect_reply=True)

Send a message to the server and possibly receive a reply.

Sends a message to the connected server.

Messages must be strings, it is up to the sender to convert the beforehand. A non-string value raises a TypeError.

This function will block until one reply has been received.

Parameters:message – A string to send.
Returns:A string containing the server reply.

Note

To set a timeout on your client transport provide a timeout keyword parameter like:

transport = HttpPostClientTransport(endpoint, timeout=0.1)

It will result in a requests.exceptions.Timeout exception when a timeout occurs.

WSGI

class tinyrpc.transports.wsgi.WsgiServerTransport(max_content_length=4096, queue_class=<class 'queue.Queue'>, allow_origin='*')

WSGI transport.

Requires werkzeug.

Due to the nature of WSGI, this transport has a few pecularities: It must be run in a thread, greenlet or some other form of concurrent execution primitive.

This is due to handle() blocking while waiting for a call to send_reply().

The parameter queue_class must be used to supply a proper queue class for the chosen concurrency mechanism (i.e. when using gevent, set it to gevent.queue.Queue).

Parameters:
  • max_content_length – The maximum request content size allowed. Should be set to a sane value to prevent DoS-Attacks.
  • queue_class – The Queue class to use.
  • allow_origin – The Access-Control-Allow-Origin header. Defaults to * (so change it if you need actual security).
handle(environ, start_response)

WSGI handler function.

The transport will serve a request by reading the message and putting it into an internal buffer. It will then block until another concurrently running function sends a reply using send_reply().

The reply will then be sent to the client being handled and handle will return.

receive_message()

Receive a message from the transport.

Blocks until another message has been received. May return a context opaque to clients that should be passed on send_reply() to identify the client later on.

Returns:A tuple consisting of (context, message).
send_reply(context, reply)

Sends a reply to a client.

The client is usually identified by passing context as returned from the original receive_message() call.

Messages must be strings, it is up to the sender to convert the beforehand. A non-string value raises a TypeError.

Parameters:
  • context – A context returned by receive_message().
  • reply – A string to send back as the reply.

CGI

class tinyrpc.transports.cgi.CGIServerTransport

CGI transport.

Reading stdin is blocking but, given that we’ve been called, something is waiting. The transport accepts both GET and POST request.

A POST request provides the entire JSON-RPC request in the body of the HTTP request.

A GET request provides the elements of the JSON-RPC request in separate query parameters and only the params field contains a JSON object or array. i.e. curl ‘http://server?jsonrpc=2.0&id=1&method=”doit”&params={“arg”=”something”}’

receive_message()

Receive a message from the transport.

Blocks until another message has been received. May return a context opaque to clients that should be passed on send_reply() to identify the client later on.

Returns:A tuple consisting of (context, message).
send_reply(context, reply)

Sends a reply to a client.

The client is usually identified by passing context as returned from the original receive_message() call.

Messages must be strings, it is up to the sender to convert the beforehand. A non-string value raises a TypeError.

Parameters:
  • context – A context returned by receive_message().
  • reply – A string to send back as the reply.

Callback

class tinyrpc.transports.callback.CallbackServerTransport(reader, writer)

Callback server transport.

Used when tinyrpc is part of a system where it cannot directly attach to a socket or stream. The methods receive_message() and send_reply() are implemented by callback functions that were passed to __init__().

This transport is also useful for testing the other modules of tinyrpc.

receive_message()

Receive a message from the transport.

Uses the callback function reader to obtain a json string. May return a context opaque to clients that should be passed on send_reply() to identify the client later on.

Returns:A tuple consisting of (context, message).
send_reply(context, reply)

Sends a reply to a client.

The client is usually identified by passing context as returned from the original receive_message() call.

Messages must be a string, it is up to the sender to convert it beforehand. A non-string value raises a TypeError.

Parameters:
  • context – A context returned by receive_message().
  • reply – A string to send back as the reply.