EM-HTTP-Request: Asynchronous HTTP Client (EventMachine + Ruby)

EM-HTTP-Request

Async (EventMachine) HTTP client, with support for:

Asynchronous HTTP API for single & parallel request execution
Keep-Alive and HTTP pipelining support
Auto-follow 3xx redirects with max depth
Automatic gzip & deflate decoding
Streaming response processing
Streaming file uploads
HTTP proxy and SOCKS5 support
Basic Auth & OAuth
Connection-level & global middleware support
HTTP parser via http_parser.rb
Works wherever EventMachine runs: Rubinius, JRuby, MRI

Getting started

gem install em-http-request

Extensions

Several higher-order Ruby projects have incorporated em-http and other Ruby HTTP clients:

EM-Synchrony - Collection of convenience classes and primitives to help untangle evented code (Ruby 1.9 + Fibers).
Rack-Client - Use Rack API for server, test, and client side. Supports Rack middleware!
- Example in action
Faraday - Modular HTTP client library using middleware heavily inspired by Rack.
- Example in action

Testing

WebMock - Library for stubbing and setting expectations on HTTP requests in Ruby.
- Example of using WebMock, VCR & EM-HTTP

Other libraries & applications using EM-HTTP

VMWare CloudFoundry - The open platform-as-a-service project
PubSubHubbub - Asynchronous PubSubHubbub ruby client
em-net-http - Monkeypatching Net::HTTP to play ball with EventMachine
chirpstream - EM client for Twitters Chirpstream API
rsolr-async - An asynchronus connection adapter for RSolr
Firering - Eventmachine powered Campfire API
RDaneel - Ruby crawler which respects robots.txt
em-eventsource - EventSource client for EventMachine
and many others.. drop me a link if you want yours included!

Author: igrigorik
Source Code: https://github.com/igrigorik/em-http-request
License: MIT License

#ruby #http #request

EM-HTTP-Request: Asynchronous HTTP Client (EventMachine + Ruby)

EM-HTTP-Request

Async (EventMachine) HTTP client, with support for:

Asynchronous HTTP API for single & parallel request execution
Keep-Alive and HTTP pipelining support
Auto-follow 3xx redirects with max depth
Automatic gzip & deflate decoding
Streaming response processing
Streaming file uploads
HTTP proxy and SOCKS5 support
Basic Auth & OAuth
Connection-level & global middleware support
HTTP parser via http_parser.rb
Works wherever EventMachine runs: Rubinius, JRuby, MRI

Getting started

gem install em-http-request

Extensions

Several higher-order Ruby projects have incorporated em-http and other Ruby HTTP clients:

EM-Synchrony - Collection of convenience classes and primitives to help untangle evented code (Ruby 1.9 + Fibers).
Rack-Client - Use Rack API for server, test, and client side. Supports Rack middleware!
- Example in action
Faraday - Modular HTTP client library using middleware heavily inspired by Rack.
- Example in action

Testing

WebMock - Library for stubbing and setting expectations on HTTP requests in Ruby.
- Example of using WebMock, VCR & EM-HTTP

Other libraries & applications using EM-HTTP

VMWare CloudFoundry - The open platform-as-a-service project
PubSubHubbub - Asynchronous PubSubHubbub ruby client
em-net-http - Monkeypatching Net::HTTP to play ball with EventMachine
chirpstream - EM client for Twitters Chirpstream API
rsolr-async - An asynchronus connection adapter for RSolr
Firering - Eventmachine powered Campfire API
RDaneel - Ruby crawler which respects robots.txt
em-eventsource - EventSource client for EventMachine
and many others.. drop me a link if you want yours included!

Author: igrigorik
Source Code: https://github.com/igrigorik/em-http-request
License: MIT License

#ruby #http #request

Johathan McGlynn

1659161160

OAuth2: A Ruby Wrapper for The OAuth 2.0 Protocol.

What

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. This is a RubyGem for implementing OAuth 2.0 clients and servers in Ruby applications. See the sibling oauth gem for OAuth 1.0 implementations in Ruby.

OAuth 2.0 Spec
oauth sibling gem for OAuth 1.0 implementations in Ruby.

Release Documentation

Version 2.0.x

2.0.x Readmes

Version	Release Date	Readme
2.0.6	2022-07-13	https://github.com/oauth-xx/oauth2/blob/v2.0.6/README.md
2.0.5	2022-07-07	https://github.com/oauth-xx/oauth2/blob/v2.0.5/README.md
2.0.4	2022-07-01	https://github.com/oauth-xx/oauth2/blob/v2.0.4/README.md
2.0.3	2022-06-28	https://github.com/oauth-xx/oauth2/blob/v2.0.3/README.md
2.0.2	2022-06-24	https://github.com/oauth-xx/oauth2/blob/v2.0.2/README.md
2.0.1	2022-06-22	https://github.com/oauth-xx/oauth2/blob/v2.0.1/README.md
2.0.0	2022-06-21	https://github.com/oauth-xx/oauth2/blob/v2.0.0/README.md

Older Releases

1.4.x Readmes

Version	Release Date	Readme
1.4.10	Jul 1, 2022	https://github.com/oauth-xx/oauth2/blob/v1.4.10/README.md
1.4.9	Feb 20, 2022	https://github.com/oauth-xx/oauth2/blob/v1.4.9/README.md
1.4.8	Feb 18, 2022	https://github.com/oauth-xx/oauth2/blob/v1.4.8/README.md
1.4.7	Mar 19, 2021	https://github.com/oauth-xx/oauth2/blob/v1.4.7/README.md
1.4.6	Mar 19, 2021	https://github.com/oauth-xx/oauth2/blob/v1.4.6/README.md
1.4.5	Mar 18, 2021	https://github.com/oauth-xx/oauth2/blob/v1.4.5/README.md
1.4.4	Feb 12, 2020	https://github.com/oauth-xx/oauth2/blob/v1.4.4/README.md
1.4.3	Jan 29, 2020	https://github.com/oauth-xx/oauth2/blob/v1.4.3/README.md
1.4.2	Oct 1, 2019	https://github.com/oauth-xx/oauth2/blob/v1.4.2/README.md
1.4.1	Oct 13, 2018	https://github.com/oauth-xx/oauth2/blob/v1.4.1/README.md
1.4.0	Jun 9, 2017	https://github.com/oauth-xx/oauth2/blob/v1.4.0/README.md

1.3.x Readmes

Version	Release Date	Readme
1.3.1	Mar 3, 2017	https://github.com/oauth-xx/oauth2/blob/v1.3.1/README.md
1.3.0	Dec 27, 2016	https://github.com/oauth-xx/oauth2/blob/v1.3.0/README.md

