From 860426b8741c139f6f6b3dbc6d9758ea853300fe Mon Sep 17 00:00:00 2001
From: Simone Basso <bassosimone@gmail.com>
Date: Wed, 31 Aug 2022 19:51:31 +0200
Subject: [PATCH] doc: document the minioonirunv2 functionality (#916)

Closes https://github.com/ooni/probe/issues/2184
---
 docs/design/dd-004-minioonirunv2.md | 98 +++++++++++++++++++++++++++++
 internal/oonirun/doc.go             |  3 +
 2 files changed, 101 insertions(+)
 create mode 100644 docs/design/dd-004-minioonirunv2.md

diff --git a/docs/design/dd-004-minioonirunv2.md b/docs/design/dd-004-minioonirunv2.md
new file mode 100644
index 0000000..3bec29a
--- /dev/null
+++ b/docs/design/dd-004-minioonirunv2.md
@@ -0,0 +1,98 @@
+# Mini OONIRun v2
+
+|              |                                                |
+|--------------|------------------------------------------------|
+| Author       | [@bassosimone](https://github.com/bassosimone) |
+| Last-Updated | 2022-08-31                                     |
+| Reviewed-by  | [@hellais](https://github.com/hellais)         |
+| Status       | approved                                       |
+
+The official spec for OONI Run v2 is under review as [ooni/spec#249](
+https://github.com/ooni/spec/pull/249). We want to start experimenting
+with OONI Run v2 before such a spec has been finalized.
+This document, in particular, describes a "mini" OONI Run v2 where
+`miniooni` users can run arbitrary OONI Run v2 "descriptors" (see below
+for a definition).
+When [ooni/spec#249](https://github.com/ooni/spec/pull/249) is merged,
+it will automatically supersede this document. The main idea of this
+document is just to explain the subset of OONI Run v2 implemented inside
+the `miniooni` research tool _until_ we have a complete spec.
+
+## Overview
+
+OONI Run v1 links do not support passing options to experiments and
+often times are longer than the maximum message size on, for example,
+WhatsApp and Telegram. To fix these issues, we're designing OONI Run v2.
+
+The general idea is the following:
+
+* there is a mobile (or desktop) OONI Run v2 deeplink;
+
+* the deeplink eventually resolves to a URL;
+
+* fetching the URL returns a JSON document telling the OONI engine
+what to measure, called _descriptor_.
+
+This document only focuses on running arbitrary v2 descriptors
+for research purposes  using `miniooni`.
+
+## OONI Run v2 descriptor
+
+We use this definition of the descriptor (which we deemed to be
+forward compatible with the _final_ descriptor format):
+
+```JSON
+{
+	"nettests": []
+}
+```
+
+where `"nettests"` is an array of objects like this:
+
+```JSON
+{
+	"inputs": [],
+	"options": {},
+	"test_name": ""
+}
+```
+
+where:
+
+- `"inputs"` is an optional list of input strings for the nettest like the ones you
+would normally pass to `miniooni` using `-i`.
+
+- `"options"` is an optional `map[string]any` where the key is a name of an option
+you can pass to a `miniooni` experiment using `-O NAME=VALUE` and `value` is the
+corresponding value. The type of the value should be the type of the original field
+inside of the experiment's options, which you can see with `./miniooni <experiment> --help`.
+
+- `"test_name"` is the `<experiment>` string you would use in `./miniooni <experiment>`.
+
+(For historical reasons, "experiment", "test", and "nettest" are synonymous.)
+
+## Functionality
+
+A `miniooni` user could run an arbitrary OONI Run v2 descriptor stored at a given URL
+by invoking the `oonirun` subcommand and passing the URL using `-i`. The user could
+specify an abitrary number of descriptor URLs. For example:
+
+```bash
+./miniooni oonirun -i https://example.com/a -i https://example.com/b
+```
+
+The OONI engine will fetch each descriptor _sequentially_ and execute the code it
+would execute if the user ran `./miniooni` from the command line
+with the specified experiment name, the given
+options and inputs.
+
+The OONI engine stores the content of each descriptor inside a cache on disk
+inside the `$OONI_HOME` of `miniooni` (generally `$HOME/.miniooni/`).
+Conceptually, this cache is a map from the descriptor URL to the latest known content
+of the descriptor. (The actual implementation _may_ differ.)
+
+On the first run, or when the descriptor has changed, `miniooni` refuses to run,
+shows what changed, and asks the user for confirmation.
+There's also a mechanism to bypass asking for confirmation that explicitly requires a
+user to add `-y` or `--yes` to the command line to automatically answer "yes" to
+all questions. (This is useful when, for example, you're running your own descriptors.)
diff --git a/internal/oonirun/doc.go b/internal/oonirun/doc.go
index 4e511d7..4a592cc 100644
--- a/internal/oonirun/doc.go
+++ b/internal/oonirun/doc.go
@@ -2,4 +2,7 @@
 //
 // This package supports OONI Run v1 and v2 as well as the direct
 // creation and instantiation of OONI experiments.
+//
+// See https://github.com/ooni/probe-cli/blob/master/docs/design/dd-004-minioonirunv2.md
+// for more information on the subset of OONI Run v2 implemented by this package.
 package oonirun