HTTPX Ruby HTTP Client

HTTPX supports concurrency by default. If you pass multiple URIs to a single method call, HTTPX will perform all requests simultaneously. It uses multiplexing on HTTP/2 sockets or HTTP/1.1 pipelining where possible to optimize performance.

Simultaneous requests (returning multiple responses):

page1, page2, page3 = HTTPX.get("https://news.ycombinator.com/news", "https://news.ycombinator.com/news?p=2", "https://news.ycombinator.com/news?p=3")

Multiplexing requests to the same origin:

HTTPX.get(
  "https://news.ycombinator.com/news",
  "https://news.ycombinator.com/news?p=2",
  "https://google.com/q=me"
) # The first two requests will be multiplexed on the same socket.

HTTPX supports concurrent requests in two ways:

1. Passing multiple URIs: Passing multiple arguments to a method like .get will execute them in parallel.
2. Using HTTPX.wrap: Using a block with HTTPX.wrap allows you to group multiple requests on a single client, where requests within the block are executed in parallel.

require "httpx"

uri = "https://google.com"

# Method 1: Multiple arguments
responses = HTTPX.get(uri, uri)

# Method 2: Using wrap for parallel execution
HTTPX.wrap do |client|
  client.get(uri)
  client.get(uri)
  client.get(uri, uri) # parallel!
end

To use HTTPX in your Ruby project, add it to your Gemfile or install it directly via the command line.

Using Gemfile:

gem "httpx"

Using command line:

gem install httpx

After installation, require it in your Ruby script:

require "httpx"

Follow Redirects

Use the :follow_redirects plugin. You can control the maximum number of redirects and whether to follow insecure redirects.

Timeouts

Use .with(timeout: { ... }) to set connect_timeout and request_timeout.

Retries

Use the :retries plugin and specify the number of attempts with .max_retries(n).

require "httpx"

# Redirects
HTTPX.plugin(:follow_redirects)
     .with(follow_insecure_redirects: false, max_redirects: 4)
     .get("https://www.google.com")

# Timeouts
HTTPX.with(timeout: { connect_timeout: 10, request_timeout: 3 }).get("https://google.com")

# Retries
HTTPX.plugin(:retries).max_retries(5).get("https://www.google.com")

You can use DNS-over-HTTPS by setting the resolver_class to :https. By default, it uses Cloudflare's DoH server. You can customize the DoH provider using resolver_options.

require "httpx"

# Option 1: Via environment variable (export HTTPX_RESOLVER=https)
HTTPX.get("https://google.com")

# Option 2: Via .with()
HTTPX.with(resolver_class: :https).get("https://google.com")

# Option 3: Custom DoH server (e.g., Quad9)
HTTPX.with(resolver_class: :https, resolver_options: { uri: "https://9.9.9.9/dns-query" }).get("https://google.com")

Disable SSL Verification (Not recommended for production)

You can disable verification using verify_mode: OpenSSL::SSL::VERIFY_NONE.

Use a PEM certificate

To use specific certificates and keys, use .with_ssl with cert, key, and verify_mode.

require "httpx"

# Disable verification
response = HTTPX.with(ssl: { verify_mode: OpenSSL::SSL::VERIFY_NONE }).get("https://secure.com/")

# Use PEM certificate
pem = File.read("/path/to/my.pem")
HTTPX.with_ssl(
  cert: OpenSSL::X509::Certificate.new(pem),
  key: OpenSSL::PKey::RSA.new(pem),
  verify_mode: OpenSSL::SSL::VERIFY_PEER,
).get("https://secure.com/")

HTTPX provides a simple, chainable API for common HTTP methods. You can perform GET and POST requests directly via the HTTPX module.

GET request:

HTTPX.get("https://nghttp2.org").to_s

POST request with form data:

HTTPX.post("http://example.com", form: { user: "john", password: "pass" })

You can debug HTTPX requests using environment variables or the .with method:

1. Environment Variable: Set HTTPX_DEBUG=1 in your shell.
2. Programmatic: Use .with(debug_level: n, debug: $stderr) to direct debug output to a stream.

# Option 1: Environment variable
# export HTTPX_DEBUG=1
HTTPX.get("https://google.com")

# Option 2: Programmatic
require "httpx"
HTTPX.with(debug_level: 1, debug: $stderr).get("https://google.com")

The RateLimiter plugin extends HTTPX to automatically retry requests when encountering rate limits or specific server availability issues. It relies on the :retries plugin to function.

It triggers retries in the following scenarios:

• The response status is 429 (Too Many Requests).
• The response status is 503 (Service Unavailable).
• A 3xx (Redirection) response is received that includes a Retry-After header.

When a Retry-After header is present, the plugin uses HTTPX::Utils.parse_retry_after to determine the wait duration before the next attempt.

# Note: This plugin requires the :retries plugin to be loaded.
HTTPX.plugin(:rate_limiter)

# Example usage (conceptual):
# HTTPX will now automatically respect 'Retry-After' headers
# and retry on 429 or 503 status codes.
response = HTTPX.plugin(:rate_limiter).get("https://api.example.com/data")

The OAuth plugin provides automated management of OAuth 2.0 sessions, including token lifecycle management (fetching, refreshing, and expiration).

Supported Grant Types:

• client_credentials
• refresh_token (preferred if a refresh token is available)

Supported Authorization Methods:

• client_secret_basic (default)
• client_secret_post

Note on Deprecation:

• The option :oauth_session is deprecated. Use :oauth_options instead.
• The method oauth_auth is deprecated. Use with(oauth_options: ...) instead.

When working with gRPC in HTTPX, errors are communicated via trailing metadata (specifically the grpc-status and grpc-message headers).

If a response is not successful (i.e., grpc-status is not 0), the HTTPX::Plugins::GRPC::Message.verify_status method (called internally by unary and stream) will raise a GRPCError.

A GRPCError contains:

• The integer status code.
• The error message.
• The trailing_metadata from the response.

When configuring :retry_after, you can use built-in backoff algorithms by passing a symbol. This is useful for managing request frequency during failures.

Supported algorithms:

• :exponential_backoff: Uses a base of 2 for the backoff calculation.
• :polynomial_backoff: Uses a base of 1 and an exponent of 2 for the backoff calculation.

# Using exponential backoff
HTTPX.plugin(:retries).with(retry_after: :exponential_backoff).get("https://example.com")