≤= 1.2.x Readmes (2016 and before)

Version	Release Date	Readme
1.2.0	Jun 30, 2016	https://github.com/oauth-xx/oauth2/blob/v1.2.0/README.md
1.1.0	Jan 30, 2016	https://github.com/oauth-xx/oauth2/blob/v1.1.0/README.md
1.0.0	May 23, 2014	https://github.com/oauth-xx/oauth2/blob/v1.0.0/README.md
< 1.0.0	Find here	https://github.com/oauth-xx/oauth2/tags

Status

	Project	bundle add oauth2
1️⃣	name, license, docs
2️⃣	version & activity
3️⃣	maintanence & linting
4️⃣	testing
5️⃣	coverage & security
6️⃣	resources
7️⃣	spread 💖	🌏 👼 💻

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add oauth2

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install oauth2

OAuth2 for Enterprise

Available as part of the Tidelift Subscription.

The maintainers of OAuth2 and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. Learn more.

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

For more see SECURITY.md.

What is new for v2.0?

Officially support Ruby versions >= 2.7
Unofficially support Ruby versions >= 2.5
Incidentally support Ruby versions >= 2.2
Drop support for the expired MAC Draft (all versions)
Support IETF rfc7523 JWT Bearer Tokens
Support IETF rfc7231 Relative Location in Redirect
Support IETF rfc6749 Don't set oauth params when nil
Support OIDC 1.0 Private Key JWT; based on the OAuth JWT assertion specification (RFC 7523)
Support new formats, including from jsonapi.org: application/vdn.api+json, application/vnd.collection+json, application/hal+json, application/problem+json
Adds new option to OAuth2::Client#get_token:
- :access_token_class (AccessToken); user specified class to use for all calls to get_token
Adds new option to OAuth2::AccessToken#initialize:
- :expires_latency (nil); number of seconds by which AccessToken validity will be reduced to offset latency
By default, keys are transformed to camel case.
- Original keys will still work as previously, in most scenarios, thanks to rash_alt gem.
- However, this is a breaking change if you rely on response.parsed.to_h, as the keys in the result will be camel case.
- As of version 2.0.4 you can turn key transformation off with the snaky: false option.
By default, the :auth_scheme is now :basic_auth (instead of :request_body)
- Third-party strategies and gems may need to be updated if a provider was requiring client id/secret in the request body
... A lot more

Compatibility

Targeted ruby compatibility is non-EOL versions of Ruby, currently 2.7, 3.0 and 3.1. Compatibility is further distinguished by supported and unsupported versions of Ruby. Ruby is limited to 2.2+ for 2.x releases. See 1-4-stable branch for older rubies.

Ruby Engine Compatibility Policy

This gem is tested against MRI, JRuby, and Truffleruby. Each of those has varying versions that target a specific version of MRI Ruby. This gem should work in the just-listed Ruby engines according to the targeted MRI compatibility in the table below. If you would like to add support for additional engines, first make sure Github Actions supports the engine, then submit a PR to the correct maintenance branch as according to the table below.

Ruby Version Compatibility Policy

If something doesn't work on one of these interpreters, it's a bug.

This library may inadvertently work (or seem to work) on other Ruby implementations, however support will only be provided for the versions listed above.

If you would like this library to support another Ruby version, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.

	Ruby OAuth2 Version	Maintenance Branch	Supported Officially	Supported Unofficially	Supported Incidentally
1️⃣	2.0.x	`master`	2.7, 3.0, 3.1	2.5, 2.6	2.2, 2.3, 2.4
2️⃣	1.4.x	`1-4-stable`	2.5, 2.6, 2.7, 3.0, 3.1	2.1, 2.2, 2.3, 2.4	1.9, 2.0
3️⃣	older	N/A	Best of luck to you!	Please upgrade!

NOTE: The 1.4 series will only receive critical security updates. See SECURITY.md

Usage Examples

`authorize_url` and `token_url` are on site root (Just Works!)

require 'oauth2'
client = OAuth2::Client.new('client_id', 'client_secret', site: 'https://example.org')
# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
# => "https://example.org/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"

access = client.auth_code.get_token('authorization_code_value', redirect_uri: 'http://localhost:8080/oauth2/callback', headers: {'Authorization' => 'Basic some_password'})
response = access.get('/api/resource', params: {'query_foo' => 'bar'})
response.class.name
# => OAuth2::Response

Relative `authorize_url` and `token_url` (Not on site root, Just Works!)

In above example, the default Authorization URL is oauth/authorize and default Access Token URL is oauth/token, and, as they are missing a leading /, both are relative.

client = OAuth2::Client.new('client_id', 'client_secret', site: 'https://example.org/nested/directory/on/your/server')
# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
# => "https://example.org/nested/directory/on/your/server/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"

Customize `authorize_url` and `token_url`

You can specify custom URLs for authorization and access token, and when using a leading / they will not be relative, as shown below:

client = OAuth2::Client.new('client_id', 'client_secret',
                            site: 'https://example.org/nested/directory/on/your/server',
                            authorize_url: '/jaunty/authorize/',
                            token_url: '/stirrups/access_token')
# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
# => "https://example.org/jaunty/authorize/?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
client.class.name
# => OAuth2::Client

snake_case and indifferent access in Response#parsed

response = access.get('/api/resource', params: {'query_foo' => 'bar'})
# Even if the actual response is CamelCase. it will be made available as snaky:
JSON.parse(response.body)         # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
response.parsed                   # => {"access_token"=>"aaaaaaaa", "additional_data"=>"additional"}
response.parsed.access_token      # => "aaaaaaaa"
response.parsed[:access_token]    # => "aaaaaaaa"
response.parsed.additional_data   # => "additional"
response.parsed[:additional_data] # => "additional"
response.parsed.class.name        # => OAuth2::SnakyHash (subclass of Hashie::Mash::Rash, from `rash_alt` gem)

What if I hate snakes and/or indifference?

response = access.get('/api/resource', params: {'query_foo' => 'bar'}, snaky: false)
JSON.parse(response.body)         # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
response.parsed                   # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
response.parsed['accessToken']    # => "aaaaaaaa"
response.parsed['additionalData'] # => "additional"
response.parsed.class.name        # => Hash (just, regular old Hash)

Debugging

Set an environment variable, however you would normally do that.

# will log both request and response, including bodies
ENV['OAUTH_DEBUG'] = 'true'

By default, debug output will go to $stdout. This can be overridden when initializing your OAuth2::Client.

