mintclient

package
v0.44.0-rc.2 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 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 up to 3 times (1s+2s backoff between attempts) and callMint retries up to 5 times (1s+2s+4s+8s backoff), for 18s of backoff spread across up to 8 HTTP round trips — each individually bounded by httpClient's 30s timeout (see doWithRetry, fetchOIDCJWT, callMint).

The literal worst case — every one of the 8 attempts hanging for the full 30s client timeout — is 258s, unrealistically long for a caller to wait out during teardown. In practice a mint-service 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 ~18s backoff-only estimate — leaving headroom for real per-request latency across up to 8 round trips, including a slow attempt or two — 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"`
	AllowedOrgs       []string `json:"allowed_orgs,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