ooapi

Documentation

Overview

Package ooapi contains a client for the OONI API. We automatically generate the code in this package from the apimodel and internal/generator packages.

Note

This package is currrently unused. We plan on replacing existing code to speak with the OONI API with it.

Usage

You need to create a Client. Make sure you set all the mandatory fields. You will then have a function for every supported OONI API. This function will take in input a context and a request. You need to fill the request, of course. The return value is either a response or an error.

If an API requires login, we will automatically perform the login. If an API uses caching, we will automatically use the cache.

Design

Most of the code in this package is auto-generated from the data model in ./apimodel and the definition of APIs provided by ./internal/generator/spec.go.

We keep the generated files up-to-date by running

go generate ./...

We have tests that ensure that the definition of the API used here is reasonably close to the server's one.

Testing

The following command

go test ./...

will, among other things, ensure that the our API spec is consistent with the server's one. Running

go test -short ./...

will exclude most (slow) integration tests.

Architecture

The ./apimodel sub-package contains the definition of request and response messages. We rely on tagging to specify how we should encode and decode messages.

The ./internal/generator sub-package contains code to generate most code in this package. In particular, the spec.go file is the specification of the APIs.

Index

• Variables
• type Client
  • func (c *Client) CheckIn(ctx context.Context, req *apimodel.CheckInRequest) (*apimodel.CheckInResponse, error)
  • func (c *Client) CheckReportID(ctx context.Context, req *apimodel.CheckReportIDRequest) (*apimodel.CheckReportIDResponse, error)
  • func (c *Client) MeasurementMeta(ctx context.Context, req *apimodel.MeasurementMetaRequest) (*apimodel.MeasurementMetaResponse, error)
  • func (c *Client) OpenReport(ctx context.Context, req *apimodel.OpenReportRequest) (*apimodel.OpenReportResponse, error)
  • func (c *Client) PsiphonConfig(ctx context.Context, req *apimodel.PsiphonConfigRequest) (apimodel.PsiphonConfigResponse, error)
  • func (c *Client) SubmitMeasurement(ctx context.Context, req *apimodel.SubmitMeasurementRequest) (*apimodel.SubmitMeasurementResponse, error)
  • func (c *Client) TestHelpers(ctx context.Context, req *apimodel.TestHelpersRequest) (apimodel.TestHelpersResponse, error)
  • func (c *Client) TorTargets(ctx context.Context, req *apimodel.TorTargetsRequest) (apimodel.TorTargetsResponse, error)
  • func (c *Client) URLs(ctx context.Context, req *apimodel.URLsRequest) (*apimodel.URLsResponse, error)
• type GobCodec
• type HTTPClient
• type JSONCodec
• type KVStore
• type RequestMaker

Examples

• Client

Variables

var (
	ErrAPICallFailed   = errors.New("ooapi: API call failed")
	ErrEmptyField      = errors.New("ooapi: empty field")
	ErrHTTPFailure     = errors.New("ooapi: http request failed")
	ErrJSONLiteralNull = errors.New("ooapi: server returned us a literal null")
	ErrMissingToken    = errors.New("ooapi: missing auth token")
	ErrUnauthorized    = errors.New("ooapi: not authorized")
)

Errors defined by this package.

Types

type Client

type Client struct {
	// KVStore is the MANDATORY key-value store. You can use
	// the kvstore.Memory{} struct for an in-memory store.
	KVStore KVStore

	// The following fields are optional. When they are empty
	// we will fallback to sensible defaults.
	BaseURL      string
	GobCodec     GobCodec
	HTTPClient   HTTPClient
	JSONCodec    JSONCodec
	RequestMaker RequestMaker
	UserAgent    string
}

Client is a client for speaking with the OONI API. Make sure you fill in the mandatory fields.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/ooni/probe-cli/v3/internal/kvstore"
	"github.com/ooni/probe-cli/v3/internal/ooapi"
	"github.com/ooni/probe-cli/v3/internal/ooapi/apimodel"
)

