From 2054fa1108537ade69ff04e28d25dab75dd97273 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= <petr.spacek@nic.cz>
Date: Mon, 20 Feb 2017 17:18:36 +0100
Subject: [PATCH] deckard: document basic functions in query/answer processing

---
 pydnstest/scenario.py   | 29 ++++++++++++++++++++++-------
 pydnstest/testserver.py | 16 ++++++++++++++--
 2 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/pydnstest/scenario.py b/pydnstest/scenario.py
index e1ad938..2ea95e1 100644
--- a/pydnstest/scenario.py
+++ b/pydnstest/scenario.py
@@ -404,7 +404,12 @@ class Range:
         return False
 
     def reply(self, query):
-        """ Find matching response to given query. """
+        """
+        Get answer for given query (adjusted if needed).
+
+        Returns:
+            (DNS message object) or None if there is no candidate in this range
+        """
         self.received += 1
         for candidate in self.stored:
             try:
@@ -539,7 +544,11 @@ class Step:
 
 
     def __query(self, ctx, tcp = False, choice = None, source = None):
-        """ Resolve a query. """
+        """
+        Send query and wait for an answer (if the query is not RAW).
+
+        The received answer is stored in self.answer and ctx.last_answer.
+        """
         if len(self.data) == 0:
             raise Exception("query definition required")
         if self.data[0].is_raw_data_entry is True:
@@ -637,10 +646,16 @@ class Scenario:
         self.force_ipv6 = False
 
     def reply(self, query, address = None):
-        """ Attempt to find a range reply for a query. """
-        step_id = 0
+        """
+        Generate answer packet for given query.
+
+        The answer can be DNS message object or a binary blob.
+        Returns:
+            (answer, boolean "is the answer binary blob?")
+        """
+        current_step_id = 0
         if self.current_step is not None:
-            step_id = self.current_step.id
+            current_step_id = self.current_step.id
         # Unknown address, select any match
         # TODO: workaround until the server supports stub zones
         all_addresses = set()
@@ -650,12 +665,12 @@ class Scenario:
             address = None
         # Find current valid query response range
         for rng in self.ranges:
-            if rng.eligible(step_id, address):
+            if rng.eligible(current_step_id, address):
                 self.current_range = rng
                 return (rng.reply(query), False)
         # Find any prescripted one-shot replies
         for step in self.steps:
-            if step.id < step_id or step.type != 'REPLY':
+            if step.id < current_step_id or step.type != 'REPLY':
                 continue
             try:
                 candidate = step.data[0]
diff --git a/pydnstest/testserver.py b/pydnstest/testserver.py
index c036ed2..6048b39 100644
--- a/pydnstest/testserver.py
+++ b/pydnstest/testserver.py
@@ -11,7 +11,13 @@ import binascii
 from dprint import dprint
 
 def recvfrom_msg(stream, raw = False):
-    """ Receive DNS/UDP/TCP message. """
+    """
+    Receive DNS message from TCP/UDP socket.
+
+    Returns:
+        if raw == False: (DNS message object, peer address)
+        if raw == True: (blob, peer address)
+    """
     if stream.type == socket.SOCK_DGRAM:
         data, addr = stream.recvfrom(4096)
     elif stream.type == socket.SOCK_STREAM:
@@ -156,7 +162,13 @@ class TestServer:
         return addrlist;
 
     def handle_query(self, client):
-        """ Handle incoming queries. """
+        """
+        Receive query from client socket and send an answer.
+
+        Returns:
+            True if client socket should be closed by caller
+            False if client socket should be kept open
+        """
         client_address = client.getsockname()[0]
         query, addr = recvfrom_msg(client)
         if query is None:
-- 
2.22.0