contractful 0.1.0

data/lib/contractful/contract/swagger2/references.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Contractful
+  module Contract
+    module Swagger2
+      # Swagger 2.0 keeps definitions, parameters and responses in top-level
+      # sections; OpenAPI 3.0 keeps them under components. Local $refs follow.
+      module References
+        SECTIONS = { 'definitions' => 'schemas', 'parameters' => 'parameters', 'responses' => 'responses' }.freeze
+
+        module_function
+
+        # Copy a document with its local $refs translated. Memoized by identity,
+        # so YAML aliases and cycles copy once and terminate.
+        def translate(node, memo = {}.compare_by_identity)
+          case node
+          when Hash then translate_hash(node, memo)
+          when Array then translate_array(node, memo)
+          else node
+          end
+        end
+
+        def translate_hash(node, memo)
+          return memo[node] if memo.key?(node)
+
+          out = memo[node] = {}
+          node.each do |key, value|
+            out[key] = key == '$ref' && value.is_a?(String) ? translate_ref(value) : translate(value, memo)
+          end
+          out
+        end
+
+        def translate_array(node, memo)
+          return memo[node] if memo.key?(node)
+
+          out = memo[node] = []
+          node.each { |value| out << translate(value, memo) }
+          out
+        end
+
+        def translate_ref(ref)
+          ref.start_with?('#') ? "##{translate_pointer(ref[1..])}" : ref
+        end
+
+        def translate_pointer(fragment)
+          return nil if fragment.nil?
+
+          fragment.sub(%r{\A/(definitions|parameters|responses)(?=/|\z)}) do
+            "/components/#{SECTIONS.fetch(Regexp.last_match(1))}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contractful/contract/swagger2.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'swagger2/references'
+require_relative 'swagger2/parameters'
+require_relative 'swagger2/operations'
+require_relative 'swagger2/components'
+
+module Contractful
+  module Contract
+    # Converts a Swagger 2.0 document into the OpenAPI 3.0 shape that
+    # {OpenAPIImport} reads. The conversion is structural and covers the
+    # constructs the importer maps: paths and operations, parameters (path,
+    # query, header, body and formData), responses, definitions and security.
+    # Everything else is copied through unchanged.
+    #
+    # Opt-in, like {OpenAPIImport}: it is loaded by
+    # <tt>require 'contractful/contract/openapi_import'</tt>.
+    module Swagger2
+      module_function
+
+      # @return [Boolean] true for a Hash that declares a Swagger 2.x version
+      def swagger?(doc)
+        doc.is_a?(Hash) && doc['swagger'].to_s.start_with?('2.')
+      end
+
+      # Convert a Swagger 2.0 document (a Hash) into an OpenAPI 3.0.3 Hash. The
+      # input is not modified.
+      def convert(doc)
+        root = References.translate(doc)
+        { 'openapi' => '3.0.3', 'x-contractful-source' => 'Swagger 2.0' }
+          .merge(document_fields(root))
+          .merge(root.select { |key, _| key.to_s.start_with?('x-') })
+      end
+
+      def document_fields(root)
+        fields = { 'servers' => Components.servers(root), 'paths' => Operations.convert_paths(root) }
+        fields['info'] = root['info'] if root['info']
+        fields['security'] = root['security'] if root['security']
+        components = Components.components(root)
+        fields['components'] = components unless components.empty?
+        fields
+      end
+
+      # Map a Swagger 2.0 $ref fragment to its OpenAPI 3.0 location, for refs
+      # from other files into a converted document.
+      def translate_pointer(fragment)
+        References.translate_pointer(fragment)
+      end
+
+      def list(value)
+        value.is_a?(Array) ? value : []
+      end
+    end
+  end
+end

