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.
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-cli/v3/internal/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 ¶
- Variables
- func NewUUID4() string
- type AtomicInt64
- type CheckInConfig
- type CheckInConfigWebConnectivity
- type CheckInInfo
- type CheckInInfoWebConnectivity
- type Context
- type ExperimentCallbacks
- type GeolocateResults
- type Logger
- type Session
- func (sess *Session) CheckIn(ctx *Context, config *CheckInConfig) (*CheckInInfo, error)
- func (sess *Session) FetchURLList(ctx *Context, config *URLListConfig) (*URLListResult, 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)
- func (sess *Session) WebConnectivity(ctx *Context, config *WebConnectivityConfig) (*WebConnectivityResults, error)
- type SessionConfig
- type SubmitMeasurementResults
- type Task
- type URLInfo
- type URLListConfig
- type URLListResult
- type WebConnectivityConfig
- type WebConnectivityResults
Constants ¶
This section is empty.
Variables ¶
var ( ActiveSessions = &AtomicInt64{&atomicx.Int64{}} ActiveContexts = &AtomicInt64{&atomicx.Int64{}} )
These two variables contain metrics pertaining to the number of Sessions and Contexts that are currently being used.
Functions ¶
Types ¶
type AtomicInt64 ¶
AtomicInt64 allows us to export atomicx.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 ("timed") 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) Add ¶
func (ckw *CheckInConfigWebConnectivity) Add(cat string)
Add 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.
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) FetchURLList ¶ added in v3.6.0
func (sess *Session) FetchURLList(ctx *Context, config *URLListConfig) (*URLListResult, error)
FetchURLList fetches the list of URLs to test
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) MaybeUpdateResources ¶
MaybeUpdateResources is a legacy stub. It does nothing. We will remove it when we're ready to bump the major number.
func (*Session) NewContext ¶
NewContext creates an new interruptible Context.
func (*Session) NewContextWithTimeout ¶
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) 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 ¶
StartTask starts an asynchronous task. The input argument is a serialized JSON conforming to MK v0.10.9's API.
func (*Task) WaitForNextEvent ¶
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 URLListConfig ¶ added in v3.6.0
type URLListConfig struct { Categories []string // Categories to query for (empty means all) CountryCode string // CountryCode is the optional country code Limit int64 // Max number of URLs (<= 0 means no limit) }
URLListConfig contains configuration for fetching the URL list.
func (*URLListConfig) AddCategory ¶ added in v3.6.0
func (ckw *URLListConfig) AddCategory(cat string)
AddCategory adds category code to the array in URLListConfig
type URLListResult ¶ added in v3.6.0
type URLListResult struct {
Results []model.OOAPIURLInfo
}
URLListResult contains the URLs returned from the FetchURL API
func (*URLListResult) At ¶ added in v3.6.0
func (ckw *URLListResult) At(idx int64) *URLInfo
At gets the URLInfo at position idx from CheckInInfoWebConnectivity.URLs. It returns nil if you are using an outs of bound index.
func (*URLListResult) Size ¶ added in v3.6.0
func (ckw *URLListResult) Size() int64
Size returns the number of URLs.
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.