Class: Faraday::RackBuilder

Inherits:
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).

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

Defined Under Namespace

Classes: Handler, StackLocked

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(handlers = []) ⇒ RackBuilder

Returns a new instance of RackBuilder.



52
53
54
55
56
57
58
59
60
61
 
# File 'lib/faraday/rack_builder.rb', line 52

def initialize(handlers = [])
  @handlers = handlers
  if block_given?
    build(&Proc.new)
  elsif @handlers.empty?
    # default stack, if nothing else is configured
    self.request :url_encoded
    self.adapter Faraday.default_adapter
  end
end

Instance Attribute Details

#handlers ⇒ Object

Returns the value of attribute handlers.



10
11
12
 
# File 'lib/faraday/rack_builder.rb', line 10

def handlers
  @handlers
end

Instance Method Details

#==(other) ⇒ Object 



166
167
168
 
# File 'lib/faraday/rack_builder.rb', line 166

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

#[](idx) ⇒ Object 



69
70
71
 
# File 'lib/faraday/rack_builder.rb', line 69

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

#adapter(key, *args, &block) ⇒ Object 



99
100
101
 
# File 'lib/faraday/rack_builder.rb', line 99

def adapter(key, *args, &block)
  use_symbol(Faraday::Adapter, key, *args, &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.



149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/faraday/rack_builder.rb', line 149

def app
  @app ||= begin
    lock!
    to_app(lambda { |env|
      response = Response.new
      env.response = response
      response.finish(env) unless env.parallel?
      response
    })
  end
end

#build(options = {}) {|_self| ... } ⇒ Object

Yields:

  • (_self)

Yield Parameters:



63
64
65
66
67
 
# File 'lib/faraday/rack_builder.rb', line 63

def build(options = {})
  raise_if_locked
  @handlers.clear unless options[:keep]
  yield(self) if block_given?
end

#build_env(connection, request) ⇒ Object

ENV Keys :method - a symbolized request 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.



190
191
192
193
194
195
 
# File 'lib/faraday/rack_builder.rb', line 190

def build_env(connection, request)
  Env.new(request.method, request.body,
    connection.build_exclusive_url(request.path, request.params, request.options.params_encoder),
    request.options, request.headers, connection.ssl,
    connection.parallel_manager)
end

#build_response(connection, request) ⇒ Object

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

connection - Faraday::Connection request - Faraday::Request

Returns a Faraday::Response.



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

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

#delete(handler) ⇒ Object 



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

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

#dup ⇒ Object 



170
171
172
 
# File 'lib/faraday/rack_builder.rb', line 170

def dup
  self.class.new(@handlers.dup)
end

#insert(index, *args, &block) ⇒ Object Also known as: insert_before

methods to push onto the various positions in the stack:



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

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

#insert_after(index, *args, &block) ⇒ Object 



114
115
116
117
 
# File 'lib/faraday/rack_builder.rb', line 114

def insert_after(index, *args, &block)
  index = assert_index(index)
  insert(index + 1, *args, &block)
end

#lock! ⇒ Object

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



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

def lock!
  @handlers.freeze
end

#locked? ⇒ Boolean

Returns:

  • (Boolean) 


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

def locked?
  @handlers.frozen?
end

#request(key, *args, &block) ⇒ Object 



91
92
93
 
# File 'lib/faraday/rack_builder.rb', line 91

def request(key, *args, &block)
  use_symbol(Faraday::Request, key, *args, &block)
end

#response(key, *args, &block) ⇒ Object 



95
96
97
 
# File 'lib/faraday/rack_builder.rb', line 95

def response(key, *args, &block)
  use_symbol(Faraday::Response, key, *args, &block)
end

#swap(index, *args, &block) ⇒ Object 



119
120
121
122
123
124
 
# File 'lib/faraday/rack_builder.rb', line 119

def swap(index, *args, &block)
  raise_if_locked
  index = assert_index(index)
  @handlers.delete_at(index)
  insert(index, *args, &block)
end

#to_app(inner_app) ⇒ Object 



161
162
163
164
 
# File 'lib/faraday/rack_builder.rb', line 161

def to_app(inner_app)
  # last added handler is the deepest and thus closest to the inner app
  @handlers.reverse.inject(inner_app) { |app, handler| handler.build(app) }
end

#use(klass, *args, &block) ⇒ Object 



82
83
84
85
86
87
88
89
 
# File 'lib/faraday/rack_builder.rb', line 82

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