Module traffic 

What this host actually spends against GitHub’s rate limits, measured.

The budget model in crate::rest projects a cost from a table of request counts. This module measures one: every response the shared crate::AuthenticatedClient receives is counted here by class, and the rate-limit headers GitHub attaches to it are kept.

Why the classes are full, not-modified, and failed

GitHub’s own words, from “Best practices for using the REST API” (https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api#use-conditional-requests-if-appropriate):

Making a conditional request does not count against your primary rate limit if a 304 response is returned and the request was made while correctly authorized with an Authorization header.

So a 304 is free against the hourly quota and a 200 is not. That is the whole reason crate::demand sends If-None-Match, and the reason this module counts the two apart: the share of 304s is the number that says whether conditional polling is paying off. Errors are counted separately because they do count against the quota and are not data.

The headers describe the ACCOUNT, not this machine

“Primary rate limits for GitHub App user access tokens … are dictated by the primary rate limits for the authenticated user. This rate limit is combined with any requests that another GitHub App or OAuth app makes on that user’s behalf and any requests that the user makes with a personal access token” (https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#primary-rate-limit-for-github-app-installations).

Every host signed in as the same person therefore draws from one bucket, and so does that person’s gh CLI. x-ratelimit-remaining on any response is the bucket’s level, whoever drained it — which is exactly why it is the right input for slowing down: this machine cannot count the other machines’ requests, but it can see what they left.

The secondary limit has no header until it is exceeded

“No more than 900 points per minute are allowed for REST API endpoints”, and a GET costs one point (https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits). GitHub does not say a 304 is exempt from that limit, so this module assumes it is not: every request is a point. The secondary headroom shown to an operator is therefore this host’s busiest minute against SECONDARY_POINTS_PER_MINUTE, stated as one host’s share of a limit the other hosts on the account share too.

Structs

ApiTraffic

Every response one client received, by class and by minute, for the last hour, plus the newest rate-limit reading.

RateLimitSnapshot

What GitHub said about the account’s hourly quota on one response.

TrafficSummary

One host’s measured traffic over (up to) the last hour.

Enums

PrimaryPressure

How much of the shared hourly quota is left, as a decision input.

Constants

CRITICAL_PRIMARY_REMAINING_PERCENT

Below this share, polling stretches further.

LOW_PRIMARY_REMAINING_PERCENT

Below this share of the hourly quota left, polling stretches.

SECONDARY_POINTS_PER_MINUTE

GitHub’s documented REST secondary limit, in points per minute.

Functions

secondary_share_percent

requests_per_minute as a share of SECONDARY_POINTS_PER_MINUTE, in whole percent: a GET is one point.