failclass

package
v0.57.0-rc.1 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

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, and a `fullsend github setup` subprocess whose final error is a GitHub 5xx the client gave up on or an HTTP/2 CANCEL stream reset — the subprocess counterpart of the gh.IsServerError rule below, since the typed error does not cross the process boundary (#9497)).
  • 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.

Jump to

Keyboard shortcuts

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