mintclient

package
v0.46.1-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source
const MaxMintDuration = 120 * time.Second

MaxMintDuration is a practical upper bound on how long a single MintToken call can take, informed by its retry schedule: fetchOIDCJWT retries within oidcRetry (exponential backoff capped at 8s, and no new attempt started more than 60s after the first — see oidcRetry), and callMint retries up to 5 times (1s+2s+4s+8s backoff). Each HTTP round trip is individually bounded by httpClient's 30s timeout (see doWithRetryPolicy, fetchOIDCJWT, callMint).

The OIDC phase therefore ends within about 60s plus one attempt (at most 90s even if that final attempt hangs for the full client timeout), and callMint adds 15s of backoff on top. The literal worst case — every callMint attempt also hanging for the full 30s client timeout — is far longer, unrealistically long for a caller to wait out during teardown. In practice an outage produces fast failing responses dominated by the backoff schedule, not attempts that each hang the full client timeout, so MaxMintDuration is a documented practical ceiling rather than that literal worst case: comfortably above the ~75s backoff-dominated estimate (a minute-long OIDC endpoint outage followed by a few mint retries), while remaining well inside a CI job's own timeout.

Callers that bound MintToken with a context deadline (e.g. the post-script remint in internal/cli, #7231) should use at least this value: a shorter bound routinely cuts off retries the client itself would have completed.

Variables

View Source
var ErrAuthenticationFailed = errors.New("authentication failed")

ErrAuthenticationFailed indicates that every available authentication mechanism was attempted and rejected (401) by the mint's /v1/status endpoint. Callers can use errors.Is to distinguish this from other terminal QueryStatus errors (e.g. network failures, non-2xx/non-401 responses, malformed URLs) that are not auth-related.

Functions

func QueryStatus added in v0.44.0

func QueryStatus(ctx context.Context, req StatusRequest, resolveGitHubToken func() (string, error)) (*StatusResult, StatusAuthMethod, error)

QueryStatus calls GET /v1/status with auto-discovered authentication.

Discovery order (per #5879):

  1. GitHub Actions OIDC — attempted when ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN are set.
  2. GitHub user token — GH_TOKEN, GITHUB_TOKEN, or the output of `gh auth token`.

The first mechanism that yields a 200 response wins. A 401 from the first mechanism triggers fallback to the next. If all mechanisms fail, the error lists what was attempted.

resolveGitHubToken is a callback that resolves a GitHub user token. The CLI passes its resolveToken function; tests supply a stub.

Types

type HTTPDoer

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer abstracts http.Client for testability.

type MintRequest

type MintRequest struct {
	MintURL   string
	Role      string
	Level     string   // optional: privilege level ("read" or "write"); server defaults to "write" when empty
	Repos     []string // required: specific repo names, or ["*"] for installation-wide token
	TargetOrg string   // optional: cross-org mint when set and differs from caller org
	Audience  string
}

MintRequest holds the parameters for minting a token via the fullsend mint service.

type MintResult

type MintResult struct {
	Token     string `json:"token"`
	ExpiresAt string `json:"expires_at"`
}

MintResult holds the minted token and its expiry.

func MintToken

func MintToken(ctx context.Context, req MintRequest) (*MintResult, error)

MintToken obtains a fresh GitHub App installation token by exchanging a GitHub Actions OIDC JWT with the fullsend token mint service.

It reads ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN from the environment. These are set automatically by GitHub Actions when the job declares id-token: write permission.

type StatusAuthMethod added in v0.44.0

type StatusAuthMethod string

StatusAuthMethod describes which mechanism authenticated a successful /v1/status call.

const (
	// StatusAuthOIDC indicates authentication via GitHub Actions OIDC.
	StatusAuthOIDC StatusAuthMethod = "OIDC"
	// StatusAuthGitHub indicates authentication via a GitHub user token
	// (GH_TOKEN, GITHUB_TOKEN, or gh auth token).
	StatusAuthGitHub StatusAuthMethod = "GitHub"
)

type StatusRequest added in v0.44.0

type StatusRequest struct {
	MintURL  string
	Audience string // OIDC audience; defaults to the standard mint audience when empty.
}

StatusRequest holds the parameters for querying GET /v1/status.

type StatusResult added in v0.44.0

type StatusResult struct {
	Org               string   `json:"org,omitempty"`
	Roles             []string `json:"roles,omitempty"`
	WorkflowHostRepos []string `json:"workflow_host_repos,omitempty"`
	Version           string   `json:"version,omitempty"`
	Commit            string   `json:"commit,omitempty"`
}

StatusResult holds the response from GET /v1/status.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL