tomGitHubWaitOf function

TomGitHubWait? tomGitHubWaitOf(
  1. Object error, {
  2. required TomBackoffPolicy backoff,
  3. required DateTime now,
  4. required double jitterSample,
})

The wait error calls for, or null when it is not a rate limit.

A primary-quota refusal waits for the reset GitHub stated. A secondary limit waits for GitHub's Retry-After when it stated one, and otherwise for backoff's fallback for its kind — a throttle and a content-creation block clear on different scales. A secondary wait is spread by the backoff jitter, additively, so clients refused together do not return together; a quota reset is not, being an instant after which quota genuinely exists.

The distinction between an instruction and a choice is kept where it belongs: GitHubSecondaryRateLimitException.retryAfter is null when GitHub said nothing, and it is here — in the layer that owns the cadence — that a wait is chosen. The API package invents none.

Implementation

TomGitHubWait? tomGitHubWaitOf(
  Object error, {
  required TomBackoffPolicy backoff,
  required DateTime now,
  required double jitterSample,
}) {
  if (error is GitHubRateLimitException) {
    return (kind: TomRateLimitKind.quota, until: error.rateLimit.resetAt);
  }
  if (error is! GitHubSecondaryRateLimitException) return null;
  // The one place the two secondary shapes are told apart. They arrive as the
  // same status with the same headers; `blockedFromContentCreation` is the
  // body's own word for it.
  final blocked = error.blockedFromContentCreation;
  final base =
      error.retryAfter ??
      (blocked ? backoff.blockFallback : backoff.throttleFallback);
  return (
    kind: blocked ? TomRateLimitKind.blocked : TomRateLimitKind.throttle,
    until: now.add(
      GitHubRetryPolicy.jittered(
        base,
        fraction: backoff.jitterFraction,
        sample: jitterSample,
      ),
    ),
  );
}