Package edu.ucsb.cs.scaffold.services

Class ApiRetryHelper

java.lang.Object

edu.ucsb.cs.scaffold.services.ApiRetryHelper

public class ApiRetryHelper
extends Object

Wraps calls to an external REST API (GitHub, PrairieLearn) with three defenses:

• Pacing: consecutive calls are kept at least paceMs apart, to stay under rate limits in the first place. The pacer only sleeps the remaining gap since the previous call, so an occasional interactive call is not delayed at all — only tight loops (like a repo sync) are slowed.
• Backoff-retries on 5xx: transient server errors (e.g. GitHub's 502 "Unicorn" page) are retried up to retryMax times, sleeping retryInitialSleepSeconds and doubling each time (8, 16, 32...). Only then does the call fail — with a one-line ApiRetryHelper.ApiUnavailableException instead of the provider's HTML error page.
• Rate-limit reaction: a 429, or a 403 whose body mentions "rate limit", counts as a retryable event and additionally doubles the pace permanently (for the life of the service instance), with a log suggestion to raise the pace's configuration variable.

All other client errors (404 for a missing path, 401/403 for a bad token) are rethrown untouched — callers depend on their semantics.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ApiRetryHelper.ApiUnavailableException	Thrown when the API is still failing after all retries; carries a clean one-line message.

Constructor Summary

Constructors

Constructor	Description
ApiRetryHelper(String apiName, String paceVariableName, long retryInitialSleepSeconds, int retryMax, long paceInitialMs)

Method Summary

Modifier and Type	Method	Description
<T> T	execute(String description, Supplier<T> call)	Runs call, pacing it relative to the previous call and retrying per the class contract.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ApiRetryHelper

public ApiRetryHelper(String apiName,
 String paceVariableName,
 long retryInitialSleepSeconds,
 int retryMax,
 long paceInitialMs)

Method Details

execute

public <T> T execute(String description,
 Supplier<T> call)

Runs call, pacing it relative to the previous call and retrying per the class contract. description identifies the request in log messages, e.g. "GET .../contents/questions".