x 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2906018cf3e05342abe1bc6c938f3d1b3cf9d1d84c3813a96a11b693fbe0960
-  data.tar.gz: f84f47e1a9ea06b101712ae1f9fd7198d71b2cbc7487a654b8442dd13e3244e0
+  metadata.gz: e5af820e6e3cd8b04becf201ad7af96c8d95d9206112673888f91c5ecf923187
+  data.tar.gz: 6f0f561be192153eca2cc7356c823c87bd98f0987256875892c0a2e9ea12b82d
 SHA512:
-  metadata.gz: 2c98c3ea7e22d0b023a328207c9599dca0f74b54d5ed05eea04378c5c2ed5a2803799b7dcafa54d041d3b7dac8b3e08c8559d4cacb03b2419796368fa153401e
-  data.tar.gz: 36c0faa98a5f6657a88ce770924e2669f91fcea2985b38f1c82dc0766d0c5a5cf6a4b0342d4684f5b679b41dc76f5fa94b791a6468b6f0514c28f6d70864b41a
+  metadata.gz: 8b208d5ba10604a34a57b0dd2ee5dc0992eb801cfbcc287a7f1b0d54444f214050a2c25b2ec6291868a8c35fff09260ad91a82641be830b87d3e6abf0207fc3e
+  data.tar.gz: 24c6a1083358b60065698320372d53404bab9c319aaad13b097508a7041653ac9d45aabd8e6f7a99204accddfc1beeeb2bce18bd67fa9ba816eb6282cbab4227

data/CHANGELOG.md

@@ -1,66 +1,82 @@
-## [Unreleased]
+## [0.11.0] - 2023-10-24
+
+* Add base Authenticator class (8c66ce2)
+* Consistently use keyword arguments (3beb271)
+* Use patern matching to build request (4d001c7)
+* Rename ResponseHandler to ResponseParser (498e890)
+* Rename methods to be more consistent (5b8c655)
+* Rename MediaUpload to MediaUploader (84f0c15)
+* Add mutant and kill mutants (b124968)
+* Fix authentication bug with request URLs that contain spaces (8de3174)
+* Refactor errors (853d39c)
+* Make Connection class threadsafe (d95d285)
+
+## [0.10.0] - 2023-10-08
+
+* Add media upload helper methods (6c6a267)
+* Add PayloadTooLargeError class (cd61850)
 
 ## [0.9.1] - 2023-10-06
 
-- Allow successful empty responses (06bf7db)
-- Update default User-Agent string (296b36a)
-- Move query parameter escaping into RequestBuilder (56d6bd2)
+* Allow successful empty responses (06bf7db)
+* Update default User-Agent string (296b36a)
+* Move query parameter escaping into RequestBuilder (56d6bd2)
 
 ## [0.9.0] - 2023-09-26
 
-- Add support for HTTP proxies (3740f4f)
+* Add support for HTTP proxies (3740f4f)
 
 ## [0.8.1] - 2023-09-20
 
-- Fix bug where setting Connection#base_uri= doesn't update the HTTP client (d5a89db)
+* Fix bug where setting Connection#base_uri= doesn't update the HTTP client (d5a89db)
 
 ## [0.8.0] - 2023-09-14
 
-- Add (back) bearer token authentication (62e141d)
-- Follow redirects (90a8c55)
-- Parse error responses with Content-Type: application/problem+json (0b697d9)
+* Add (back) bearer token authentication (62e141d)
+* Follow redirects (90a8c55)
+* Parse error responses with Content-Type: application/problem+json (0b697d9)
 
 ## [0.7.1] - 2023-09-02
 
-- Fix bug in X::Authenticator#split_uri (ebc9d5f)
+* Fix bug in X::Authenticator#split_uri (ebc9d5f)
 
 ## [0.7.0] - 2023-09-02
 
-- Remove OAuth gem (7c29bb1)
+* Remove OAuth gem (7c29bb1)
 
 ## [0.6.0] - 2023-08-30
 
