tasks

Documentation

Overview

Package tasks implements tasks run using the oonimkall API.

Index

• Constants
• func Run(ctx context.Context, settings *Settings, out chan<- *Event)
• type ChanLogger
  • func NewChanLogger(emitter *EventEmitter, logLevel string, out chan<- *Event) *ChanLogger
  • func (cl *ChanLogger) Debug(msg string)
  • func (cl *ChanLogger) Debugf(format string, v ...interface{})
  • func (cl *ChanLogger) Info(msg string)
  • func (cl *ChanLogger) Infof(format string, v ...interface{})
  • func (cl *ChanLogger) Warn(msg string)
  • func (cl *ChanLogger) Warnf(format string, v ...interface{})
• type Event
• type EventEmitter
  • func NewEventEmitter(disabledEvents []string, out chan<- *Event) *EventEmitter
  • func (ee *EventEmitter) Emit(key string, value interface{})
  • func (ee *EventEmitter) EmitFailureGeneric(name, failure string)
  • func (ee *EventEmitter) EmitFailureStartup(failure string)
  • func (ee *EventEmitter) EmitStatusProgress(percentage float64, message string)
• type EventFailure
• type EventLog
• type EventStatusProgress
• type Runner
  • func NewRunner(settings *Settings, out chan<- *Event) *Runner
  • func (r *Runner) Run(ctx context.Context)
• type Settings
• type SettingsOptions

Constants

const FailureInvalidVersion = "invalid Settings.Version number"

FailureInvalidVersion is the failure returned when Version is invalid

Functions

func Run

func Run(ctx context.Context, settings *Settings, out chan<- *Event)

Run runs the task specified by settings.Name until completion. This is the top-level API that should be called by oonimkall.

Types

type ChanLogger

type ChanLogger struct {
	// contains filtered or unexported fields
}

ChanLogger is a logger targeting a channel

func NewChanLogger

func NewChanLogger(emitter *EventEmitter, logLevel string,
	out chan<- *Event) *ChanLogger

NewChanLogger creates a new ChanLogger instance.

func (*ChanLogger) Debug

func (cl *ChanLogger) Debug(msg string)

Debug implements Logger.Debug

func (*ChanLogger) Debugf

func (cl *ChanLogger) Debugf(format string, v ...interface{})

Debugf implements Logger.Debugf

func (*ChanLogger) Info

func (cl *ChanLogger) Info(msg string)

Info implements Logger.Info

func (*ChanLogger) Infof

func (cl *ChanLogger) Infof(format string, v ...interface{})

Infof implements Logger.Infof

func (*ChanLogger) Warn

func (cl *ChanLogger) Warn(msg string)

Warn implements Logger.Warn

func (*ChanLogger) Warnf

func (cl *ChanLogger) Warnf(format string, v ...interface{})

Warnf implements Logger.Warnf

type Event

type Event struct {
	Key   string      `json:"key"`
	Value interface{} `json:"value"`
}

