oonirun

Documentation

Overview

Package oonirun contains code to run OONI experiments.

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.

Index

• Variables
• func V2MeasureDescriptor(ctx context.Context, config *LinkConfig, desc *V2Descriptor) error
• type Experiment
  • func (ed *Experiment) Run(ctx context.Context) error
• type LinkConfig
• type LinkRunner
  • func NewLinkRunner(c *LinkConfig, URL string) LinkRunner
• type Session
• type V2Descriptor
• type V2Nettest

Variables

var (
	// ErrInvalidV1URLScheme indicates a v1 OONI Run URL has an invalid scheme.
	ErrInvalidV1URLScheme = errors.New("oonirun: invalid v1 URL scheme")

	// ErrInvalidV1URLHost indicates a v1 OONI Run URL has an invalid host.
	ErrInvalidV1URLHost = errors.New("oonirun: invalid v1 URL host")

	// ErrInvalidV1URLPath indicates a v1 OONI Run URL has an invalid path.
	ErrInvalidV1URLPath = errors.New("oonirun: invalid v1 URL path")

	// ErrInvalidV1URLQueryArgument indicates a v1 OONI Run URL query argument is invalid.
	ErrInvalidV1URLQueryArgument = errors.New("oonirun: invalid v1 URL query argument")
)

var ErrHTTPRequestFailed = errors.New("oonirun: HTTP request failed")

ErrHTTPRequestFailed indicates that an HTTP request failed.

var ErrNeedToAcceptChanges = errors.New("oonirun: need to accept changes")

ErrNeedToAcceptChanges indicates that the user needs to accept changes (i.e., a new or modified set of descriptors) before we can actually run this set of descriptors.

var ErrNilDescriptor = errors.New("oonirun: descriptor is nil")

ErrNilDescriptor indicates that we have been passed a descriptor that is nil.

Functions

func V2MeasureDescriptor

func V2MeasureDescriptor(ctx context.Context, config *LinkConfig, desc *V2Descriptor) error

V2MeasureDescriptor performs the measurement or measurements described by the given list of v2Descriptor.

Types

type Experiment

type Experiment struct {
	// Annotations contains OPTIONAL Annotations for the experiment.
	Annotations map[string]string

	// ExtraOptions contains OPTIONAL extra options for the experiment.
	ExtraOptions map[string]any

	// Inputs contains the OPTIONAL experiment Inputs
	Inputs []string

	// InputFilePaths contains OPTIONAL files to read inputs from.
	InputFilePaths []string

	// MaxRuntime is the OPTIONAL maximum runtime in seconds.
	MaxRuntime int64

	// Name is the MANDATORY experiment name.
	Name string

	// NoCollector OPTIONALLY indicates we should not be using any collector.
	NoCollector bool

	// NoJSON OPTIONALLY indicates we don't want to save measurements to a JSON file.
	NoJSON bool

	// Random OPTIONALLY indicates we should randomize inputs.
	Random bool

	// ReportFile is the MANDATORY file in which to save reports, which is only
	// used when noJSON is set to false.
	ReportFile string

	// Session is the MANDATORY session.
	Session Session
	// contains filtered or unexported fields
}

Experiment describes an experiment to run. You MUST fill all the fields that are marked as MANDATORY, otherwise Experiment.Run will cause panics.

func (*Experiment) Run

func (ed *Experiment) Run(ctx context.Context) error

Run runs the given experiment.

type LinkConfig

type LinkConfig struct {
	// AcceptChanges is OPTIONAL and tells this library that the user is
	// okay with running a new or modified OONI Run link without previously
	// reviewing what it contains or what has changed.
	AcceptChanges bool

	// Annotations contains OPTIONAL Annotations for the experiment.
	Annotations map[string]string

	// KVStore is the MANDATORY key-value store to use to keep track of
	// OONI Run links and know when they are new or modified.
	KVStore model.KeyValueStore

	// MaxRuntime is the OPTIONAL maximum runtime in seconds.
	MaxRuntime int64

	// NoCollector OPTIONALLY indicates we should not be using any collector.
	NoCollector bool

	// NoJSON OPTIONALLY indicates we don't want to save measurements to a JSON file.
	NoJSON bool

	// Random OPTIONALLY indicates we should randomize inputs.
	Random bool

	// ReportFile is the MANDATORY file in which to save reports, which is only
	// used when noJSON is set to false.
	ReportFile string

	// Session is the MANDATORY Session to use.
	Session Session
}

LinkConfig contains config for an OONI Run link. You MUST fill all the fields that are marked as MANDATORY, or the LinkConfig would cause crashes.

type LinkRunner

type LinkRunner interface {
	Run(ctx context.Context) error
}

LinkRunner knows how to run an OONI Run v1 or v2 link.

func NewLinkRunner

func NewLinkRunner(c *LinkConfig, URL string) LinkRunner

NewLinkRunner creates a suitable link runner for the current config and the given URL, which is one of the following:

1. OONI Run v1 link with https scheme (e.g., https://run.ooni.io/nettest?...)

2. OONI Run v1 link with ooni scheme (e.g., ooni://nettest?...)

3. arbitrary URL of the OONI Run v2 descriptor.

type Session

type Session interface {
	// A Session is also an InputLoaderSession.
	engine.InputLoaderSession

	// A Session is also a SubmitterSession.
	engine.SubmitterSession

	// DefaultHTTPClient returns the session's default HTTPClient.
	DefaultHTTPClient() model.HTTPClient

	// Logger returns the logger used by this Session.
	Logger() model.Logger

	// NewExperimentBuilder creates a new engine.ExperimentBuilder.
	NewExperimentBuilder(name string) (model.ExperimentBuilder, error)
}

Session is the definition of Session used by this package.

type V2Descriptor

type V2Descriptor struct {
	// Name is the name of this descriptor.
	Name string `json:"name"`

	// Description contains a long description.
	Description string `json:"description"`

	// Author contains the author's name.
	Author string `json:"author"`

	// Nettests contains the list of nettests to run.
	Nettests []V2Nettest `json:"nettests"`
}

V2Descriptor describes a list of nettests to run together.

type V2Nettest

type V2Nettest struct {
	// Inputs contains inputs for the experiment.
	Inputs []string `json:"inputs"`

	// Options contains the experiment options. Any option name starting with
	// `Safe` will be available for the experiment run, but omitted from
	// the serialized Measurement that the experiment builder will submit
	// to the OONI backend.
	Options map[string]any `json:"options"`

	// TestName contains the nettest name.
	TestName string `json:"test_name"`
}

V2Nettest specifies how a nettest should run.