ZEO Network Protocol (sans authentication)
This document describes the ZEO network protocol. It assumes that the optional authentication protocol isn’t used. At the lowest level, the protocol consists of sized messages. All communication between the client and server consists of sized messages. A sized message consists of a 4-byte unsigned big-endian content length, followed by the content. There are two subprotocols, for protocol negotiation, and for normal operation. The normal operation protocol is a basic RPC protocol.
In the protocol negotiation phase, the server sends a protocol identifier to the client. The client chooses a protocol to use to the server. The client or the server can fail if it doesn’t like the protocol string sent by the other party. After sending their protocol strings, the client and server switch to RPC mode.
The RPC protocol uses messages that are pickled tuples consisting of:
- message_id
The message id is used to match replies with requests, allowing multiple outstanding synchronous requests.
- async_flag
An integer 0 for a regular (2-way) request and 1 for a one-way request. Two-way requests have a reply. One way requests don’t. ZRS tries to use as many one-way requests as possible to avoid network round trips.
- name
The name of a method to call. If this is the special string “.reply”, then the message is interpreted as a return from a synchronous call.
- args
A tuple of positional arguments or returned values.
After making a connection and negotiating the protocol, the following interactions occur:
The client requests the authentication protocol by calling getAuthProtocol. For this discussion, we’ll assume the server returns None. Note that if the server doesn’t require authentication, this step is optional.
The client calls register passing a storage identifier and a read-only flag. The server doesn’t return a value, but it may raise an exception either if the storage doesn’t exist, or if the storage is readonly and the read-only flag passed by the client is false.
At this point, the client and server send each other messages as needed. The client may make regular or one-way calls to the server. The server sends replies and one-way calls to the client.