c/ooni-probe-cli
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fce6eb779b
ooni-probe-cli/pkg/oonimkall/doc.go

53 lines
2.2 KiB
Go
Raw Normal View History

[forwardport] fix(oonimkall): ensure we can submit last measurement (#699) This diff forward ports 018b5de8ce10040b553f0923f70543c1071b954c, whose original commit message follows: - - - The underlying issue causing https://github.com/ooni/probe/issues/2037 is that the final measurement of a web_connectivity run is not submitted because the context expires while we're submitting it in most cases. In turn, this happens because a web_connectivity measurement is not interrupted midway, since it's not interruptible. This choice is sound in that we want to finish an in progress measurement. And this is also why the max_runtime is never 100% accurate. Yet, once the context is expired, the subsequent submission fails. Fix the issue by using three contexts. The root context is the one that the user controls. The measurement context is the one tied to the max runtime. The submit context is tied to the max runtime plus extra slack time to ensure we submit the measurement. With this diff applied, I run the mobile app a couple of times and did not notice any unsubmitted measurements. Still, more testing is also probably required to further ensure we've properly fixed. I'm committing this diff in the release/3.14 branch but we WILL also need to forward port it into the master branch. While there, since pkg/oonimkall is a large package, let us create a doc.go file for keeping the docs. Conflicts: pkg/oonimkall/task.go
2022-02-23 12:38:58 +01:00
// 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.
//
doc: publish the step-by-step design document (#814) This pull request publishes the step-by-step design document that I have been discussing with @hellais and @DecFox recently. Compared to the document that was approved, this one has been edited for readability. While there, I figured it was also be beneficial to publish the few ooni/probe-cli related design documents we produced in the past, because they probably help someone to get acquainted with the codebase. Reference issue for this pull request: https://github.com/ooni/probe/issues/2148
2022-06-14 14:38:29 +02:00
// Design
//
// See docs/design/dd-001-oonimkall.md in the probe-cli repository.
//
[forwardport] fix(oonimkall): ensure we can submit last measurement (#699) This diff forward ports 018b5de8ce10040b553f0923f70543c1071b954c, whose original commit message follows: - - - The underlying issue causing https://github.com/ooni/probe/issues/2037 is that the final measurement of a web_connectivity run is not submitted because the context expires while we're submitting it in most cases. In turn, this happens because a web_connectivity measurement is not interrupted midway, since it's not interruptible. This choice is sound in that we want to finish an in progress measurement. And this is also why the max_runtime is never 100% accurate. Yet, once the context is expired, the subsequent submission fails. Fix the issue by using three contexts. The root context is the one that the user controls. The measurement context is the one tied to the max runtime. The submit context is tied to the max runtime plus extra slack time to ensure we submit the measurement. With this diff applied, I run the mobile app a couple of times and did not notice any unsubmitted measurements. Still, more testing is also probably required to further ensure we've properly fixed. I'm committing this diff in the release/3.14 branch but we WILL also need to forward port it into the master branch. While there, since pkg/oonimkall is a large package, let us create a doc.go file for keeping the docs. Conflicts: pkg/oonimkall/task.go
2022-02-23 12:38:58 +01:00
// 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-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.
package oonimkall
Reference in New Issue Copy Permalink