require 'oauth2'
client = OAuth2::Client.new(
  'client_id',
  'client_secret',
  site: 'https://example.org',
  logger: Logger.new('example.log', 'weekly')
)

OAuth2::Response

The AccessToken methods #get, #post, #put and #delete and the generic #request will return an instance of the #OAuth2::Response class.

This instance contains a #parsed method that will parse the response body and return a Hash-like OAuth2::SnakyHash if the Content-Type is application/x-www-form-urlencoded or if the body is a JSON object. It will return an Array if the body is a JSON array. Otherwise, it will return the original body string.

The original response body, headers, and status can be accessed via their respective methods.

OAuth2::AccessToken

If you have an existing Access Token for a user, you can initialize an instance using various class methods including the standard new, from_hash (if you have a hash of the values), or from_kvform (if you have an application/x-www-form-urlencoded encoded string of the values).

OAuth2::Error

On 400+ status code responses, an OAuth2::Error will be raised. If it is a standard OAuth2 error response, the body will be parsed and #code and #description will contain the values provided from the error and error_description parameters. The #response property of OAuth2::Error will always contain the OAuth2::Response instance.

If you do not want an error to be raised, you may use :raise_errors => false option on initialization of the client. In this case the OAuth2::Response instance will be returned as usual and on 400+ status code responses, the Response instance will contain the OAuth2::Error instance.

Authorization Grants

Currently the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion authentication grant types have helper strategy classes that simplify client use. They are available via the #auth_code, #implicit, #password, #client_credentials, and #assertion methods respectively.

These aren't full examples, but demonstrative of the differences between usage for each strategy.

auth_url = client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth/callback')
access = client.auth_code.get_token('code_value', redirect_uri: 'http://localhost:8080/oauth/callback')

auth_url = client.implicit.authorize_url(redirect_uri: 'http://localhost:8080/oauth/callback')
# get the token params in the callback and
access = OAuth2::AccessToken.from_kvform(client, query_string)

access = client.password.get_token('username', 'password')

access = client.client_credentials.get_token

# Client Assertion Strategy
# see: https://tools.ietf.org/html/rfc7523
claimset = {
  iss: 'http://localhost:3001',
  aud: 'http://localhost:8080/oauth2/token',
  sub: 'me@example.com',
  exp: Time.now.utc.to_i + 3600,
}
assertion_params = [claimset, 'HS256', 'secret_key']
access = client.assertion.get_token(assertion_params)

# The `access` (i.e. access token) is then used like so:
access.token # actual access_token string, if you need it somewhere
access.get('/api/stuff') # making api calls with access token

If you want to specify additional headers to be sent out with the request, add a 'headers' hash under 'params':

access = client.auth_code.get_token('code_value', redirect_uri: 'http://localhost:8080/oauth/callback', headers: {'Some' => 'Header'})

You can always use the #request method on the OAuth2::Client instance to make requests for tokens for any Authentication grant type.

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.

As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency 'oauth2', '~> 2.0'

License

Copyright (c) 2011-2013 Michael Bleigh and Intridea, Inc.
Copyright (c) 2017-2022 oauth-xx organization
See LICENSE for details.

FOSSA Status

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

See CONTRIBUTING.md

Contributors

Made with contributors-img.

Code of Conduct

Everyone interacting in the OAuth2 project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Author: oauth-xx
Source code: https://github.com/oauth-xx/oauth2
License: MIT license

#ruby #ruby-on-rails

Royce Reinger

1656998940

Http: A Fast Ruby HTTP Client with A Chainable API, Streaming Support

About

HTTP (The Gem! a.k.a. http.rb) is an easy-to-use client library for making requests from Ruby. It uses a simple method chaining system for building requests, similar to Python's Requests.

Under the hood, http.rb uses the llhttp parser, a fast HTTP parsing native extension. This library isn't just yet another wrapper around Net::HTTP. It implements the HTTP protocol natively and outsources the parsing to native extensions.

Why http.rb?

Clean API: http.rb offers an easy-to-use API that should be a breath of fresh air after using something like Net::HTTP.

Maturity: http.rb is one of the most mature Ruby HTTP clients, supporting features like persistent connections and fine-grained timeouts.

Performance: using native parsers and a clean, lightweight implementation, http.rb achieves high performance while implementing HTTP in Ruby instead of C.

Installation

Add this line to your application's Gemfile:

gem "http"

And then execute:

$ bundle

Or install it yourself as:

$ gem install http

Inside of your Ruby program do:

require "http"

...to pull it in as a dependency.

Documentation

Please see the http.rb wiki for more detailed documentation and usage notes.

The following API documentation is also available:

Basic Usage

Here's some simple examples to get you started:

>> HTTP.get("https://github.com").to_s
=> "\n\n\n<!DOCTYPE html>\n<html lang=\"en\" class=\"\">\n  <head prefix=\"o..."

That's all it takes! To obtain an HTTP::Response object instead of the response body, all we have to do is omit the #to_s on the end:

>> HTTP.get("https://github.com")
=> #<HTTP::Response/1.1 200 OK {"Server"=>"GitHub.com", "Date"=>"Tue, 10 May...>

We can also obtain an HTTP::Response::Body object for this response:

>> HTTP.get("https://github.com").body
=> #<HTTP::Response::Body:3ff756862b48 @streaming=false>

The response body can be streamed with HTTP::Response::Body#readpartial. In practice, you'll want to bind the HTTP::Response::Body to a local variable and call #readpartial on it repeatedly until it returns nil:

>> body = HTTP.get("https://github.com").body
=> #<HTTP::Response::Body:3ff756862b48 @streaming=false>
>> body.readpartial
=> "\n\n\n<!DOCTYPE html>\n<html lang=\"en\" class=\"\">\n  <head prefix=\"o..."
>> body.readpartial
=> "\" href=\"/apple-touch-icon-72x72.png\">\n    <link rel=\"apple-touch-ic..."
# ...
>> body.readpartial
=> nil

Supported Ruby Versions

This library aims to support and is tested against the following Ruby versions:

Ruby 2.6
Ruby 2.7
Ruby 3.0
Ruby 3.1
JRuby 9.3

If something doesn't work on one of these versions, it's a bug.

This library may inadvertently work (or seem to work) on other Ruby versions, however support will only be provided for the versions listed above.

If you would like this library to support another Ruby version or implementation, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.

Contributing to http.rb

Fork http.rb on GitHub
Make your changes
Ensure all tests pass (bundle exec rake)
Send a pull request
If we like them we'll merge them
If we've accepted a patch, feel free to ask for commit access!

Documentation

