Class: Faraday::Connection
- Extended by:
- Forwardable
- Defined in:
- lib/faraday/connection.rb
Constant Summary collapse
- METHODS =
Set.new [:get, :post, :put, :delete, :head, :patch, :options]
- METHODS_WITH_BODIES =
Set.new [:post, :put, :patch, :options]
Instance Attribute Summary collapse
-
#builder ⇒ Object
readonly
Returns the value of attribute builder.
-
#default_parallel_manager ⇒ Object
Internal: Traverse the middleware stack in search of a parallel-capable adapter.
-
#headers ⇒ Object
Returns the value of attribute headers.
-
#options ⇒ Object
readonly
Returns the value of attribute options.
-
#parallel_manager ⇒ Object
readonly
Returns the value of attribute parallel_manager.
-
#params ⇒ Object
Returns the value of attribute params.
-
#ssl ⇒ Object
readonly
Returns the value of attribute ssl.
-
#url_prefix ⇒ Object
Returns the value of attribute url_prefix.
Class Method Summary collapse
-
.URI(url) ⇒ Object
normalize URI() behavior across Ruby versions.
Instance Method Summary collapse
-
#app ⇒ Object
The “rack app” wrapped in middleware.
- #authorization(type, token) ⇒ Object
- #basic_auth(login, pass) ⇒ Object
-
#build_exclusive_url(url, params = nil) ⇒ Object
Internal: Build an absolute URL based on url_prefix.
-
#build_request(method) ⇒ Object
Internal: Creates and configures the request object.
-
#build_url(url, extra_params = nil) ⇒ Object
Takes a relative url for a request and combines it with the defaults set on the connection instance.
- #dup ⇒ Object
- #in_parallel(manager = nil) ⇒ Object
- #in_parallel? ⇒ Boolean
-
#initialize(url = nil, options = {}) {|_self| ... } ⇒ Connection
constructor
Public: Initializes a new Faraday::Connection.
-
#path_prefix=(value) ⇒ Object
Ensures that the path prefix always has a leading but no trailing slash.
- #proxy(arg = nil) ⇒ Object
- #run_request(method, url, body, headers) ⇒ Object
- #token_auth(token, options = nil) ⇒ Object
-
#with_uri_credentials(uri) ⇒ Object
Internal: Yields username and password extracted from a URI if they both exist.
Constructor Details
#initialize(url = nil, options = {}) {|_self| ... } ⇒ Connection
Public: Initializes a new Faraday::Connection.
url - URI or String base URL to use as a prefix for all
requests (optional).
options - Hash of settings that will be applied to every request made
from this Connection (default: {}).
:url - URI or String base URL (default: "http:/").
:params - Hash of URI query unencoded key/value pairs.
:headers - Hash of unencoded HTTP header key/value pairs.
:request - Hash of request options.
:ssl - Hash of SSL options.
:proxy - URI, String or Hash of HTTP proxy options
(default: "http_proxy" environment variable).
:uri - URI or String
:user - String (optional)
:password - String (optional)
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 |
# File 'lib/faraday/connection.rb', line 32 def initialize(url = nil, = {}) if url.is_a?(Hash) = url url = [:url] end @headers = Utils::Headers.new @params = Utils::ParamsHash.new @options = [:request] || {} @ssl = [:ssl] || {} @parallel_manager = nil @default_parallel_manager = [:parallel_manager] @builder = [:builder] || begin # pass an empty block to Builder so it doesn't assume default middleware block = block_given?? Proc.new {|b| } : nil Builder.new(&block) end self.url_prefix = url || 'http:/' @params.update [:params] if [:params] @headers.update [:headers] if [:headers] @proxy = nil proxy(.fetch(:proxy) { ENV['http_proxy'] }) yield self if block_given? @headers[:user_agent] ||= "Faraday v#{VERSION}" end |
Instance Attribute Details
#builder ⇒ Object (readonly)
Returns the value of attribute builder.
13 14 15 |
# File 'lib/faraday/connection.rb', line 13 def builder @builder end |
#default_parallel_manager ⇒ Object
Internal: Traverse the middleware stack in search of a parallel-capable adapter.
Yields in case of not found.
Returns a parallel manager or nil if not found.
138 139 140 141 142 143 144 145 146 147 148 |
# File 'lib/faraday/connection.rb', line 138 def default_parallel_manager @default_parallel_manager ||= begin handler = @builder.handlers.detect do |h| h.klass.respond_to?(:supports_parallel?) and h.klass.supports_parallel? end if handler then handler.klass.setup_parallel_manager elsif block_given? then yield end end end |
#headers ⇒ Object
Returns the value of attribute headers.
13 14 15 |
# File 'lib/faraday/connection.rb', line 13 def headers @headers end |
#options ⇒ Object (readonly)
Returns the value of attribute options.
13 14 15 |
# File 'lib/faraday/connection.rb', line 13 def @options end |
#parallel_manager ⇒ Object (readonly)
Returns the value of attribute parallel_manager.
13 14 15 |
# File 'lib/faraday/connection.rb', line 13 def parallel_manager @parallel_manager end |
#params ⇒ Object
Returns the value of attribute params.
13 14 15 |
# File 'lib/faraday/connection.rb', line 13 def params @params end |
#ssl ⇒ Object (readonly)
Returns the value of attribute ssl.
13 14 15 |
# File 'lib/faraday/connection.rb', line 13 def ssl @ssl end |
#url_prefix ⇒ Object
Returns the value of attribute url_prefix.
13 14 15 |
# File 'lib/faraday/connection.rb', line 13 def url_prefix @url_prefix end |
Class Method Details
.URI(url) ⇒ Object
normalize URI() behavior across Ruby versions
186 187 188 189 190 191 192 193 194 |
# File 'lib/faraday/connection.rb', line 186 def self.URI(url) if url.respond_to?(:host) url elsif url.respond_to?(:to_str) Kernel.URI(url) else raise ArgumentError, "bad argument (expected URI object or URI string)" end end |
Instance Method Details
#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.
84 85 86 87 88 89 90 91 92 93 94 |
# File 'lib/faraday/connection.rb', line 84 def app @app ||= begin builder.lock! builder.to_app(lambda { |env| # the inner app that creates and returns the Response object response = Response.new response.finish(env) unless env[:parallel_manager] env[:response] = response }) end end |
#authorization(type, token) ⇒ Object
127 128 129 130 |
# File 'lib/faraday/connection.rb', line 127 def (type, token) headers[Faraday::Request::Authorization::KEY] = Faraday::Request::Authorization.header(type, token) end |
#basic_auth(login, pass) ⇒ Object
117 118 119 120 |
# File 'lib/faraday/connection.rb', line 117 def basic_auth(login, pass) headers[Faraday::Request::Authorization::KEY] = Faraday::Request::BasicAuthentication.header(login, pass) end |
#build_exclusive_url(url, params = nil) ⇒ Object
Internal: Build an absolute URL based on url_prefix.
url - A String or URI-like object params - A Faraday::Utils::ParamsHash to replace the query values
of the resulting url (default: nil).
Returns the resulting URI instance.
290 291 292 293 294 295 296 297 298 299 300 301 |
# File 'lib/faraday/connection.rb', line 290 def build_exclusive_url(url, params = nil) url = nil if url.respond_to?(:empty?) and url.empty? base = url_prefix if url and base.path and base.path !~ /\/$/ base = base.dup base.path = base.path + '/' # ensure trailing slash end uri = url ? base + url : base uri.query = params.to_query if params uri.query = nil if uri.query and uri.query.empty? uri end |
#build_request(method) ⇒ Object
Internal: Creates and configures the request object.
Returns the new Request.
253 254 255 256 257 258 259 260 |
# File 'lib/faraday/connection.rb', line 253 def build_request(method) Request.create(method) do |req| req.params = self.params.dup req.headers = self.headers.dup req. = self..merge(:proxy => self.proxy) yield req if block_given? end end |
#build_url(url, extra_params = nil) ⇒ Object
Takes a relative url for a request and combines it with the defaults set on the connection instance.
conn = Faraday::Connection.new { ... }
conn.url_prefix = "https://sushi.com/api?token=abc"
conn.scheme # => https
conn.path_prefix # => "/api"
conn.build_url("nigiri?page=2") # => https://sushi.com/api/nigiri?token=abc&page=2
conn.build_url("nigiri", :page => 2) # => https://sushi.com/api/nigiri?token=abc&page=2
273 274 275 276 277 278 279 280 281 |
# File 'lib/faraday/connection.rb', line 273 def build_url(url, extra_params = nil) uri = build_exclusive_url(url) query_values = self.params.dup.merge_query(uri.query) query_values.update extra_params if extra_params uri.query = query_values.empty? ? nil : query_values.to_query uri end |
#dup ⇒ Object
303 304 305 |
# File 'lib/faraday/connection.rb', line 303 def dup self.class.new(build_url(''), :headers => headers.dup, :params => params.dup, :builder => builder.dup, :ssl => ssl.dup) end |
#in_parallel(manager = nil) ⇒ Object
154 155 156 157 158 159 160 161 162 163 164 |
# File 'lib/faraday/connection.rb', line 154 def in_parallel(manager = nil) @parallel_manager = manager || default_parallel_manager { warn "Warning: `in_parallel` called but no parallel-capable adapter on Faraday stack" warn caller[2,10].join("\n") nil } yield @parallel_manager && @parallel_manager.run ensure @parallel_manager = nil end |
#in_parallel? ⇒ Boolean
150 151 152 |
# File 'lib/faraday/connection.rb', line 150 def in_parallel? !!@parallel_manager end |
#path_prefix=(value) ⇒ Object
Ensures that the path prefix always has a leading but no trailing slash
226 227 228 229 230 231 232 |
# File 'lib/faraday/connection.rb', line 226 def path_prefix=(value) url_prefix.path = if value value = value.chomp '/' value = '/' + value unless value[0,1] == '/' value end end |
#proxy(arg = nil) ⇒ Object
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 |
# File 'lib/faraday/connection.rb', line 166 def proxy(arg = nil) return @proxy if arg.nil? @proxy = if arg.is_a? Hash uri = self.class.URI arg.fetch(:uri) { raise ArgumentError, "missing :uri" } arg.merge :uri => uri else uri = self.class.URI(arg) {:uri => uri} end with_uri_credentials(uri) do |user, password| @proxy[:user] ||= user @proxy[:password] ||= password end @proxy end |
#run_request(method, url, body, headers) ⇒ Object
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 |
# File 'lib/faraday/connection.rb', line 234 def run_request(method, url, body, headers) if !METHODS.include?(method) raise ArgumentError, "unknown http method: #{method}" end request = build_request(method) do |req| req.url(url) if url req.headers.update(headers) if headers req.body = body if body yield req if block_given? end env = request.to_env(self) self.app.call(env) end |
#token_auth(token, options = nil) ⇒ Object
122 123 124 125 |
# File 'lib/faraday/connection.rb', line 122 def token_auth(token, = nil) headers[Faraday::Request::Authorization::KEY] = Faraday::Request::TokenAuthentication.header(token, ) end |
#with_uri_credentials(uri) ⇒ Object
Internal: Yields username and password extracted from a URI if they both exist.
308 309 310 311 312 |
# File 'lib/faraday/connection.rb', line 308 def with_uri_credentials(uri) if uri.user and uri.password yield Utils.unescape(uri.user), Utils.unescape(uri.password) end end |