-- Add configurable debug output stream for logging (fd2d4b0)
-- Remove bearer token authentication (efff940)
-- Define RBS type signatures (d7f63ba)
+* Add configurable debug output stream for logging (fd2d4b0)
+* Remove bearer token authentication (efff940)
+* Define RBS type signatures (d7f63ba)
 
 ## [0.5.1] - 2023-08-16
 
-- Fix bearer token authentication (1a1ca93)
+* Fix bearer token authentication (1a1ca93)
 
 ## [0.5.0] - 2023-08-10
 
-- Add configurable write timeout (2a31f84)
-- Use built-in Gem::Version class (066e0b6)
+* Add configurable write timeout (2a31f84)
+* Use built-in Gem::Version class (066e0b6)
 
 ## [0.4.0] - 2023-08-06
 
-- Refactor Client into Authenticator, RequestBuilder, Connection, ResponseHandler (6bee1e9)
-- Add configurable open timeout (1000f9d)
-- Allow configuration of content type (f33a732)
+* Refactor Client into Authenticator, RequestBuilder, Connection, ResponseHandler (6bee1e9)
+* Add configurable open timeout (1000f9d)
+* Allow configuration of content type (f33a732)
 
 ## [0.3.0] - 2023-08-04
 
-- Add accessors to X::Client (e61fa73)
-- Add configurable read timeout (41502b9)
-- Handle network-related errors (9ed1fb4)
-- Include response body in errors (a203e6a)
+* Add accessors to X::Client (e61fa73)
+* Add configurable read timeout (41502b9)
+* Handle network-related errors (9ed1fb4)
+* Include response body in errors (a203e6a)
 
 ## [0.2.0] - 2023-08-02
 
-- Allow configuration of base URL (4bc0531)
-- Improve error handling (14dc0cd)
+* Allow configuration of base URL (4bc0531)
+* Improve error handling (14dc0cd)
 
 ## [0.1.0] - 2023-08-02
 
-- Initial release
+* Initial release

data/README.md

@@ -130,11 +130,15 @@ Pull requests will only be accepted if they meet all the following criteria:
 
        bundle exec rake standard
 
-2. For any new code paths, tests must be added to maintain 100% C0 code coverage. This can be verified with:
+2. 100% C0 code coverage. This can be verified with:
 
        bundle exec rake test
 
-3. For any new classes or methods, RBS type signatures must be added (to sig/x.rbs). This can be verified with:
+3. 100% mutation coverage. This can be verified with:
+
+       bundle exec rake mutant
+
+4. RBS type signatures (in `sig/x.rbs`). This can be verified with:
 
        bundle exec rake steep
 

data/lib/x/authenticator.rb

@@ -0,0 +1,8 @@
+module X
+  # Base Authenticator class
+  class Authenticator
+    def header(_request)
+      {"Authorization" => ""}
+    end
+  end
+end

data/lib/x/bearer_token_authenticator.rb

@@ -1,14 +1,16 @@
+require_relative "authenticator"
+
 module X
   # Handles bearer token authentication
-  class BearerTokenAuthenticator
+  class BearerTokenAuthenticator < Authenticator
     attr_accessor :bearer_token
 
-    def initialize(bearer_token)
+    def initialize(bearer_token:) # rubocop:disable Lint/MissingSuper
       @bearer_token = bearer_token
     end
 
     def header(_request)
-      "Bearer #{bearer_token}"
+      {"Authorization" => "Bearer #{bearer_token}"}
     end
   end
 end

data/lib/x/cgi.rb

@@ -0,0 +1,15 @@
+require "cgi"
+
+module X
+  # Namespaced CGI class
+  class CGI
+    # TODO: Replace CGI.escape with CGI.escapeURIComponent when support for Ruby 3.1 is dropped
+    def self.escape(value)
+      ::CGI.escape(value).gsub("+", "%20")
+    end
+
+    def self.escape_params(params)
+      params.map { |k, v| "#{k}=#{escape(v)}" }.join("&")
+    end
+  end
+end

data/lib/x/client.rb

@@ -1,84 +1,87 @@
 require "forwardable"
 require_relative "bearer_token_authenticator"