Author: httprb
Source Code: https://github.com/httprb/http
License: MIT license

#ruby #http #client

Royce Reinger

1657054920

RESTClient: Simple HTTP and REST Client for Ruby

REST Client -- simple DSL for accessing HTTP and REST resources

A simple HTTP and REST client for Ruby, inspired by the Sinatra's microframework style of specifying actions: get, put, post, delete.

Requirements

MRI Ruby 2.0 and newer are supported. Alternative interpreters compatible with 2.0+ should work as well.

Earlier Ruby versions such as 1.8.7, 1.9.2, and 1.9.3 are no longer supported. These versions no longer have any official support, and do not receive security updates.

The rest-client gem depends on these other gems for usage at runtime:

There are also several development dependencies. It's recommended to use bundler to manage these dependencies for hacking on rest-client.

Upgrading to rest-client 2.0 from 1.x

Users are encouraged to upgrade to rest-client 2.0, which cleans up a number of API warts and wrinkles, making rest-client generally more useful. Usage is largely compatible, so many applications will be able to upgrade with no changes.

Overview of significant changes:

requires Ruby >= 2.0
RestClient::Response objects are a subclass of String rather than a Frankenstein monster. And #body or #to_s return a true String object.
cleanup of exception classes, including new RestClient::Exceptions::Timeout
improvements to handling of redirects: responses and history are properly exposed
major changes to cookie support: cookie jars are used for browser-like behavior throughout
encoding: Content-Type charset response headers are used to automatically set the encoding of the response string
HTTP params: handling of GET/POST params is more consistent and sophisticated for deeply nested hash objects, and ParamsArray can be used to pass ordered params
improved proxy support with per-request proxy configuration, plus the ability to disable proxies set by environment variables
default request headers: rest-client sets Accept: */* and User-Agent: rest-client/...

See history.md for a more complete description of changes.

Usage: Raw URL

Basic usage:

require 'rest-client'

RestClient.get(url, headers={})

RestClient.post(url, payload, headers={})

In the high level helpers, only POST, PATCH, and PUT take a payload argument. To pass a payload with other HTTP verbs or to pass more advanced options, use RestClient::Request.execute instead.

More detailed examples:

require 'rest-client'

RestClient.get 'http://example.com/resource'

RestClient.get 'http://example.com/resource', {params: {id: 50, 'foo' => 'bar'}}

RestClient.get 'https://user:password@example.com/private/resource', {accept: :json}

RestClient.post 'http://example.com/resource', {param1: 'one', nested: {param2: 'two'}}

RestClient.post "http://example.com/resource", {'x' => 1}.to_json, {content_type: :json, accept: :json}

RestClient.delete 'http://example.com/resource'

>> response = RestClient.get 'http://example.com/resource'
=> <RestClient::Response 200 "<!doctype h...">
>> response.code
=> 200
>> response.cookies
=> {"Foo"=>"BAR", "QUUX"=>"QUUUUX"}
>> response.headers
=> {:content_type=>"text/html; charset=utf-8", :cache_control=>"private" ... }
>> response.body
=> "<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>\n\n ..."

RestClient.post( url,
  {
    :transfer => {
      :path => '/foo/bar',
      :owner => 'that_guy',
      :group => 'those_guys'
    },
     :upload => {
      :file => File.new(path, 'rb')
    }
  })

Passing advanced options

The top level helper methods like RestClient.get accept a headers hash as their last argument and don't allow passing more complex options. But these helpers are just thin wrappers around RestClient::Request.execute.

RestClient::Request.execute(method: :get, url: 'http://example.com/resource',
                            timeout: 10)

RestClient::Request.execute(method: :get, url: 'http://example.com/resource',
                            ssl_ca_file: 'myca.pem',
                            ssl_ciphers: 'AESGCM:!aNULL')

You can also use this to pass a payload for HTTP verbs like DELETE, where the RestClient.delete helper doesn't accept a payload.

RestClient::Request.execute(method: :delete, url: 'http://example.com/resource',
                            payload: 'foo', headers: {myheader: 'bar'})

Due to unfortunate choices in the original API, the params used to populate the query string are actually taken out of the headers hash. So if you want to pass both the params hash and more complex options, use the special key :params in the headers hash. This design may change in a future major release.

RestClient::Request.execute(method: :get, url: 'http://example.com/resource',
                            timeout: 10, headers: {params: {foo: 'bar'}})

➔ GET http://example.com/resource?foo=bar

Multipart

Yeah, that's right! This does multipart sends for you!

RestClient.post '/data', :myfile => File.new("/path/to/image.jpg", 'rb')

This does two things for you:

Auto-detects that you have a File value sends it as multipart
Auto-detects the mime of the file and sets it in the HEAD of the payload for each entry

If you are sending params that do not contain a File object but the payload needs to be multipart then:

RestClient.post '/data', {:foo => 'bar', :multipart => true}

Usage: ActiveResource-Style

resource = RestClient::Resource.new 'http://example.com/resource'
resource.get

private_resource = RestClient::Resource.new 'https://example.com/private/resource', 'user', 'pass'
private_resource.put File.read('pic.jpg'), :content_type => 'image/jpg'

See RestClient::Resource module docs for details.

Usage: Resource Nesting

site = RestClient::Resource.new('http://example.com')
site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'

See RestClient::Resource docs for details.

Exceptions (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)

for result codes between 200 and 207, a RestClient::Response will be returned
for result codes 301, 302 or 307, the redirection will be followed if the request is a GET or a HEAD
for result code 303, the redirection will be followed and the request transformed into a GET
for other cases, a RestClient::ExceptionWithResponse holding the Response will be raised; a specific exception class will be thrown for known error codes
call .response on the exception to get the server's response

>> RestClient.get 'http://example.com/nonexistent'
Exception: RestClient::NotFound: 404 Not Found

>> begin
     RestClient.get 'http://example.com/nonexistent'
   rescue RestClient::ExceptionWithResponse => e
     e.response
   end
=> <RestClient::Response 404 "<!doctype h...">

Other exceptions

While most exceptions have been collected under RestClient::RequestFailed aka RestClient::ExceptionWithResponse, there are a few quirky exceptions that have been kept for backwards compatibility.

RestClient will propagate up exceptions like socket errors without modification:

>> RestClient.get 'http://localhost:12345'
Exception: Errno::ECONNREFUSED: Connection refused - connect(2) for "localhost" port 12345

RestClient handles a few specific error cases separately in order to give better error messages. These will hopefully be cleaned up in a future major release.

RestClient::ServerBrokeConnection is translated from EOFError to give a better error message.

RestClient::SSLCertificateNotVerified is raised when HTTPS validation fails. Other OpenSSL::SSL::SSLError errors are raised as is.

Redirection

By default, rest-client will follow HTTP 30x redirection requests.

New in 2.0: RestClient::Response exposes a #history method that returns a list of each response received in a redirection chain.

>> r = RestClient.get('http://httpbin.org/redirect/2')
=> <RestClient::Response 200 "{\n  \"args\":...">

# see each response in the redirect chain
>> r.history
=> [<RestClient::Response 302 "<!DOCTYPE H...">, <RestClient::Response 302 "">]

# see each requested URL
>> r.request.url
=> "http://httpbin.org/get"
>> r.history.map {|x| x.request.url}
=> ["http://httpbin.org/redirect/2", "http://httpbin.org/relative-redirect/1"]

Manually following redirection

To disable automatic redirection, set :max_redirects => 0.

New in 2.0: Prior versions of rest-client would raise RestClient::MaxRedirectsReached, with no easy way to access the server's response. In 2.0, rest-client raises the normal RestClient::ExceptionWithResponse as it would with any other non-HTTP-20x response.

>> RestClient::Request.execute(method: :get, url: 'http://httpbin.org/redirect/1')
=> RestClient::Response 200 "{\n  "args":..."

>> RestClient::Request.execute(method: :get, url: 'http://httpbin.org/redirect/1', max_redirects: 0)
RestClient::Found: 302 Found

To manually follow redirection, you can call Response#follow_redirection. Or you could of course inspect the result and choose custom behavior.

>> RestClient::Request.execute(method: :get, url: 'http://httpbin.org/redirect/1', max_redirects: 0)
RestClient::Found: 302 Found
>> begin
       RestClient::Request.execute(method: :get, url: 'http://httpbin.org/redirect/1', max_redirects: 0)
   rescue RestClient::ExceptionWithResponse => err
   end
>> err
=> #<RestClient::Found: 302 Found>
>> err.response
=> RestClient::Response 302 "<!DOCTYPE H..."
>> err.response.headers[:location]
=> "/get"
>> err.response.follow_redirection
=> RestClient::Response 200 "{\n  "args":..."

Result handling

The result of a RestClient::Request is a RestClient::Response object.

New in 2.0: RestClient::Response objects are now a subclass of String. Previously, they were a real String object with response functionality mixed in, which was very confusing to work with.

Response objects have several useful methods. (See the class rdoc for more details.)

Response#code: The HTTP response code
Response#body: The response body as a string. (AKA .to_s)
Response#headers: A hash of HTTP response headers
Response#raw_headers: A hash of HTTP response headers as unprocessed arrays
Response#cookies: A hash of HTTP cookies set by the server
Response#cookie_jar: New in 1.8 An HTTP::CookieJar of cookies
Response#request: The RestClient::Request object used to make the request
Response#history: New in 2.0 If redirection was followed, a list of prior Response objects

RestClient.get('http://example.com')
➔ <RestClient::Response 200 "<!doctype h...">

begin
 RestClient.get('http://example.com/notfound')
rescue RestClient::ExceptionWithResponse => err
  err.response
end
➔ <RestClient::Response 404 "<!doctype h...">

Response callbacks, error handling

A block can be passed to the RestClient method. This block will then be called with the Response. Response.return! can be called to invoke the default response's behavior.

# Don't raise exceptions but return the response
>> RestClient.get('http://example.com/nonexistent') {|response, request, result| response }
=> <RestClient::Response 404 "<!doctype h...">

# Manage a specific error code
RestClient.get('http://example.com/resource') { |response, request, result, &block|
  case response.code
  when 200
    p "It worked !"
    response
  when 423
    raise SomeCustomExceptionIfYouWant
  else
    response.return!(&block)
  end
}

But note that it may be more straightforward to use exceptions to handle different HTTP error response cases:

begin
  resp = RestClient.get('http://example.com/resource')
rescue RestClient::Unauthorized, RestClient::Forbidden => err
  puts 'Access denied'
  return err.response
rescue RestClient::ImATeapot => err
  puts 'The server is a teapot! # RFC 2324'
  return err.response
else
  puts 'It worked!'
  return resp
end

For GET and HEAD requests, rest-client automatically follows redirection. For other HTTP verbs, call .follow_redirection on the response object (works both in block form and in exception form).

# Follow redirections for all request types and not only for get and head
# RFC : "If the 301, 302 or 307 status code is received in response to a request other than GET or HEAD,
#        the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user,
#        since this might change the conditions under which the request was issued."

# block style
RestClient.post('http://example.com/redirect', 'body') { |response, request, result|
  case response.code
  when 301, 302, 307
    response.follow_redirection
  else
    response.return!
  end
}

# exception style by explicit classes
begin
  RestClient.post('http://example.com/redirect', 'body')
rescue RestClient::MovedPermanently,
       RestClient::Found,
       RestClient::TemporaryRedirect => err
  err.response.follow_redirection
end

# exception style by response code
begin
  RestClient.post('http://example.com/redirect', 'body')
rescue RestClient::ExceptionWithResponse => err
  case err.http_code
  when 301, 302, 307
    err.response.follow_redirection
  else
    raise
  end
end

Non-normalized URIs

If you need to normalize URIs, e.g. to work with International Resource Identifiers (IRIs), use the Addressable gem (https://github.com/sporkmonger/addressable/) in your code:

  require 'addressable/uri'
  RestClient.get(Addressable::URI.parse("http://www.詹姆斯.com/").normalize.to_str)

Lower-level access

For cases not covered by the general API, you can use the RestClient::Request class, which provides a lower-level API.

You can:

specify ssl parameters
override cookies
manually handle the response (e.g. to operate on it as a stream rather than reading it all into memory)

See RestClient::Request's documentation for more information.

Streaming request payload

RestClient will try to stream any file-like payload rather than reading it into memory. This happens through RestClient::Payload::Streamed, which is automatically called internally by RestClient::Payload.generate on anything with a read method.

>> r = RestClient.put('http://httpbin.org/put', File.open('/tmp/foo.txt', 'r'),
                      content_type: 'text/plain')
=> <RestClient::Response 200 "{\n  \"args\":...">

In Multipart requests, RestClient will also stream file handles passed as Hash (or new in 2.1 ParamsArray).

>> r = RestClient.put('http://httpbin.org/put',
                      {file_a: File.open('a.txt', 'r'),
                       file_b: File.open('b.txt', 'r')})
=> <RestClient::Response 200 "{\n  \"args\":...">

# received by server as two file uploads with multipart/form-data
>> JSON.parse(r)['files'].keys
=> ['file_a', 'file_b']

Streaming responses

Normally, when you use RestClient.get or the lower level RestClient::Request.execute method: :get to retrieve data, the entire response is buffered in memory and returned as the response to the call.

However, if you are retrieving a large amount of data, for example a Docker image, an iso, or any other large file, you may want to stream the response directly to disk rather than loading it in memory. If you have a very large file, it may become impossible to load it into memory.

There are two main ways to do this:

`raw_response`, saves into Tempfile

If you pass raw_response: true to RestClient::Request.execute, it will save the response body to a temporary file (using Tempfile) and return a RestClient::RawResponse object rather than a RestClient::Response.

Note that the tempfile created by Tempfile.new will be in Dir.tmpdir (usually /tmp/), which you can override to store temporary files in a different location. This file will be unlinked when it is dereferenced.

If logging is enabled, this will also print download progress. New in 2.1: Customize the interval with :stream_log_percent (defaults to 10 for printing a message every 10% complete).

For example:

>> raw = RestClient::Request.execute(
           method: :get,
           url: 'http://releases.ubuntu.com/16.04.2/ubuntu-16.04.2-desktop-amd64.iso',
           raw_response: true)
=> <RestClient::RawResponse @code=200, @file=#<Tempfile:/tmp/rest-client.20170522-5346-1pptjm1>, @request=<RestClient::Request @method="get", @url="http://releases.ubuntu.com/16.04.2/ubuntu-16.04.2-desktop-amd64.iso">>
>> raw.file.size
=> 1554186240
>> raw.file.path
=> "/tmp/rest-client.20170522-5346-1pptjm1"
raw.file.path
=> "/tmp/rest-client.20170522-5346-1pptjm1"

>> require 'digest/sha1'
>> Digest::SHA1.file(raw.file.path).hexdigest
=> "4375b73e3a1aa305a36320ffd7484682922262b3"

`block_response`, receives raw Net::HTTPResponse

If you want to stream the data from the response to a file as it comes, rather than entirely in memory, you can also pass RestClient::Request.execute a parameter :block_response to which you pass a block/proc. This block receives the raw unmodified Net::HTTPResponse object from Net::HTTP, which you can use to stream directly to a file as each chunk is received.

Note that this bypasses all the usual HTTP status code handling, so you will want to do you own checking for HTTP 20x response codes, redirects, etc.

The following is an example:

File.open('/some/output/file', 'w') {|f|
  block = proc { |response|
    response.read_body do |chunk|
      f.write chunk
    end
  }
  RestClient::Request.execute(method: :get,
                              url: 'http://example.com/some/really/big/file.img',
                              block_response: block)
}

Shell

The restclient shell command gives an IRB session with RestClient already loaded:

$ restclient
>> RestClient.get 'http://example.com'

Specify a URL argument for get/post/put/delete on that resource:

$ restclient http://example.com
>> put '/resource', 'data'

Add a user and password for authenticated resources:

$ restclient https://example.com user pass
>> delete '/private/resource'

Create ~/.restclient for named sessions:

  sinatra:
    url: http://localhost:4567
  rack:
    url: http://localhost:9292
  private_site:
    url: http://example.com
    username: user
    password: pass

Then invoke:

$ restclient private_site

Use as a one-off, curl-style:

$ restclient get http://example.com/resource > output_body

$ restclient put http://example.com/resource < input_body

Logging

To enable logging globally you can:

set RestClient.log with a Ruby Logger

RestClient.log = STDOUT

or set an environment variable to avoid modifying the code (in this case you can use a file name, "stdout" or "stderr"):

$ RESTCLIENT_LOG=stdout path/to/my/program

You can also set individual loggers when instantiating a Resource or making an individual request:

resource = RestClient::Resource.new 'http://example.com/resource', log: Logger.new(STDOUT)

RestClient::Request.execute(method: :get, url: 'http://example.com/foo', log: Logger.new(STDERR))

All options produce logs like this:

RestClient.get "http://some/resource"
# => 200 OK | text/html 250 bytes
RestClient.put "http://some/resource", "payload"
# => 401 Unauthorized | application/xml 340 bytes

Note that these logs are valid Ruby, so you can paste them into the restclient shell or a script to replay your sequence of rest calls.

Proxy

All calls to RestClient, including Resources, will use the proxy specified by RestClient.proxy:

RestClient.proxy = "http://proxy.example.com/"
RestClient.get "http://some/resource"
# => response from some/resource as proxied through proxy.example.com

Often the proxy URL is set in an environment variable, so you can do this to use whatever proxy the system is configured to use:

  RestClient.proxy = ENV['http_proxy']

New in 2.0: Specify a per-request proxy by passing the :proxy option to RestClient::Request. This will override any proxies set by environment variable or by the global RestClient.proxy value.

RestClient::Request.execute(method: :get, url: 'http://example.com',
                            proxy: 'http://proxy.example.com')
# => single request proxied through the proxy

This can be used to disable the use of a proxy for a particular request.

RestClient.proxy = "http://proxy.example.com/"
RestClient::Request.execute(method: :get, url: 'http://example.com', proxy: nil)
# => single request sent without a proxy

Query parameters

Rest-client can render a hash as HTTP query parameters for GET/HEAD/DELETE requests or as HTTP post data in x-www-form-urlencoded format for POST requests.

New in 2.0: Even though there is no standard specifying how this should work, rest-client follows a similar convention to the one used by Rack / Rails servers for handling arrays, nested hashes, and null values.

The implementation in ./lib/rest-client/utils.rb closely follows Rack::Utils.build_nested_query, but treats empty arrays and hashes as nil. (Rack drops them entirely, which is confusing behavior.)

If you don't like this behavior and want more control, just serialize params yourself (e.g. with URI.encode_www_form) and add the query string to the URL directly for GET parameters or pass the payload as a string for POST requests.

Basic GET params:

RestClient.get('https://httpbin.org/get', params: {foo: 'bar', baz: 'qux'})
# GET "https://httpbin.org/get?foo=bar&baz=qux"

Basic x-www-form-urlencoded POST params:

>> r = RestClient.post('https://httpbin.org/post', {foo: 'bar', baz: 'qux'})
# POST "https://httpbin.org/post", data: "foo=bar&baz=qux"
=> <RestClient::Response 200 "{\n  \"args\":...">
>> JSON.parse(r.body)
=> {"args"=>{},
    "data"=>"",
    "files"=>{},
    "form"=>{"baz"=>"qux", "foo"=>"bar"},
    "headers"=>
    {"Accept"=>"*/*",
        "Accept-Encoding"=>"gzip, deflate",
        "Content-Length"=>"15",
        "Content-Type"=>"application/x-www-form-urlencoded",
        "Host"=>"httpbin.org"},
    "json"=>nil,
    "url"=>"https://httpbin.org/post"}

