Class: OAuth2::Response — Documentation by YARD 0.9.45

# Class: OAuth2::Response

Inherits:
  Object
  - Object
  - OAuth2::Response
  show all

Defined in:
  lib/oauth2/response.rb

## Overview

The Response class handles HTTP responses in the OAuth2 gem, providing methods
to access and parse response data in various formats.

Since:

- 1.0.0

## Constant Summary collapse

DEFAULT_OPTIONS =

Default configuration options for Response instances

Returns:

- (`Hash`) —

  The default options hash

Since:

- 1.0.0

      {
        parse: :automatic,
        snaky: true,
        snaky_hash_klass: SnakyHash::StringKeyed,
      }.freeze

@@parsers =

Storage for response body parser procedures

Returns:

- (`Hash<Symbol, Proc>`) —

  Hash of parser procs keyed by format symbol

Since:

- 1.0.0

      {
        query: ->(body) { Rack::Utils.parse_query(body) },
        text: ->(body) { body },
      }

@@content_types =

Maps content types to parser symbols

Returns:

- (`Hash<String, Symbol>`) —

  Hash of content types mapped to parser symbols

Since:

- 1.0.0

      {
        "application/x-www-form-urlencoded" => :query,
        "text/plain" => :text,
      }

## Instance Attribute Summary collapse

- #options ⇒ Hash

  The options hash for this instance.

- #response ⇒ Faraday::Response readonly

  The raw Faraday response object.

## Class Method Summary collapse

- .register_parser(key, mime_types) {|String| ... } ⇒ void

  Adds a new content type parser.

## Instance Method Summary collapse

- #body ⇒ String

  The HTTP response body.

- #content_type ⇒ String?

  Determines the content type of the response.

- #headers ⇒ Hash

  The HTTP response headers.

- #initialize(response, parse: :automatic, snaky: true, snaky_hash_klass: nil, **options) ⇒ OAuth2::Response constructor

  Initializes a Response instance.

- #parsed ⇒ Object, ...

  The parsed response body.

- #parser ⇒ Proc, ...

  Determines the parser to be used for the response body.

- #status ⇒ Integer

  The HTTP response status code.

## Constructor Details

### #initialize(response, parse: :automatic, snaky: true, snaky_hash_klass: nil, **options) ⇒ `OAuth2::Response`

Initializes a Response instance

Parameters:

- response (`Faraday::Response`) —

  The Faraday response instance

- parse (`Symbol`) (defaults to: `:automatic`) —

  (:automatic) How to parse the response body

- snaky (`Boolean`) (defaults to: `true`) —

  (true) Whether to convert parsed response to snake_case using SnakyHash

- snaky_hash_klass (`Class`, `nil`) (defaults to: `nil`) —

  (nil) Custom class for snake_case hash conversion

- options (`Hash`) —

  Additional options for the response

Options Hash (`**options`):

- :parse (`Symbol`) — default: `:automatic` —

  Parse strategy (:query, :json, or :automatic)

- :snaky (`Boolean`) — default: `true` —

  Enable/disable snake_case conversion

- :snaky_hash_klass (`Class`) — default: `SnakyHash::StringKeyed` —

  Class to use for hash conversion

Since:

- 1.0.0

    75
    76
    77
    78
    79
    80
    81
    82
    # File 'lib/oauth2/response.rb', line 75

    def initialize(response, parse: :automatic, snaky: true, snaky_hash_klass: nil, **options)
      @response = response
      @options = {
        parse: parse,
        snaky: snaky,
        snaky_hash_klass: snaky_hash_klass,
      }.merge(options)
    end

## Instance Attribute Details

### #options ⇒ `Hash`

Returns The options hash for this instance.

Returns:

- (`Hash`) —

  The options hash for this instance

Since:

- 1.0.0

    27
    28
    29
    # File 'lib/oauth2/response.rb', line 27

    def options
      @options
    end

### #response ⇒ `Faraday::Response` (readonly)

Returns The raw Faraday response object.

Returns:

- (`Faraday::Response`) —

  The raw Faraday response object

Since:

