Package net.ygbstudio.jbrave.core.executors

Class BraveExecutionGate

java.lang.Object
net.ygbstudio.jbrave.core.executors.BraveExecutionGate
public class BraveExecutionGate extends Object
Serializes execution of HTTP requests against a shared Brave API execution context.

BraveExecutionGate acts as a single-admission execution gate: at most one request may be executed at a time. Callers attempting to submit a request while another request is in progress will block until execution becomes available or until the calling thread is interrupted.

This class is designed to coordinate access to a rate-limited API token. It ensures:

  • Strict FIFO fairness between competing callers
  • Global serialization of request execution
  • Consistent handling of HTTP 429 (rate limit) responses
  • Retry and backoff behavior based on server-provided rate limit metadata

Concurrency model: This gate uses a fair ReentrantLock to provide mutual exclusion. Lock acquisition is interruptible, allowing callers to cancel admission while waiting. Rate-limit backoff is performed while holding the lock, ensuring that no subsequent request executes until the backoff window has elapsed.

Blocking semantics: Calls to submit(HttpRequest) and submit(HttpRequest, int) are synchronous and may block for extended periods of time due to rate limiting or retry backoff. This behavior is intentional and reflects the semantics of a shared, rate-limited execution resource.

Default retry policy: Rate-limited (HTTP 429) responses are retried up to DEFAULT_MAX_RETRIES times by default, sleeping for the server-provided rate limit reset window before each attempt. The retry is what activates the rate-aware backoff; without it, a rate-limited response would be returned without honoring the server's backoff guidance.

Failure handling:

This class does not perform authentication, request construction, or asynchronous scheduling. It is a coordination primitive, not a general-purpose executor.

  • Constructor Details

    • BraveExecutionGate

      public BraveExecutionGate()

  • Method Details

    • submit

      public HttpResponse<String> submit(@NotNull @NotNull HttpRequest httpRequest, int maxRetries)
      Submits a request for serialized execution through the execution gate.

      If another request is currently executing, the calling thread will block until execution becomes available or until the thread is interrupted.

      The request will be executed synchronously and may be retried if the Brave API responds with a rate-limit (HTTP 429) error at least once. Retry behavior is governed by the maxRetries parameter and server-provided rate limit metadata.

      Parameters:
      httpRequest - the HttpRequest to execute
      maxRetries - the maximum number of retry attempts for rate-limited responses
      Returns:
      the completed HTTP response
      Throws:
      RequestProcessingInterrupted - if the thread is interrupted while waiting to acquire execution admission
      RequestRetryInterruptedException - if the thread is interrupted during retry backoff
      BraveApiException - if an unrecoverable API error is returned by the server (e.g. Monthly limit exhaustion)
      BraveClientException - if a rate-limited response does not carry the rate limit window headers required to activate rate-aware backoff

    • submit

      public HttpResponse<String> submit(@NotNull @NotNull HttpRequest httpRequest)
      Submits a request for serialized execution with a default retry policy.

      This method is equivalent to calling submit(HttpRequest, int) with the default retry policy.

      Parameters:
      httpRequest - the HttpRequest to execute
      Returns:
      the completed HTTP response
      Throws:
      RequestProcessingInterrupted - if the thread is interrupted while waiting to acquire execution admission
      RequestRetryInterruptedException - if the thread is interrupted during retry backoff
      BraveApiException - if an unrecoverable API error occurs
      BraveClientException - if a rate-limited response does not carry the rate limit window headers required to activate rate-aware backoff