targetloading

Documentation

Overview

Package targetloading contains common code to load richer-input targets.

Index

• Variables
• func LoadStatic(config *Loader) ([]string, error)
• type Loader
  • func (il *Loader) Load(ctx context.Context) ([]model.ExperimentTarget, error)
• type Logger
• type Session

Variables

var (
	ErrNoURLsReturned    = errors.New("no URLs returned")
	ErrDetectedEmptyFile = errors.New("file did not contain any input")
	ErrInputRequired     = errors.New("no input provided")
	ErrNoInputExpected   = errors.New("we did not expect any input")
	ErrNoStaticInput     = errors.New("no static input for this experiment")
	ErrInvalidInputType  = errors.New("invalid richer input type")
	ErrInvalidInput      = errors.New("input does not conform to spec")
)

These errors are returned by the *Loader or the experiment execution.

Functions

func LoadStatic

func LoadStatic(config *Loader) ([]string, error)

LoadStatic loads inputs from the *Loader StaticInputs and SourceFiles.

Types

type Loader

type Loader struct {
	// CheckInConfig contains options for the CheckIn API. If
	// not set, then we'll create a default config. If set but
	// there are fields inside it that are not set, then we
	// will set them to a default value.
	CheckInConfig *model.OOAPICheckInConfig

	// ExperimentName is the name of the experiment. This field
	// is only used together with the InputOrStaticDefault policy.
	ExperimentName string

	// InputPolicy specifies the input policy for the
	// current experiment. We will not load any input if
	// the policy says we should not. You MUST fill in
	// this field.
	InputPolicy model.InputPolicy

	// Logger is the optional logger that the [*Loader]
	// should be using. If not set, we will use the default
	// logger of github.com/apex/log.
	Logger Logger

	// Session is the current measurement session. You
	// MUST fill in this field.
	Session Session

	// StaticInputs contains optional input to be added
	// to the resulting input list if possible.
	StaticInputs []string

	// SourceFiles contains optional files to read input
	// from. Each file should contain a single input string
	// per line. We will fail if any file is unreadable
	// as well as if any file is empty.
	SourceFiles []string
}

Loader loads input according to the specified policy either from command line and input files or from OONI services. The behaviour depends on the input policy as described below.

You MUST NOT change any public field of this structure when in use, because that MAY lead to data races.

InputNone

We fail if there is any StaticInput or any SourceFiles. If there's no input, we return a single, empty entry that causes experiments that don't require input to run once.

InputOptional

We gather input from StaticInput and SourceFiles. If there is input, we return it. Otherwise we return a single, empty entry that causes experiments that don't require input to run once.

InputOrQueryBackend

We gather input from StaticInput and SourceFiles. If there is input, we return it. Otherwise, we use OONI's probe services to gather input using the best API for the task.

InputOrStaticDefault

We gather input from StaticInput and SourceFiles. If there is input, we return it. Otherwise, we return an internal static list of inputs to be used with this experiment.

InputStrictlyRequired

We gather input from StaticInput and SourceFiles. If there is input, we return it. Otherwise, we return an error.

func (*Loader) Load

func (il *Loader) Load(ctx context.Context) ([]model.ExperimentTarget, error)

Load attempts to load input using the specified input loader. We will return a list of URLs because this is the only input we support.

type Logger

type Logger interface {
	// Warnf formats and emits a warning message.
	Warnf(format string, v ...interface{})
}

Logger is the model.Logger according to a *Loader.

type Session

type Session = model.ExperimentTargetLoaderSession

Session is the session according to a *Loader instance.