ooapi

README

Package ./internal/engine/ooapi

Automatically generated API clients for speaking with OONI servers.

Please, run go doc ./internal/engine/ooapi to see API documentation.

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.

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.

See the example describing auto-login for more information on how to use auto-login.

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

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 {
	BaseURL      string       // optional
	GobCodec     GobCodec     // optional
	HTTPClient   HTTPClient   // optional
	JSONCodec    JSONCodec    // optional
	KVStore      KVStore      // mandatory
	RequestMaker RequestMaker // optional
	UserAgent    string       // optional
}

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

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.

type HTTPClient

type HTTPClient interface {
	// Do should work like http.Client.Do.
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is the interface of a generic HTTP client.

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.

type KVStore

type KVStore interface {
	// Get gets a value from the key-value store.
	Get(key string) ([]byte, error)

	// Set stores a value into the key-value store.
	Set(key string, value []byte) error
}

KVStore is a key-value store.

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.