diff --git a/CHEATSHEET.md b/CHEATSHEET.md index de9a8161..20c78717 100644 --- a/CHEATSHEET.md +++ b/CHEATSHEET.md @@ -56,13 +56,13 @@ HTTPX.delete("https://myapi.com/users/1") require "httpx" # Basic Auth -response = HTTPX.plugin(:basic_authentication).basic_authentication("username", "password").get("https://google.com") +response = HTTPX.plugin(:basic_auth).basic_auth("username", "password").get("https://google.com") # Digest Auth -response = HTTPX.plugin(:digest_authentication).digest_authentication("username", "password").get("https://google.com") +response = HTTPX.plugin(:digest_auth).digest_auth("username", "password").get("https://google.com") # Bearer Token Auth -response = HTTPX.plugin(:authentication).authentication("eyrandomtoken").get("https://google.com") +response = HTTPX.plugin(:auth).authorization("eyrandomtoken").get("https://google.com") ``` diff --git a/README.md b/README.md index b4a16230..ef7fc3b7 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ And also: * Compression (gzip, deflate, brotli) * Streaming Requests -* Authentication (Basic Auth, Digest Auth, NTLM) +* Auth (Basic Auth, Digest Auth, NTLM) * Expect 100-continue * Multipart Requests * Advanced Cookie handling diff --git a/doc/release_notes/1_0_0.md b/doc/release_notes/1_0_0.md index 6d29ad58..434b9f10 100644 --- a/doc/release_notes/1_0_0.md +++ b/doc/release_notes/1_0_0.md @@ -8,6 +8,18 @@ * `:read_timeout` and `:write_timeout` are now set to 60 seconds by default, and preferred over `:operation_timeout`; * the exception being in the `:stream` plugin, as the response is theoretically endless (so `:read_timeout` is unset). +### plugins + +* `:authentication` plugin becomes `:auth` + * `.authentication` helper becomes `.authorization` +* `:basic_authentication` plugin becomes `:basic_auth` + * `:basic_authentication` helper is removed +* `:digest_authentication` plugin becomes `:digest_auth` + * `:digest_authentication` helper is removed +* `:ntlm_authentication` plugin becomes `:ntlm_auth` + * `:ntlm_authentication` helper is removed +* OAuth plugin: `:oauth_authentication` helper is rename to `:oauth_auth` + ### Support removed for deprecated APIs * The deprecated `HTTPX::Client` constant lookup has been removed (use `HTTPX::Session` instead). diff --git a/lib/httpx/plugins/auth.rb b/lib/httpx/plugins/auth.rb new file mode 100644 index 00000000..2d56556d --- /dev/null +++ b/lib/httpx/plugins/auth.rb @@ -0,0 +1,25 @@ +# frozen_string_literal: true + +module HTTPX + module Plugins + # + # This plugin adds a shim +authorization+ method to the session, which will fill + # the HTTP Authorization header, and another, +bearer_auth+, which fill the "Bearer " prefix + # in its value. + # + # https://gitlab.com/os85/httpx/wikis/Auth#authorization + # + module Auth + module InstanceMethods + def authorization(token) + with(headers: { "authorization" => token }) + end + + def bearer_auth(token) + authorization("Bearer #{token}") + end + end + end + register_plugin :auth, Auth + end +end diff --git a/lib/httpx/plugins/authentication/basic.rb b/lib/httpx/plugins/auth/basic.rb similarity index 100% rename from lib/httpx/plugins/authentication/basic.rb rename to lib/httpx/plugins/auth/basic.rb diff --git a/lib/httpx/plugins/authentication/digest.rb b/lib/httpx/plugins/auth/digest.rb similarity index 100% rename from lib/httpx/plugins/authentication/digest.rb rename to lib/httpx/plugins/auth/digest.rb diff --git a/lib/httpx/plugins/authentication/ntlm.rb b/lib/httpx/plugins/auth/ntlm.rb similarity index 100% rename from lib/httpx/plugins/authentication/ntlm.rb rename to lib/httpx/plugins/auth/ntlm.rb diff --git a/lib/httpx/plugins/authentication/socks5.rb b/lib/httpx/plugins/auth/socks5.rb similarity index 100% rename from lib/httpx/plugins/authentication/socks5.rb rename to lib/httpx/plugins/auth/socks5.rb diff --git a/lib/httpx/plugins/authentication.rb b/lib/httpx/plugins/authentication.rb deleted file mode 100644 index 3c41ac13..00000000 --- a/lib/httpx/plugins/authentication.rb +++ /dev/null @@ -1,24 +0,0 @@ -# frozen_string_literal: true - -module HTTPX - module Plugins - # - # This plugin adds a shim +authentication+ method to the session, which will fill - # the HTTP Authorization header. - # - # https://gitlab.com/os85/httpx/wikis/Authentication#authentication - # - module Authentication - module InstanceMethods - def authentication(token) - with(headers: { "authorization" => token }) - end - - def bearer_auth(token) - authentication("Bearer #{token}") - end - end - end - register_plugin :authentication, Authentication - end -end diff --git a/lib/httpx/plugins/basic_authentication.rb b/lib/httpx/plugins/basic_auth.rb similarity index 54% rename from lib/httpx/plugins/basic_authentication.rb rename to lib/httpx/plugins/basic_auth.rb index a921bc5a..d680e609 100644 --- a/lib/httpx/plugins/basic_authentication.rb +++ b/lib/httpx/plugins/basic_auth.rb @@ -5,26 +5,25 @@ module HTTPX # # This plugin adds helper methods to implement HTTP Basic Auth (https://tools.ietf.org/html/rfc7617) # - # https://gitlab.com/os85/httpx/wikis/Authentication#basic-authentication + # https://gitlab.com/os85/httpx/wikis/Authorization#basic-auth # module BasicAuth class << self def load_dependencies(_klass) - require_relative "authentication/basic" + require_relative "auth/basic" end def configure(klass) - klass.plugin(:authentication) + klass.plugin(:auth) end end module InstanceMethods def basic_auth(user, password) - authentication(Authentication::Basic.new(user, password).authenticate) + authorization(Authentication::Basic.new(user, password).authenticate) end - alias_method :basic_authentication, :basic_auth end end - register_plugin :basic_authentication, BasicAuth + register_plugin :basic_auth, BasicAuth end end diff --git a/lib/httpx/plugins/digest_authentication.rb b/lib/httpx/plugins/digest_auth.rb similarity index 83% rename from lib/httpx/plugins/digest_authentication.rb rename to lib/httpx/plugins/digest_auth.rb index d78662d8..713fba52 100644 --- a/lib/httpx/plugins/digest_authentication.rb +++ b/lib/httpx/plugins/digest_auth.rb @@ -5,7 +5,7 @@ module HTTPX # # This plugin adds helper methods to implement HTTP Digest Auth (https://tools.ietf.org/html/rfc7616) # - # https://gitlab.com/os85/httpx/wikis/Authentication#authentication + # https://gitlab.com/os85/httpx/wikis/Authorization#digest-auth # module DigestAuth DigestError = Class.new(Error) @@ -16,7 +16,7 @@ module HTTPX end def load_dependencies(*) - require_relative "authentication/digest" + require_relative "auth/digest" end end @@ -29,11 +29,11 @@ module HTTPX end module InstanceMethods - def digest_authentication(user, password, hashed: false) + def digest_auth(user, password, hashed: false) with(digest: Authentication::Digest.new(user, password, hashed: hashed)) end - alias_method :digest_auth, :digest_authentication + private def send_requests(*requests) requests.flat_map do |request| @@ -57,6 +57,6 @@ module HTTPX end end - register_plugin :digest_authentication, DigestAuth + register_plugin :digest_auth, DigestAuth end end diff --git a/lib/httpx/plugins/ntlm_authentication.rb b/lib/httpx/plugins/ntlm_auth.rb similarity index 83% rename from lib/httpx/plugins/ntlm_authentication.rb rename to lib/httpx/plugins/ntlm_auth.rb index 0482a971..77e93b09 100644 --- a/lib/httpx/plugins/ntlm_authentication.rb +++ b/lib/httpx/plugins/ntlm_auth.rb @@ -3,12 +3,12 @@ module HTTPX module Plugins # - # https://gitlab.com/os85/httpx/wikis/Authentication#ntlm-authentication + # https://gitlab.com/os85/httpx/wikis/Authorization#ntlm-auth # module NTLMAuth class << self def load_dependencies(_klass) - require_relative "authentication/ntlm" + require_relative "auth/ntlm" end def extra_options(options) @@ -25,11 +25,11 @@ module HTTPX end module InstanceMethods - def ntlm_authentication(user, password, domain = nil) + def ntlm_auth(user, password, domain = nil) with(ntlm: Authentication::Ntlm.new(user, password, domain: domain)) end - alias_method :ntlm_auth, :ntlm_authentication + private def send_requests(*requests) requests.flat_map do |request| @@ -55,6 +55,6 @@ module HTTPX end end end - register_plugin :ntlm_authentication, NTLMAuth + register_plugin :ntlm_auth, NTLMAuth end end diff --git a/lib/httpx/plugins/oauth.rb b/lib/httpx/plugins/oauth.rb index 6422e57d..a5a16f5d 100644 --- a/lib/httpx/plugins/oauth.rb +++ b/lib/httpx/plugins/oauth.rb @@ -8,7 +8,7 @@ module HTTPX module OAuth class << self def load_dependencies(_klass) - require_relative "authentication/basic" + require_relative "auth/basic" end end @@ -106,7 +106,7 @@ module HTTPX end module InstanceMethods - def oauth_authentication(**args) + def oauth_auth(**args) with(oauth_session: OAuthSession.new(**args)) end diff --git a/lib/httpx/plugins/proxy.rb b/lib/httpx/plugins/proxy.rb index 24b4d313..8c3f9e5f 100644 --- a/lib/httpx/plugins/proxy.rb +++ b/lib/httpx/plugins/proxy.rb @@ -53,7 +53,7 @@ module HTTPX auth_scheme = scheme.to_s.capitalize - require_relative "authentication/#{scheme}" unless defined?(Authentication) && Authentication.const_defined?(auth_scheme, false) + require_relative "auth/#{scheme}" unless defined?(Authentication) && Authentication.const_defined?(auth_scheme, false) @authenticator = Authentication.const_get(auth_scheme).new(@username, @password, **extra) end diff --git a/lib/httpx/plugins/proxy/socks5.rb b/lib/httpx/plugins/proxy/socks5.rb index 46e71b00..cf7f0b1c 100644 --- a/lib/httpx/plugins/proxy/socks5.rb +++ b/lib/httpx/plugins/proxy/socks5.rb @@ -20,7 +20,7 @@ module HTTPX class << self def load_dependencies(*) - require_relative "../authentication/socks5" + require_relative "../auth/socks5" end def extra_options(options) diff --git a/sig/chainable.rbs b/sig/chainable.rbs index d4dffcae..3d210dc2 100644 --- a/sig/chainable.rbs +++ b/sig/chainable.rbs @@ -12,10 +12,10 @@ module HTTPX def with: (options) -> Session | (options) { (Session) -> void } -> void - def plugin: (:authentication, ?options) -> Plugins::sessionAuthentication - | (:basic_authentication, ?options) -> Plugins::sessionBasicAuth - | (:digest_authentication, ?options) -> Plugins::sessionDigestAuth - | (:ntlm_authentication, ?options) -> Plugins::sessionNTLMAuth + def plugin: (:auth, ?options) -> Plugins::sessionAuthorization + | (:basic_auth, ?options) -> Plugins::sessionBasicAuth + | (:digest_auth, ?options) -> Plugins::sessionDigestAuth + | (:ntlm_auth, ?options) -> Plugins::sessionNTLMAuth | (:aws_sdk_authentication, ?options) -> Plugins::sessionAwsSdkAuthentication | (:compression, ?options) -> Session | (:cookies, ?options) -> Plugins::sessionCookies diff --git a/sig/plugins/auth.rbs b/sig/plugins/auth.rbs new file mode 100644 index 00000000..c161f2b1 --- /dev/null +++ b/sig/plugins/auth.rbs @@ -0,0 +1,13 @@ +module HTTPX + module Plugins + module Authorization + module InstanceMethods + def authorization: (string token) -> instance + + def bearer_auth: (string token) -> instance + end + end + + type sessionAuthorization = Session & Authorization::InstanceMethods + end +end diff --git a/sig/plugins/authentication/basic.rbs b/sig/plugins/auth/basic.rbs similarity index 100% rename from sig/plugins/authentication/basic.rbs rename to sig/plugins/auth/basic.rbs diff --git a/sig/plugins/authentication/digest.rbs b/sig/plugins/auth/digest.rbs similarity index 100% rename from sig/plugins/authentication/digest.rbs rename to sig/plugins/auth/digest.rbs diff --git a/sig/plugins/authentication/ntlm.rbs b/sig/plugins/auth/ntlm.rbs similarity index 100% rename from sig/plugins/authentication/ntlm.rbs rename to sig/plugins/auth/ntlm.rbs diff --git a/sig/plugins/authentication/socks5.rbs b/sig/plugins/auth/socks5.rbs similarity index 100% rename from sig/plugins/authentication/socks5.rbs rename to sig/plugins/auth/socks5.rbs diff --git a/sig/plugins/authentication.rbs b/sig/plugins/authentication.rbs deleted file mode 100644 index 334d558d..00000000 --- a/sig/plugins/authentication.rbs +++ /dev/null @@ -1,13 +0,0 @@ -module HTTPX - module Plugins - module Authentication - module InstanceMethods - def authentication: (string token) -> instance - - def bearer_auth: (string token) -> instance - end - end - - type sessionAuthentication = Session & Authentication::InstanceMethods - end -end diff --git a/sig/plugins/basic_authentication.rbs b/sig/plugins/basic_auth.rbs similarity index 54% rename from sig/plugins/basic_authentication.rbs rename to sig/plugins/basic_auth.rbs index 59c3b767..e477a673 100644 --- a/sig/plugins/basic_authentication.rbs +++ b/sig/plugins/basic_auth.rbs @@ -6,10 +6,10 @@ module HTTPX def self.configure: (singleton(Session)) -> void module InstanceMethods - def basic_authentication: (string user, string password) -> instance + def basic_auth: (string user, string password) -> instance end end - type sessionBasicAuth = sessionAuthentication & Authentication::InstanceMethods & BasicAuth::InstanceMethods + type sessionBasicAuth = sessionAuthorization & BasicAuth::InstanceMethods end end diff --git a/sig/plugins/digest_authentication.rbs b/sig/plugins/digest_auth.rbs similarity index 67% rename from sig/plugins/digest_authentication.rbs rename to sig/plugins/digest_auth.rbs index 720523ab..3c5b4eaa 100644 --- a/sig/plugins/digest_authentication.rbs +++ b/sig/plugins/digest_auth.rbs @@ -12,10 +12,10 @@ module HTTPX def self.load_dependencies: (*untyped) -> void module InstanceMethods - def digest_authentication: (string user, string password, ?hashed: bool) -> instance + def digest_auth: (string user, string password, ?hashed: bool) -> instance end end - type sessionDigestAuth = sessionAuthentication & DigestAuth::InstanceMethods + type sessionDigestAuth = sessionAuthorization & DigestAuth::InstanceMethods end end diff --git a/sig/plugins/ntlm_authentication.rbs b/sig/plugins/ntlm_auth.rbs similarity index 65% rename from sig/plugins/ntlm_authentication.rbs rename to sig/plugins/ntlm_auth.rbs index 734d7f21..8e86da04 100644 --- a/sig/plugins/ntlm_authentication.rbs +++ b/sig/plugins/ntlm_auth.rbs @@ -11,11 +11,11 @@ module HTTPX def self.load_dependencies: (*untyped) -> void module InstanceMethods - def ntlm_authentication: (string user, string password, ?string? domain) -> instance + def ntlm_auth: (string user, string password, ?string? domain) -> instance end end - type sessionNTLMAuth = sessionAuthentication & NTLMAuth::InstanceMethods + type sessionNTLMAuth = sessionAuthorization & NTLMAuth::InstanceMethods end end diff --git a/sig/plugins/oauth.rbs b/sig/plugins/oauth.rbs index 1ed047c9..e4c8828a 100644 --- a/sig/plugins/oauth.rbs +++ b/sig/plugins/oauth.rbs @@ -43,7 +43,7 @@ module HTTPX end module InstanceMethods - def oauth_authentication: (**untyped args) -> instance + def oauth_auth: (**untyped args) -> instance def with_access_token: () -> instance end diff --git a/test/support/requests/plugins/authentication.rb b/test/support/requests/plugins/auth.rb similarity index 77% rename from test/support/requests/plugins/authentication.rb rename to test/support/requests/plugins/auth.rb index 8183b896..bf9daaf4 100644 --- a/test/support/requests/plugins/authentication.rb +++ b/test/support/requests/plugins/auth.rb @@ -7,7 +7,7 @@ module Requests def test_plugin_bearer_auth get_uri = build_uri("/get") - session = HTTPX.plugin(:authentication) + session = HTTPX.plugin(:auth) response = session.bearer_auth("TOKEN").get(get_uri) verify_status(response, 200) body = json_body(response) @@ -16,13 +16,13 @@ module Requests # Basic Auth - def test_plugin_basic_authentication + def test_plugin_basic_auth no_auth_response = HTTPX.get(basic_auth_uri) verify_status(no_auth_response, 401) verify_header(no_auth_response.headers, "www-authenticate", "Basic realm=\"Fake Realm\"") no_auth_response.close - session = HTTPX.plugin(:basic_authentication) + session = HTTPX.plugin(:basic_auth) response = session.basic_auth(user, pass).get(basic_auth_uri) verify_status(response, 200) body = json_body(response) @@ -35,8 +35,8 @@ module Requests # Digest - def test_plugin_digest_authentication - session = HTTPX.plugin(:digest_authentication).with_headers("cookie" => "fake=fake_value") + def test_plugin_digest_auth + session = HTTPX.plugin(:digest_auth).with_headers("cookie" => "fake=fake_value") response = session.digest_auth(user, pass).get(digest_auth_uri) verify_status(response, 200) body = json_body(response) @@ -45,8 +45,8 @@ module Requests end %w[SHA1 SHA2 SHA256 SHA384 SHA512 RMD160].each do |alg| - define_method "test_plugin_digest_authentication_#{alg}" do - session = HTTPX.plugin(:digest_authentication).with_headers("cookie" => "fake=fake_value") + define_method "test_plugin_digest_auth_#{alg}" do + session = HTTPX.plugin(:digest_auth).with_headers("cookie" => "fake=fake_value") response = session.digest_auth(user, pass).get("#{digest_auth_uri}/#{alg}") verify_status(response, 200) body = json_body(response) @@ -56,10 +56,10 @@ module Requests end %w[MD5 SHA1].each do |alg| - define_method "test_plugin_digest_authentication_#{alg}_sess" do + define_method "test_plugin_digest_auth_#{alg}_sess" do start_test_servlet(DigestServer, algorithm: "#{alg}-sess") do |server| uri = "#{server.origin}/" - session = HTTPX.plugin(:digest_authentication).with_headers("cookie" => "fake=fake_value") + session = HTTPX.plugin(:digest_auth).with_headers("cookie" => "fake=fake_value") response = session.digest_auth(user, server.get_passwd(user), hashed: true).get(uri) verify_status(response, 200) assert response.read == "yay" @@ -67,8 +67,8 @@ module Requests end end - def test_plugin_digest_authentication_bypass - session = HTTPX.plugin(:digest_authentication).with_headers("cookie" => "fake=fake_value") + def test_plugin_digest_auth_bypass + session = HTTPX.plugin(:digest_auth).with_headers("cookie" => "fake=fake_value") response = session.get(digest_auth_uri) verify_status(response, 401) response = session.get(build_uri("/get")) @@ -81,12 +81,12 @@ module Requests if RUBY_VERSION < "3.1.0" # TODO: enable again once ruby-openssl 3 supports legacy ciphers - def test_plugin_ntlm_authentication + def test_plugin_ntlm_auth return if origin.start_with?("https") start_test_servlet(NTLMServer) do |server| uri = "#{server.origin}/" - HTTPX.plugin(SessionWithPool).plugin(:ntlm_authentication).wrap do |http| + HTTPX.plugin(SessionWithPool).plugin(:ntlm_auth).wrap do |http| # skip unless NTLM no_auth_response = http.get(uri) verify_status(no_auth_response, 401) @@ -100,7 +100,7 @@ module Requests verify_status(response, 200) response = http.ntlm_auth("user", "password").get(build_uri("/get")) verify_status(response, 200) - # invalid_response = http.ntlm_authentication("user", "fake").get(uri) + # invalid_response = http.ntlm_auth("user", "fake").get(uri) # verify_status(invalid_response, 401) end end diff --git a/test/support/requests/plugins/oauth.rb b/test/support/requests/plugins/oauth.rb index bb013ee9..f5affe92 100644 --- a/test/support/requests/plugins/oauth.rb +++ b/test/support/requests/plugins/oauth.rb @@ -5,7 +5,7 @@ module Requests module OAuth def test_plugin_oauth_options with_oauth_metadata do |server| - opts = HTTPX.plugin(:oauth).oauth_authentication( + opts = HTTPX.plugin(:oauth).oauth_auth( issuer: server.origin, client_id: "CLIENT_ID", client_secret: "SECRET", scope: "all" @@ -16,7 +16,7 @@ module Requests assert opts.oauth_session.token_endpoint_auth_method == "client_secret_basic" assert opts.oauth_session.scope == %w[all] - opts = HTTPX.plugin(:oauth).oauth_authentication( + opts = HTTPX.plugin(:oauth).oauth_auth( issuer: "https://smthelse", token_endpoint_auth_method: "client_secret_post", client_id: "CLIENT_ID", client_secret: "SECRET", @@ -29,7 +29,7 @@ module Requests assert opts.oauth_session.scope == %w[foo bar] assert_raises(HTTPX::Error) do - HTTPX.plugin(:oauth).oauth_authentication( + HTTPX.plugin(:oauth).oauth_auth( issuer: server.origin, client_id: "CLIENT_ID", client_secret: "SECRET", token_endpoint_auth_method: "unsupported" @@ -40,7 +40,7 @@ module Requests def test_plugin_oauth_client_credentials with_oauth_metadata do |server| - session = HTTPX.plugin(:oauth).oauth_authentication( + session = HTTPX.plugin(:oauth).oauth_auth( issuer: server.origin, client_id: "CLIENT_ID", client_secret: "SECRET", scope: "all" ) @@ -57,7 +57,7 @@ module Requests def test_plugin_oauth_refresh_token with_oauth_metadata do |server| - session = HTTPX.plugin(:oauth).oauth_authentication( + session = HTTPX.plugin(:oauth).oauth_auth( issuer: server.origin, token_endpoint_auth_method: "client_secret_post", client_id: "CLIENT_ID", client_secret: "SECRET", diff --git a/test/support/requests/plugins/webdav.rb b/test/support/requests/plugins/webdav.rb index 53e37ef0..9c7f8b88 100644 --- a/test/support/requests/plugins/webdav.rb +++ b/test/support/requests/plugins/webdav.rb @@ -94,7 +94,7 @@ module Requests private def webdav_client - @webdav_client ||= HTTPX.plugin(:basic_authentication).plugin(:webdav, origin: start_webdav_server).basic_auth("user", "pass") + @webdav_client ||= HTTPX.plugin(:basic_auth).plugin(:webdav, origin: start_webdav_server).basic_auth("user", "pass") end def start_webdav_server