OONI probe measurement engine

This repository contains OONI probe's measurement engine. That is, the piece of software that implements OONI nettests.

API

You can browse ooni/probe-engine's API online at godoc.org. We currently don't provide any API stability guarantees.

This repository also allows to build miniooni, a small command line client useful to test the functionality in here without integrating with OONI probe. You can browse the manual of this tool online at godoc.org. We currently don't promise that the miniooni CLI will be stable over time.

Integrating ooni/probe-engine

This software uses Go modules and requires Go v1.14+. We also depend on Measurement Kit, a C++14 library implementing many OONI tests, a.k.a. MK.

Note that passing the -tags nomk flag to Go will disable linking Measurement Kit into the resulting Go binaries. You may want that in cases where you only want to use experiments written in Go.

We plan on gradually rewriting all OONI tests in Go, therefore the dependency on Measurement Kit will eventually be removed. A future version of this document will provide platform specific instructions for installing Measurement Kit and linking to it.

Building miniooni

go build -v -tags nomk ./cmd/miniooni/

Omit -tags nomk to link with MK.

Building Android bindings

./build-android.bash

When building Android bindings, we automatically omit linking with MK.

Release procedure

make sure that dependencies are up to date
make sure that resources are up to date
commit, tag, and push
create new release on GitHub

Updating dependencies

update direct dependencies using:

for name in `grep -v indirect go.mod | awk '/^\t/{print $1}'`; do \
  go get -u -v $name;                                             \
done

pin to a specific psiphon version (we usually track the staging-client branch) using:

go get -v github.com/Psiphon-Labs/psiphon-tunnel-core@COMMITHASH

clone psiphon-tunnel-core, checkout the tip of the staging-client branch and generate a go.mod by running go mod init && go mod tidy in the toplevel dir
rewrite go.mod such that it contains only your direct dependencies followed by the exact content of psiphon-tunnel-core's go.mod
run go mod tidy
make sure you don't downgrade bolt and goselect because this will break downstream builds on MIPS:

go get -u -v github.com/Psiphon-Labs/bolt github.com/creack/goselect

This allows us to pin all psiphon dependencies precisely.