Expand description
What a session of requests to GitHub cost, counted rather than argued about.
Nothing here decides anything: it records what left this crate and adds it up. It exists because a query strategy cannot be chosen between without measuring what each one costs.
§What one record carries
One Request per outgoing HTTP request. A GraphQL request is named by the document
it sent, read out of graphql::DOCUMENTS rather than from
a second list of names, and carries that document’s worst-case node count under the
bindings that request actually sent — node_count, the same
offline calculation tests/node_count.rs holds every document to, never a second
arithmetic. A REST request sends no document and has no node count, so it names the
endpoint it addressed instead. Both record whether they read or wrote, how they ended,
and the rate-limit facts that response’s own headers carried.
Two quantities of GitHub’s, kept apart by name. nodeCount is the most nodes one
query may return, checked per query; it is what Call::Document carries.
cost is rate-limit points, metered per hour across everything one credential does; it
is what Spend is in. A document well under the node limit says nothing about the
second.
§How a session’s spend is arrived at, and what it is not
Per budget, accumulated per call, from whatever that call itself makes attributable:
Budget::Restis metered in requests, so a call is its own measure and is attributed one request (Basis::Counted).Budget::Graphqlis metered in points. Where the request was shaped so GitHub reports its owncost— a document selectingrateLimit { cost }— that is what is attributed (Basis::Reported). Otherwise this repository’s stated cost model applies: GitHub charges at least one point for any call, so one point is attributed (Basis::Modelled), and the report says how much of the total came that way. That is a lower bound and the accounting says so rather than implying a measurement: a call over a large connection really costs more, and no document this source sends today asks GitHub what.- A rate-limited refusal is attributed nothing (
Basis::NotRun), because a request GitHub refused for a rate limit did not run — the same reading of a refusal that makes retrying one safe inGitHubProjectsSource::graphql.
What a session spent is never inferred by differencing a shared counter. This account is shared and rate-limited, and other work draws on the same budgets in the same window, so an allowance that fell by sixty while this session made ten calls measures the account rather than the session. The report gives that movement anyway — it is worth seeing — and says on its face that it is the account’s and not this session’s.
§Where a reader finds the report
Session::report renders one from a snapshot, and the credentialed lane in
tests/live.rs prints it at the end of every run, passed or failed — from a Drop, so
that the run whose cost is most worth reading, the one that broke, is not the run that
skips it. It carries no credential, no token, no issue body and no board content: a call
is named by a document description this crate wrote or by an Endpoint, which is a
path template rather than the URL a run built, and everything else in it is a number.
Structs§
- Accounting
- Every request one session sent, and what each cost.
- Budget
Report - One budget a session drew on, with its own figures kept apart from the account’s.
- Endpoint
- A REST endpoint, spelled the way GitHub’s own documentation spells one.
- Rate
Limit - The rate-limit facts one response’s own headers carried.
- Request
- One outgoing HTTP request, and what it cost.
- Sending
- One outgoing HTTP request, described before it is sent.
- Session
- One session’s requests, as a value a caller can hold, compare and report on.
- Spend
- What one call is attributed against its budget, and where that figure came from.
- Status
Code - An HTTP status code (
status-codein RFC 9110 et al.).