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 ¶
Constants ¶
This section is empty.
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.
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 ¶
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.
Source Files