oonimkall

package
v3.19.0-alpha.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2023 License: GPL-3.0 Imports: 20 Imported by: 0

README

Package github.com/ooni/probe-cli/pkg/oonimkall

Package oonimkall implements APIs used by OONI mobile apps. We expose these APIs to mobile apps using gomobile.

We expose two APIs: the task API, which is derived from the API originally exposed by Measurement Kit, and the session API, which is a Go API that mobile apps can use via gomobile.

This package is named oonimkall because it contains a partial reimplementation of the mkall API implemented by Measurement Kit in, e.g., mkall-ios.

The basic tenet of the task API is that you define an experiment task you wanna run using a JSON, then you start a task for it, and you receive events as serialized JSONs. In addition to this functionality, we also include extra APIs used by OONI mobile.

The basic tenet of the session API is that you create an instance of Session and use it to perform the operations you need.

Documentation

Overview

Package oonimkall implements APIs used by OONI mobile apps. We expose these APIs to mobile apps using gomobile.

We expose two APIs: the task API, which is derived from the API originally exposed by Measurement Kit, and the session API, which is a Go API that mobile apps can use via `gomobile`.

This package is named oonimkall because it contains a partial reimplementation of the mkall API implemented by Measurement Kit in, e.g., https://github.com/measurement-kit/mkall-ios.

Design

See docs/design/dd-001-oonimkall.md in the probe-cli repository.

Semantic versioning policy

This package is public for technical reasons. We cannot use `go mobile` on a private package. Yet, we are not going to bump this repository's major number in case we change oonimkall's API. We consider this package our private API for interfacing with our mobile applications for Android and iOS.

Task API

The basic tenet of the task API is that you define an experiment task you wanna run using a JSON, then you start a task for it, and you receive events as serialized JSONs. In addition to this functionality, we also include extra APIs used by OONI mobile.

The task API was first defined in Measurement Kit v0.9.0. In this context, it was called "the FFI API". The API we expose here is not strictly an FFI API, but is close enough for the purpose of using OONI from Android and iOS. See https://git.io/Jv4Rv (measurement-kit/measurement-kit@v0.10.9) for a comprehensive description of MK's FFI API.

See also https://github.com/ooni/probe-engine/pull/347 for the design document describing the task API.

See also https://github.com/ooni/probe-engine/blob/master/DESIGN.md, which explains why we implemented the oonimkall API.

Session API

The Session API is a Go API that can be exported to mobile apps using the gomobile tool. The latest design document for this API is at https://github.com/ooni/probe-engine/pull/954.

The basic tenet of the session API is that you create an instance of `Session` and use it to perform the operations you need.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ActiveSessions = &AtomicInt64{&atomic.Int64{}}
	ActiveContexts = &AtomicInt64{&atomic.Int64{}}
)

These two variables contain metrics pertaining to the number of Sessions and Contexts that are currently being used.

Functions

func NewUUID4 

func NewUUID4() string

NewUUID4 generates a new UUID4 string. This functionality is typically used by mobile apps to generate random unique identifiers.

Types

type AtomicInt64 

type AtomicInt64 struct {
	*atomic.Int64
}

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

type CheckInConfig 

type CheckInConfig struct {
	// Charging indicates whether the phone is charging.
	Charging bool

	// OnWiFi indicates whether the phone is using the Wi-Fi.
	OnWiFi bool

	// Platform is the mobile platform (e.g. "android")
	Platform string

	// RunType indicates whether this is an automated (model.RunTypeTimed) run
	// or otherwise a manual run initiated by the user.
	RunType string

	// SoftwareName is the name of the application.
	SoftwareName string

	// SoftwareVersion is the version of the application.
	SoftwareVersion string

	// WebConnectivity contains configuration items specific of
	// the WebConnectivity experiment.
	WebConnectivity *CheckInConfigWebConnectivity
}

CheckInConfig contains configuration for the check-in API.

type CheckInConfigWebConnectivity 

type CheckInConfigWebConnectivity struct {
	// CategoryCodes contains zero or more category codes (e.g. "HUMR").
	CategoryCodes []string
}

CheckInConfigWebConnectivity contains WebConnectivity configuration for the check-in API.

func (*CheckInConfigWebConnectivity) AddCategory added in v3.17.0 

func (ckw *CheckInConfigWebConnectivity) AddCategory(cat string)

AddCategory adds a category code to ckw.CategoryCode. This method allows you to edit ckw.CategoryCodes, which is inaccessible from Java/ObjC.

type CheckInInfo 

type CheckInInfo struct {
	// WebConnectivity contains results that are specific to
	// the WebConnectivity experiment. This field MAY be null
	// if the server's response did not contain any info.
	WebConnectivity *CheckInInfoWebConnectivity
}

CheckInInfo contains the result of the check-in API.

type CheckInInfoWebConnectivity 

type CheckInInfoWebConnectivity struct {
	// ReportID is the report ID we should be using.
	ReportID string

	// URLs contains the list of URLs to measure.
	URLs []model.OOAPIURLInfo
}

CheckInInfoWebConnectivity contains the WebConnectivity specific results of the check-in API call.

func (*CheckInInfoWebConnectivity) At 

func (ckw *CheckInInfoWebConnectivity) At(idx int64) *URLInfo

At returns the URLInfo at index idx. Note that this function will return nil/null if the index is out of bounds.

func (*CheckInInfoWebConnectivity) Size 

func (ckw *CheckInInfoWebConnectivity) Size() int64

Size returns the number of URLs included into the result.

type Context 

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 (*Context) Cancel 

func (ctx *Context) Cancel()

Cancel cancels pending operations using this context. This method is idempotent. Calling it more than once is fine. The first invocation cancels the context. Subsequent invocations are no-operations.

type ExperimentCallbacks added in v3.8.0 

