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 |
# 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? 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.
136 137 138 139 140 141 142 143 144 145 146 |
# File 'lib/faraday/connection.rb', line 136 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
184 185 186 187 188 189 190 191 192 |
# File 'lib/faraday/connection.rb', line 184 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.
82 83 84 85 86 87 88 89 90 91 92 |
# File 'lib/faraday/connection.rb', line 82 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
125 126 127 128 |
# File 'lib/faraday/connection.rb', line 125 def (type, token) headers[Faraday::Request::Authorization::KEY] = Faraday::Request::Authorization.header(type, token) end |
#basic_auth(login, pass) ⇒ Object
115 116 117 118 |
# File 'lib/faraday/connection.rb', line 115 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.
288 289 290 291 292 293 294 295 296 297 298 299 |
# File 'lib/faraday/connection.rb', line 288 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.
251 252 253 254 255 256 257 258 |
# File 'lib/faraday/connection.rb', line 251 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
271 272 273 274 275 276 277 278 279 |
# File 'lib/faraday/connection.rb', line 271 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
301 302 303 |
# File 'lib/faraday/connection.rb', line 301 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
152 153 154 155 156 157 158 159 160 161 162 |
# File 'lib/faraday/connection.rb', line 152 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
148 149 150 |
# File 'lib/faraday/connection.rb', line 148 def in_parallel? !!@parallel_manager end |
#path_prefix=(value) ⇒ Object
Ensures that the path prefix always has a leading but no trailing slash
224 225 226 227 228 229 230 |
# File 'lib/faraday/connection.rb', line 224 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
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 |
# File 'lib/faraday/connection.rb', line 164 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
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 |
# File 'lib/faraday/connection.rb', line 232 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
120 121 122 123 |
# File 'lib/faraday/connection.rb', line 120 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.
306 307 308 309 310 |
# File 'lib/faraday/connection.rb', line 306 def with_uri_credentials(uri) if uri.user and uri.password yield Utils.unescape(uri.user), Utils.unescape(uri.password) end end |