func main() {
	clnt := &ooapi.Client{
		KVStore: &kvstore.Memory{},
	}
	ctx := context.Background()
	resp, err := clnt.CheckIn(ctx, &apimodel.CheckInRequest{
		Charging:        false,
		OnWiFi:          false,
		Platform:        "linux",
		ProbeASN:        "AS30722",
		ProbeCC:         "IT",
		RunType:         "timed",
		SoftwareName:    "miniooni",
		SoftwareVersion: "0.1.0-dev",
		WebConnectivity: apimodel.CheckInRequestWebConnectivity{
			CategoryCodes: []string{"NEWS"},
		},
	})
	fmt.Printf("%+v\n", err)

	if resp == nil {
		log.Fatal("expected non-nil response")
	}
}

Output:

<nil>

func (*Client) CheckIn

func (c *Client) CheckIn(
	ctx context.Context, req *apimodel.CheckInRequest,
) (*apimodel.CheckInResponse, error)

CheckIn calls the CheckIn API.

func (*Client) CheckReportID

func (c *Client) CheckReportID(
	ctx context.Context, req *apimodel.CheckReportIDRequest,
) (*apimodel.CheckReportIDResponse, error)

CheckReportID calls the CheckReportID API.

func (*Client) MeasurementMeta

func (c *Client) MeasurementMeta(
	ctx context.Context, req *apimodel.MeasurementMetaRequest,
) (*apimodel.MeasurementMetaResponse, error)

MeasurementMeta calls the MeasurementMeta API.

func (*Client) OpenReport

func (c *Client) OpenReport(
	ctx context.Context, req *apimodel.OpenReportRequest,
) (*apimodel.OpenReportResponse, error)

OpenReport calls the OpenReport API.

func (*Client) PsiphonConfig

func (c *Client) PsiphonConfig(
	ctx context.Context, req *apimodel.PsiphonConfigRequest,
) (apimodel.PsiphonConfigResponse, error)

PsiphonConfig calls the PsiphonConfig API.

func (*Client) SubmitMeasurement

func (c *Client) SubmitMeasurement(
	ctx context.Context, req *apimodel.SubmitMeasurementRequest,
) (*apimodel.SubmitMeasurementResponse, error)

SubmitMeasurement calls the SubmitMeasurement API.

func (*Client) TestHelpers

func (c *Client) TestHelpers(
	ctx context.Context, req *apimodel.TestHelpersRequest,
) (apimodel.TestHelpersResponse, error)

TestHelpers calls the TestHelpers API.

func (*Client) TorTargets

func (c *Client) TorTargets(
	ctx context.Context, req *apimodel.TorTargetsRequest,
) (apimodel.TorTargetsResponse, error)

TorTargets calls the TorTargets API.

func (*Client) URLs

func (c *Client) URLs(
	ctx context.Context, req *apimodel.URLsRequest,
) (*apimodel.URLsResponse, error)

URLs calls the URLs API.

type GobCodec

type GobCodec interface {
	// Encode encodes v as a serialized gob byte slice.
	Encode(v interface{}) ([]byte, error)

	// Decode decodes the serialized gob byte slice into v.
	Decode(b []byte, v interface{}) error
}

GobCodec is a Gob encoder and decoder. Generally, we use a default GobCodec in Client. This is the interface to implement if you want to override such a default.

type HTTPClient

type HTTPClient = model.HTTPClient

HTTPClient is the interface of a generic HTTP client. The stdlib's http.Client implements this interface. We use http.DefaultClient as the default HTTPClient used by Client. Consumers of this package typically provide a custom HTTPClient with additional functionality (e.g., DoH, circumvention).

type JSONCodec

type JSONCodec interface {
	// Encode encodes v as a serialized JSON byte slice.
	Encode(v interface{}) ([]byte, error)

	// Decode decodes the serialized JSON byte slice into v.
	Decode(b []byte, v interface{}) error
}

JSONCodec is a JSON encoder and decoder. Generally, we use a default JSONCodec in Client. This is the interface to implement if you want to override such a default.

type KVStore

type KVStore = model.KeyValueStore

KVStore is a key-value store. This is the interface the client expect for the key-value store used to save persistent state (typically on the file system).

type RequestMaker

type RequestMaker interface {
	// NewRequest creates a new HTTP request.
	NewRequest(ctx context.Context, method, URL string, body io.Reader) (*http.Request, error)
}

RequestMaker makes an HTTP request. Generally, we use a default RequestMaker in Client. This is the interface to implement if you want to override such a default.