Class: Faraday::RackBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/faraday/rack_builder.rb

Overview

A Builder that processes requests into responses by passing through an inner middleware stack (heavily inspired by Rack).

Examples:

Faraday::Connection.new(url: 'http://httpbingo.org') do |builder|
  builder.request  :url_encoded  # Faraday::Request::UrlEncoded
  builder.adapter  :net_http     # Faraday::Adapter::NetHttp
end

Defined Under Namespace

Classes: Handler, StackLocked

Constant Summary collapse

NO_ARGUMENT =

Used to detect missing arguments

Object.new
LOCK_ERR = 
"can't modify middleware stack after making a request"
MISSING_ADAPTER_ERROR = 
"An attempt to run a request with a Faraday::Connection without adapter has been made.\n" \
"Please set Faraday.default_adapter or provide one when initializing the connection.\n" \
'For more info, check https://lostisland.github.io/faraday/usage/.'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(&block) ⇒ RackBuilder

Returns a new instance of RackBuilder.



66
67
68
69
70
 
# File 'lib/faraday/rack_builder.rb', line 66

def initialize(&block)
  @adapter = nil
  @handlers = []
  build(&block)
end

Instance Attribute Details

#handlers ⇒ Object

Returns the value of attribute handlers.



23
24
25
 
# File 'lib/faraday/rack_builder.rb', line 23

def handlers
  @handlers
end

Instance Method Details

#==(other) ⇒ Object 



184
185
186
187
188
 
# File 'lib/faraday/rack_builder.rb', line 184

def ==(other)
  other.is_a?(self.class) &&
    @handlers == other.handlers &&
    @adapter == other.adapter
end

#[](idx) ⇒ Object 



84
85
86
 
# File 'lib/faraday/rack_builder.rb', line 84

def [](idx)
  @handlers[idx]
end

#adapter(klass = NO_ARGUMENT, *args, **kwargs, &block) ⇒ Object 



115
116
117
118
119
120
 
# File 'lib/faraday/rack_builder.rb', line 115

def adapter(klass = NO_ARGUMENT, *args, **kwargs, &block)
  return @adapter if klass == NO_ARGUMENT || klass.nil?

  klass = Faraday::Adapter.lookup_middleware(klass) if klass.is_a?(Symbol)
  @adapter = self.class::Handler.new(klass, *args, **kwargs, &block)
end

#app ⇒ Object

The “rack app” wrapped in middleware. All requests are sent here.

The builder is responsible for creating the app object. After this, the builder gets locked to ensure no further modifications are made to the middleware stack.

Returns an object that responds to ‘call` and returns a Response.



168
169
170
171
172
173
174
 
# File 'lib/faraday/rack_builder.rb', line 168

def app
  @app ||= begin
    lock!
    ensure_adapter!
    to_app
  end
end

#build ⇒ Object 



78
79
80
81
82
 
# File 'lib/faraday/rack_builder.rb', line 78

def build
  raise_if_locked
  block_given? ? yield(self) : request(:url_encoded)
  adapter(Faraday.default_adapter, **Faraday.default_adapter_options) unless @adapter
end

#build_env(connection, request) ⇒ Object

ENV Keys :http_method - a symbolized request HTTP method (:get, :post) :body - the request body that will eventually be converted to a string. :url - URI instance for the current request. :status - HTTP response status code :request_headers - hash of HTTP Headers to be sent to the server :response_headers - Hash of HTTP headers from the server :parallel_manager - sent if the connection is in parallel mode :request - Hash of options for configuring the request.

:timeout      - open/read timeout Integer in seconds
:open_timeout - read timeout Integer in seconds
:proxy        - Hash of proxy options
  :uri        - Proxy Server URI
  :user       - Proxy server username
  :password   - Proxy server password

:ssl - Hash of options for configuring SSL requests.



206
207
208
209
210
211
212
213
214
215
 
# File 'lib/faraday/rack_builder.rb', line 206

def build_env(connection, request)
  exclusive_url = connection.build_exclusive_url(
    request.path, request.params,
    request.options.params_encoder
  )

  Env.new(request.http_method, request.body, exclusive_url,
          request.options, request.headers, connection.ssl,
          connection.parallel_manager)
end

#build_response(connection, request) ⇒ Faraday::Response

Processes a Request into a Response by passing it through this Builder’s middleware stack.

Parameters:

Returns:



157
158
159
 
# File 'lib/faraday/rack_builder.rb', line 157

def build_response(connection, request)
  app.call(build_env(connection, request))
end

#delete(handler) ⇒ Object 



145
146
147
148
 
# File 'lib/faraday/rack_builder.rb', line 145

def delete(handler)
  raise_if_locked
  @handlers.delete(handler)
end

#initialize_dup(original) ⇒ Object 



72
73
74
75
76
 
# File 'lib/faraday/rack_builder.rb', line 72

def initialize_dup(original)
  super
  @adapter = original.adapter
  @handlers = original.handlers.dup
end

#insert(index) ⇒ Object Also known as: insert_before

methods to push onto the various positions in the stack:



124
125
126
127
128
129
 
# File 'lib/faraday/rack_builder.rb', line 124

def insert(index, ...)
  raise_if_locked
  index = assert_index(index)
  handler = self.class::Handler.new(...)
  @handlers.insert(index, handler)
end

#insert_after(index) ⇒ Object 



133
134
135
136
 
# File 'lib/faraday/rack_builder.rb', line 133

def insert_after(index, ...)
  index = assert_index(index)
  insert(index + 1, ...)
end

#lock! ⇒ Object

Locks the middleware stack to ensure no further modifications are made.



89
90
91
 
# File 'lib/faraday/rack_builder.rb', line 89

def lock!
  @handlers.freeze
end

#locked? ⇒ Boolean

Returns:

  • (Boolean) 


93
94
95
 
# File 'lib/faraday/rack_builder.rb', line 93

def locked?
  @handlers.frozen?
end

#request(key) ⇒ Object 



107
108
109
 
# File 'lib/faraday/rack_builder.rb', line 107

def request(key, ...)
  use_symbol(Faraday::Request, key, ...)
end

#response ⇒ Object 



111
112
113
 
# File 'lib/faraday/rack_builder.rb', line 111

def response(...)
  use_symbol(Faraday::Response, ...)
end

#swap(index) ⇒ Object 



138
139
140
141
142
143
 
# File 'lib/faraday/rack_builder.rb', line 138

def swap(index, ...)
  raise_if_locked
  index = assert_index(index)
  @handlers.delete_at(index)
  insert(index, ...)
end

#to_app ⇒ Object 



176
177
178
179
180
181
182
 
# File 'lib/faraday/rack_builder.rb', line 176

def to_app
  # last added handler is the deepest and thus closest to the inner app
  # adapter is always the last one
  @handlers.reverse.inject(@adapter.build) do |app, handler|
    handler.build(app)
  end
end

#use(klass) ⇒ Object 



97
98
99
100
101
102
103
104
105
 
# File 'lib/faraday/rack_builder.rb', line 97

def use(klass, ...)
  if klass.is_a? Symbol
    use_symbol(Faraday::Middleware, klass, ...)
  else
    raise_if_locked
    raise_if_adapter(klass)
    @handlers << self.class::Handler.new(klass, ...)
  end
end