6 # Public: This is the main namespace for Faraday. You can either use it to
7 # create Faraday::Connection objects, or access it directly.
11 # Faraday.get "http://faraday.com"
13 # conn = Faraday.new "http://faraday.com"
20 # Public: Gets or sets the root path that Faraday is being loaded from.
21 # This is the root from where the libraries are auto-loaded from.
22 attr_accessor :root_path
24 # Public: Gets or sets the path that the Faraday libs are loaded from.
25 attr_accessor :lib_path
27 # Public: Gets or sets the Symbol key identifying a default Adapter to use
28 # for the default Faraday::Connection.
29 attr_reader :default_adapter
31 # Public: Sets the default Faraday::Connection for simple scripts that
32 # access the Faraday constant directly.
34 # Faraday.get "https://faraday.com"
35 attr_writer :default_connection
37 # Public: Sets the default options used when calling Faraday#new.
38 attr_writer :default_connection_options
40 # Public: Initializes a new Faraday::Connection.
42 # url - The optional String base URL to use as a prefix for all
43 # requests. Can also be the options Hash.
44 # options - The optional Hash used to configure this Faraday::Connection.
45 # Any of these values will be set on every request made, unless
46 # overridden for a specific request.
47 # :url - String base URL.
48 # :params - Hash of URI query unencoded key/value pairs.
49 # :headers - Hash of unencoded HTTP header key/value pairs.
50 # :request - Hash of request options.
51 # :ssl - Hash of SSL options.
52 # :proxy - Hash of Proxy options.
56 # Faraday.new 'http://faraday.com'
58 # # http://faraday.com?page=1
59 # Faraday.new 'http://faraday.com', :params => {:page => 1}
63 # Faraday.new :url => 'http://faraday.com',
64 # :params => {:page => 1}
66 # Returns a Faraday::Connection.
67 def new(url = nil, options = nil)
68 block = block_given? ? Proc.new : nil
69 options = options ? default_connection_options.merge(options) : default_connection_options.dup
70 Faraday::Connection.new(url, options, &block)
73 # Internal: Requires internal Faraday libraries.
75 # *libs - One or more relative String names to Faraday classes.
78 def require_libs(*libs)
80 require "#{lib_path}/#{lib}"
84 # Public: Updates default adapter while resetting
85 # #default_connection.
87 # Returns the new default_adapter.
88 def default_adapter=(adapter)
89 @default_connection = nil
90 @default_adapter = adapter
93 alias require_lib require_libs
96 # Internal: Proxies method calls on the Faraday constant to
97 # #default_connection.
98 def method_missing(name, *args, &block)
99 default_connection.send(name, *args, &block)
103 self.root_path = File.expand_path "..", __FILE__
104 self.lib_path = File.expand_path "../faraday", __FILE__
105 self.default_adapter = :net_http
107 # Gets the default connection used for simple scripts.
109 # Returns a Faraday::Connection, configured with the #default_adapter.
110 def self.default_connection
111 @default_connection ||= Connection.new
114 # Gets the default connection options used when calling Faraday#new.
116 # Returns a Faraday::ConnectionOptions.
117 def self.default_connection_options
118 @default_connection_options ||= ConnectionOptions.new
121 if (!defined?(RUBY_ENGINE) || "ruby" == RUBY_ENGINE) && RUBY_VERSION < '1.9'
123 require 'system_timer'
126 warn "Faraday: you may want to install system_timer for reliable timeouts"
130 unless const_defined? :Timer
135 # Public: Adds the ability for other modules to register and lookup
136 # middleware classes.
137 module MiddlewareRegistry
138 # Public: Register middleware class(es) on the current module.
140 # mapping - A Hash mapping Symbol keys to classes. Classes can be expressed
141 # as fully qualified constant, or a Proc that will be lazily
142 # called to return the former.
148 # # Middleware looked up by :foo returns Faraday::Whatever::Foo.
149 # register_middleware :foo => Foo
151 # # Middleware looked up by :bar returns Faraday::Whatever.const_get(:Bar)
152 # register_middleware :bar => :Bar
154 # # Middleware looked up by :baz requires 'baz' and returns Faraday::Whatever.const_get(:Baz)
155 # register_middleware :baz => [:Baz, 'baz']
160 def register_middleware(autoload_path = nil, mapping = nil)
162 mapping = autoload_path
166 @middleware_autoload_path = autoload_path if autoload_path
167 (@registered_middleware ||= {}).update(mapping)
171 # Public: Lookup middleware class with a registered Symbol shortcut.
173 # key - The Symbol key for the registered middleware.
179 # register_middleware :foo => Foo
183 # Faraday::Whatever.lookup_middleware(:foo)
184 # # => Faraday::Whatever::Foo
186 # Returns a middleware Class.
187 def lookup_middleware(key)
188 load_middleware(key) ||
189 raise(Faraday::Error.new("#{key.inspect} is not registered on #{self}"))
192 def middleware_mutex(&block)
193 @middleware_mutex ||= begin
197 @middleware_mutex.synchronize(&block)
200 def fetch_middleware(key)
201 defined?(@registered_middleware) && @registered_middleware[key]
204 def load_middleware(key)
205 value = fetch_middleware(key)
211 @registered_middleware[key] = const_get(value)
215 @registered_middleware[key] = value.call
220 if root = @middleware_autoload_path
221 path = "#{root}/#{path}"
224 @registered_middleware[key] = const
231 def self.const_missing(name)
232 if name.to_sym == :Builder
233 warn "Faraday::Builder is now Faraday::RackBuilder."
234 const_set name, RackBuilder
240 require_libs "utils", "options", "connection", "rack_builder", "parameters",
241 "middleware", "adapter", "request", "response", "upload_io", "error"
243 if !ENV["FARADAY_NO_AUTOLOAD"]
244 require_lib 'autoload'
248 # not pulling in active-support JUST for this method. And I love this method.
250 # The primary purpose of this method is to "tap into" a method chain,
251 # in order to perform operations on intermediate results within the chain.
255 # (1..10).tap { |x| puts "original: #{x.inspect}" }.to_a.
256 # tap { |x| puts "array: #{x.inspect}" }.
257 # select { |x| x%2 == 0 }.
258 # tap { |x| puts "evens: #{x.inspect}" }.
260 # tap { |x| puts "squares: #{x.inspect}" }
267 end unless Object.respond_to?(:tap)