HTTPX design goals are to be simple and intuitive to use, to not reinvent the wheel, and to be forwards-compatible with the protocols of tomorrow.
It was made in order to provide a ruby http test library that could support both HTTP/2 and HTTP/1 (and its unique features) using the same API. Beyond that, it tried to take the best features of existing ruby HTTP libraries, and avoiding its inconsistencies.
HTTPX ships with a plugin system “inherited” from sequel, roda or shrine. It allows for controlled extension of the core functionality, i.e. it can be plugged-in at the instance level.
require "httpx" # sends request with the "Authentication" header auth_client = HTTPX.plugin(:authentication) auth_client.authentication("SECRET-TOKEN").get("http://example.com") #=> ...Authentication: "SECRET-TOKEN"\r\n... # does NOT send the "Authentication" header HTTPX.get("http://example.come")
Expect: 100-continueheader in requests with a body.
httpx ships with custom third-party integrations for the following gems:
httpxrequests for webmock.
httpxhandles errors when using multiple requests.
If you want to contribute, here’s what you’ll need to know.
In order to contribute, you can choose to develop in your machine, or use the
docker-compose setup we use for the CI builds.
If you choose to develop locally, you’ll have to have ruby installed. It’s recommended you use a ruby version manager for this. If you never worked with one, my personal recommendation is to use
ruby-install. You’ll also need
make installed (some development dependencies require the installation of C-extensions). All test runs will hit publicly available peers (i.e.:
If you choose to develop using
# this example is for ruby 2.7 specifically, there's a compose file for each supported version > docker-compose -f docker-compose.yml -f docker-compose-ruby-2.7.yml run --entrypoint sh httpx > test/support/ci/build.sh
and you’re good to go. All tests will run against the containerized services.
When writing tests, you have to focus on minimalism. If you look at the test suite, only one assertion method from
minitest is being used in most cases:
assert. There will be exceptions, but you’ll be asked to use
assert whenever possible.
All HTTP features have an integration test using
httpbin (with a few exceptions). If you want to add a specific HTTP feature, test it using an endpoint from
httpbin which can validate it.