roctokit

Roctokit [core]: Rust Interfaces for a Generated GitHub v3 API

Roctokit provides high-level client interfaces for interacting with GitHub's v3 API, supporting both synchronous and asynchronous HTTP clients, as well as WebAssembly compatibility.

This library extends the adapter subsystem, offering flexible and extensible client implementations suitable for production systems. Roctokit is designed to be used alongside roctogen, which generates API models and endpoints from GitHub's OpenAPI specification.

Getting Started

To use Roctokit, enable the appropriate feature in your Cargo build command:

• Asynchronous requests with reqwest: cargo build --feature reqwest
• Synchronous requests with ureq: cargo build --feature ureq
• WebAssembly support: cargo build --target wasm32-unknown-unknown

Add both roctogen and roctokit as dependencies in your Cargo.toml:

[dependencies]
roctogen = "*"
roctokit = "*"

Client Creation

GitHub's v3 API supports multiple authentication methods, affecting both access and rate limits. These methods are encapsulated in the Auth struct, which is passed to the client:

• Basic Authentication: Auth::Basic(user, pass)
• Personal Access Token: Auth::Token(token)
• OAuth Bearer Token: Auth::Bearer(bearer)
• Unauthenticated Access: Auth::None

Clients can use either a stock implementation or a custom one that conforms to the adapter::Client trait. Roctokit provides a convenience function to create clients when the appropriate feature is enabled:

use roctokit::adapters::client;
use roctokit::auth::Auth;

let auth = Auth::None;

let client = client(&auth).expect("Failed to create client");

APIs and Endpoints

The API endpoints are automatically generated by roctogen. For a comprehensive overview of supported endpoints, models, and parameters, consult the roctogen documentation.

Additional examples on building query parameter structs and making requests are available in the roctogen README.

Custom Client Adapters

Beyond the stock implementations, Roctokit allows custom client adapters, providing control over pagination, backpressure, and alternative HTTP frameworks. This is an advanced feature best explored through the examples.

To create a custom client, implement the adapters::Client trait:

struct MyClient;

impl roctokit::adapters::Client for MyClient {
    type Req = MyRequest;
    type Err = MyError;
    type Body = Vec<u8>;

    // Implement required methods...
}

A custom client integrates with roctogen by handling authentication, request building, HTTP transport, and response parsing:

• type Req: Represents a request compatible with the chosen HTTP client.
• type Err: Defines an error type convertible to roctokit::adapters::AdapterError.
• type Body: Specifies the request payload type (e.g., JSON body).

The following methods must be implemented:

• new: Creates the client instance.
• build: Constructs a type Req from a GitHubRequest.
• fetch / fetch_async: Sends the request synchronously or asynchronously.
• from_json: Serialises a roctogen model into a request body.

Additionally, the GitHubResponseExt trait must be implemented for the response type used by the HTTP client. It includes:

• is_success: Determines whether the response is successful.
• status_code: Retrieves the response status code.
• to_json / to_json_async: Parses the response body into a roctogen model.

Testing

By default, tests make real HTTP requests to the GitHub API. Some tests use a mock server when the mock feature is enabled. The wasm tests require wasm-pack to run.

WebAssembly Tests

wasm-pack test --firefox --headless

Synchronous Tests

cargo test --target x86_64-unknown-linux-gnu -- --nocapture

To avoid hitting GitHub’s API rate limits, you can run a local WireMock server:

docker run -d --name wiremock -p 8080:8080 -v $PWD/tests/stubs:/home/wiremock rodolpheche/wiremock
cargo test --features mock,ureq

Regenerating WireMock Stubs

If GitHub's API changes, regenerate the WireMock stubs:

docker run -d --name wiremock -p 8080:8080 -v $PWD/tests/stubs:/home/wiremock -u $(id -u):$(id -g) \
  rodolpheche/wiremock --verbose --proxy-all="https://api.github.com" --record-mappings

License

This project is licensed under the Apache 2.0 License.

License: Apache-2.0