Documentation
¶
Overview ¶
Package github is aayudha's GitHub API client (WP2.3): REST through go-github for issues, sub-issues, issue types, labels, comments, refs, and rulesets, and GraphQL through githubv4 only for Projects v2. One transport stack adds an ETag cache, primary and secondary rate-limit handling with serialized writes, a per-verb call budget, the actions capability guard, and a refusal of any mutating request that does not go through internal/actions (ground rule 6). GHES is unsupported in 0.1.
Index ¶
- Constants
- Variables
- func All[T any](ctx context.Context, ...) ([]T, error)
- func AllPer[T any](ctx context.Context, perPage int, ...) ([]T, error)
- func External(err error) bool
- func IssueLabels(is *gh.Issue) []string
- func NotFound(err error) bool
- func SplitRepo(repo string) (owner, name string, err error)
- type Client
- func (c *Client) DryRun() bool
- func (c *Client) Identity() string
- func (c *Client) Stats() Stats
- func (c *Client) UpsertComment(ctx context.Context, repo string, number int, marker, body string, ...) (bool, error)
- func (c *Client) Write(ctx context.Context, a actions.Action, ...) (actions.Record, error)
- type Options
- type Stats
- type WriteGate
Constants ¶
const DefaultBudget = 2000
DefaultBudget is the call budget of one verb run when Options.Budget is 0.
const DefaultTimeout = 5 * time.Minute
DefaultTimeout is the longest one request may take, its reply's body included, when Options.Timeout is 0 (Bug #822).
Variables ¶
var ( // ErrBudget means the run used its call budget; nothing further is sent. ErrBudget = errors.New("GitHub API call budget for this run is used up") // ErrUnlogged means code tried a GitHub write outside Client.Write, i.e. // outside internal/actions (ground rule 6). It is a bug in aayudha. ErrUnlogged = errors.New("GitHub write attempted outside internal/actions") // ErrRateLimited means GitHub's rate limit would take longer than // Options.MaxWait to clear. ErrRateLimited = errors.New("GitHub rate limit") // ErrTimeout means GitHub did not answer one request within // Options.Timeout. ErrTimeout = errors.New("GitHub did not answer in time") )
Errors.
Functions ¶
func All ¶
func All[T any](ctx context.Context, list func(ctx context.Context, opts gh.ListOptions) ([]T, *gh.Response, error)) ([]T, error)
All collects every page of a REST list call, 100 items per page.
func AllPer ¶
func AllPer[T any](ctx context.Context, perPage int, list func(ctx context.Context, opts gh.ListOptions) ([]T, *gh.Response, error)) ([]T, error)
AllPer is All with an explicit page size.
func External ¶
External reports whether err came from GitHub or the network rather than from aayudha: callers map it to exit code 5.
func IssueLabels ¶
IssueLabels returns an issue's label names.
Types ¶
type Client ¶
type Client struct {
REST *gh.Client
GraphQL *githubv4.Client
// contains filtered or unexported fields
}
Client is the GitHub client of one verb run.
func (*Client) UpsertComment ¶
func (c *Client) UpsertComment(ctx context.Context, repo string, number int, marker, body string, a actions.Action) (bool, error)
UpsertComment keeps one comment per marker on an issue, replaced in place: it edits the comment whose body contains marker, or creates one, and does nothing when the body is already current. It reports whether it wrote.
func (*Client) Write ¶
func (c *Client) Write(ctx context.Context, a actions.Action, perform func(ctx context.Context) (any, error)) (actions.Record, error)
Write performs one GitHub write as an action: a is logged through actions.Do (which applies --dry-run, the idempotency key, the capability, and redaction), and perform runs with a context that lets its mutating requests through the transport. In a dry run perform never runs.
type Options ¶
type Options struct {
Token string
BaseURL string // REST base, default https://api.github.com/ (tests point it at a fake)
Transport http.RoundTripper // innermost transport; default http.DefaultTransport
Log *actions.Log // every write is logged here; required for writes
Identity string // stamped on actions: human, bot, or human-fallback
Capability string // e.g. actions.CapLabelsOnly; enforced on every request
Budget int // maximum API calls (including 304s) for this run; 0 means DefaultBudget
WriteGap time.Duration // minimum gap between mutating calls; default 1s (GitHub's guidance), negative disables
Writes *WriteGate // shared with other clients so their writes never overlap; nil: this client's own
MaxWait time.Duration // longest rate-limit wait before failing; default 2 minutes
// Timeout bounds each attempt of a request, its reply's body included;
// the rate-limit and 5xx waits between attempts are MaxWait's. Default
// DefaultTimeout.
Timeout time.Duration
Retries int // rate-limit retries per request; default 3
// ServerRetries are the retries of a 5xx on a request that cannot write
// twice (WP5.5); default 3, negative disables.
ServerRetries int
Sleep func(ctx context.Context, d time.Duration) error
Now func() time.Time
}
Options configure a client. Zero values are production defaults.
type Stats ¶
type Stats struct {
REST int `json:"rest"`
GraphQL int `json:"graphql"`
NotChanged int `json:"not_modified"` // 304 responses served from the ETag cache
Retries int `json:"retries"`
WaitedMS int64 `json:"rate_limit_wait_ms"`
Budget int `json:"budget"`
}
Stats counts the calls of one run; verbs report it in --json.
type WriteGate ¶ added in v0.3.0
type WriteGate struct {
// contains filtered or unexported fields
}
WriteGate serializes writes and keeps GitHub's gap between them. Clients that share one (Options.Writes) never overlap their writes, though each was built on its own: the inbox's background writes do.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fake is an in-memory GitHub for tests of the verbs: the REST endpoints M2 uses (users, repositories, labels, issue types, rulesets, git refs/trees/commits, issues, comments, sub-issues) with enough fidelity that a verb's second run sees what its first run wrote.
|
Package fake is an in-memory GitHub for tests of the verbs: the REST endpoints M2 uses (users, repositories, labels, issue types, rulesets, git refs/trees/commits, issues, comments, sub-issues) with enough fidelity that a verb's second run sees what its first run wrote. |
|
Package scratch creates and deletes the aayu-scratch-* repositories that live tests (AAYU_LIVE=1) run against.
|
Package scratch creates and deletes the aayu-scratch-* repositories that live tests (AAYU_LIVE=1) run against. |