-require_relative "oauth_authenticator"
 require_relative "connection"
+require_relative "oauth_authenticator"
 require_relative "redirect_handler"
 require_relative "request_builder"
-require_relative "response_handler"
+require_relative "response_parser"
 
 module X
   # Main public interface
   class Client
     extend Forwardable
 
+    DEFAULT_BASE_URL = "https://api.twitter.com/2/".freeze
+
+    attr_accessor :base_url
+
     def_delegators :@authenticator, :bearer_token, :api_key, :api_key_secret, :access_token, :access_token_secret
     def_delegators :@authenticator, :bearer_token=, :api_key=, :api_key_secret=, :access_token=, :access_token_secret=
-    def_delegators :@connection, :base_uri, :open_timeout, :read_timeout, :write_timeout, :debug_output
-    def_delegators :@connection, :base_uri=, :open_timeout=, :read_timeout=, :write_timeout=, :debug_output=
-    def_delegators :@request_builder, :content_type, :user_agent
-    def_delegators :@request_builder, :content_type=, :user_agent=
-    def_delegators :@response_handler, :array_class, :object_class
-    def_delegators :@response_handler, :array_class=, :object_class=
+    def_delegators :@connection, :open_timeout, :read_timeout, :write_timeout, :proxy_url, :debug_output
+    def_delegators :@connection, :open_timeout=, :read_timeout=, :write_timeout=, :proxy_url=, :debug_output=
+    def_delegators :@redirect_handler, :max_redirects
+    def_delegators :@redirect_handler, :max_redirects=
+    def_delegators :@response_parser, :array_class, :object_class
+    def_delegators :@response_parser, :array_class=, :object_class=
 
     def initialize(bearer_token: nil,
       api_key: nil, api_key_secret: nil, access_token: nil, access_token_secret: nil,
-      base_url: Connection::DEFAULT_BASE_URL,
+      base_url: DEFAULT_BASE_URL,
       open_timeout: Connection::DEFAULT_OPEN_TIMEOUT,
       read_timeout: Connection::DEFAULT_READ_TIMEOUT,
       write_timeout: Connection::DEFAULT_WRITE_TIMEOUT,
       proxy_url: nil,
-      content_type: RequestBuilder::DEFAULT_CONTENT_TYPE,
-      user_agent: RequestBuilder::DEFAULT_USER_AGENT,
       debug_output: nil,
-      array_class: ResponseHandler::DEFAULT_ARRAY_CLASS,
-      object_class: ResponseHandler::DEFAULT_OBJECT_CLASS,
+      array_class: nil,
+      object_class: nil,
       max_redirects: RedirectHandler::DEFAULT_MAX_REDIRECTS)
 
+      @base_url = base_url
       initialize_authenticator(bearer_token, api_key, api_key_secret, access_token, access_token_secret)