data/lib/contractful/contract.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Contractful
+  # Contract-first architecture for contractful.
+  #
+  # Instead of hand-writing request code, you declare a *contract* — the HTTP
+  # shape of an API (verb, path, typed parameters, expected responses) — and
+  # metaprogramming generates the client methods, path builders, validation
+  # and introspection for you:
+  #
+  #   class GitHubAPI
+  #     include Contractful::Contract
+  #
+  #     base 'https://api.github.com'
+  #     default_headers 'Accept' => 'application/vnd.github+json'
+  #
+  #     contract :list_users, 'GET /users' do
+  #       param :page,     Integer, default: 1
+  #       param :per_page, Integer, inclusion: (1..100), default: 30
+  #     end
+  #
+  #     contract :create_issue, 'POST /repos/:owner/:repo/issues' do
+  #       param :owner, String, required: true
+  #       param :repo,  String, required: true
+  #       param :title, String, required: true
+  #     end
+  #   end
+  #
+  #   api = GitHubAPI.new
+  #   api.list_users(page: 2)
+  #   api.create_issue(owner: 'octo', repo: 'hello', title: 'Hi')
+  #
+  # The contract *is* the implementation: nothing about the request is
+  # written imperatively. Violations raise precise errors from the
+  # {Contract::Error} hierarchy instead of producing malformed requests.
+  module Contract
+    # Root of all contract errors (definition mistakes, param violations,
+    # response mismatches, misconfiguration).
+    class Error < StandardError; end
+
+    # Raised at definition time when a contract, param or macro is invalid.
+    class InvalidDefinition < Error; end
+
+    # Raised at execution time when no base URL is configured.
+    class MissingBaseUrl < Error; end
+
+    # Base class for parameter violations (missing, unknown, invalid).
+    class ParamError < Error; end
+
+    # A required param was not provided.
+    class MissingParam < ParamError; end
+
+    # A param was provided that the contract does not declare (strict mode).
+    class UnknownParam < ParamError; end
+
+    # A param value could not be coerced/validated against its declared type.
+    class InvalidParam < ParamError; end
+
+    # The HTTP response did not satisfy the contract's response declaration
+    # (unexpected status code, body type mismatch or failed verify_response
+    # block). The offending +response+ is attached for inspection.
+    class UnexpectedResponse < Error
+      attr_reader :response
+
+      def initialize(message = nil, response: nil)
+        @response = response
+        super(message)
+      end
+    end
+
+    # Sentinel for "no default value declared" (distinct from `default: nil`).
+    NO_DEFAULT = Object.new.freeze
+  end
+end
+
+require_relative 'contract/param'
+require_relative 'contract/response_field'
+require_relative 'contract/auth'
+require_relative 'contract/pagination'
+require_relative 'contract/definition'
+require_relative 'contract/config'
+require_relative 'contract/executor'
+require_relative 'contract/dsl'