JSON payload: rest-client does not speak JSON natively, so serialize your payload to a string before passing it to rest-client.

>> payload = {'name' => 'newrepo', 'description': 'A new repo'}
>> RestClient.post('https://api.github.com/user/repos', payload.to_json, content_type: :json)
=> <RestClient::Response 201 "{\"id\":75149...">

Advanced GET params (arrays):

>> r = RestClient.get('https://http-params.herokuapp.com/get', params: {foo: [1,2,3]})
# GET "https://http-params.herokuapp.com/get?foo[]=1&foo[]=2&foo[]=3"
=> <RestClient::Response 200 "Method: GET...">
>> puts r.body
query_string: "foo[]=1&foo[]=2&foo[]=3"
decoded:      "foo[]=1&foo[]=2&foo[]=3"

GET:
  {"foo"=>["1", "2", "3"]}

Advanced GET params (nested hashes):

>> r = RestClient.get('https://http-params.herokuapp.com/get', params: {outer: {foo: 123, bar: 456}})
# GET "https://http-params.herokuapp.com/get?outer[foo]=123&outer[bar]=456"
=> <RestClient::Response 200 "Method: GET...">
>> puts r.body
...
query_string: "outer[foo]=123&outer[bar]=456"
decoded:      "outer[foo]=123&outer[bar]=456"