- 1.0.0

    24
    25
    26
    # File 'lib/oauth2/response.rb', line 24

    def response
      @response
    end

## Class Method Details

### .register_parser(key, mime_types) {|String| ... } ⇒ `void`

This method returns an undefined value.

Adds a new content type parser.

Parameters:

- key (`Symbol`) —

  A descriptive symbol key such as :json or :query

- mime_types (`Array<String>`, `String`) —

  One or more mime types to which this parser applies

Yields:

- (`String`) —

  Block that will be called to parse the response body

Yield Parameters:

- body (`String`) —

  The response body to parse

Since:

- 1.0.0

    55
    56
    57
    58
    59
    60
    61
    # File 'lib/oauth2/response.rb', line 55

    def register_parser(key, mime_types, &block)
      key = key.to_sym
      @@parsers[key] = block
      Array(mime_types).each do |mime_type|
        @@content_types[mime_type] = key
      end
    end

## Instance Method Details

### #body ⇒ `String`

The HTTP response body

Returns:

- (`String`) —

  The response body or empty string if nil

Since:

- 1.0.0

    101
    102
    103
    # File 'lib/oauth2/response.rb', line 101

    def body
      response.body || ""
    end

### #content_type ⇒ `String`?

Determines the content type of the response

Returns:

- (`String`, `nil`) —

  The content type or nil if headers are not present

Since:

- 1.0.0

    136
    137
    138
    139
    140
    141
    # File 'lib/oauth2/response.rb', line 136

    def content_type
      response_headers = response.headers
      return unless response_headers

      ((response_headers.values_at("content-type", "Content-Type").compact.first || "").split(";").first || "").strip.downcase
    end

### #headers ⇒ `Hash`

The HTTP response headers

Returns:

- (`Hash`) —

  The response headers

Since:

- 1.0.0

    87
    88
    89
    # File 'lib/oauth2/response.rb', line 87

    def headers
      response.headers
    end

### #parsed ⇒ `Object`, ...

The parsed response body

Returns:

- (`Object`, `SnakyHash::StringKeyed`) —

  The parsed response body

- (`nil`) —

  If no parser is available

Since:

- 1.0.0

    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    # File 'lib/oauth2/response.rb', line 109

    def parsed
      return @parsed if defined?(@parsed)

      response_parser = parser
      @parsed =
        if response_parser.respond_to?(:call)
          case response_parser.arity
          when 0
            response_parser.call
          when 1
            response_parser.call(body)
          else
            response_parser.call(body, response)
          end
        end

      if options[:snaky] && @parsed.is_a?(Hash)
        hash_klass = options[:snaky_hash_klass] || DEFAULT_OPTIONS[:snaky_hash_klass]
        @parsed = hash_klass[@parsed]
      end

      @parsed
    end

### #parser ⇒ `Proc`, ...

Note:

The parser can be supplied as the +:parse+ option in the form of a Proc
(or other Object responding to #call) or a Symbol. In the latter case,
the actual parser will be looked up in @@parsers by the supplied Symbol.

Note:

If no +:parse+ option is supplied, the lookup Symbol will be determined
by looking up #content_type in @@content_types.

Note:

If #parser is a Proc, it will be called with no arguments, just
#body, or #body and #response, depending on the Proc’s arity.

Determines the parser to be used for the response body

Returns:

- (`Proc`, `#call`) —

  The parser proc or callable object

- (`nil`) —

  If no suitable parser is found

Since:

- 1.0.0

    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    # File 'lib/oauth2/response.rb', line 157

    def parser
      return @parser if defined?(@parser)

      parse_option = options[:parse]
      @parser =
        if parse_option.respond_to?(:call)
          parse_option
        elsif parse_option
          @@parsers[parse_option.to_sym]
        end

      @parser ||= @@parsers[@@content_types[content_type]]
    end

### #status ⇒ `Integer`

The HTTP response status code

Returns:

- (`Integer`) —

  The response status code

Since:

- 1.0.0

    94
    95
    96
    # File 'lib/oauth2/response.rb', line 94

    def status
      response.status
    end