update docs

lbryio · Feb 2, 2017 · cffe6ce · cffe6ce
1 parent e4091ec
commit cffe6ce
Show file tree

Hide file tree

Showing 3 changed files with 79 additions and 77 deletions.
diff --git a/lbrynet/reflector/__init__.py b/lbrynet/reflector/__init__.py
@@ -1,3 +1,69 @@
+"""
+Reflector is a protocol to re-host lbry blobs and streams
+Client queries and server responses follow, all dicts are encoded as json
+
+############# Handshake request and response #############
+Upon connecting, the client sends a version handshake:
+{
+    'version': int,
+}
+
+The server replies with the same version
+{
+    'version': int,
+}
+
+############# Stream descriptor requests and responses #############
+(if sending blobs directly this is skipped)
+If the client is reflecting a whole stream, they send a stream descriptor request:
+{
+    'sd_blob_hash': str,
+    'sd_blob_size': int
+}
+
+The server indicates if it's aware of this stream already by requesting (or not requesting)
+the stream descriptor blob. If the server has a validated copy of the sd blob, it will
+include the needed_blobs field (a list of blob hashes missing from reflector) in the response.
+If the server does not have the sd blob the needed_blobs field will not be included, as the
+server does not know what blobs it is missing - so the client should send all of the blobs
+in the stream.
+{
+    'send_sd_blob': bool
+    'needed_blobs': list, conditional
+}
+
+The client may begin the file transfer of the sd blob if send_sd_blob was True.
+If the client sends the blob, after receiving it the server indicates if the
+transfer was successful:
+{
+    'received_sd_blob': bool
+}
+If the transfer was not successful (False), the blob is added to the needed_blobs queue
+
+############# Blob requests and responses #############
+A client with blobs to reflect (either populated by the client or by the stream descriptor
+response) queries if the server is ready to begin transferring a blob
+{
+    'blob_hash': str,
+    'blob_size': int
+}
+
+The server replies, send_blob will be False if the server has a validated copy of the blob:
+{
+    'send_blob': bool
+}
+
+The client may begin the raw blob file transfer if the server replied True.
+If the client sends the blob, the server replies:
+{
+    'received_blob': bool
+}
+If the transfer was not successful (False), the blob is re-added to the needed_blobs queue
+
+Blob requests continue for each of the blobs the client has queued to send, when completed
+the client disconnects.
+"""
+
 from lbrynet.reflector.server.server import ReflectorServerFactory as ServerFactory
 from lbrynet.reflector.client.client import EncryptedFileReflectorClientFactory as ClientFactory
 from lbrynet.reflector.client.blob import BlobReflectorClientFactory as BlobClientFactory

diff --git a/lbrynet/reflector/client/client.py b/lbrynet/reflector/client/client.py
@@ -1,75 +1,3 @@
-"""
-The reflector protocol (all dicts encoded in json):
-
-Client Handshake (sent once per connection, at the start of the connection):
-
-{
-    'version': 1,
-}
-
-
-Server Handshake (sent once per connection, after receiving the client handshake):
-
-{
-    'version': 1,
-}
-
-Client Descriptor Request:
-
-{
-    'sd_blob_hash': "<sd_blob_hash>",
-    'sd_blob_size': <sd_blob_size>
-}
-
-Server Descriptor Response (sent in response to Client Descriptor Request):
-
-{
-    'send_sd_blob': True|False
-    'needed_blobs': []
-}
-
-If response is 'YES', client may send a Client Stream Descriptor or a Client Info Request.
-If response is 'NO', client may send a Client Info Request for a needed blob.
-
-Client Stream Descriptor Request:
-<raw blob_data>  # this blob data must match the info sent in the most recent Client Info Request
-
-Server Stream Descriptor Response (sent in response to Client Stream Descriptor Request):
-{
-    'received_sd_blob': True
-}
-
-Client Info Request:
-
-{
-    'blob_hash': "<blob_hash>",
-    'blob_size': <blob_size>
-}
-
-Server Info Response (sent in response to Client Info Request):
-
-{
-    'send_blob': True|False
-}
-
-If response is 'YES', client may send a Client Blob Request or a Client Info Request.
-If response is 'NO', client may only send a Client Info Request
-
-
-Client Blob Request:
-
-{}  # Yes, this is an empty dictionary, in case something needs to go here in the future
-<raw blob_data>  # this blob data must match the info sent in the most recent Client Info Request
-
-
-Server Blob Response (sent in response to Client Blob Request):
-{
-    'received_blob': True
-}
-
-Client may now send another Client Info Request
-
-"""
 import json
 import logging
 
@@ -81,7 +9,6 @@
 from lbrynet.reflector.common import IncompleteResponse, ReflectorRequestError
 from lbrynet.reflector.common import REFLECTOR_V1, REFLECTOR_V2
 
-
 log = logging.getLogger(__name__)
 
 

diff --git a/lbrynet/reflector/common.py b/lbrynet/reflector/common.py
@@ -3,16 +3,25 @@
 
 
 class ReflectorClientVersionError(Exception):
-    pass
+    """
+    Raised by reflector server if client sends an incompatible or unknown version
+    """
 
 
 class ReflectorRequestError(Exception):
-    pass
+    """
+    Raised by reflector server if client sends a message without the required fields
+    """
 
 
 class ReflectorRequestDecodeError(Exception):
-    pass
+    """
+    Raised by reflector server if client sends an invalid json request
+    """
 
 
 class IncompleteResponse(Exception):
-    pass
+    """
+    Raised by reflector server when client sends a portion of a json request,
+    used buffering the incoming request
+    """