Event is an event emitted by a task. This structure extends the event described by MK v0.10.9 FFI API (https://git.io/Jv4Rv).

type EventEmitter

type EventEmitter struct {
	// contains filtered or unexported fields
}

EventEmitter emits event on a channel

func NewEventEmitter

func NewEventEmitter(disabledEvents []string, out chan<- *Event) *EventEmitter

NewEventEmitter creates a new Emitter

func (*EventEmitter) Emit

func (ee *EventEmitter) Emit(key string, value interface{})

Emit emits the specified event

func (*EventEmitter) EmitFailureGeneric

func (ee *EventEmitter) EmitFailureGeneric(name, failure string)

EmitFailureGeneric emits a failure event

func (*EventEmitter) EmitFailureStartup

func (ee *EventEmitter) EmitFailureStartup(failure string)

EmitFailureStartup emits the failureStartup event

func (*EventEmitter) EmitStatusProgress

func (ee *EventEmitter) EmitStatusProgress(percentage float64, message string)

EmitStatusProgress emits the status.Progress event

type EventFailure

type EventFailure struct {
	Failure string `json:"failure"`
}

EventFailure contains information on a failure.

type EventLog

type EventLog struct {
	LogLevel string `json:"log_level"`
	Message  string `json:"message"`
}

EventLog is an event containing a log message.

type EventStatusProgress

type EventStatusProgress struct {
	Message    string  `json:"message"`
	Percentage float64 `json:"percentage"`
}

EventStatusProgress reports progress information.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner runs a specific task

func NewRunner

func NewRunner(settings *Settings, out chan<- *Event) *Runner

NewRunner creates a new task runner

func (*Runner) Run

func (r *Runner) Run(ctx context.Context)

Run runs the runner until completion. The context argument controls when to stop when processing multiple inputs, as well as when to stop experiments explicitly marked as interruptible.

type Settings

type Settings struct {
	// Annotations contains the annotations to be added
	// to every measurements performed by the task.
	Annotations map[string]string `json:"annotations,omitempty"`

	// AssetsDir is the directory where to store assets. This
	// field is an extension of MK's specification. If
	// this field is empty, the task won't start.
	AssetsDir string `json:"assets_dir"`

	// DisabledEvents contains disabled events. See
	// https://git.io/Jv4Rv for the events names.
	DisabledEvents []string `json:"disabled_events,omitempty"`

	// Inputs contains the inputs. The task will fail if it
	// requires input and you provide no input.
	Inputs []string `json:"inputs,omitempty"`

	// LogLevel contains the logs level. See https://git.io/Jv4Rv
	// for the names of the available log levels.
	LogLevel string `json:"log_level,omitempty"`

	// Name contains the task name. By https://git.io/Jv4Rv the
	// names are in camel case, e.g. `Ndt`.
	Name string `json:"name"`

	// Options contains the task options.
	Options SettingsOptions `json:"options"`

	// Proxy allows you to optionally force a specific proxy
	// rather than using no proxy (the default).
	//
	// Use `psiphon:///` to force using Psiphon with the
	// embedded configuration file. Not all builds have
	// an embedded configuration file, but OONI builds have
	// such a file, so they can use this functionality.
	//
	// Use `socks5://10.0.0.1:9050/` to connect to a SOCKS5
	// proxy running on 10.0.0.1:9050. This could be, for
	// example, a suitably configured `tor` instance.
	Proxy string

	// StateDir is the directory where to store persistent data. This
	// field is an extension of MK's specification. If
	// this field is empty, the task won't start.
	StateDir string `json:"state_dir"`

	// TempDir is the temporary directory. This field is an extension of MK's
	// specification. If this field is empty, we will pick the tempdir that
	// ioutil.TempDir uses by default, which may not work on mobile. According
	// to our experiments as of 2020-06-10, leaving the TempDir empty works
	// for iOS and does not work for Android.
	TempDir string `json:"temp_dir"`

	// TunnelDir is the directory where to store persistent state
	// related to circumvention tunnels. This directory is required
	// only if you want to use the tunnels. Added since 3.10.0.
	TunnelDir string `json:"tunnel_dir"`

	// Version indicates the version of this structure.
	Version int64 `json:"version"`
}

Settings contains settings for a task. This structure derives from the one described by MK v0.10.9 FFI API (https://git.io/Jv4Rv), yet since 2020-12-03 we're not backwards compatible anymore.

type SettingsOptions

type SettingsOptions struct {
	// MaxRuntime is the maximum runtime expressed in seconds. A negative
	// value for this field disables the maximum runtime. Using
	// a zero value will also mean disabled. This is not the
	// original behaviour of Measurement Kit, which used to run
	// for zero time in such case.
	MaxRuntime float64 `json:"max_runtime,omitempty"`

	// NoCollector indicates whether to use a collector
	NoCollector bool `json:"no_collector,omitempty"`

	// ProbeServicesBaseURL contains the probe services base URL.
	ProbeServicesBaseURL string `json:"probe_services_base_url,omitempty"`

	// SoftwareName is the software name. If this option is not
	// present, then the library startup will fail.
	SoftwareName string `json:"software_name,omitempty"`

	// SoftwareVersion is the software version. If this option is not
	// present, then the library startup will fail.
	SoftwareVersion string `json:"software_version,omitempty"`
}

SettingsOptions contains the settings options