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 NewSaver(config SaverConfig) (model.Saver, error)
• func V2MeasureDescriptor(ctx context.Context, config *LinkConfig, desc *V2Descriptor) error
• type Experiment
  • func (ed *Experiment) Run(ctx context.Context) error
• type InputProcessor
  • func (ip *InputProcessor) Run(ctx context.Context) error
• type InputProcessorExperiment
• type InputProcessorExperimentWrapper
  • func NewInputProcessorExperimentWrapper(exp InputProcessorExperiment) InputProcessorExperimentWrapper
• type InputProcessorSaverWrapper
  • func NewInputProcessorSaverWrapper(saver model.Saver) InputProcessorSaverWrapper
• type InputProcessorSubmitterWrapper
  • func NewInputProcessorSubmitterWrapper(submitter Submitter) InputProcessorSubmitterWrapper
• type LinkConfig
• type LinkRunner
  • func NewLinkRunner(c *LinkConfig, URL string) LinkRunner
• type SaverConfig
• type Session
• type Submitter
  • func NewSubmitter(ctx context.Context, config SubmitterConfig) (Submitter, error)
• type SubmitterConfig
• type SubmitterSession
• 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 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 NewSaver

func NewSaver(config SaverConfig) (model.Saver, error)

NewSaver creates a new instance of Saver.

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 that modify the
	// default experiment-specific configuration. We apply
	// the changes described by this field after using the InitialOptions
	// field to initialize the experiment-specific configuration.
	ExtraOptions map[string]any

	// InitialOptions contains an OPTIONAL [json.RawMessage] object
	// used to initialize the default experiment-specific
	// configuration. After we have initialized the configuration
	// as such, we then apply the changes described by the ExtraOptions.
	InitialOptions json.RawMessage

	// 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 InputProcessor

type InputProcessor struct {
	// Annotations contains the measurement annotations
	Annotations map[string]string

	// Experiment is the code that will run the experiment.
	Experiment InputProcessorExperimentWrapper

	// Inputs is the list of inputs to measure.
	Inputs []model.ExperimentTarget

	// MaxRuntime is the optional maximum runtime
	// when looping over a list of inputs (e.g. when
	// running Web Connectivity). Zero means that
	// there will be no MaxRuntime limit.
	MaxRuntime time.Duration

	// Saver is the code that will save measurement results
	// on persistent storage (e.g. the file system).
	Saver InputProcessorSaverWrapper

	// Submitter is the code that will submit measurements
	// to the OONI collector.
	Submitter InputProcessorSubmitterWrapper
}

InputProcessor processes inputs. We perform a Measurement for each input using the given Experiment.

func (*InputProcessor) Run

func (ip *InputProcessor) Run(ctx context.Context) error

Run processes all the input subject to the duration of the context. The code will perform measurements using the given experiment; submit measurements using the given submitter; save measurements using the given saver.

Annotations and Options will be saved in the measurement.

The default behaviour of this code is that an error while measuring, while submitting, or while saving a measurement is always causing us to break out of the loop. The user though is free to choose different policies by configuring the Experiment, Submitter, and Saver fields properly.

type InputProcessorExperiment

type InputProcessorExperiment interface {
	MeasureWithContext(ctx context.Context, target model.ExperimentTarget) (*model.Measurement, error)
}

InputProcessorExperiment is the Experiment according to InputProcessor.

type InputProcessorExperimentWrapper

type InputProcessorExperimentWrapper interface {
	MeasureWithContext(ctx context.Context, target model.ExperimentTarget, idx int) (*model.Measurement, error)
}

InputProcessorExperimentWrapper is a wrapper for an Experiment that also allow to pass around the input index.

func NewInputProcessorExperimentWrapper

func NewInputProcessorExperimentWrapper(
	exp InputProcessorExperiment) InputProcessorExperimentWrapper

NewInputProcessorExperimentWrapper creates a new instance of InputProcessorExperimentWrapper.

type InputProcessorSaverWrapper

type InputProcessorSaverWrapper interface {
	SaveMeasurement(idx int, m *model.Measurement) error
}

InputProcessorSaverWrapper is InputProcessor's wrapper for a Saver implementation.

func NewInputProcessorSaverWrapper

func NewInputProcessorSaverWrapper(saver model.Saver) InputProcessorSaverWrapper

NewInputProcessorSaverWrapper wraps a Saver for InputProcessor.

type InputProcessorSubmitterWrapper

type InputProcessorSubmitterWrapper interface {
	Submit(ctx context.Context, idx int, m *model.Measurement) error
}

InputProcessorSubmitterWrapper is InputProcessor's wrapper for a Submitter implementation.

func NewInputProcessorSubmitterWrapper

func NewInputProcessorSubmitterWrapper(submitter Submitter) InputProcessorSubmitterWrapper

NewInputProcessorSubmitterWrapper wraps a Submitter for the InputProcessor.

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

	// AuthFile is OPTIONAL and will add an authentication header to the
	// request used for fetching this OONI Run link.
	AuthFile string

	// 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 SaverConfig

type SaverConfig struct {
	// Enabled is true if saving is enabled.
	Enabled bool

	// FilePath is the filepath where to append the measurement as a
	// serialized JSON followed by a newline character.
	FilePath string

	// Logger is the logger used by the saver.
	Logger model.Logger
}

SaverConfig is the configuration for creating a new Saver.

type Session

type Session interface {
	// A Session is also an [targetloading.Session].
	targetloading.Session

	// A Session is also a SubmitterSession.
	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 Submitter

type Submitter = model.Submitter

Submitter is an alias for model.Submitter

func NewSubmitter

func NewSubmitter(ctx context.Context, config SubmitterConfig) (Submitter, error)

NewSubmitter creates a new submitter instance. Depending on whether submission is enabled or not, the returned submitter instance migh just be a stub implementation.

type SubmitterConfig

type SubmitterConfig struct {
	// Enabled is true if measurement submission is enabled.
	Enabled bool

	// Session is the current session.
	Session SubmitterSession

	// Logger is the logger to be used.
	Logger model.Logger
}

SubmitterConfig contains settings for NewSubmitter.

type SubmitterSession

type SubmitterSession interface {
	// NewSubmitter creates a new probeservices Submitter.
	NewSubmitter(ctx context.Context) (Submitter, error)
}

SubmitterSession is the Submitter's view of the Session.

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 json.RawMessage `json:"options"`

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

V2Nettest specifies how a nettest should run.