GET:
  {"outer"=>{"foo"=>"123", "bar"=>"456"}}

New in 2.0: The new RestClient::ParamsArray class allows callers to provide ordering even to structured parameters. This is useful for unusual cases where the server treats the order of parameters as significant or you want to pass a particular key multiple times.

Multiple fields with the same name using ParamsArray:

>> RestClient.get('https://httpbin.org/get', params:
                  RestClient::ParamsArray.new([[:foo, 1], [:foo, 2]]))
# GET "https://httpbin.org/get?foo=1&foo=2"

Nested ParamsArray:

>> RestClient.get('https://httpbin.org/get', params:
                  {foo: RestClient::ParamsArray.new([[:a, 1], [:a, 2]])})
# GET "https://httpbin.org/get?foo[a]=1&foo[a]=2"

Headers

Request headers can be set by passing a ruby hash containing keys and values representing header names and values:

# GET request with modified headers
RestClient.get 'http://example.com/resource', {:Authorization => 'Bearer cT0febFoD5lxAlNAXHo6g'}

# POST request with modified headers
RestClient.post 'http://example.com/resource', {:foo => 'bar', :baz => 'qux'}, {:Authorization => 'Bearer cT0febFoD5lxAlNAXHo6g'}

# DELETE request with modified headers
RestClient.delete 'http://example.com/resource', {:Authorization => 'Bearer cT0febFoD5lxAlNAXHo6g'}

