From 66384d32dd78ff267d95fa3fbc00edc69ef6421b Mon Sep 17 00:00:00 2001 From: iMacTia Date: Sun, 19 May 2019 17:41:27 +0100 Subject: [PATCH] Merges #970. Adds table of content to homepage. Adds details page for logger middleware. --- README.md | 29 +------- docs/_sass/faraday.sass | 27 ++++++-- docs/adapters/index.md | 43 ++++++++++++ docs/index.md | 39 ++++++++++- docs/middleware/env.md | 7 +- docs/middleware/{README.md => index.md} | 24 +++++-- docs/middleware/response/logger.md | 92 +++++++++++++++++++++++++ docs/{adapters => }/testing.md | 7 +- 8 files changed, 227 insertions(+), 41 deletions(-) create mode 100644 docs/adapters/index.md rename docs/middleware/{README.md => index.md} (68%) create mode 100644 docs/middleware/response/logger.md rename docs/{adapters => }/testing.md (95%) diff --git a/README.md b/README.md index 6699a326..d9c6be29 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Rack::Test, and a Test adapter for stubbing requests by hand. * [Faraday API RubyDoc](http://www.rubydoc.info/gems/faraday) * [Middleware](./docs/middleware) * [Middleware Environment](./docs/middleware/env.md) -* [Testing](./docs/adapters/testing.md) +* [Testing](docs/testing.md) ## Usage @@ -61,33 +61,6 @@ conn = Faraday.new(:url => 'http://sushi.com') do |faraday| faraday.response :logger # log requests and responses to $stdout faraday.adapter Faraday.default_adapter # make requests with Net::HTTP end - -# Filter sensitive information from logs with a regex matcher - -conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday| - faraday.request :url_encoded # form-encode POST params - faraday.response :logger do | logger | - logger.filter(/(api_key=)(\w+)/,'\1[REMOVED]') - end - faraday.adapter Faraday.default_adapter # make requests with Net::HTTP -end - -# Override the log formatting on demand - -class MyFormatter < Faraday::Response::Logger::Formatter - def request(env) - info('Request', env) - end - - def request(env) - info('Response', env) - end -end - -conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday| - faraday.response :logger, StructLogger.new(STDOUT), formatter: MyFormatter -end - ``` Once you have the connection object, use it to make HTTP requests. You can pass parameters to it in a few different ways: diff --git a/docs/_sass/faraday.sass b/docs/_sass/faraday.sass index 01c27a86..58ebd35e 100644 --- a/docs/_sass/faraday.sass +++ b/docs/_sass/faraday.sass @@ -1,15 +1,30 @@ // Custom Styles added on top of the theme. .btn + color: white background-color: $link-color padding: 5px 10px border-radius: 4px &:hover background-color: darken($link-color, 10%) - -p - a color: white - &:hover - color: white - text-decoration: none \ No newline at end of file + text-decoration: none + +.text-center + text-align: center + +.mt-60 + margin-top: 60px + +pre.highlight + padding: 20px + background-color: #F6F6F6 + border-radius: 4px + code + word-wrap: normal + overflow: scroll + +code.highlighter-rouge + background-color: #EEE + padding: 0 5px + border-radius: 3px \ No newline at end of file diff --git a/docs/adapters/index.md b/docs/adapters/index.md new file mode 100644 index 00000000..f1060695 --- /dev/null +++ b/docs/adapters/index.md @@ -0,0 +1,43 @@ +--- +layout: page +title: "Adapters" +permalink: /adapters +hide: true +--- + +Adapters are what performs the HTTP Request in the background. +They receive a `Faraday::Request` and make the actual call, returning a `Faraday::Response`. +Faraday allows you to change the adapter at any time through the configuration block. + +{: .mt-60} +## Supported adapters + +Faraday supports these adapters out of the box: + +* [Net::HTTP][net_http] _(this is the default adapter)_ +* [Net::HTTP::Persistent][persistent] +* [Excon][excon] +* [Patron][patron] +* [EM-Synchrony][em-synchrony] +* [HTTPClient][httpclient] + +Adapters are slowly being moved into their own gems, or bundled with HTTP clients. +Please refer to their documentation for usage examples. +Here is the list of known external adapters: + +* [Typhoeus][typhoeus] +* [HTTP.rb][faraday-http] + +Faraday also includes a Rack adapter for hitting loaded Rack applications through +Rack::Test, and a [Test adapter][testing] for stubbing requests by hand. + + +[net_http]: ./net-http +[persistent]: ./net-http-persistent +[excon]: ./excon +[patron]: ./patron +[em-synchrony]: ./em-synchrony +[httpclient]: ./httpclient +[typhoeus]: https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb +[faraday-http]: https://github.com/lostisland/faraday-http +[testing]: ../testing \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index ad54d23f..c265ac20 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,4 +12,41 @@ hide: true Faraday is an HTTP client library that provides a common interface over many adapters (such as Net::HTTP) and embraces the concept of Rack middleware when processing the request/response cycle. -[Click me](http://www.google.com){: .btn} \ No newline at end of file +{: .text-center} +[ Fork on GitHub](https://github.com/lostisland/faraday){: .btn} +[ Chat with us](https://gitter.im/lostisland/faraday){: .btn} + +{: .mt-60} +## Getting Started + +Add this line to your application's Gemfile: + +```ruby +gem 'faraday' +``` + +And then execute: + +```bash +$ bundle +``` + +Or install it yourself as: + +```bash +$ gem install faraday +``` + +You can also install the [`faraday_middleware`](https://github.com/lostisland/faraday_middleware) +extension gem to access a collection of useful Faraday middleware. + +{: .mt-60} +## Usage + +Table of contents: + +* [Faraday API RubyDoc](http://www.rubydoc.info/gems/faraday) +* [Adapters](./adapters) +* [Middleware](./middleware) + * [Middleware Environment](./middleware/env) +* [Testing](./testing) diff --git a/docs/middleware/env.md b/docs/middleware/env.md index 28748365..da0b2c41 100644 --- a/docs/middleware/env.md +++ b/docs/middleware/env.md @@ -1,3 +1,8 @@ -# Faraday Env +--- +layout: page +title: "Faraday Env" +permalink: /middleware/env +hide: true +--- Faraday loves the environment. diff --git a/docs/middleware/README.md b/docs/middleware/index.md similarity index 68% rename from docs/middleware/README.md rename to docs/middleware/index.md index 495fadb7..a9317900 100644 --- a/docs/middleware/README.md +++ b/docs/middleware/index.md @@ -1,4 +1,9 @@ -# Middleware Usage +--- +layout: page +title: "Middleware Usage" +permalink: /middleware +hide: true +--- A `Faraday::Connection` uses a `Faraday::RackBuilder` to assemble a Rack-inspired middleware stack for making HTTP requests. Each middleware runs @@ -7,6 +12,8 @@ run, Faraday will return a `Faraday::Response` to the end user. ## Middleware Types +### Request + **Request middleware** can modify Request details before the Adapter runs. Most middleware set Header values or transform the request body based on the content type. @@ -17,8 +24,17 @@ base64 representation. multipart form request. * `UrlEncoded` converts a `Faraday::Request#body` hash of key/value pairs into a url- encoded request body. - -**Adapters** make requests. TBD - * `Retry` automatically retries requests that fail due to intermittent client or server errors (such as network hiccups). + + +### Response + +**Response middleware** receives the response from the adapter and can modify its details +before returning it. + +* [`Logger`][logger] logs both the request and the response body and headers. +* `RaiseError` checks the response HTTP code and raises an exception if not in the 2xx range. + + +[logger]: ./logger \ No newline at end of file diff --git a/docs/middleware/response/logger.md b/docs/middleware/response/logger.md new file mode 100644 index 00000000..e6d40d55 --- /dev/null +++ b/docs/middleware/response/logger.md @@ -0,0 +1,92 @@ +--- +layout: page +title: "Logger Middleware" +permalink: /middleware/logger +hide: true +--- + +The `Logger` middleware logs both the request and the response body and headers. +It is highly customizable and allows to mask confidential information if necessary. + +### Basic Usage + +```ruby +conn = Faraday.new(url: 'http://sushi.com') do |faraday| + faraday.response :logger # log requests and responses to $stdout +end + +conn.get +# => INFO -- request: GET http://sushi.com/ +# => DEBUG -- request: User-Agent: "Faraday v1.0.0" +# => INFO -- response: Status 301 +# => DEBUG -- response: date: "Sun, 19 May 2019 16:05:40 GMT" +``` + +### Customize the logger + +By default, the `Logger` middleware uses the Ruby `Logger.new($stdout)`. +You can customize it to use any logger you want by providing it when you add the middleware to the stack: + +```ruby +conn = Faraday.new(url: 'http://sushi.com') do |faraday| + faraday.response :logger, MyLogger.new($stdout) +end +``` + +### Include and exclude headers/bodies + +By default, the `logger` middleware logs only headers for security reasons, however, you can configure it +to log bodies as well, or disable headers logging if you need to. To do so, simply provide a configuration hash +when you add the middleware to the stack: + +```ruby +conn = Faraday.new(url: 'http://sushi.com') do |faraday| + faraday.response :logger, nil, { headers: true, bodies: true } +end +``` + +Please note this only works with the default formatter. + +### Filter sensitive information + +You can filter sensitive information from Faraday logs using a regex matcher: + +```ruby +conn = Faraday.new(url: 'http://sushi.com') do |faraday| + faraday.response :logger do | logger | + logger.filter(/(api_key=)(\w+)/,'\1[REMOVED]') + end +end + +conn.get('/', api_key: 'secret') +# => INFO -- request: GET http://sushi.com/?api_key=[REMOVED] +# => DEBUG -- request: User-Agent: "Faraday v1.0.0" +# => INFO -- response: Status 301 +# => DEBUG -- response: date: "Sun, 19 May 2019 16:12:36 GMT" +``` + +### Customize the formatter + +You can also provide a custom formatter to control how requests and responses are logged. +Any custom formatter MUST implement the `request` and `response` method, with one argument which +will be passed being the Faraday environment. +If you make your formatter inheriting from `Faraday::Response::Logger::Formatter`, +then the methods `debug`, `info`, `warn`, `error` and `fatal` are automatically delegated to the logger. + +```ruby +class MyFormatter < Faraday::Logging::Formatter + def request(env) + # Build a custom message using `env` + info('Request') { 'Sending Request' } + end + + def response(env) + # Build a custom message using `env` + info('Response') { 'Response Received' } + end +end + +conn = Faraday.new(url: 'http://sushi.com/api_key=s3cr3t') do |faraday| + faraday.response :logger, nil, formatter: MyFormatter +end +``` \ No newline at end of file diff --git a/docs/adapters/testing.md b/docs/testing.md similarity index 95% rename from docs/adapters/testing.md rename to docs/testing.md index ecaa4597..beb79934 100644 --- a/docs/adapters/testing.md +++ b/docs/testing.md @@ -1,4 +1,9 @@ -# Testing +--- +layout: page +title: "Testing" +permalink: /testing +hide: true +--- The built-in Faraday Test adapter lets you define stubbed HTTP requests. This can be used to mock out network services in an application's unit tests.