commit 65c049b0217493193477ee2545f2b7a47f8e01f1 Author: kudrom kudrom@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'} +```