spec
spec copied to clipboard
ooni
Add initial spec for OONI run
Forgot to mention: we should also specify how a canonical OONI Run v2 link looks like. Because we're using deep linking, I assume it could be something like https://run.ooni.io/api/v2/nettest/ID or ooni://nettest/v2/ID.
Since conversation for this spec seems to be still open, I'll leave here a comment that I made recently to @bassosimone: if the constrains in the information that can be conveyed in the url params is the limiting factor to move to a backend-based solution, we could consider encoding the information in some other way?
One obvious candidate is QRs. They're quite ubiquitous nowadays, and registering the right intent they might perhaps be able to encode a complete experiment run (we can try to pack it more efficiently; and perhaps a little research into information density of different types of QR is in order).
This is not to say not to pursue a backend (a backend with community control brings a lot of advantages: curation, sharing, common visibility), but perhaps some runs do not need of it after all.
I like the QR code idea! However I am not sure how practical it's going to be. In practice the use-case for sharing OONI Run links is that people share them through digital means (ex. IM or social media). If you are to use a QR code image on social media, it's going to be tricky to scan the QR code from social media or IM unless you have two devices. Unless there is some other way to go from a QR code inside of say WhatsApp to a the native phone app for handing the code.
Unless there is some other way to go from a QR code inside of say WhatsApp to a the native phone app for handing the code.
it seems there are a few options to open from a stored photo: https://www.wikihow.com/Scan-a-QR-Code-from-Photos
Following a discussion I had with @ainghazal, I have updated the spec to include more details about the descriptor format.
I also factored into it the plans we had for redoing the dashboard based on the OONI Run v2 format and provided examples for how we could implement the dashboard using them.
To show how this could also work for the use-case of @ainghazal, we could imagine having an OONI Run v2 link for let's say RiseupVPN which could look like this:
{
"name": "RiseupVPN",
"short_description": "Run experiments related to testing RiseupVPN",
"author": "[email protected]",
"nettests":
[
{
"inputs": [
"https://api.black.riseup.net:443/3/config/eip-service.json",
"https://riseup.net/provider.json",
"https://api.black.riseup.net:9001/json",
],
"options": {
"SkipTLSVerify": true
},
"test_name": "web_connectivity"
},
{
"test_settings": {
"provider": "riseupvpn"
},
"test_name": "openvpn"
},
]
}
Where SkipTLSVerify should be some options understood by the OONI Probe engine to skip certificate verification (we need this since the riseup endpoints are using their own root CA) and provider is expected to be understood by the check-in API to derive the input and configuration vectors for the openvpn test.
We could take this approach even further and consider applying a similar treatment to all the IM tests and rebuild them using these more basic building blocks.
This does however raise the question of whether or not we would like to have an additional layer of grouping/nesting for the nettests.
For example I might want to put the RiseupVPN OONI Run link inside of the Circumvention test group, but as it's done now, I am not able to do so because the structure is too flat.
We could do this in at least two different ways.
- We just add a tag inside of each nettest, that the apps will then know to group by ex.
{
"name": "VPN tests",
"short_description": "Run experiments related to testing VPNs",
"author": "[email protected]",
"nettests":
[
{
"inputs": [
"https://api.black.riseup.net:443/3/config/eip-service.json",
"https://riseup.net/provider.json",
"https://api.black.riseup.net:9001/json",
],
"options": {
"SkipTLSVerify": true
},
"tag": "riseupvpn",
"test_name": "web_connectivity"
},
{
"test_settings": {
"provider": "riseupvpn"
},
"tag": "riseupvpn",
"test_name": "openvpn"
},
{
"inputs": [
"https://tunnebear.com/targets.json",
],
"tag": "tunnelbear",
"test_name": "web_connectivity"
},
{
"test_settings": {
"provider": "tunnelbear"
},
"tag": "tunnelbear",
"test_name": "openvpn"
},
]
}
-
We add an extra level of nesting in the nettests
-
is probably easier and it doesn't require changing the data format, but might limit our ability to enrich the tags with extra metadata (like title and description related to a certain tag).
One thing to discuss, but can be done in a future PR, is how we handle incompatible updates to the OONI Run descriptor format. We might want a version field which tells probes that they need to support at least this version of OONI Run descriptor parsing to use it.
Concrete use-cases include the parsing of new $settings variables or certain features of the descriptor.