Timeouts

By default the timeout for a request is 60 seconds. Timeouts for your request can be adjusted by setting the timeout: to the number of seconds that you would like the request to wait. Setting timeout: will override both read_timeout: and open_timeout:.

RestClient::Request.execute(method: :get, url: 'http://example.com/resource',
                            timeout: 120)

Additionally, you can set read_timeout: and open_timeout: separately.

RestClient::Request.execute(method: :get, url: 'http://example.com/resource',
                            read_timeout: 120, open_timeout: 240)

Cookies

Request and Response objects know about HTTP cookies, and will automatically extract and set headers for them as needed:

response = RestClient.get 'http://example.com/action_which_sets_session_id'
response.cookies
# => {"_applicatioN_session_id" => "1234"}

response2 = RestClient.post(
  'http://localhost:3000/',
  {:param1 => "foo"},
  {:cookies => {:session_id => "1234"}}
)
# ...response body

Full cookie jar support (new in 1.8)

The original cookie implementation was very naive and ignored most of the cookie RFC standards. New in 1.8: An HTTP::CookieJar of cookies

Response objects now carry a cookie_jar method that exposes an HTTP::CookieJar of cookies, which supports full standards compliant behavior.

SSL/TLS support

Various options are supported for configuring rest-client's TLS settings. By default, rest-client will verify certificates using the system's CA store on all platforms. (This is intended to be similar to how browsers behave.) You can specify an :ssl_ca_file, :ssl_ca_path, or :ssl_cert_store to customize the certificate authorities accepted.

SSL Client Certificates

RestClient::Resource.new(
  'https://example.com',
  :ssl_client_cert  =>  OpenSSL::X509::Certificate.new(File.read("cert.pem")),
  :ssl_client_key   =>  OpenSSL::PKey::RSA.new(File.read("key.pem"), "passphrase, if any"),
  :ssl_ca_file      =>  "ca_certificate.pem",
  :verify_ssl       =>  OpenSSL::SSL::VERIFY_PEER
).get

Self-signed certificates can be generated with the openssl command-line tool.

Hook

RestClient.add_before_execution_proc add a Proc to be called before each execution. It's handy if you need direct access to the HTTP request.

Example:

# Add oauth support using the oauth gem
require 'oauth'
access_token = ...

RestClient.add_before_execution_proc do |req, params|
  access_token.sign! req
end

RestClient.get 'http://example.com'

Need caching, more advanced logging or any ability provided by Rack middleware?

Have a look at rest-client-components: http://github.com/crohr/rest-client-components

Credits


REST Client Team	Andy Brody
Creator	Adam Wiggins
Maintainers Emeriti	Lawrence Leonard Gilbert, Matthew Manning, Julien Kirch
Major contributions	Blake Mizerany, Julien Kirch

A great many generous folks have contributed features and patches. See AUTHORS for the full list.

Main page: https://github.com/rest-client/rest-client
Mailing list: https://groups.io/g/rest-client

New mailing list

We have a new email list for announcements, hosted by Groups.io.

Subscribe on the web: https://groups.io/g/rest-client

Subscribe by sending an email: mailto:rest-client+subscribe@groups.io

Open discussion subgroup: https://groups.io/g/rest-client+discuss

The old Librelist mailing list is defunct, as Librelist appears to be broken and not accepting new mail. The old archives are still up, but have been imported into the new list archives as well. http://librelist.com/browser/rest.client

Author: Rest-client
Source Code: https://github.com/rest-client/rest-client
License: MIT license

#ruby #client #http #rest

Royce Reinger

1657051020

Patron: Ruby HTTP Client Based on Libcurl

