Documentation
¶
Overview ¶
Package failclass classifies behaviour-suite failure errors as infrastructure (environment) or scenario (assertion) failures.
It is the composite half of a two-package layout: the stdlib-only marker leaf internal/behaviourfail lets producers with context-dependent modes (install drivers, e2etest bootstrap) tag their errors with behaviourfail.Mark, while this package recognizes the structural error types — the GitHub forge client's APIError and the install driver's CapacityError — which requires importing them. Both halves exist because the install driver must import the marker to tag its errors while the classifier must import the driver to recognize them; a single package would be an import cycle (failclass → install → failclass).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Classify ¶
func Classify(err error) behaviourfail.Class
Classify returns err's failure class for the behaviour suite: behaviourfail.Infrastructure when the error matches a known infrastructure mode, behaviourfail.Scenario otherwise — including for nil.
The allowlist is deliberately narrow; each rule names a failure mode the behaviour suite has observed in CI (#8036):
- behaviourfail.Is: an error a producer explicitly marked as infrastructure (setup-poll exhaustion, GCP WIF quota, token mint/download).
- a rate-limit gh.APIError: primary 429, or a 403 whose message says "rate limit" (secondary limit), per gh.IsRateLimitError.
- a GitHub server error, per gh.IsServerError: a REST gh.APIError with status 500–504 that the client did not retry further (its retries were used up, or it did not resend because the request may already have been applied; the suite then retries the scenario, it does not resend the request), or a GraphQL error with no type whose message starts with GitHub's generic "Something went wrong while executing your query" (#9472).
- an install.CapacityError: the slot pool could not provide capacity — every cause (rate-limited, denied, or failed orgs) is an environment condition, not a product assertion. A slot wait ended by cancellation joins the context error to it, and that join stays scenario under the rule below.
- the gh.ErrInvitationPending sentinel: collaborator access awaits an accepted invitation.
Joined errors (errors.Join, or fmt.Errorf with multiple %w verbs) classify as infrastructure only when every branch independently matches an infrastructure rule. A scenario branch joined beside an infra branch — a lease race joined with a rate-limited release, for example — is an independent cause that keeps the whole error scenario-classified, so the single automatic retry never masks it (spec R4: any scenario-classified failure fails immediately). A behaviourfail mark placed on the joined error itself still wins: the mark is the producer's explicit statement that the whole failure is environmental.
Everything else classifies as scenario: nil, plain assertion failures, unrecognized API errors (a 4xx other than a rate limit, or a typed GraphQL error such as FORBIDDEN), and errors whose message merely mentions rate limits. This conservative default is what makes the single automatic retry safe — an infrastructure-classified run is retried exactly once, so a broader allowlist would risk masking product regressions behind that retry. Unknown infrastructure modes surface as scenario failures in the per-failure report instead of silently retrying.
Extending the allowlist for a new mode is one rule here (or, for context-dependent modes, one behaviourfail.Mark at the producing call site); anything unmatched stays scenario, which is the safe direction.
Types ¶
This section is empty.