QuadrastackQuadrastack
Documentation

Docs

HTTP Clients

Configure HTTP client behavior with timeout, retries, TLS, and connection settings

HTTP Clients

Configure how Quadrastack makes HTTP requests with custom client configurations.

Overview

HTTP clients let you customize request behavior like timeouts, retry logic, TLS settings, and default headers. Define multiple clients for different API endpoints or environments.

Basic HTTP Client

httpClients:
  default:
    baseUrl: https://api.example.com
    timeout: "30s"

Client Structure

Client Names

Top-level keys in httpClients are client names. The default client is used when no client is specified.

httpClients:
  default:           # Used by default
    baseUrl: https://api.example.com
    timeout: "30s"

  api-client:        # Custom client
    baseUrl: https://api.example.com
    timeout: "60s"

  auth-client:       # Another custom client
    baseUrl: https://auth.example.com
    timeout: "10s"

Use a specific client in requests:

requests:
  get-users:
    method: GET
    url: /users
    client: api-client  # Uses api-client configuration

Configuration Fields

baseUrl

Base URL prepended to all request URLs using this client.

Type: string

httpClients:
  default:
    baseUrl: https://api.example.com

requests:
  get-users:
    method: GET
    url: /users  # Full URL: https://api.example.com/users

With templates:

httpClients:
  default:
    baseUrl: "{{.vars.apiBaseUrl}}"

headers

Default headers sent with all requests using this client.

Type: object

httpClients:
  default:
    baseUrl: https://api.example.com
    headers:
      Authorization: "Bearer {{.vars.apiToken}}"
      User-Agent: quadrastack/1.0
      Accept: application/json
      X-API-Version: v1

Request-level headers override client headers:

requests:
  special-request:
    method: GET
    url: /data
    headers:
      Accept: application/xml  # Overrides client's Accept header

timeout

Request timeout duration.

Type: string (duration format) Format: number + unit (ns, us, µs, ms, s, m, h)

httpClients:
  default:
    timeout: "30s"    # 30 seconds

  patient-client:
    timeout: "5m"     # 5 minutes

  fast-client:
    timeout: "500ms"  # 500 milliseconds

proxy

HTTP/HTTPS proxy URL.

Type: string

httpClients:
  default:
    proxy: http://proxy.example.com:8080

  socks-client:
    proxy: socks5://localhost:1080

TLS Settings

caCertFile

Path to CA certificate file for TLS verification.

Type: string

httpClients:
  default:
    baseUrl: https://internal-api.example.com
    caCertFile: ./certs/ca.crt  # Relative to playbook file

skipVerify

Skip TLS certificate verification (insecure - use only for testing).

Type: boolean Default: false

httpClients:
  dev-client:
    baseUrl: https://localhost:8443
    skipVerify: true  # For local development only

Warning: Only use skipVerify: true for local testing. Never in production.

Redirect Behavior

HTTP clients automatically follow redirects by default (up to 10 redirects). This behavior cannot be customized in the current version.

retry

Retry configuration for failed requests.

Type: object

httpClients:
  default:
    retry:
      maxAttempts: 3                      # Total attempts (1 = no retry)
      retryOn: [500, 502, 503, 504]      # Status codes to retry
      backoff: exponential                # Backoff strategy
      initialDelay: 1000                  # Initial delay in ms
      maxDelay: 10000                     # Max delay in ms

See Retry Configuration below for details.

Retry Configuration

Configure automatic retry logic for failed requests.

maxAttempts

Maximum number of attempts (1 = no retry, 2+ = retry).

Type: integer Minimum: 1 Default: 1

httpClients:
  default:
    retry:
      maxAttempts: 3  # 1 initial + 2 retries

retryOn

HTTP status codes that trigger a retry.

Type: array of integers Default: [] (no retries)

httpClients:
  default:
    retry:
      maxAttempts: 3
      retryOn: [500, 502, 503, 504]  # Retry on server errors

  rate-limited-client:
    retry:
      maxAttempts: 5
      retryOn: [429, 503]  # Retry on rate limit and service unavailable

backoff

Backoff strategy for retry delays.

Type: string Values: fixed, linear, exponential Default: fixed

  • fixed: Constant delay between retries
  • linear: Delay increases linearly (initialDelay × attempt)
  • exponential: Delay doubles each time (initialDelay × 2^attempt)
httpClients:
  fixed-retry:
    retry:
      backoff: fixed
      initialDelay: 1000  # Always wait 1s between retries

  linear-retry:
    retry:
      backoff: linear
      initialDelay: 1000  # Wait 1s, then 2s, then 3s...

  exponential-retry:
    retry:
      backoff: exponential
      initialDelay: 1000  # Wait 1s, then 2s, then 4s, then 8s...

initialDelay

Initial delay in milliseconds before first retry.

Type: integer Minimum: 0 Default: 1000

httpClients:
  default:
    retry:
      initialDelay: 500   # Wait 500ms before first retry

maxDelay

Maximum delay in milliseconds (caps exponential backoff).

Type: integer Minimum: 0 Default: 30000

httpClients:
  default:
    retry:
      backoff: exponential
      initialDelay: 1000
      maxDelay: 10000  # Never wait more than 10s

Complete Examples

Production API Client

httpClients:
  default:
    description: Production API client with retry logic
    baseUrl: https://api.example.com
    headers:
      Authorization: "Bearer {{.vars.apiToken}}"
      User-Agent: quadrastack/1.0
      Accept: application/json
    timeout: "30s"
    retry:
      maxAttempts: 3
      retryOn: [500, 502, 503, 504]
      backoff: exponential
      initialDelay: 1000
      maxDelay: 10000

Internal Service Client

httpClients:
  internal-api:
    description: Internal service with custom CA cert
    baseUrl: https://internal-service.local
    headers:
      X-Internal-Token: "{{.vars.internalToken}}"
    timeout: "60s"
    caCertFile: ./certs/internal-ca.crt
    retry:
      maxAttempts: 2
      retryOn: [503]
      backoff: fixed
      initialDelay: 500

Development Client

httpClients:
  dev-client:
    description: Local development client
    baseUrl: https://localhost:8443
    timeout: "10s"
    skipVerify: true  # Self-signed cert
    headers:
      X-Debug: "true"

Multiple Clients Example

httpClients:
  # Default client for main API
  default:
    baseUrl: https://api.example.com
    headers:
      Authorization: "Bearer {{.vars.apiToken}}"
    timeout: "30s"
    retry:
      maxAttempts: 3
      retryOn: [500, 502, 503, 504]
      backoff: exponential
      initialDelay: 1000
      maxDelay: 10000

  # Separate auth service
  auth-client:
    baseUrl: https://auth.example.com
    timeout: "10s"
    retry:
      maxAttempts: 2
      retryOn: [503]
      backoff: fixed
      initialDelay: 500

  # Slow batch processing endpoint
  batch-client:
    baseUrl: https://batch.example.com
    timeout: "5m"  # Long timeout for batch operations
    retry:
      maxAttempts: 1  # No retry for long operations

  # Third-party API with rate limiting
  external-api:
    baseUrl: https://external-api.com
    headers:
      X-API-Key: "{{.vars.externalApiKey}}"
    timeout: "60s"
    retry:
      maxAttempts: 5
      retryOn: [429, 503]  # Rate limit and service unavailable
      backoff: linear
      initialDelay: 2000
      maxDelay: 30000

requests:
  # Uses default client
  get-users:
    method: GET
    url: /users

  # Uses auth-client
  login:
    method: POST
    url: /login
    client: auth-client

  # Uses batch-client
  process-batch:
    method: POST
    url: /batch/process
    client: batch-client

  # Uses external-api
  get-weather:
    method: GET
    url: /weather
    client: external-api

Common Patterns

Aggressive Retry for Critical Endpoints

httpClients:
  critical-client:
    baseUrl: https://critical-api.example.com
    timeout: "60s"
    retry:
      maxAttempts: 5
      retryOn: [500, 502, 503, 504, 429]
      backoff: exponential
      initialDelay: 500
      maxDelay: 30000

Fast Fail for Health Checks

httpClients:
  health-check:
    baseUrl: https://api.example.com
    timeout: "2s"
    retry:
      maxAttempts: 1  # No retry - fail fast

Proxy Configuration

httpClients:
  corporate-api:
    baseUrl: https://internal-api.corp.com
    proxy: http://proxy.corp.com:8080
    timeout: "30s"
    retry:
      maxAttempts: 2
      retryOn: [503]

Best Practices

1. Always Define a Default Client

httpClients:
  default:  # Always include default
    baseUrl: https://api.example.com
    timeout: "30s"

2. Use Appropriate Timeouts

  • Fast endpoints: 5-10 seconds
  • Normal endpoints: 30 seconds
  • Long operations: 1-5 minutes
httpClients:
  default:
    timeout: "30s"

  batch-client:
    timeout: "5m"

3. Retry on Transient Errors Only

Only retry on errors that might succeed on retry:

✅ Good:

retry:
  retryOn: [500, 502, 503, 504]  # Server errors

❌ Bad:

retry:
  retryOn: [400, 401, 403, 404]  # Client errors won't succeed on retry

4. Use Exponential Backoff for Most Cases

retry:
  backoff: exponential
  initialDelay: 1000
  maxDelay: 10000

5. Don't Skip TLS Verification in Production

❌ Bad:

httpClients:
  production:
    skipVerify: true  # NEVER do this in production!

✅ Good:

httpClients:
  production:
    caCertFile: ./certs/ca.crt  # Use proper CA cert

6. Set Reasonable Retry Limits

Don't retry indefinitely:

retry:
  maxAttempts: 3  # Reasonable limit
  maxDelay: 30000 # Cap max wait time

7. Use Variables for Configuration

vars:
  default:
    apiBaseUrl: https://api.example.com
    apiToken: token-123
    requestTimeout: "30s"

httpClients:
  default:
    baseUrl: "{{.vars.apiBaseUrl}}"
    headers:
      Authorization: "Bearer {{.vars.apiToken}}"
    timeout: "{{.vars.requestTimeout}}"

Client Inheritance

The default client provides base configuration that other clients inherit from. This feature allows you to define common settings once:

httpClients:
  # Base configuration
  default:
    headers:
      User-Agent: quadrastack/1.0
      Accept: application/json
    timeout: "30s"
    retry:
      maxAttempts: 3
      retryOn: [500, 502, 503, 504]

  # Inherits from default, adds specific config
  api-client:
    baseUrl: https://api.example.com
    headers:
      Authorization: "Bearer {{.vars.apiToken}}"

  # Inherits from default, overrides timeout
  slow-client:
    baseUrl: https://slow-api.example.com
    timeout: "5m"  # Overrides default timeout

See Also

HTTP Clients - Quadrastack Docs