Connection Pooling

Tune HTTP/2, keepalive, connect timeout and per-host connection limits for parallel runs.

OverviewCopy Anchor Link

Connection pooling is a set of connection settings for runs that send many requests. When connectionPool.enabled is true, curl-runner forces HTTP/2 for every request, applies your keepalive and connect-timeout settings, and caps how many connections a parallel run opens per host.

• HTTP/2 forced: Every request negotiates HTTP/2 (falls back to HTTP/1.1 if the server does not support it)
• Keepalive: TCP keepalive interval from keepaliveTime (default 60 seconds)
• Connect timeout: connectTimeout (default 30 seconds) limits connection establishment
• Host connection cap: In parallel runs, maxStreamsPerHost (default 10) limits the connections opened to each host

How It WorksCopy Anchor Link

Parallel runs already execute through one shared libcurl multi handle, so requests to the same host can reuse connections and multiplex over HTTP/2 with or without pooling. Enabling the pool adds these settings:

• Every request uses HTTP/2.
• Every request, sequential or parallel, gets the pool's keepaliveTime and connectTimeout.
• In parallel runs, maxStreamsPerHost is passed to libcurl as the maximum number of connections per host.

Retries, maxConcurrency and expect work exactly as in any other run. Status codes are judged only through expect.

Basic UsageCopy Anchor Link

Enable connection pooling with connectionPool.enabled in your global configuration.

global:
  execution: parallel
  connectionPool:
    enabled: true

requests:
  - name: Get Users
    url: https://api.example.com/users
  - name: Get Posts
    url: https://api.example.com/posts
  - name: Get Comments
    url: https://api.example.com/comments

CLI OptionsCopy Anchor Link

Enable and configure connection pooling directly from the command line.

# Enable connection pooling via CLI
curl-runner api.yaml -p --connection-pool

# With custom settings
curl-runner api.yaml -p --connection-pool --max-streams 20

# Via environment variables
CURL_RUNNER_CONNECTION_POOL=true curl-runner api.yaml -p

# Full example with env vars
CURL_RUNNER_CONNECTION_POOL=true \
CURL_RUNNER_MAX_STREAMS_PER_HOST=15 \
CURL_RUNNER_KEEPALIVE_TIME=120 \
curl-runner api.yaml -p

Environment VariablesCopy Anchor Link

Configure connection pooling using environment variables for CI/CD pipelines.

Configuration OptionsCopy Anchor Link

Fine-tune connection pooling behavior with these configuration options.

global:
  execution: parallel
  connectionPool:
    enabled: true
    maxStreamsPerHost: 10    # Max connections per host (parallel runs)
    keepaliveTime: 60        # TCP keepalive in seconds
    connectTimeout: 30       # Connection timeout in seconds

requests:
  - name: Get Users
    url: https://api.example.com/users
    method: GET
  - name: Get Posts
    url: https://api.example.com/posts
    method: GET
  - name: Create Order
    url: https://api.example.com/orders
    method: POST
    body:
      productId: 123
  - name: Get Inventory
    url: https://api.example.com/inventory
    method: GET

Connection Timeout ErrorsCopy Anchor Link

When a request fails while resolving or connecting and the pool's connectTimeout is shorter than the request timeout, the error reads Connection timeout after <ms>ms instead of the request timeout message.

When to UseCopy Anchor Link

• Recommended For
  • Parallel runs with many requests to the same host
  • Test suites that benefit from HTTP/2 multiplexing
  • Tuning keepalive or connect timeouts for slow or flaky networks
• Not Needed For
  • A single request
  • Servers that only speak HTTP/1.1
  • Runs where the defaults already work for you

LimitationsCopy Anchor Link

• Host cap applies to parallel runs: maxStreamsPerHost only matters with execution: parallel. Keepalive, connect timeout and HTTP/2 apply to sequential runs as well.
• HTTP/2 is forced: Servers without HTTP/2 support are used over HTTP/1.1.
• Idle connections: Idle keep-alive connections stay open until the run ends.

Related FeaturesCopy Anchor Link

• HTTP/2 Support: Enable HTTP/2 protocol
• Parallel Execution: Run requests simultaneously
• Performance Profiling: Measure connection timing metrics