1 files changed, 95 insertions, 0 deletions
diff --git a/catapult/telemetry/third_party/web-page-replay/documentation/Rules.md b/catapult/telemetry/third_party/web-page-replay/documentation/Rules.md
new file mode 100644
index 00000000..35176357
--- /dev/null
+++ b/catapult/telemetry/third_party/web-page-replay/documentation/Rules.md
@@ -0,0 +1,95 @@
+WebPageReplay Rule Language
+===========================
+
+WebPageReplay rules allows developers to customize record/replay handling.
+
+Motiviation
+-----------
+
+Web sites often require custom replay logic, e.g.:
+
+  1. The recording uploads various metrics/logs to:
+
+        http://example.com/gen_204?emsg=foo
+
+     but, during replay, it uploads different parameters:
+
+        http://example.com/gen_204?emsg=bar
+
+     so (as-is) our replay fails.  We want "*/gen_204" to always respond
+     "HTTP 204 No Change".
+
+  2. The recording fetches data from one server:
+
+        http://mirrorA.example.com/stuff
+
+     but replay selects a different server:
+
+        http://mirrorB.example.com/stuff
+
+     which breaks replay.  We want "mirror*.example.com/stuff" to be equivalent.
+
+  3. The recorded URL + response contains a UID, e.g.:
+
+        http://example.com?q=foo  -->  "you sent foo."
+
+     but the replay asks for:
+
+        http://example.com?q=bar  -->  replay error!
+
+     We want it to reply "you sent bar."
+
+We could hack all the above rules into the code, but that can''t be (cleanly) extended or open sourced.
+
+Instead, we want a simple config file of "predicate --> action" rules.
+
+
+Format
+------
+
+The JSON-formatted rule file is specified on the command line:
+
+    replay.py ... --rules_path my_rules ...
+
+The rules file must contain an array of single-item objects, e.g.:
+
+    [{"comment": "ignore me"},
+     {"LogUrl": {"url": "example\\.com/logme.*"}},
+     {"LogUrl": {"url": "example\\.com/someotherpath"}}
+    ]
+
+All "comment" items are ignored and support arbitrary values, e.g., a string
+or commented-out rule(s).
+
+All other items must specify a string TYPE key and object ARGS value, e.g.:
+
+     {"LogUrl": {"url": "example\\.com/test", "stop": false}}
+
+The default TYPE package is "rules" and the default rule_parser
+"allowed_imports" is similarly restricted to only allow "rules" classes.
+
+The TYPE implementation class must match the Rule API defined in
+"rules/rule.py":
+
+  class Rule(object):
+    def IsType(self, rule_type_name): ...
+    def ApplyRule(self, return_value, request, response): ...
+
+The ARGS must match the rule-specific constructor, e.g.:
+
+    class LogUrl(rule.Rule):
+      def __init__(self, url, stop=False):
+        self._url_re = re.compile(url)
+        self._stop = stop
+      ...
+
+All rules of the same rule_type_name are chained together and applied in the
+same order as they appear in the input JSON file.
+
+
+Rules
+-------
+
+### rules.LogUrl:
+
+If the url pattern matches then log the request URL.