type ExperimentCallbacks interface {
	// OnProgress provides information about an experiment progress.
	OnProgress(percentage float64, message string)
}

ExperimentCallbacks contains experiment callbacks.

type GeolocateResults 

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 results of session.Geolocate.

type Logger 

type Logger interface {
	// Debug handles debug messages.
	Debug(msg string)

	// Info handles informational messages.
	Info(msg string)

	// Warn handles warning messages.
	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 

type Session struct {
	// Hooks for testing (should not appear in Java/ObjC, because they
	// cannot be automatically transformed to Java/ObjC code.)
	TestingCheckInBeforeNewProbeServicesClient func(ctx *Context)
	TestingCheckInBeforeCheckIn                func(ctx *Context)
	// 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. This is what you would normally done with Java/ObjC.

func NewSession 

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

NewSession is like NewSessionWithContext but without context. This factory is deprecated and will be removed when we bump the major version number of ooni/probe-cli.

func NewSessionWithContext added in v3.10.0 

func NewSessionWithContext(ctx *Context, config *SessionConfig) (*Session, error)

NewSessionWithContext creates a new session. You should use a session for running a set of operations in a relatively short time frame. You SHOULD NOT create a single session and keep it all alive for the whole app lifecyle, since the Session code is not specifically designed for this use case.

func (*Session) CheckIn 

func (sess *Session) CheckIn(ctx *Context, config *CheckInConfig) (*CheckInInfo, error)

CheckIn calls the check-in API. Both ctx and config MUST NOT be nil. This function will fail if config is missing required settings. The return value is either an error or a valid CheckInInfo instance. Beware that the returned object MAY still contain nil fields depending on the server's response.

This function locks the session until it's done. That is, no other operation can be performed as long as this function is pending.

func (*Session) Geolocate 

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

Geolocate performs a geolocate operation and returns the results.

This function locks the session until it's done. That is, no other operation can be performed as long as this function is pending.

func (*Session) NewContext 

func (sess *Session) NewContext() *Context

NewContext creates an new interruptible Context.

func (*Session) NewContextWithTimeout 

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

NewContextWithTimeout creates an new interruptible Context that will automatically cancel itself after the given timeout. Setting a zero or negative timeout implies there is no actual timeout configured for the Context, making this invocation equivalent to calling NewContext().

func (*Session) OONIRunFetch added in v3.18.1 

func (sess *Session) OONIRunFetch(ctx *Context, ID int64) (string, error)

OONIRunFetch fetches a given OONI run descriptor.

The ID argument is the unique identifier of the OONI Run link. For example, in: 

https://api.ooni.io/api/_/ooni_run/fetch/297500125102

The OONI Run link ID is 297500125102.

Warning: this API is currently experimental and we only expose it to facilitate developing OONI Run v2. Do not use this API in production.

func (*Session) Submit 

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

Submit submits the given measurement and returns the results.

This function locks the session until it's done. That is, no other operation can be performed as long as this function is pending.

func (*Session) WebConnectivity added in v3.9.0 

func (sess *Session) WebConnectivity(ctx *Context, config *WebConnectivityConfig) (*WebConnectivityResults, error)

WebConnectivity runs the WebConnectivity experiment. Both ctx and config MUST NOT be nil. Returns either an error or the experiment results.

This function locks the session until it's done. That is, no other operation can be performed as long as this function is pending.

This API is currently experimental. We do not promise that we will bump the major version number when changing it.

type SessionConfig 

type SessionConfig struct {
	// AssetsDir is the mandatory directory where to store assets
	// required by a Session, e.g. MaxMind DB files.
	//
	// This field is currently deprecated and unused. We will
	// remove it when we'll bump the major number.
	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

	// 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

	// 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

	// TunnelDir is the directory where the Session shall store
	// persistent data regarding circumvention tunnels. This directory
	// is mandatory if you want to use tunnels.
	TunnelDir 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 

type SubmitMeasurementResults struct {
	// UpdateMeasurement is the measurement with updated report ID.
	UpdatedMeasurement string

	// UpdatedReportID is the report ID used for the measurement.
	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 

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

StartTask starts an asynchronous task. The input argument is a serialized JSON conforming to MK v0.10.9's API.

func (*Task) Interrupt 

func (t *Task) Interrupt()

Interrupt interrupts the task.

func (*Task) IsDone 

func (t *Task) IsDone() bool

IsDone returns true if the task is done.

func (*Task) WaitForNextEvent 

func (t *Task) WaitForNextEvent() string

WaitForNextEvent blocks until the next event occurs. The returned string is a serialized JSON following MK v0.10.9's API.

type URLInfo 

type URLInfo struct {
	// CategoryCode is the URL's category code (e.g. "HUMR").
	CategoryCode string

	// CountryCode is the test list from which this URL
	// comes from (e.g. "IT", "FR").
	CountryCode string

	// URL is the URL itself.
	URL string
}

URLInfo contains info on a specific URL to measure.

type WebConnectivityConfig added in v3.9.0 

type WebConnectivityConfig struct {
	// Callbacks contains the experiment callbacks. This field is
	// optional. Leave it empty and we'll use a default set of
	// callbacks that use the session logger.
	Callbacks ExperimentCallbacks

	// Input contains the URL to measure. This field must be set
	// by the user, otherwise the experiment fails.
	Input string
}

WebConnectivityConfig contains settings for WebConnectivity.

type WebConnectivityResults added in v3.9.0 

type WebConnectivityResults struct {
	// KibiBytesReceived contains the KiB received.
	KibiBytesReceived float64

	// KibiBytesSent contains the KiB sent.
	KibiBytesSent float64

	// Measurement contains the resulting measurement.
	Measurement string
}

WebConnectivityResults contains the results of WebConnectivity.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.