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 originalreceive_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.
- context – A context returned by
-
-
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 originalreceive_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.
- context – A context returned by
-
classmethod
-
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.
-
classmethod
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 anHTTP
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.
- endpoint – The URL to send
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 tosend_reply()
.The parameter
queue_class
must be used to supply a proper queue class for the chosen concurrency mechanism (i.e. when usinggevent
, set it togevent.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 originalreceive_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.
- context – A context returned by
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”¶ms={“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 originalreceive_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.
- context – A context returned by
-
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()
andsend_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 onsend_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 originalreceive_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.
- context – A context returned by
-