Add docs for framing

aiorpcx/framing.py

@@ -57,15 +57,15 @@ def messages(self, data):
 class NewlineFramer(FramerBase):
     '''A framer for a protocol where messages are separated by newlines.'''
 
-    def __init__(self, max_size=250*500):
+    def __init__(self, max_size=250*4000):
         '''max_size - an anti-DoS measure.  If, after processing an incoming
         message, buffered data would exceed max_size bytes, that
         buffered data is dropped entirely and the framer waits for a
         newline character to re-synchronize the stream.
         '''
         # The default max_size value is motivated by JSONRPC, where a
         # normal request will be 250 bytes or less, and a reasonable
-        # batch may contain 500 requests.
+        # batch may contain 4000 requests.
         self.max_size = max_size
         self.parts = []
         self.synchronizing = False

aiorpcx/rpc.py

@@ -100,7 +100,6 @@ class RPCResponse(object):
     '''
 
     def __init__(self, result, request_id):
-        assert request_id is not None
         # result is an RPCError object if an error was returned
         self.result = result
         self.request_id = request_id

docs/framing.rst

@@ -0,0 +1,45 @@
+.. currentmodule:: aiorpcx
+
+Framing
+=======
+
+Message :dfn:`framing` is the method by which RPC messages are wrapped
+in a byte stream so that message boundaries can be determined.
+
+:mod:`aiorpcx` provides an abstract base class for framers, and a
+single implementation: :class:`NewlineFramer`.  A framer must know how
+to take outgoing messages and frame them, and also how to break an
+incoming byte stream into message frames in order to extract the RPC
+messages from it.
+
+.. class:: FramerBase
+
+  Derive from this class to implement your own message framing
+  methodology.
+
+  .. method:: frame(messages)
+
+    Frame each message and return the concatenated result.
+
+    :param message: an iterable; each message should be of type
+                    :class:`bytes` or :class:`bytearray`
+    :return: the concatenated bytestream
+    :rtype: bytes
+
+  .. method:: messages(data)
+
+    :param data: incoming data of type :class:`bytes` or
+                 :class:`bytearray`
+    :raises MemoryError: if the internal data buffer overflows
+
+    .. note:: since this may raise an exception, the caller should
+              process messages as they are yielded.  Converting the
+              messages to a list will lose earlier ones if an
+              exception is raised later.
+
+
+.. class:: NewlineFramer(max_size=1000000)
+
+  A framer where messages are delimited by an ASCII newline character in
+  a text stream.  The internal buffer for partial messages will hold up
+  to *max_size* bytes.

docs/index.rst

@@ -47,6 +47,7 @@ Documentation
 
 .. toctree::
 
+   framing
    json-rpc
    rpc
 

docs/json-rpc.rst

@@ -3,7 +3,7 @@
 JSON RPC
 ========
 
-The :mod:`jsonrpc` module provides classes to interpret and construct
+The :mod:`aiorpcx` module provides classes to interpret and construct
 JSON RPC protocol messages.  Class instances are not used; all methods
 are class methods.  Just call methods on the classes directly.