H2
H2 is a basic, experimental HTTP/2 client based on the http-2 gem.
H2 uses:
- keyword arguments (>=2.0)
- exception-less socket IO (>=2.3).
Usage
require 'h2'
#
# --- one-shot convenience
#
stream = H2.get url: 'https://example.com'
stream.ok? #=> true
stream.headers #=> Hash
stream.body #=> String
stream.closed? #=> true
client = stream.client #=> H2::Client
client.closed? #=> true
#
# --- normal connection
#
client = H2::Client.new addr: 'example.com', port: 443
stream = client.get path: '/'
stream.ok? #=> true
stream.headers #=> Hash, method blocks until stream is closed
stream.body #=> String, method blocks until stream is closed
stream.closed? #=> true
client.closed? #=> false unless server sent GOAWAY
stream = client.get path: '/push_promise' do |s| # H2::Stream === s
s.on :headers do |h|
if h['ETag'] == 'some_value']
s.cancel! # already have
end
end
end
stream.block! # blocks until this stream and any associated push streams are closed
stream.ok? #=> true
stream.headers #=> Hash
stream.body #=> String
stream.closed? #=> true
stream.pushes #=> Set
stream.pushes.each do |pp|
pp.parent == stream #=> true
pp.headers #=> Hash
pp.body #=> String
end
client.goaway!
CLI
For more info on using the CLI h2
installed with this gem:
$ h2 --help
Alternate Concurrency Models
Right now, h2 uses one new thread per connection. This is hardly ideal, so a couple other models are tentatively supported out of the box:
Neither of these gems are hard dependencies. If you want to use either one, you must
have it available to your Ruby VM, most likely via Bundler, and require the
sub-component of h2 that will prepend and extend H2::Client
. They are also intended
to be mutually exclusive: you can have both in your VM, but you can only use one at a
time with h2.
Celluloid Pool
To use a celluloid actor pool for reading from H2::Client
connections:
require 'h2/client/celluloid'
This will lazily fire up a celluloid pool, with defaults defined by Celluloid.
Concurrent-Ruby ThreadPoolExecutor
To use a concurrent-ruby thread pool executor for reading from H2::Client
connections:
require 'h2/client/concurrent'
This will lazily fire up a Concurrent::ThreadPoolExecutor
with the following settings:
procs = ::Concurrent.processor_count
min_threads: 0,
max_threads: procs,
max_queue: procs * 5
TODO
- [x] HTTPS / TLS
- [x] push promise cancellation
- [x] alternate concurrency models
- [ ] fix up CLI to be more curlish
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/kenichi/h2. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.