oonimkall

type AtomicInt64 ¶ added in v0.19.0

type AtomicInt64 struct {
	*atomicx.Int64
}

AtomicInt64 allows us to export atomicx.Int64 variables to mobile libraries so we can use them in testing.

type Context ¶ added in v0.17.0

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

Context is the context of an operation. You use this context to cancel a long running operation by calling Cancel(). Because you create a Context from a Session and because the Session is keeping track of the Context instances it owns, you do don't need to call the Cancel method when you're done.

func (ctx *Context) Cancel()

type GeolocateResults ¶ added in v0.17.0

type GeolocateResults struct {
	// ASN is the autonomous system number.
	ASN string

	// Country is the country code.
	Country string

	// IP is the IP address.
	IP string

	// Org is the commercial name of the ASN.
	Org string
}

GeolocateResults contains the GeolocateTask results.

type Logger ¶ added in v0.17.0

type Logger interface {
	Debug(msg string)
	Info(msg string)
	Warn(msg string)
}

Logger is the logger used by a Session. You should implement a class compatible with this interface in Java/ObjC and then save a reference to this instance in the SessionConfig object. All log messages that the Session will generate will be routed to this Logger.

type Session ¶ added in v0.17.0

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

Session contains shared state for running experiments and/or other OONI related task (e.g. geolocation). Note that the Session isn't mean to be a long living object. The workflow is to create a Session, do the operations you need to do with it now, then make sure it is not referenced by other variables, so the Go GC can finalize it.

Future directions ¶

We will eventually rewrite the code for running new experiments such that a Task will be created from a Session, such that experiments could share the same Session and save geolookups, etc. For now, we are in the suboptimal situations where Tasks create, use, and close their own session, thus running more lookups than needed.

func NewSession(config *SessionConfig) (*Session, error)

func (sess *Session) Geolocate(ctx *Context) (*GeolocateResults, error)

func (sess *Session) MaybeUpdateResources(ctx *Context) error

func (sess *Session) NewContext() *Context

func (sess *Session) NewContextWithTimeout(timeout int64) *Context

func (sess *Session) Submit(ctx *Context, measurement string) (*SubmitMeasurementResults, error)

type SessionConfig ¶ added in v0.17.0

type SessionConfig struct {
	// AssetsDir is the mandatory directory where to store assets
	// required by a Session, e.g. MaxMind DB files.
	AssetsDir string

	// Logger is the optional logger that will receive all the
	// log messages generated by a Session. If this field is nil
	// then the session will not emit any log message.
	Logger Logger

	// ProbeServicesURL allows you to optionally force the
	// usage of an alternative probe service instance. This setting
	// should only be used for implementing integration tests.
	ProbeServicesURL string

	// SoftwareName is the mandatory name of the application
	// that will be using the new Session.
	SoftwareName string

	// SoftwareVersion is the mandatory version of the application
	// that will be using the new Session.
	SoftwareVersion string

	// StateDir is the mandatory directory where to store state
	// information required by a Session.
	StateDir string

	// TempDir is the mandatory directory where the Session shall
	// store temporary files. Among other tasks, Session.Close will
	// remove any temporary file created within this Session.
	TempDir string

	// Verbose is optional. If there is a non-null Logger and this
	// field is true, then the Logger will also receive Debug messages,
	// otherwise it will not receive such messages.
	Verbose bool
}

SessionConfig contains configuration for a Session. You should fill all the mandatory fields and could also optionally fill some of the optional fields. Then pass this struct to NewSession.

type SubmitMeasurementResults ¶ added in v0.17.0

type SubmitMeasurementResults struct {
	UpdatedMeasurement string
	UpdatedReportID    string
}

SubmitMeasurementResults contains the results of a single measurement submission to the OONI backends using the OONI collector API.

type Task ¶

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

Task is an asynchronous task running an experiment. It mimics the namesake concept initially implemented in Measurement Kit.

Future directions ¶

Currently Task and Session are two unrelated APIs. As part of evolving the APIs with which apps interact with the engine, we will modify Task to run in the context of a Session. We will do that to save extra lookups and to allow several experiments running as subsequent Tasks to reuse the Session connections created with the OONI probe services backends.

func StartTask(input string) (*Task, error)

func (t *Task) Interrupt()

func (t *Task) IsDone() bool

func (t *Task) WaitForNextEvent() string