Module: Excon
- Defined in:
- lib/excon.rb,
lib/excon/error.rb,
lib/excon/utils.rb,
lib/excon/socket.rb,
lib/excon/headers.rb,
lib/excon/version.rb,
lib/excon/response.rb,
lib/excon/constants.rb,
lib/excon/connection.rb,
lib/excon/ssl_socket.rb,
lib/excon/test/server.rb,
lib/excon/unix_socket.rb,
lib/excon/pretty_printer.rb,
lib/excon/middlewares/base.rb,
lib/excon/middlewares/mock.rb,
lib/excon/middlewares/expects.rb,
lib/excon/middlewares/decompress.rb,
lib/excon/middlewares/idempotent.rb,
lib/excon/middlewares/escape_path.rb,
lib/excon/test/plugin/server/exec.rb,
lib/excon/test/plugin/server/puma.rb,
lib/excon/middlewares/instrumentor.rb,
lib/excon/test/plugin/server/unicorn.rb,
lib/excon/test/plugin/server/webrick.rb,
lib/excon/middlewares/capture_cookies.rb,
lib/excon/middlewares/response_parser.rb,
lib/excon/middlewares/redirect_follower.rb,
lib/excon/instrumentors/logging_instrumentor.rb,
lib/excon/instrumentors/standard_instrumentor.rb
Overview
Define defaults first so they will be available to other files
Defined Under Namespace
Modules: Errors, Middleware, Test, Utils Classes: Connection, Error, Headers, LoggingInstrumentor, PrettyPrinter, Response, SSLSocket, Socket, StandardInstrumentor, UnixSocket
Constant Summary collapse
- VERSION =
'1.2.2'
- CR_NL =
"\r\n"
- DEFAULT_CA_FILE =
File.(File.join(File.dirname(__FILE__), '..', '..', 'data', 'cacert.pem'))
- DEFAULT_CHUNK_SIZE =
1 megabyte
1_048_576
- CHUNK_SIZE =
avoid overwrite if somebody has redefined
DEFAULT_CHUNK_SIZE
- DEFAULT_REDIRECT_LIMIT =
10
- DEFAULT_RETRY_LIMIT =
4
- DEFAULT_RETRY_ERRORS =
[ Excon::Error::RequestTimeout, Excon::Error::Server, Excon::Error::Socket, Excon::Error::Timeout, Excon::Error::TooManyRequests ].freeze
- FORCE_ENC =
CR_NL.respond_to?(:force_encoding)
- HTTP_1_1 =
" HTTP/1.1\r\n"
- HTTP_VERBS =
%w[connect delete get head options patch post put trace].freeze
- HTTPS =
'https'
- NO_ENTITY =
[204, 205, 304].freeze
- REDACTED =
'REDACTED'
- UNIX =
'unix'
- USER_AGENT =
"excon/#{VERSION}"
- VERSIONS =
"#{USER_AGENT} (#{RUBY_PLATFORM}) ruby/#{RUBY_VERSION}"
- VALID_REQUEST_KEYS =
%i[ allow_unstubbed_requests body chunk_size debug_request debug_response dns_timeouts headers instrumentor logger method middlewares password path persistent pipeline query read_timeout request_block resolv_resolver response_block stubs timeout user versions write_timeout ].freeze
- VALID_CONNECTION_KEYS =
VALID_REQUEST_KEYS + %i[ ciphers client_key client_key_data client_key_pass client_cert client_cert_data client_chain client_chain_data certificate certificate_path disable_proxy private_key private_key_path connect_timeout family keepalive host hostname include_default_port omit_default_port nonblock reuseaddr port proxy scheme socket ssl_ca_file ssl_ca_path ssl_cert_store ssl_verify_callback ssl_verify_peer ssl_verify_peer_host ssl_verify_hostname ssl_version ssl_min_version ssl_max_version ssl_security_level ssl_proxy_headers ssl_uri_schemes tcp_nodelay thread_safe_sockets uri_parser ]
- DEPRECATED_VALID_REQUEST_KEYS =
{ captures: 'Mock', expects: 'Expects', idempotent: 'Idempotent', instrumentor_name: 'Instrumentor', mock: 'Mock', retries_remaining: 'Idempotent', # referenced in Instrumentor, but only relevant with Idempotent retry_errors: 'Idempotent', retry_interval: 'Idempotent', retry_limit: 'Idempotent' # referenced in Instrumentor, but only relevant with Idempotent }.freeze
- DEFAULTS =
these come last as they rely on the above
{ chunk_size: CHUNK_SIZE || DEFAULT_CHUNK_SIZE, # see https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28default.29 # list provided then had DES related things sorted to the end ciphers: 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:DES-CBC3-SHA:!DSS', connect_timeout: 60, debug_request: false, debug_response: false, dns_timeouts: nil, # nil allows Resolv::DNS default timeout value (see https://ruby-doc.org/3.2.2/stdlibs/resolv/Resolv/DNS.html#method-i-timeouts-3D) headers: { 'User-Agent' => USER_AGENT, 'Accept' => '*/*' }, idempotent: false, instrumentor_name: 'excon', middlewares: [ Excon::Middleware::ResponseParser, Excon::Middleware::Decompress, Excon::Middleware::Expects, Excon::Middleware::Idempotent, Excon::Middleware::Instrumentor, Excon::Middleware::Mock ], mock: false, include_default_port: false, nonblock: true, omit_default_port: true, persistent: false, read_timeout: 60, resolv_resolver: nil, retry_errors: DEFAULT_RETRY_ERRORS, retry_limit: DEFAULT_RETRY_LIMIT, ssl_verify_peer: true, ssl_uri_schemes: [HTTPS], stubs: :global, tcp_nodelay: false, thread_safe_sockets: true, timeout: nil, uri_parser: URI, versions: VERSIONS, write_timeout: 60 }
Class Attribute Summary collapse
-
.defaults ⇒ Hash
Defaults for Excon connections.
Class Method Summary collapse
- .display_warning(warning) ⇒ Object
-
.mock ⇒ Object
Status of mocking.
-
.mock=(new_mock) ⇒ Object
Change the status of mocking false is the default and works as expected true returns a value from stubs or raises.
-
.new(url, params = {}) ⇒ Connection
Initializes a new keep-alive session for a given remote host.
- .set_raise_on_warnings!(should_raise) ⇒ Object
-
.ssl_ca_path ⇒ String
The filesystem path to the SSL Certificate Authority.
-
.ssl_ca_path=(new_ssl_ca_path) ⇒ String
Change path to the SSL Certificate Authority.
-
.ssl_verify_peer ⇒ true, false
Whether or not to verify the peer’s SSL certificate / chain.
-
.ssl_verify_peer=(new_ssl_verify_peer) ⇒ Object
Change the status of ssl peer verification.
-
.stub(request_params = {}, response_params = nil, &block) ⇒ Object
push an additional stub onto the list to check for mock requests.
-
.stub_for(request_params = {}) ⇒ Hash<Symbol, >
get a stub matching params or nil.
-
.stubs ⇒ Object
get a list of defined stubs.
-
.unstub(request_params = {}) ⇒ Hash<Symbol, >
remove first/oldest stub matching request_params or nil if none match.
Class Attribute Details
.defaults ⇒ Hash
Returns defaults for Excon connections.
50 51 52 |
# File 'lib/excon.rb', line 50 def defaults @defaults ||= DEFAULTS end |
Class Method Details
.display_warning(warning) ⇒ Object
58 59 60 61 62 63 64 65 |
# File 'lib/excon.rb', line 58 def display_warning(warning) # Show warning if $VERBOSE or ENV['EXCON_DEBUG'] is set ($VERBOSE || ENV['EXCON_DEBUG']) && Warning.warn("[excon][WARNING] #{warning}\n#{caller.join("\n")}") return unless @raise_on_warnings raise(Error::Warning, warning) end |
.mock ⇒ Object
Status of mocking
72 73 74 75 |
# File 'lib/excon.rb', line 72 def mock display_warning('Excon#mock is deprecated, use Excon.defaults[:mock] instead.') self.defaults[:mock] end |
.mock=(new_mock) ⇒ Object
Change the status of mocking false is the default and works as expected true returns a value from stubs or raises
80 81 82 83 |
# File 'lib/excon.rb', line 80 def mock=(new_mock) display_warning('Excon#mock is deprecated, use Excon.defaults[:mock]= instead.') self.defaults[:mock] = new_mock end |
.new(url, params = {}) ⇒ Connection
Initializes a new keep-alive session for a given remote host
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 |
# File 'lib/excon.rb', line 116 def new(url, params = {}) uri_parser = params[:uri_parser] || defaults[:uri_parser] uri = uri_parser.parse(url) params[:path] && uri_parser.parse(params[:path]) raise(ArgumentError, "Invalid URI: #{uri}") unless uri.scheme params = { host: uri.host, hostname: uri.hostname, path: uri.path, port: uri.port, query: uri.query, scheme: uri.scheme }.merge(params) uri.password && params[:password] = Utils.unescape_uri(uri.password) uri.user && params[:user] = Utils.unescape_uri(uri.user) Excon::Connection.new(params) end |
.set_raise_on_warnings!(should_raise) ⇒ Object
67 68 69 |
# File 'lib/excon.rb', line 67 def set_raise_on_warnings!(should_raise) @raise_on_warnings = should_raise end |
.ssl_ca_path ⇒ String
Returns The filesystem path to the SSL Certificate Authority.
86 87 88 89 |
# File 'lib/excon.rb', line 86 def ssl_ca_path display_warning('Excon#ssl_ca_path is deprecated, use Excon.defaults[:ssl_ca_path] instead.') self.defaults[:ssl_ca_path] end |
.ssl_ca_path=(new_ssl_ca_path) ⇒ String
Change path to the SSL Certificate Authority
93 94 95 96 |
# File 'lib/excon.rb', line 93 def ssl_ca_path=(new_ssl_ca_path) display_warning('Excon#ssl_ca_path= is deprecated, use Excon.defaults[:ssl_ca_path]= instead.') self.defaults[:ssl_ca_path] = new_ssl_ca_path end |
.ssl_verify_peer ⇒ true, false
Returns Whether or not to verify the peer’s SSL certificate / chain.
99 100 101 102 |
# File 'lib/excon.rb', line 99 def ssl_verify_peer display_warning('Excon#ssl_verify_peer is deprecated, use Excon.defaults[:ssl_verify_peer] instead.') self.defaults[:ssl_verify_peer] end |
.ssl_verify_peer=(new_ssl_verify_peer) ⇒ Object
Change the status of ssl peer verification
106 107 108 109 |
# File 'lib/excon.rb', line 106 def ssl_verify_peer=(new_ssl_verify_peer) display_warning('Excon#ssl_verify_peer= is deprecated, use Excon.defaults[:ssl_verify_peer]= instead.') self.defaults[:ssl_verify_peer] = new_ssl_verify_peer end |
.stub(request_params = {}, response_params = nil, &block) ⇒ Object
push an additional stub onto the list to check for mock requests
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 |
# File 'lib/excon.rb', line 138 def stub(request_params = {}, response_params = nil, &block) if (method = request_params.delete(:method)) request_params[:method] = method.to_s.downcase.to_sym end if (url = request_params.delete(:url)) uri = URI.parse(url) request_params = { host: uri.host, path: uri.path.empty? ? '/' : uri.path, port: uri.port, query: uri.query, scheme: uri.scheme }.merge!(request_params) if uri.user || uri.password request_params[:headers] ||= {} user = Utils.unescape_form(uri.user.to_s) pass = Utils.unescape_form(uri.password.to_s) request_params[:headers]['Authorization'] ||= 'Basic ' + ["#{user}:#{pass}"].pack('m').delete(Excon::CR_NL) end end if request_params.key?(:headers) headers = Excon::Headers.new request_params[:headers].each do |key, value| headers[key] = value end request_params[:headers] = headers end request_params[:query] = Utils.query_string(request_params)[1...] if request_params.key?(:query) if block_given? raise(ArgumentError, 'stub requires either response_params OR a block') if response_params stub = [request_params, block] elsif response_params stub = [request_params, response_params] else raise(ArgumentError, 'stub requires either response_params OR a block') end stubs.unshift(stub) stub end |
.stub_for(request_params = {}) ⇒ Hash<Symbol, >
get a stub matching params or nil
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 |
# File 'lib/excon.rb', line 182 def stub_for(request_params={}) if (method = request_params.delete(:method)) request_params[:method] = method.to_s.downcase.to_sym end request_params[:query] = Utils.query_string(request_params)[1...] if request_params.key?(:query) Excon.stubs.each do |stub, response_params| captures = { headers: {} } headers_match = !stub.key?(:headers) || stub[:headers].keys.all? do |key| case value = stub[:headers][key] when Regexp case request_params[:headers][key] when String if (match = value.match(request_params[:headers][key])) captures[:headers][key] = match.captures end when Regexp # for unstub on regex params match = (value == request_params[:headers][key]) end match else value == request_params[:headers][key] end end non_headers_match = (stub.keys - [:headers]).all? do |key| case value = stub[key] when Regexp case request_params[key] when String if (match = value.match(request_params[key])) captures[key] = match.captures end when Regexp # for unstub on regex params match = (value == request_params[key]) end match else value == request_params[key] end end if headers_match && non_headers_match request_params[:captures] = captures return [stub, response_params] end end nil end |