NetHttp2 is an HTTP/2 client for Ruby.
Ruby Shell
Pull request Compare This branch is 6 commits behind ostinelli:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
spec
.gitignore
.rspec
.ruby-gemset
.ruby-version
.travis.yml
Gemfile
LICENSE.md
README.md
Rakefile
net-http2.gemspec

README.md

Build Status Code Climate Gem Version

NetHttp2

NetHttp2 is an HTTP/2 client for Ruby.

Installation

Just install the gem:

$ gem install net-http2

Or add it to your Gemfile:

gem 'net-http2'

Usage

NetHttp2 can perform sync and async calls. Sync calls are very similar to the HTTP/1 calls, while async calls take advantage of the streaming properties of HTTP/2.

To perform a sync call:

require 'net-http2'

# create a client
client = NetHttp2::Client.new("http://nghttp2.org")

# send request
response = client.call(:get, '/')

# read the response
response.ok?      # => true
response.status   # => '200'
response.headers  # => {":status"=>"200"}
response.body     # => "A body"

# close the connection
client.close

To perform an async call:

require 'net-http2'

# create a client
client = NetHttp2::Client.new("http://nghttp2.org")

# prepare request
request = client.prepare_request(:get, '/')
request.on(:headers) { |headers| p headers }
request.on(:body_chunk) { |chunk| p chunk }
request.on(:close) { puts "request completed!" }

# send
client.call_async(request)

# Wait for all outgoing stream to be closed
client.join

# close the connection
client.close

Objects

NetHttp2::Client

Methods

  • new(url, options={})NetHttp2::Client

    Returns a new client. url is a string such as http://nghttp2.org. The current options are:

    • :connect_timeout, specifies the max connect timeout in seconds (defaults to 60).
    • :ssl_context, in case the url has an https scheme and you want your SSL client to use a custom context.

    To create a new client:

    NetHttp2::Client.new("http://nghttp2.org")

    To create a new client with a custom SSL context:

    certificate = File.read("cert.pem")
    ctx         = OpenSSL::SSL::SSLContext.new
    ctx.key     = OpenSSL::PKey::RSA.new(certificate, "cert_password")
    ctx.cert    = OpenSSL::X509::Certificate.new(certificate)
    
    NetHttp2::Client.new("https://nghttp2.org", ssl_context: ctx)
  • uriURI

    Returns the URI of the endpoint.

Blocking calls

These behave similarly to HTTP/1 calls.

  • call(method, path, options={})NetHttp2::Response or nil

    Sends a request. Returns nil in case a timeout occurs.

    method is a symbol that specifies the :method header (:get, :post, :put, :patch, :delete, :options). The body, headers and query-string params of the request can be specified in the options, together with the timeout.

    response_1 = client.call(:get, '/path1')
    response_2 = client.call(:get, '/path2', headers: { 'x-custom' => 'custom' })
    response_3 = client.call(:post, '/path3', body: "the request body", timeout: 1)
    response_3 = client.call(:post, '/path4', params: { page: 4 })
Non-blocking calls

The real benefit of HTTP/2 is being able to receive body and header streams. Instead of buffering the whole response, you might want to react immediately upon receiving those streams. This is what non-blocking calls are for.

  • prepare_request(method, path, options={})NetHttp2::Request

    Prepares an async request. Arguments are the same as the call method, with the difference that the :timeout option will be ignored. In an async call, you will need to write your own logic for timeouts.

    request = client.prepare_request(:get, '/path', headers: { 'x-custom-header' => 'custom' })
  • call_async(request)

    Calls the server with the async request.

  • join

    Wait for all outstanding requests to be completed.

NetHttp2::Request

Methods

  • methodsymbol

    The request's method.

  • uriURI

    The request's URI.

  • pathstring

    The request's path.

  • paramshash

    The query string params in hash format, for example {one: 1, two: 2}. These will be encoded and appended to path.

  • bodystring

    The request's body.

  • timeoutinteger

    The request's timeout.

  • on(event, &block)

    Allows to set a callback for the request. Available events are:

    • :headers: triggered when headers are received (called once).
    • :body_chunk: triggered when body chunks are received (may be called multiple times).
    • :close: triggered when the request has been completed (called once).

    Even if NetHttp2 is thread-safe, the async callbacks will be executed in a different thread, so ensure that your code in the callbacks is thread-safe.

    request.on(:headers) { |headers| p headers }
    request.on(:body_chunk) { |chunk| p chunk }
    request.on(:close) { puts "request completed!" }

NetHttp2::Response

Methods

  • ok?boolean

    Returns if the request was successful.

  • headershash

    Returns a Hash containing the Headers of the response.

  • statusstring

    Returns the status code.

  • bodystring

    Returns the RAW body of the response.

Thread-Safety

NetHttp2 is thread-safe.

Contributing

So you want to contribute? That's great! Please follow the guidelines below. It will make it easier to get merged in.

Before implementing a new feature, please submit a ticket to discuss what you intend to do. Your feature might already be in the works, or an alternative implementation might have already been discussed.

Do not commit to master in your fork. Provide a clean branch without merge commits. Every pull request should have its own topic branch. In this way, every additional adjustments to the original pull request might be done easily, and squashed with git rebase -i. The updated branch will be visible in the same pull request, so there will be no need to open new pull requests when there are changes to be applied.

Ensure to include proper testing. To run tests you simply have to be in the project's root directory and run:

$ rake