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.

Index

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

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.

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
}

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.