github

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: BSD-3-Clause Imports: 16 Imported by: 0

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

View Source
const DefaultBudget = 2000

DefaultBudget is the call budget of one verb run when Options.Budget is 0.

View Source
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

View Source
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

func External(err error) bool

External reports whether err came from GitHub or the network rather than from aayudha: callers map it to exit code 5.

func IssueLabels

func IssueLabels(is *gh.Issue) []string

IssueLabels returns an issue's label names.

func NotFound

func NotFound(err error) bool

NotFound reports whether err is a GitHub 404.

func SplitRepo

func SplitRepo(repo string) (owner, name string, err error)

SplitRepo splits owner/name.

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 New

func New(opts Options) (*Client, error)

New builds a client.

func (*Client) DryRun

func (c *Client) DryRun() bool

DryRun reports whether writes are only planned.

func (*Client) Identity

func (c *Client) Identity() string

Identity is the identity stamped on this client's writes.

func (*Client) Stats

func (c *Client) Stats() Stats

Stats returns the call counts so far.

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.

func (Stats) Calls

func (s Stats) Calls() int

Calls is the number of requests sent.

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.

Jump to

Keyboard shortcuts

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