Async::HTTP

To avoid making real network requests during testing, you can use Async::HTTP::Mock::Endpoint. This feature runs a real server in a separate background task and intercepts requests made by a client.

To implement this:

1. Create an instance of Async::HTTP::Mock::Endpoint.
2. Start a background server task using mock_endpoint.run where you define the logic to return a Protocol::HTTP::Response.
3. Wrap your target Async::HTTP::Endpoint using mock_endpoint.wrap(endpoint).
4. Initialize your Async::HTTP::Client with the wrapped endpoint.

require 'async/http'
require 'async/http/mock'

mock_endpoint = Async::HTTP::Mock::Endpoint.new

Sync do
  # Start a background server:
  server_task = Async(transient: true) do
    mock_endpoint.run do |request|
      # Respond to the request:
      ::Protocol::HTTP::Response[200, {}, ["Hello, World"]]
    end
  end
  
  endpoint = Async::HTTP::Endpoint.parse("https://www.google.com")
  mocked_endpoint = mock_endpoint.wrap(endpoint)
  client = Async::HTTP::Client.new(mocked_endpoint)
  
  response = client.get("/")
  puts response.read
  # => "Hello, World"
end

You can achieve 'transparent mocking' by using your test framework (like Sus) to intercept Async::HTTP::Client.new. This allows your application code to instantiate a standard client while the test framework automatically injects a mocked endpoint.

When using Sus::Fixtures::Async::ReactorContext, you can wrap the :new method of Async::HTTP::Client to return a client initialized with a mock_endpoint.wrap(endpoint) instead of the original endpoint.

require 'async/http'
require 'async/http/mock'
require 'sus/fixtures/async/reactor_context'

include Sus::Fixtures::Async::ReactorContext

let(:mock_endpoint) {Async::HTTP::Mock::Endpoint.new}

def before
  super
  
  # Mock the HTTP client:
  mock(Async::HTTP::Client) do |mock|
    mock.wrap(:new) do |original, endpoint|
      original.call(mock_endpoint.wrap(endpoint))
    end
  end
  
  # Run the mock server:
  Async(transient: true) do
    mock_endpoint.run do |request|
      ::Protocol::HTTP::Response[200, {}, ["Hello, World"]]
    end
  end
end

it "should perform a web request" do
  client = Async::HTTP::Client.new(Async::HTTP::Endpoint.parse("https://www.google.com"))
  response = client.get("/")
  # The response is mocked:
  expect(response.read).to be == "Hello, World"
end

Use Async::HTTP::Internet for simple request patterns. It supports several HTTP methods including :patch, :options, :connect, :post, :get, :delete, :head, :trace, and :put.

Automatic Resource Management

When you pass a block to a request method, the response is automatically closed when the block completes:

require 'async/http/internet/instance'

Sync do
  Async::HTTP::Internet.get("https://httpbin.org/get") do |response|
    puts response.read
  end
end

Manual Resource Management

If you do not use a block, you must ensure the response is closed manually to avoid leaking resources, as responses are streamed. Use an ensure block to guarantee closure:

require 'async/http/internet/instance'

Sync do
  response = Async::HTTP::Internet.get("https://httpbin.org/get")
  puts response.read
ensure
  response&.close
end

Connection Persistence

Async::HTTP::Internet automatically manages connection persistence. It creates an Async::HTTP::Client for each remote host and keeps connections open to reduce latency for subsequent requests to the same host. Connections are closed automatically when the event loop exits.