[Zodb-checkins] SVN: ZODB/trunk/src/ZEO/protocol.txt provided some minimal documentation of the zeo protocol.

[Jim Fulton]

Log message for revision 102358:
  provided some minimal documentation of the zeo protocol.
  

Changed:
  A   ZODB/trunk/src/ZEO/protocol.txt

-=-
Added: ZODB/trunk/src/ZEO/protocol.txt
===================================================================
--- ZODB/trunk/src/ZEO/protocol.txt	                        (rev 0)
+++ ZODB/trunk/src/ZEO/protocol.txt	2009-07-28 20:07:28 UTC (rev 102358)
@@ -0,0 +1,54 @@
+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
+btween 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 replys 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 athentication protocol by calling .  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 the
+  stroage 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.


Property changes on: ZODB/trunk/src/ZEO/protocol.txt
___________________________________________________________________
Added: svn:eol-style
   + native