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.
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.
-
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.
-
classmethod
HTTP¶
There is only an HTTP client, no server (use WSGI instead).
-
class
tinyrpc.transports.http.
HttpPostClientTransport
(endpoint, **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. - kwargs – Additional parameters for
requests.post()
.
- endpoint – The URL to send
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.