Rename report pending exception to clarify its purpose

Rename CuckooReportPendingException to PeekabooAnalysisDeferred to more
clearly state its purpose. Document its intent. Remove Exception suffix
to also show that it's not actually indicating an error state but
influences control flow.

4 files changed, 25 insertions, 13 deletions

diff --git a/peekaboo/exceptions.py b/peekaboo/exceptions.py
index 7559cac..1ee8097 100644
--- a/peekaboo/exceptions.py
+++ b/peekaboo/exceptions.py
@@ -40,10 +40,23 @@ class PeekabooRulesetException(PeekabooException):
     pass
 
 
-class CuckooReportPendingException(PeekabooRulesetException):
-    """ An exception signifying that we're waiting for Cuckoo to finish its
-    analysis an defer our interpretation of its findings until its report
-    becomes available. """
+class PeekabooAnalysisDeferred(PeekabooRulesetException):
+    """ Analysis has been deferred to a later point in time.
+
+    An exception signifying that analysis has been deferred to a later point in
+    time. Ruleset processing will be aborted (without error). Useful if we're
+    waiting for someone to finish their analysis and defer our interpretation
+    of their findings until they become available, most notably the Cuckoo
+    report.
+
+    Not an exception in the traditional sense since it does not indicate an
+    error but actually influences control flow instead. Somewhat questionable
+    in that regard.
+
+    The raiser becomes owner of the sample and is responsible to appropriately
+    resubmit it into Peekaboo once it wants processing to continue. That should
+    take into account that the ruleset will be rerun from the very beginning.
+    """
     pass
 
 
diff --git a/peekaboo/queuing.py b/peekaboo/queuing.py
index e80cedf..f9eac95 100644
--- a/peekaboo/queuing.py
+++ b/peekaboo/queuing.py
@@ -29,7 +29,7 @@ from queue import Queue, Empty
 from time import sleep
 from peekaboo.ruleset import Result, RuleResult
 from peekaboo.ruleset.engine import RulesetEngine
-from peekaboo.exceptions import CuckooReportPendingException, \
+from peekaboo.exceptions import PeekabooAnalysisDeferred, \
     PeekabooDatabaseError
 
 
@@ -395,7 +395,7 @@ class Worker(Thread):
             engine = RulesetEngine(sample, self.ruleset_config, self.db_con)
             try:
                 engine.run()
-            except CuckooReportPendingException:
+            except PeekabooAnalysisDeferred:
                 logger.debug("Report for sample %s still pending", sample)
                 continue
 
diff --git a/peekaboo/ruleset/engine.py b/peekaboo/ruleset/engine.py
index 3370c33..2d6467d 100644
--- a/peekaboo/ruleset/engine.py
+++ b/peekaboo/ruleset/engine.py
@@ -28,7 +28,7 @@ import logging
 from peekaboo.ruleset import Result, RuleResult
 from peekaboo.ruleset.rules import *
 from peekaboo.toolbox.peekabooyar import ContainsPeekabooYarRule
-from peekaboo.exceptions import CuckooReportPendingException
+from peekaboo.exceptions import PeekabooAnalysisDeferred
 
 
 logger = logging.getLogger(__name__)
@@ -89,7 +89,7 @@ class RulesetEngine(object):
                     further_analysis=True)
 
             sample.add_rule_result(result)
-        except CuckooReportPendingException as e:
+        except PeekabooAnalysisDeferred:
             # in case the Sample is requesting the Cuckoo report
             raise
         # catch all other exceptions for this rule
diff --git a/peekaboo/ruleset/rules.py b/peekaboo/ruleset/rules.py
index 379adf4..120e4f5 100644
--- a/peekaboo/ruleset/rules.py
+++ b/peekaboo/ruleset/rules.py
@@ -29,7 +29,7 @@
 import re
 import logging
 from peekaboo.ruleset import Result, RuleResult
-from peekaboo.exceptions import CuckooReportPendingException, \
+from peekaboo.exceptions import PeekabooAnalysisDeferred, \
         CuckooSubmitFailedException
 
 
@@ -186,13 +186,12 @@ class CuckooRule(Rule):
         """ If a report is present for the sample in question we call method
         evaluate_report() implemented by subclasses to evaluate it for
         findings. Otherwise we submit the sample to Cuckoo and raise
-        CuckooReportPendingException to abort the current run of the ruleset
+        PeekabooAnalysisDeferred to abort the current run of the ruleset
         until the report arrives. If submission to Cuckoo fails we will
         ourselves report the sample as failed.
 
         @param sample: The sample to evaluate.
-        @raises CuckooReportPendingException: if the sample was submitted to
-                                              Cuckoo
+        @raises PeekabooAnalysisDeferred: if the sample was submitted to Cuckoo
         @returns: RuleResult containing verdict.
         """
         report = sample.cuckoo_report
@@ -212,7 +211,7 @@ class CuckooRule(Rule):
 
             logger.info('Sample submitted to Cuckoo. Job ID: %s. '
                         'Sample: %s', job_id, sample)
-            raise CuckooReportPendingException()
+            raise PeekabooAnalysisDeferred()
 
         # call report evaluation function if we get here
         return self.evaluate_report(report)