#gaato/github

Status: unofficial and experimental. Minor releases may contain breaking changes; the changelog lists each one with a migration note.

#Install

moon add gaato/github
moon add gaato/http
moon add gaato/mttp
moon add gaato/http-async

#Usage

///|
let backend = @codings.Decompress::new(@backend.AsyncBackend::new())

///|
let clock = @runtime.AsyncClock::new()

///|
/// Reads a repository's star count.
pub async fn stars(
  backend : &@http.Backend,
  clock : &@rt.Clock,
  token~ : String,
) -> Result[Int32, @github.GitHubFailure] {
  let gh = @github.GitHub::new(backend, clock, token~)
  let repo = gh.call(
    @gen.repos_get_request("gaato", "mbt-sdk"),
    @gen.repos_get_decode,
  )
  match repo {
    Ok(repo) => Ok(repo.stargazers_count)
    Err(error) => Err(error)
  }
}

#Packages

#Requests and responses

///|
/// Reads the diff between two refs.
pub async fn compare_diff(
  gh : @github.GitHub,
  range : String,
) -> Result[String, @github.GitHubFailure] {
  let response = gh.send(
    @gen.repos_compare_commits_request("gaato", "mbt-sdk", range).header(
      "accept", "application/vnd.github.diff",
    ),
  )
  match response {
    Ok(response) => Ok(@utf8.decode_lossy(response.body))
    Err(error) => Err(error)
  }
}

#Downloads and redirects

• repos_download_tarball_archive and repos_download_zipball_archive
• actions_download_artifact and the actions_download_*_logs operations
• migrations_download_archive_for_org and migrations_get_archive_for_authenticated_user
• some of the time, repos_get_release_asset with accept: application/octet-stream and code_scanning_get_codeql_database with accept: application/zip

#Pagination

///|
/// Lists up to 250 of a user's repositories.
pub async fn user_repos(
  gh : @github.GitHub,
  user : String,
) -> Result[Array[@gen.MinimalRepository], @github.GitHubFailure] {
  let repos = gh.paginator(
    @gen.repos_list_for_user_request(user, per_page=100),
    @gen.repos_list_for_user_decode,
  )
  repos.collect(max=250)
}

#GraphQL

///|
/// Reads a repository's star count through GraphQL.
pub async fn stars_graphql(
  gh : @github.GitHub,
) -> Result[Json, @github.GitHubFailure] {
  gh.graphql(
    query="query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { stargazerCount } }",
    variables={ "owner": "gaato", "name": "mbt-sdk" },
  )
}

#Rate limits

• writes and every GraphQL request at least 1 s apart;
• writes that send notifications 3 s apart, which also holds the next write;
• searches 2 s apart.

///|
let gh = @github.GitHub::new(backend, clock, token~, gate=() => {
  @runtime.SemaphoreGate::new()
})

#Errors and retries

• api_error reads GitHub's error body (message, documentation_url, status, errors) out of one.
• is_not_modified recognises the 304 answer to a conditional request.
• is_secondary_rate_limit recognises the secondary rate limit, a different mechanism from the hourly quota, reported as 403 or 429 with retry-after or a message naming it.

• Three retries, as octokit. A 5xx, 408, 409 or a timeout after sending is retried only for an idempotent request: a POST is not resent, because GitHub has no idempotency key and a second issue or comment could be created.
• A secondary limit is retried for any method, after retry-after, or else after 60 s, 120 s and 240 s, as GitHub's documentation asks. The policy's Retry-After cap does not apply; its retry count and total_timeout_ms do.
• A primary limit (x-ratelimit-remaining: 0, or GraphQL RATE_LIMITED) is retried once, one second after x-ratelimit-reset. That can be up to an hour away, so set total_timeout_ms to bound it.

#GitHub Enterprise Server

#Links

• Changelog
• Repository
• Spec provenance and generation overlays
• Untyped fields census (in Japanese)

#License