Class EquinixHttpClient

java.lang.Object
com.eqixiac.equinix.core.http.EquinixHttpClient
All Implemented Interfaces:
Closeable, AutoCloseable
public class EquinixHttpClient extends Object implements Closeable
The SDK's pooled, timeout-bounded HTTP client. Executes a single EquinixRequest against the Equinix API with automatic, policy-driven retry of transient failures (see RetryPolicy), mapping error responses to typed exceptions via ResponseErrorMapper. One instance is shared across calls and is safe to reuse; close() shuts down the owned connection pool.

Every logical request is tagged with a generated correlation id (a UUID), sent to the API as an X-Correlation-Id header (shared by all retry attempts of that request), included in the request/retry log lines, and carried on any resulting EquinixServiceException - so a failure in application logs, the SDK's logs, and Equinix's server-side logs can be tied together by one id.

An opt-in CircuitBreaker (see setCircuitBreaker(CircuitBreaker)) is consulted per attempt, alongside the retry policy; when open it fails fast with a CircuitOpenException without touching the network.

Author:
ianjones

  • Constructor Details

    • EquinixHttpClient

      public EquinixHttpClient()

      Builds a connection-pooled, timeout-bounded HTTP client. Without explicit timeouts a stalled server can block a calling thread indefinitely; without a pooled connection manager every concurrent call would open (and leak) its own socket. The pool and timeouts below are sensible defaults for typical SDK use.

  • Method Details

    • setClock

      public void setClock(Clock clock)
      Replaces the clock used to resolve a Retry-After HTTP-date into a delay.
      Parameters:
      clock - the clock; must not be null

    • setRetryPolicy

      public void setRetryPolicy(RetryPolicy retryPolicy)
      Overrides the retry policy for transient failures.
      Parameters:
      retryPolicy - the policy to apply; RetryPolicy.none() disables retries

    • setCircuitBreaker

      public void setCircuitBreaker(CircuitBreaker circuitBreaker)
      Enables (or, with null, disables) the opt-in circuit breaker. When set, every request attempt asks the breaker for permission first: after the configured number of consecutive service failures (5xx or transport IOException) the breaker opens and requests fail fast with a CircuitOpenException until the cooldown elapses and a probe succeeds. Disabled by default.
      Parameters:
      circuitBreaker - the breaker to consult, or null to disable

    • setOutputRequestJson

      public void setOutputRequestJson(boolean outputRequestJson)
      Enables or disables DEBUG-level logging of request bodies.
      Parameters:
      outputRequestJson - true to log request bodies (at DEBUG), false to suppress

    • executeWithRetries

      public <T> EquinixResponse<T> executeWithRetries(EquinixRequest<T> equinixRequest) throws EquinixClientException
      Executes a request with automatic retry of transient failures per the configured RetryPolicy. Retries are bounded by the policy's max attempts, gated on retryable status codes / IOExceptions and - for 5xx/IO failures - on HTTP-method idempotency (POST and PATCH are not retried by default, to avoid duplicate side effects; a 429 is exempt from that gate because the server explicitly did not process the request), and spaced by exponential backoff with full jitter (honoring Retry-After). Each retry is logged at WARN. A request-body serialization failure (JsonProcessingException) is a deterministic client-side bug: it is thrown immediately, never retried, and never recorded on the circuit breaker.

      A single correlation id (UUID) is generated per logical request and shared by all of its retry attempts, sent as X-Correlation-Id. When a CircuitBreaker is configured, each attempt first asks the breaker for permission (an open circuit fails fast with CircuitOpenException) and its outcome is reported back: 5xx responses and transport IOExceptions count as failures, any completed exchange below 500 counts as healthy.

      Type Parameters:
      T - the response payload type
      Parameters:
      equinixRequest - the request to execute
      Returns:
      the successful response
      Throws:
      EquinixClientException - on a non-retryable failure or once retries are exhausted

    • getProtocol

      public Protocol getProtocol()
      The protocol endpoints default to when none is given.
      Returns:
      Protocol.HTTPS

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException