Configuration

Request Forge uses a builder pattern for flexible, readable configuration.

Basic Configuration

from requestforge import HttpClientConfigBuilder

config = (
    HttpClientConfigBuilder()
    .with_base_url('https://api.example.com')
    .with_timeout(30.0)
    .build()
)

Configuration Options

Base URL

Set the base URL for all requests:

builder.with_base_url('https://api.example.com')

Requests to relative URLs will be prefixed with this base URL.

Timeout

Configure request timeout in seconds:

builder.with_timeout(30.0)  # 30 seconds

Default is 30 seconds.

Headers

Set default headers for all requests:

# Multiple headers
builder.with_headers({
    'User-Agent': 'MyApp/1.0',
    'X-API-Version': 'v2'
})

# Single header
builder.with_header('Authorization', 'Bearer token')

SSL Verification

Enable or disable SSL certificate verification:

builder.with_verify_ssl(True)  # Default
builder.with_verify_ssl(False)  # Disable (not recommended)

Warning

Disabling SSL verification is not recommended for production use.

Redirects

Configure redirect behavior:

builder.with_redirects(
    allow=True,        # Follow redirects
    max_redirects=10   # Maximum redirect hops
)

Connection Pooling

Configure connection pool size:

builder.with_pool_connection(10)   # Pool connections
builder.with_pool_maxsize(20)      # Maximum pool size

Retry Strategy

Configure retry behavior:

# Simple configuration
builder.with_retry(
    max_retries=3,
    base_delay=1.0,
    max_delay=60.0
)

# Custom strategy
from requestforge import ExponentialBackoffRetryStrategy

strategy = ExponentialBackoffRetryStrategy(
    max_retries=5,
    base_delay=2.0,
    max_delay=120.0,
    multiplier=2.0,
    jitter=True
)
builder.with_retry_strategy(strategy)

Authentication

Bearer Token

builder.with_bearer_token('your-api-token')

API Key

builder.with_api_key('your-api-key', header_name='X-API-Key')

Token Manager

For automatic token refresh:

from requestforge import TokenManager, ClientCredentialsTokenProvider

provider = ClientCredentialsTokenProvider(
    token_url='https://auth.example.com/token',
    client_id='your-client-id',
    client_secret='your-client-secret',
    service_name='example-api'
)

token_manager = TokenManager(provider)

builder.with_token_auth(
    token_manager=token_manager,
    excluded_paths={'/health', '/public/*'}
)

Logging

Enable built-in logging:

builder.with_logging(
    log_headers=True,
    log_body=False,
    sensitive_keys={'authorization', 'x-api-key'}
)

Complete Example

from requestforge import HttpClientConfigBuilder, HttpClient

config = (
    HttpClientConfigBuilder()
    # Basic settings
    .with_base_url('https://api.example.com')
    .with_timeout(30.0)
    .with_verify_ssl(True)

    # Headers
    .with_header('User-Agent', 'MyApp/1.0')
    .with_header('Accept', 'application/json')

    # Authentication
    .with_bearer_token('your-token')

    # Retry configuration
    .with_retry(
        max_retries=3,
        base_delay=1.0,
        max_delay=60.0
    )

    # Connection pooling
    .with_pool_connection(10)
    .with_pool_maxsize(20)

    # Logging
    .with_logging(log_headers=True)

    .build()
)

client = HttpClient(config)

Immutability

Configuration objects are immutable (frozen dataclasses). Once built, they cannot be modified:

config = builder.build()

# This will raise an error:
# config.base_url = 'new-url'  # ❌ FrozenInstanceError

To change configuration, create a new config object.

Validation

Configuration is validated during creation:

# This will raise ValueError:
builder.with_timeout(-1)  # ❌ Timeout must be positive
builder.with_redirects(max_redirects=-1)  # ❌ Must be non-negative