Project

h2

0.01
No commit activity in last 3 years
No release in over 3 years
a pure ruby http/2 client & server based on http-2
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.16
~> 5.0
~> 12.0

Runtime

>= 0.10.0, ~> 0.10
 Project Readme

H2

Build Status

H2 is an HTTP/2 client and server based on the http-2 gem.

H2 uses:

  • keyword arguments (>=2.0)
  • exception-less socket IO (>=2.3).

Server Usage

Server API is currently optional, so h2/server must be required separately. The server uses Celluloid::IO, but h2's gemspec does not require it, so celluloid-io must be separately added to Gemfile. It is currently based on celluloid-io-0.17.3.

require 'h2/server'

server = H2::Server::HTTP.new host: addr, port: port do |connection|
  connection.each_stream do |stream|
    stream.respond status: 200, body: "hello, world!\n"
    stream.connection.goaway
  end
end

stream = H2.get url: "http://#{addr}:#{port}", tls: false
stream.body #=> "hello, world!\n"

See more server examples:

Client 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 host: '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

client.on :promise do |p| # check/cancel a promise
  p.on :headers do |h|
    if h['etag'] == 'some_value'
      p.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!

Client CLI

For more info on using the CLI h2 installed with this gem:

$ h2 --help

Using TLS CA Certificates with the Client

If you're running on macOS and using Homebrew's openssl package, you may need to specify the CA file in the TLS options:

client = H2::Client.new host: 'example.com', port: 443, tls: { ca_file: '/usr/local/etc/openssl/cert.pem' }

or when using the CLI:

$ h2 --cafile /usr/local/etc/openssl/cert.pem https://example.com/

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's client.

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.

NOTE: if you've added celluloid-io and required the 'h2/server' API, Celluloid will be loaded in your Ruby VM already; however, you must still require this to have the client use Celluloid actor pools.

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

  • HTTPS / TLS
  • push promise cancellation
  • alternate concurrency models
  • fix up CLI to be more curlish
  • update server API

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.