[tor-commits] [spec/master] Review of policy aware changes

[art at torproject.org]

commit 65c049b0217493193477ee2545f2b7a47f8e01f1
Author: kudrom <kudrom at riseup.net>
Date:   Mon Aug 25 23:32:58 2014 +0200

    Review of policy aware changes
---
 oonib.md |   72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 68 insertions(+), 4 deletions(-)

diff --git a/oonib.md b/oonib.md
index 7f31b78..81d83a3 100644
--- a/oonib.md
+++ b/oonib.md
@@ -571,10 +571,14 @@ This is the service that will allow the ooni-probe to discover collectors that r
 
 ### POST /bouncer
 
-This will return a list of required collectors and test helpers.
+This will return a list of required collectors.
 
-Client sends:
+Currently a client has two ways to request the required collectors.
 
+The first and old way is to provide a bunch of test-helpers, oonib then will return the identity of 
+the collectors and the addresses of machines that can run the requested test helpers.
+
+This way, the client sends:
 ```
 {
   'test-helpers': [
@@ -583,7 +587,7 @@ Client sends:
 }
 ```
 
-Bouncer replies:
+And the bouncer replies:
 
 ```
 {
@@ -607,7 +611,67 @@ Bouncer replies:
 
 If it is not possible to find a test helper for one of the required test
 helpers an error message is returned:
-
 ```
 {'error': 'test-helper-not-found'}
 ```
+
+The second and policy respectful way is to provide a bunch of nettests, then the bouncer
+will return the identity of the machines that:
+ 1. Can run the required test-helpers
+ 2. Can send back to the client a set of required inputs
+ 3. Can collect the report of the nettest
+ 
+If a known collector to the bouncer cannot provide any of the three previous requirements,
+the collector won't be sent back to the client in the bouncer request.
+
+If no policy respectful collector can be returned to the client, a default one will be sent
+when the bouncer knows the identity of a collector that accepts any request, which is 
+expressed as a lack of any policy for that collector in the oonib.conf file.
+
+Both the test-helpers and the input-hashed attributes are optional for the client's request,
+but the nettest's name is mandatory.
+
+This way the client sends:
+```
+{
+    'net-tests': [
+        {
+            'test-helpers': ['required test helper', ...],
+            'input-hashed': ['required input id', ...],
+            'name': 'name of nettest',
+            'version': 'version of nettest'
+        },
+        ....
+    ]
+}
+```
+
+And the bouncer replies:
+```
+{
+    'net-tests': [
+        {
+            'test-helpers': [
+                {'requested test helper': 'address'},
+                ...
+            ],
+            'input-hashed': ['requested input id', ...],
+            'name': 'name of nettest',
+            'version': 'version of nettest',
+            'collector': 'address'
+        },
+        ....
+    ]
+}
+```
+
+If it's not possible to find a collector for the request, oonib will respond with:
+```
+{'error': 'collector-not-found'}
+```
+
+Both ways to communicate with the bouncer are explicitly set with the proper JSON object in the
+payload of the POST request. If an invalid JSON object is provided, oonib will respond with:
+```
+{'error': 'test-helpers-or-net-test-key-missing'}
+```