-      @connection = Connection.new(base_url: base_url, open_timeout: open_timeout, read_timeout: read_timeout,
+      @connection = Connection.new(open_timeout: open_timeout, read_timeout: read_timeout,
         write_timeout: write_timeout, debug_output: debug_output, proxy_url: proxy_url)
-      @request_builder = RequestBuilder.new(content_type: content_type, user_agent: user_agent)
-      @redirect_handler = RedirectHandler.new(@authenticator, @connection, @request_builder,
-        max_redirects: max_redirects)
-      @response_handler = ResponseHandler.new(array_class: array_class, object_class: object_class)
+      @request_builder = RequestBuilder.new
+      @redirect_handler = RedirectHandler.new(authenticator: @authenticator, connection: @connection,
+        request_builder: @request_builder, max_redirects: max_redirects)
+      @response_parser = ResponseParser.new(array_class: array_class, object_class: object_class)
     end
 
-    def get(endpoint)
-      send_request(:get, endpoint)
+    def get(endpoint, headers: {})
+      execute_request(:get, endpoint, headers: headers)
     end
 
-    def post(endpoint, body = nil)
-      send_request(:post, endpoint, body)
+    def post(endpoint, body = nil, headers: {})
+      execute_request(:post, endpoint, body: body, headers: headers)
     end
 
-    def put(endpoint, body = nil)
-      send_request(:put, endpoint, body)
+    def put(endpoint, body = nil, headers: {})
+      execute_request(:put, endpoint, body: body, headers: headers)
     end
 
-    def delete(endpoint)
-      send_request(:delete, endpoint)
+    def delete(endpoint, headers: {})
+      execute_request(:delete, endpoint, headers: headers)
     end
 
     private
 
     def initialize_authenticator(bearer_token, api_key, api_key_secret, access_token, access_token_secret)
       @authenticator = if bearer_token
-        BearerTokenAuthenticator.new(bearer_token)
+        BearerTokenAuthenticator.new(bearer_token: bearer_token)
       elsif api_key && api_key_secret && access_token && access_token_secret
-        OauthAuthenticator.new(api_key, api_key_secret, access_token, access_token_secret)
+        OAuthAuthenticator.new(api_key: api_key, api_key_secret: api_key_secret, access_token: access_token,
+          access_token_secret: access_token_secret)
       else
-        raise ArgumentError,
-          "Client must be initialized with either a bearer_token or " \
-          "an api_key, api_key_secret, access_token, and access_token_secret"
+        Authenticator.new
       end
     end
 
-    def send_request(http_method, endpoint, body = nil)
-      uri = URI.join(base_uri.to_s, endpoint)
-      request = @request_builder.build(@authenticator, http_method, uri, body: body)
-      response = @connection.send_request(request)
-      final_response = @redirect_handler.handle_redirects(response, request, base_uri)
-      @response_handler.handle(final_response)
+    def execute_request(http_method, endpoint, headers:, body: nil)
+      uri = URI.join(base_url, endpoint)
+      request = @request_builder.build(authenticator: @authenticator, http_method: http_method, uri: uri, body: body,
+        headers: headers)
+      response = @connection.perform(request: request)
+      response = @redirect_handler.handle(response: response, request: request, base_url: base_url)
+      @response_parser.parse(response: response)
     end
   end
 end

data/lib/x/connection.rb

@@ -1,5 +1,6 @@
 require "forwardable"
 require "net/http"
+require "openssl"
 require "uri"
 require_relative "errors/network_error"
 
@@ -8,96 +9,72 @@ module X
   class Connection
     extend Forwardable
 
-    DEFAULT_BASE_URL = "https://api.twitter.com/2/".freeze
-    DEFAULT_HOST = "https://api.twitter.com".freeze
+    DEFAULT_HOST = "api.twitter.com".freeze
     DEFAULT_PORT = 443
     DEFAULT_OPEN_TIMEOUT = 60 # seconds
     DEFAULT_READ_TIMEOUT = 60 # seconds
     DEFAULT_WRITE_TIMEOUT = 60 # seconds
+    DEFAULT_DEBUG_OUTPUT = File.open(File::NULL, "w")
     NETWORK_ERRORS = [
       Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
       Net::OpenTimeout,
-      Net::ReadTimeout
+      Net::ReadTimeout,
+      OpenSSL::SSL::SSLError
     ].freeze
 
-    attr_reader :base_uri, :proxy_uri, :http_client
+    attr_accessor :open_timeout, :read_timeout, :write_timeout, :debug_output
+    attr_reader :proxy_url, :proxy_uri
 
-    def_delegators :@http_client, :open_timeout, :read_timeout, :write_timeout
-    def_delegators :@http_client, :open_timeout=, :read_timeout=, :write_timeout=
-    def_delegator :@http_client, :set_debug_output, :debug_output=
+    def_delegator :proxy_uri, :host, :proxy_host
+    def_delegator :proxy_uri, :port, :proxy_port
+    def_delegator :proxy_uri, :user, :proxy_user
+    def_delegator :proxy_uri, :password, :proxy_pass
 
-    def initialize(base_url: DEFAULT_BASE_URL, open_timeout: DEFAULT_OPEN_TIMEOUT,
-      read_timeout: DEFAULT_READ_TIMEOUT, write_timeout: DEFAULT_WRITE_TIMEOUT, proxy_url: nil, debug_output: nil)
-      @proxy_uri = URI(proxy_url) unless proxy_url.nil?
-      self.base_uri = base_url
-      apply_http_client_settings(
-        open_timeout: open_timeout,
-        read_timeout: read_timeout,
-        write_timeout: write_timeout,
-        debug_output: debug_output
-      )
+    def initialize(open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT, debug_output: DEFAULT_DEBUG_OUTPUT, proxy_url: nil)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @write_timeout = write_timeout
+      @debug_output = debug_output
+      self.proxy_url = proxy_url unless proxy_url.nil?
     end
 
-    def send_request(request)
-      @http_client.request(request)
+    def perform(request:)
+      host = request.uri.host || DEFAULT_HOST
+      port = request.uri.port || DEFAULT_PORT
+      http_client = build_http_client(host, port)
+      http_client.use_ssl = request.uri.scheme.eql?("https")
+      http_client.request(request)
     rescue *NETWORK_ERRORS => e
-      raise NetworkError, "Network error: #{e.message}"
+      raise NetworkError, "Network error: #{e}"
     end
 
-    def base_uri=(base_url)
-      base_uri = URI(base_url)
-      raise ArgumentError, "Invalid base URL" unless base_uri.is_a?(URI::HTTPS) || base_uri.is_a?(URI::HTTP)
+    def proxy_url=(proxy_url)
+      @proxy_url = proxy_url
+      proxy_uri = URI(proxy_url)
+      raise ArgumentError, "Invalid proxy URL: #{proxy_uri}" unless proxy_uri.is_a?(URI::HTTP)
 
-      @base_uri = base_uri
-      update_http_client_settings
-    end
-
-    def debug_output
-      @http_client.instance_variable_get(:@debug_output)
+      @proxy_uri = proxy_uri
     end
 
     private
 
-    def apply_http_client_settings(open_timeout:, read_timeout:, write_timeout:, debug_output:)
-      @http_client.open_timeout = open_timeout
-      @http_client.read_timeout = read_timeout
-      @http_client.write_timeout = write_timeout
-      @http_client.set_debug_output(debug_output) if debug_output
-    end
-
-    def current_http_client_settings
-      {
-        open_timeout: @http_client.open_timeout,
-        read_timeout: @http_client.read_timeout,
-        write_timeout: @http_client.write_timeout,
-        debug_output: debug_output
-      }
-    end
-
-    def update_http_client_settings
-      conditionally_apply_http_client_settings do
-        host = @base_uri.host || DEFAULT_HOST
-        port = @base_uri.port || DEFAULT_PORT
-        @http_client = build_http_client(host: host, port: port)
-        @http_client.use_ssl = @base_uri.scheme == "https"
-      end
-    end
-
-    def build_http_client(host:, port:)
-      if @proxy_uri.nil?
-        Net::HTTP.new(host, port)
+    def build_http_client(host = DEFAULT_HOST, port = DEFAULT_PORT)
+      http_client = if proxy_uri
+        Net::HTTP.new(host, port, proxy_host, proxy_port, proxy_user, proxy_pass)
       else
-        Net::HTTP.new(host, port, @proxy_uri&.host, @proxy_uri&.port, @proxy_uri&.user, @proxy_uri&.password)
+        Net::HTTP.new(host, port)
       end
+      configure_http_client(http_client)
     end
 
-    def conditionally_apply_http_client_settings
-      if @http_client
-        settings = current_http_client_settings
-        yield
-        apply_http_client_settings(**settings)
-      else
-        yield
+    def configure_http_client(http_client)
+      http_client.tap do |c|
+        c.open_timeout = open_timeout
+        c.read_timeout = read_timeout
+        c.write_timeout = write_timeout
+        c.set_debug_output(debug_output)
       end
     end
   end

data/lib/x/errors/bad_gateway.rb

@@ -0,0 +1,5 @@
+require_relative "server_error"
+
+module X
+  class BadGateway < ServerError; end
+end

data/lib/x/errors/{not_found_error.rb → bad_request.rb}

@@ -1,5 +1,5 @@
 require_relative "client_error"
 
 module X
-  class NotFoundError < ClientError; end
+  class BadRequest < ClientError; end
 end

data/lib/x/errors/connection_exception.rb

@@ -0,0 +1,5 @@
+require_relative "client_error"
+
+module X
+  class ConnectionException < ClientError; end
+end

data/lib/x/errors/error.rb

@@ -1,15 +1,7 @@
-require "json"
-require "net/http"
-
 module X
   # Base error class
   class Error < ::StandardError
-    JSON_CONTENT_TYPE_REGEXP = %r{application/(problem\+|)json}
-
-    attr_reader :object
-
-    def initialize(msg, response:)
-      @object = JSON.parse(response.body || "{}") if JSON_CONTENT_TYPE_REGEXP.match?(response["content-type"])
+    def initialize(msg, _response = nil)
       super(msg)
     end
   end

data/lib/x/errors/{forbidden_error.rb → forbidden.rb}

@@ -1,5 +1,5 @@
 require_relative "client_error"
 
 module X
-  class ForbiddenError < ClientError; end
+  class Forbidden < ClientError; end
 end

data/lib/x/errors/gateway_timeout.rb

@@ -0,0 +1,5 @@
+require_relative "server_error"
+
+module X
+  class GatewayTimeout < ServerError; end
+end

data/lib/x/errors/{bad_request_error.rb → gone.rb}

@@ -1,5 +1,5 @@
 require_relative "client_error"
 
 module X
-  class BadRequestError < ClientError; end
+  class Gone < ClientError; end
 end

data/lib/x/errors/internal_server_error.rb

@@ -0,0 +1,5 @@
+require_relative "server_error"
+
+module X
+  class InternalServerError < ServerError; end
+end

data/lib/x/errors/network_error.rb

@@ -1,5 +1,5 @@
 require_relative "error"
 
 module X
-  class NetworkError < StandardError; end
+  class NetworkError < Error; end
 end

data/lib/x/errors/not_acceptable.rb

@@ -0,0 +1,5 @@
+require_relative "client_error"
+
+module X
+  class NotAcceptable < ClientError; end
+end

data/lib/x/errors/not_found.rb

@@ -0,0 +1,5 @@
+require_relative "client_error"
+
+module X
+  class NotFound < ClientError; end
+end

data/lib/x/errors/payload_too_large.rb

@@ -0,0 +1,5 @@
+require_relative "client_error"
+
+module X
+  class PayloadTooLarge < ClientError; end
+end

data/lib/x/errors/service_unavailable.rb

@@ -0,0 +1,5 @@
+require_relative "server_error"
+
+module X
+  class ServiceUnavailable < ServerError; end
+end

data/lib/x/errors/too_many_redirects.rb

@@ -0,0 +1,5 @@
+require_relative "client_error"
+
+module X
+  class TooManyRedirects < ClientError; end
+end

data/lib/x/errors/too_many_requests.rb

@@ -0,0 +1,29 @@
+require_relative "client_error"
+
+module X
+  # Rate limit error
+  class TooManyRequests < ClientError
+    def initialize(msg, response)
+      @response = response
+      super(msg)
+    end
+
+    def limit
+      @response["x-rate-limit-limit"].to_i
+    end
+
+    def remaining
+      @response["x-rate-limit-remaining"].to_i
+    end
+
+    def reset_at
+      Time.at(@response["x-rate-limit-reset"].to_i)
+    end
+
+    def reset_in
+      [(reset_at - Time.now).ceil, 0].max
+    end
+
+    alias_method :retry_after, :reset_in
+  end
+end

data/lib/x/errors/unauthorized.rb

@@ -0,0 +1,5 @@
+require_relative "client_error"
+
+module X
+  class Unauthorized < ClientError; end
+end

data/lib/x/errors/unprocessable_entity.rb

@@ -0,0 +1,5 @@
+require_relative "client_error"
+
+module X
+  class UnprocessableEntity < ClientError; end
+end