data/lib/contractful/exceptions.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+# Root namespace: exceptions raised for non-2xx responses and request
+# failures, each carrying the originating response when one exists.
+module Contractful
+  # Hash of HTTP status code => message.
+  #
+  # 1xx: Informational - Request received, continuing process
+  # 2xx: Success - The action was successfully received, understood, and
+  #      accepted
+  # 3xx: Redirection - Further action must be taken in order to complete the
+  #      request
+  # 4xx: Client Error - The request contains bad syntax or cannot be fulfilled
+  # 5xx: Server Error - The server failed to fulfill an apparently valid
+  #      request
+  #
+  # @see
+  #   http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
+  #
+  STATUSES = { 100 => 'Continue',
+               101 => 'Switching Protocols',
+               102 => 'Processing', # WebDAV
+
+               200 => 'OK',
+               201 => 'Created',
+               202 => 'Accepted',
+               203 => 'Non-Authoritative Information', # http/1.1
+               204 => 'No Content',
+               205 => 'Reset Content',
+               206 => 'Partial Content',
+               207 => 'Multi-Status', # WebDAV
+               208 => 'Already Reported', # RFC5842
+               226 => 'IM Used', # RFC3229
+
+               300 => 'Multiple Choices',
+               301 => 'Moved Permanently',
+               302 => 'Found',
+               303 => 'See Other', # http/1.1
+               304 => 'Not Modified',
+               305 => 'Use Proxy', # http/1.1
+               306 => 'Switch Proxy', # no longer used
+               307 => 'Temporary Redirect', # http/1.1
+               308 => 'Permanent Redirect', # RFC7538
+
+               400 => 'Bad Request',
+               401 => 'Unauthorized',
+               402 => 'Payment Required',
+               403 => 'Forbidden',
+               404 => 'Not Found',
+               405 => 'Method Not Allowed',
+               406 => 'Not Acceptable',
+               407 => 'Proxy Authentication Required',
+               408 => 'Request Timeout',
+               409 => 'Conflict',
+               410 => 'Gone',
+               411 => 'Length Required',
+               412 => 'Precondition Failed',
+               413 => 'Payload Too Large', # RFC7231 (renamed, see below)
+               414 => 'URI Too Long', # RFC7231 (renamed, see below)
+               415 => 'Unsupported Media Type',
+               416 => 'Range Not Satisfiable', # RFC7233 (renamed, see below)
+               417 => 'Expectation Failed',
+               418 => 'I\'m A Teapot', # RFC2324
+               421 => 'Too Many Connections From This IP',
+               422 => 'Unprocessable Entity', # WebDAV
+               423 => 'Locked', # WebDAV
+               424 => 'Failed Dependency', # WebDAV
+               425 => 'Unordered Collection', # WebDAV
+               426 => 'Upgrade Required',
+               428 => 'Precondition Required', # RFC6585
+               429 => 'Too Many Requests', # RFC6585
+               431 => 'Request Header Fields Too Large', # RFC6585
+               449 => 'Retry With', # Microsoft
+               450 => 'Blocked By Windows Parental Controls', # Microsoft
+
+               500 => 'Internal Server Error',
+               501 => 'Not Implemented',
+               502 => 'Bad Gateway',
+               503 => 'Service Unavailable',
+               504 => 'Gateway Timeout',
+               505 => 'HTTP Version Not Supported',
+               506 => 'Variant Also Negotiates',
+               507 => 'Insufficient Storage', # WebDAV
+               508 => 'Loop Detected', # RFC5842
+               509 => 'Bandwidth Limit Exceeded', # Apache
+               510 => 'Not Extended',
+               511 => 'Network Authentication Required' } # RFC6585
+
+  STATUSES_COMPATIBILITY = {
+    # The RFCs all specify "Not Found", but "Resource Not Found" was used in
+    # earlier Contractful releases.
+    404 => ['ResourceNotFound'],
+
+    # HTTP 413 was renamed to "Payload Too Large" in RFC7231.
+    413 => ['RequestEntityTooLarge'],
+
+    # HTTP 414 was renamed to "URI Too Long" in RFC7231.
+    414 => ['RequestURITooLong'],
+
+    # HTTP 416 was renamed to "Range Not Satisfiable" in RFC7233.
+    416 => ['RequestedRangeNotSatisfiable']
+  }
+
+  # This is the base Contractful exception class. Rescue it if you want to
+  # catch any exception that your request might raise
+  # You can get the status code by e.http_code, or see anything about the
+  # response via e.response.
+  # For example, the entire result body (which is
+  # probably an HTML error page) is e.response.
+  class Exception < RuntimeError
+    attr_accessor :response, :original_exception
+    attr_writer :message
+
+    def initialize response = nil, initial_response_code = nil
+      super()
+      @response = response
+      @message = nil
+      @initial_response_code = initial_response_code
+    end
+
+    def http_code
+      # return integer for compatibility
+      if @response
+        @response.code.to_i
+      else
+        @initial_response_code
+      end
+    end
+
+    def http_headers
+      @response&.headers
+    end
+
+    def http_body
+      @response&.body
+    end
+
+    # Part of the error model: is this failure transient (worth retrying)
+    # or terminal? Exceptions without a response are terminal by default;
+    # subclasses override (see {Exceptions::RETRIABLE_STATUSES} for the
+    # status classification of response-bearing errors).
+    def retryable?
+      false
+    end
+
+    def to_s
+      message
+    end
+
+    def message
+      @message || default_message
+    end
+
+    def default_message
+      self.class.name
+    end
+  end
+
+  # Compatibility
+  class ExceptionWithResponse < Contractful::Exception
+    # Retryable when the HTTP status itself classifies as transient
+    # (408/425/429 and the usual 5xx gateway/server errors — see
+    # {Exceptions::RETRIABLE_STATUSES}). Every other status is terminal.
+    def retryable?
+      Exceptions::RETRIABLE_STATUSES.include?(http_code)
+    end
+  end
+
+  # The request failed with an error code not managed by the code
+  class RequestFailed < ExceptionWithResponse
+    def default_message
+      "HTTP status code #{http_code}"
+    end
+
+    def to_s
+      message
+    end
+  end
+
+  # Contractful exception classes. TODO: move all exceptions into this module.
+  #
+  # We will a create an exception for each status code, see
+  # http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
+  #
+  module Exceptions
+    # Map http status codes to the corresponding exception class
+    EXCEPTIONS_MAP = {}
+
+    # HTTP statuses whose failures are TRANSIENT rather than terminal — the
+    # retryable side of the error model. 408 (request timeout), 425 (too
+    # early), 429 (rate limited) and the standard gateway/server breakdowns.
+    # Everything else (401, 404, 422, 501, ...) is terminal: retrying will
+    # not fix a bad token, a missing resource or a bad payload.
+    RETRIABLE_STATUSES = [408, 425, 429, 500, 502, 503, 504].freeze
+
+    # Network-level failure classes that classify as retryable. NOTE:
+    # ::Timeout::Error is referenced with a top-level scope because
+    # Contractful::Exceptions::Timeout shadows the Timeout module here.
+    def self.network_errors
+      @network_errors ||= begin
+        require 'net/http'
+        require 'timeout'
+        [
+          SocketError,
+          EOFError,
+          Errno::ECONNRESET,
+          Errno::ECONNABORTED,
+          Errno::EPIPE,
+          Errno::ECONNREFUSED,
+          Errno::EHOSTUNREACH,
+          Errno::ENETUNREACH,
+          ::Timeout::Error,
+          Net::OpenTimeout,
+          Net::ReadTimeout,
+          Net::WriteTimeout
+        ].freeze
+      end
+    end
+
+    # Classify a failure as retryable (transient) or terminal.
+    #
+    # Accepts an Integer HTTP status, a Contractful::Exception instance, or
+    # any other exception object (checked against {network_errors}).
+    #
+    #   Exceptions.retryable?(429)                          # => true
+    #   Exceptions.retryable?(404)                          # => false
+    #   Exceptions.retryable?(Contractful::NotFound.new)     # => false
+    #   Exceptions.retryable?(SocketError.new('boom'))      # => true
+    def self.retryable?(candidate)
+      case candidate
+      when Integer
+        RETRIABLE_STATUSES.include?(candidate)
+      when Contractful::Exception
+        candidate.retryable?
+      else
+        network_errors.any? { |klass| candidate.is_a?(klass) }
+      end
+    end
+  end
+
+  # Create HTTP status exception classes
+  STATUSES.each_pair do |code, message|
+    klass = Class.new(RequestFailed) do
+      send(:define_method, :default_message) { "#{"#{http_code} " if http_code}#{message}" }
+    end
+    klass_constant = const_set(message.delete(' \-\''), klass)
+    Exceptions::EXCEPTIONS_MAP[code] = klass_constant
+  end
+
+  # Create HTTP status exception classes used for backwards compatibility
+  STATUSES_COMPATIBILITY.each_pair do |code, compat_list|
+    klass = Exceptions::EXCEPTIONS_MAP.fetch(code)
+    compat_list.each do |old_name|
+      const_set(old_name, klass)
+    end
+  end
+
+  module Exceptions
+    # We have to split the Exceptions module like we do here because the
+    # EXCEPTIONS_MAP is under Exceptions, but we depend on
+    # Contractful::RequestTimeout below.
+
+    # Base class for request timeouts.
+    #
+    # NB: Previous releases of contractful would raise RequestTimeout both for
+    # HTTP 408 responses and for actual connection timeouts.
+    class Timeout < Contractful::RequestTimeout
+      def initialize(message = nil, original_exception = nil)
+        super(nil, nil)
+        self.message = message if message
+        self.original_exception = original_exception if original_exception
+      end
+
+      # A network timeout never carries an HTTP status, so the status-based
+      # classification cannot see it — network timeouts are transient by
+      # definition.
+      def retryable?
+        true
+      end
+    end
+
+    # Timeout when connecting to a server. Typically wraps Net::OpenTimeout (in
+    # ruby 2.0 or greater).
+    class OpenTimeout < Timeout
+      def default_message
+        'Timed out connecting to server'
+      end
+    end
+
+    # Timeout when reading from a server. Typically wraps Net::ReadTimeout (in
+    # ruby 2.0 or greater).
+    class ReadTimeout < Timeout
+      def default_message
+        'Timed out reading data from server'
+      end
+    end
+
+    # Timeout when writing to a server. Typically wraps Net::WriteTimeout.
+    class WriteTimeout < Timeout
+      def default_message
+        'Timed out writing data to server'
+      end
+    end
+  end
+
+  # The server broke the connection prior to the request completing.  Usually
+  # this means it crashed, or sometimes that your network connection was
+  # severed before it could complete.
+  class ServerBrokeConnection < Contractful::Exception
+    def initialize(message = 'Server broke connection')
+      super(nil, nil)
+      self.message = message
+    end
+
+    def retryable?
+      true
+    end
+  end
+
+  # Raised when an HTTPS response fails certificate verification while
+  # verify_ssl is enabled.
+  class SSLCertificateNotVerified < Contractful::Exception
+    def initialize(message = 'SSL certificate not verified')
+      super(nil, nil)
+      self.message = message
+    end
+  end
+end

data/lib/contractful/notifications/active_support.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Optional bridge from contractful's internal notification hub to
+# ActiveSupport::Notifications (the Rails-ecosystem standard). Loading this
+# file — never loaded by <tt>require 'contractful'</tt> — forwards every
+# {Contractful::Notifications} event to AS::Notifications so Rails
+# subscribers, LogSubscribers and APM agents receive them natively:
+#
+#   require 'contractful'
+#   require 'contractful/notifications/active_support'
+#
+#   ActiveSupport::Notifications.subscribe(/^contractful\./) do |*args|
+#     event = ActiveSupport::Notifications::Event.new(*args)
+#     Rails.logger.info "#{event.name} #{event.payload.inspect} (#{event.duration}ms)"
+#   end
+#
+# Each event is forwarded as <tt>contractful.<name></tt> with the event
+# payload as instrument payload (plus the monotonic <tt>:at</tt> timestamp).
+# Unsubscribe from the internal hub with
+# <tt>Contractful::Notifications.clear!</tt> to detach the bridge.
+#
+# Requires the +activesupport+ gem (>= 6.0) at load time; it is an optional
+# integration and never a runtime dependency of the gem itself.
+
+# 'active_support' rather than just 'active_support/notifications': since
+# ActiveSupport 7.1 the notifications module depends on
+# IsolatedExecutionState and friends and is not self-sufficient standalone.
+begin
+  require 'active_support'
+rescue LoadError => e
+  raise LoadError,
+        "contractful's ActiveSupport bridge requires the activesupport gem " \
+        "(add `gem 'activesupport'` to your Gemfile): #{e.message}"
+end
+
+Contractful::Notifications.subscribe do |event|
+  ActiveSupport::Notifications.instrument(
+    "contractful.#{event[:name]}", **event[:payload], at: event[:at]
+  )
+end