Patron

Patron is a Ruby HTTP client library based on libcurl. It does not try to expose the full "power" (read complexity) of libcurl but instead tries to provide a sane API while taking advantage of libcurl under the hood.

Usage

First, you instantiate a Session object. You can set a few default options on the Session instance that will be used by all subsequent requests:

sess = Patron::Session.new
sess.timeout = 10
sess.base_url = "http://myserver.com:9900"
sess.headers['User-Agent'] = 'myapp/1.0'

You can set options with a hash in the constructor:

sess = Patron::Session.new({ :timeout => 10,
                             :base_url => 'http://myserver.com:9900',
                             :headers => {'User-Agent' => 'myapp/1.0'} } )

Or the set options in a block:

sess = Patron::Session.new do |patron|
    patron.timeout = 10
    patron.base_url = 'http://myserver.com:9900'
    patron.headers = {'User-Agent' => 'myapp/1.0'}
end

Output debug log:

sess.enable_debug "/tmp/patron.debug"

The Session is used to make HTTP requests.

resp = sess.get("/foo/bar")

Requests return a Response object:

if resp.status < 400
  puts resp.body
end

The GET, HEAD, PUT, POST and DELETE operations are all supported.

sess.put("/foo/baz", "some data")
sess.delete("/foo/baz")

You can ship custom headers with a single request:

sess.post("/foo/stuff", "some data", {"Content-Type" => "text/plain"})

Threading

By itself, the Patron::Session objects are not thread safe (each Session holds a single curl_state pointer from initialization to garbage collection). At this time, Patron has no support for curl_multi_* family of functions for doing concurrent requests. However, the actual code that interacts with libCURL does unlock the RVM GIL, so using multiple Session objects in different threads actually enables a high degree of parallelism. For sharing a resource of sessions between threads we recommend using the excellent connection_pool gem by Mike Perham.

patron_pool = ConnectionPool.new(size: 5, timeout: 5) { Patron::Session.new }
patron_pool.with do |session|
  session.get(...)
end

Sharing Session objects between requests will also allow you to benefit from persistent connections (connection reuse), see below.

Persistent connections

Patron follows the libCURL guidelines on connection reuse. If you create the Session object once and use it for multiple requests, the same libCURL handle is going to be used across these requests and if requests go to the same hostname/port/protocol the connection should get reused.

Performance with parallel requests

When performing the libCURL request, Patron goes out of it's way to unlock the GVL (global VM lock) to allow other threads to be scheduled in parallel. The GVL is going to be released when the libCURL request starts, and will then be shortly re-acquired to provide the progress callback - if the callback has been configured, and then released again until the libCURL request has been performed and the response has been read in full. This allows one to execute multiple libCURL requests in parallel, as well as perform other activities on other MRI threads that are currently active in the process.

Requirements

Patron 1.0 and up requires MRI Ruby 2.3 or newer. The 0.x versions support Ruby 1.9.3 and these versions get tagged and developed on the v0.x branch.

A recent version of libCURL is required. We recommend at least 7.19.4 because it supports limiting the protocols, and that is very important for security - especially if you follow redirects.

On OSX the provided libcurl is sufficient if you are not using fork+SSL combination (see below). You will have to install the libcurl development packages on Debian or Ubuntu. Other Linux systems are probably similar. For Windows we do not have an established build instruction at the moment, unfortunately.

Forking webservers on macOS and SSL

Currently, an issue is at play with OSX builds of curl which use Apple's SecureTransport. Such builds (which Patron is linking to), are causing segfaults when performing HTTPS requests in forked subprocesses. If you need to check whether your system is affected, run the Patron test suite by performing

$ bundle install && bundle exec rspec

in the Patron install directory. Most default curl configurations on OSX (both the Apple-shipped version and the version available via Homebrew) are linked to SecureTransport and are likely to be affected. This issue may also manifest in forking webserver implementations (such as Unicorn or Passenger) and in forking job execution engines (such as resque), so even though you may not be using fork() directly your server engine might be doing it for you.

To circumvent the issue, you need to build curl with OpenSSL via homebrew. When doing so, curl will use openssl as it's SSL driver. You also need to change the Patron compile flag:

$ brew install curl-openssl && \
    gem install patron -- --with-curl-config=/usr/local/opt/curl-openssl/bin/curl-config

You can also save this parameter for all future Bundler-driven gem installs by setting this flag in Bundler proper:

$ bundle config build.patron --with-curl-config=/usr/local/opt/curl-openssl/bin/curl-config

Installation

sudo gem install patron

Author: toland
Source Code: https://github.com/toland/patron
License: MIT license

#ruby #http #client

EM-HTTP-Request: Asynchronous HTTP Client (EventMachine + Ruby)

EM-HTTP-Request

Getting started

Extensions

Testing

Other libraries & applications using EM-HTTP

EM-HTTP-Request

Getting started

Extensions

Testing

Other libraries & applications using EM-HTTP

What

Release Documentation

Version 2.0.x

Older Releases

Status

Installation

OAuth2 for Enterprise

Security contact information

What is new for v2.0?

Compatibility

Usage Examples

authorize_url and token_url are on site root (Just Works!)

Relative authorize_url and token_url (Not on site root, Just Works!)

Customize authorize_url and token_url

snake_case and indifferent access in Response#parsed

What if I hate snakes and/or indifference?

OAuth2::Response

OAuth2::AccessToken

OAuth2::Error

Authorization Grants

Versioning

License

Development

Contributing

Contributors

Code of Conduct

About

Why http.rb?

Installation

Documentation

Basic Usage

Supported Ruby Versions

Contributing to http.rb

Requirements

Upgrading to rest-client 2.0 from 1.x

Usage: Raw URL

Passing advanced options

Multipart

Usage: ActiveResource-Style

Usage: Resource Nesting

Exceptions (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)

Other exceptions

Redirection

Manually following redirection

Result handling

Response callbacks, error handling

Non-normalized URIs

Lower-level access

Streaming request payload

Streaming responses

raw_response, saves into Tempfile

block_response, receives raw Net::HTTPResponse

Shell

Logging

Proxy

Query parameters

Headers

Timeouts

Cookies

Full cookie jar support (new in 1.8)

SSL/TLS support

SSL Client Certificates

Hook

More

Credits

New mailing list

Patron

Usage

Threading

`authorize_url` and `token_url` are on site root (Just Works!)

Relative `authorize_url` and `token_url` (Not on site root, Just Works!)

Customize `authorize_url` and `token_url`

`raw_response`, saves into Tempfile

`block_response`, receives raw Net::HTTPResponse