contractful 0.1.0

data/lib/contractful/contract/auth.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Contractful
+  module Contract
+    # Authentication schemes declared on a contract-first client.
+    #
+    # The contract is the source of truth for HOW to authenticate; the
+    # client supplies only the credentials. Values may be literals or
+    # callables — callables are invoked on every request so short-lived
+    # tokens stay fresh:
+    #
+    #   auth bearer: -> { fetch_token }                       # Authorization: Bearer ...
+    #   auth api_key: { name: 'access-token', value: token }  # custom header
+    #   auth api_key: [                                       # multiple keys at once
+    #     { name: 'access-token', value: -> { token } },
+    #     { name: 'client-id',    value: client_id },
+    #   ]
+    #   auth basic: -> { [user, pass] }                       # Authorization: Basic ...
+    #
+    # api_key schemes can also live in the query string with
+    # <tt>in: :query</tt>.
+    #
+    # Auth is resolved right before the before_request callbacks run, so
+    # callbacks can still inspect or override the resolved credentials.
+    class Auth # rubocop:disable Metrics/ClassLength
+      VALID_LOCATIONS = %i[header query].freeze
+
+      attr_reader :schemes
+
+      def initialize(**schemes)
+        if schemes.empty?
+          raise InvalidDefinition,
+                'auth requires at least one scheme (bearer:, api_key:, basic: or token_provider:)'
+        end
+
+        @schemes = []
+        schemes.each do |name, value|
+          case name
+          when :bearer then add_bearer(value)
+          when :api_key then add_api_keys(value)
+          when :basic then add_basic(value)
+          when :token_provider then add_token_provider(value)
+          else
+            raise InvalidDefinition,
+                  "unknown auth scheme #{name.inspect} " \
+                  '(supported: :bearer, :api_key, :basic, :token_provider)'
+          end
+        end
+        freeze_scheme_values!
+      end
+
+      # Resolve the schemes against the current moment: callable values are
+      # invoked now, so tokens fetched per request are always fresh.
+      #
+      # @return [Hash] +{ headers: Hash, query: Hash }+ to merge into the
+      #   outgoing request
+      def resolve
+        headers = {}
+        query = {}
+        @schemes.each do |scheme|
+          case scheme[:scheme]
+          when :token_provider
+            token = scheme[:value].token
+            validate_resolved_credential!(token, :token_provider)
+            headers['Authorization'] = "Bearer #{token}"
+          when :bearer
+            token = credential(scheme[:value])
+            validate_resolved_credential!(token, :bearer)
+            headers['Authorization'] = "Bearer #{token}"
+          when :basic
+            user, pass = credential(scheme[:value])
+            # basic auth allows a blank password (RFC 7617), but a nil
+            # user or nil pass means the callable did not return a
+            # usable pair — refuse to send the request rather than
+            # emit a header the server will reject.
+            validate_resolved_credential!(user, :basic_user)
+            pass = pass.to_s
+            token = ["#{user}:#{pass}"].pack('m0')
+            headers['Authorization'] = "Basic #{token}"
+          when :api_key
+            value = credential(scheme[:value])
+            validate_resolved_credential!(value, :api_key)
+            if scheme[:location] == :query
+              query[scheme[:name].to_s] = value
+            else
+              headers[scheme[:name].to_s] = value
+            end
+          end
+        end
+        { headers: headers, query: query }
+      end
+
+      # Reject nil resolved credentials before they hit the wire.
+      # Without this guard, an unset ENV['API_TOKEN'] would let the
+      # request go out as `Authorization: Bearer ` (empty token) and a
+      # misconfigured basic callable returning `[nil, nil]` would emit
+      # `Basic Og==` (the base64 of `:`). Both look like valid auth to
+      # the server, which then 401s in a confusing way that hides the
+      # real cause (a missing environment variable or a typo'd callable).
+      def validate_resolved_credential!(value, kind)
+        return unless value.nil?
+        return if kind == :basic_user # allow empty user/pass on basic
+
+        raise Contractful::Contract::InvalidDefinition,
+              "resolved #{kind} credential is nil — check the " \
+              'callable or ENV var referenced by the auth scheme'
+      end
+
+      # The token provider object when the contract authenticates with
+      # <tt>auth token_provider:</tt>, otherwise nil. The executor uses this
+      # to drive the refresh-on-401 flow.
+      def token_provider
+        scheme = @schemes.find { |s| s[:scheme] == :token_provider }
+        scheme && scheme[:value]
+      end
+
+      def to_s
+        @schemes.map { |s| s[:scheme] }.uniq.join('+')
+      end
+
+      def inspect
+        "#<Contractful::Contract::Auth #{self}>"
+      end
+
+      private
+
+      def add_bearer(value)
+        validate_credential!(value, :bearer)
+        @schemes << { scheme: :bearer, value: value }
+      end
+
+      # A token provider is an object, not a callable: it must answer
+      # #token (the current credential) and #refresh (force a new token).
+      # The executor refreshes it in one flight when a 401 arrives.
+      def add_token_provider(value)
+        unless value.respond_to?(:token) && value.respond_to?(:refresh)
+          raise InvalidDefinition,
+                'auth token_provider: expects an object responding to ' \
+                '#token and #refresh, got ' + value.inspect
+        end
+        @schemes << { scheme: :token_provider, value: value }
+      end
+
+      def add_api_keys(value)
+        # Array() would explode a Hash into key/value pairs — normalize here.
+        entries = value.is_a?(Array) ? value : [value]
+        entries.each do |entry|
+          unless entry.is_a?(Hash)
+            raise InvalidDefinition,
+                  'auth api_key: expects a Hash {name:, value:, in:} or an ' \
+                  "Array of them, got #{entry.inspect}"
+          end
+          name = entry[:name] || entry['name']
+          unless name.is_a?(String) || name.is_a?(Symbol)
+            raise InvalidDefinition,
+                  "auth api_key: requires a name, got #{name.inspect}"
+          end
+          credential_value = entry[:value] || entry['value']
+          validate_credential!(credential_value, :api_key)
+          location = (entry[:in] || entry['in'] || :header).to_sym
+          unless VALID_LOCATIONS.include?(location)
+            raise InvalidDefinition,
+                  "auth api_key: in: must be :header or :query, got #{location.inspect}"
+          end
+          @schemes << { scheme: :api_key, name: name,
+                        value: credential_value, location: location }
+        end
+      end
+
+      def add_basic(value)
+        validate_credential!(value, :basic)
+        @schemes << { scheme: :basic, value: value }
+      end
+
+      def validate_credential!(value, scheme_name)
+        ok = value.is_a?(String) || value.is_a?(Symbol) ||
+             (value.is_a?(Array) && scheme_name == :basic) ||
+             value.respond_to?(:call)
+        return if ok
+
+        raise InvalidDefinition,
+              "auth #{scheme_name}: value must be a literal or a callable, " \
+              "got #{value.inspect}"
+        
+      end
+
+      def credential(value)
+        value.respond_to?(:call) ? value.call : value
+      end
+
+      # Basic-auth pairs are resolved lazily; everything else is frozen so a
+      # misconfigured literal fails fast.
+      def freeze_scheme_values!
+        @schemes.each do |scheme|
+          scheme[:value].freeze if scheme[:scheme] != :basic && scheme[:value].is_a?(String)
+        end
+        @schemes.freeze
+      end
+    end
+
+    # One-flight refresh coordination for token providers: concurrent 401s
+    # for the same provider never run #refresh concurrently — the first
+    # caller holds the per-provider mutex while refreshing, later callers
+    # block and then re-resolve the token (their #token call sees the
+    # new credential). Refreshes post a `token_refresh` notification.
+    #
+    # The previous implementation did NOT deduplicate: every caller that
+    # acquired the per-provider mutex ALSO called `provider.refresh`, so
+    # N concurrent 401s produced N sequential refresh calls (defeating
+    # the "one-flight" goal). Track a `@last_refreshed_at[provider]`
+    # timestamp inside the per-provider lock; later callers that arrive
+    # within the deduplication window skip the refresh call and just
+    # re-resolve via `provider.token`.
+    module TokenRefresh
+      @registry = {}
+      @last_refreshed_at = {}
+      @mutex = Mutex.new
+      DEDUP_WINDOW_SECONDS = 5
+
+      class << self
+        def refresh(provider)
+          lock = lock_for(provider)
+          lock.synchronize do
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            last = @last_refreshed_at[provider]
+            if last && (now - last) < DEDUP_WINDOW_SECONDS
+              # A refresh completed within the dedup window — skip the
+              # refresh call and re-resolve the token. The provider's
+              # implementation is responsible for returning a fresh
+              # token via #token.
+              token = provider.token
+            else
+              token = provider.refresh
+              @last_refreshed_at[provider] = now
+              Notifications.post('token_refresh',
+                                 provider: provider.class.name)
+            end
+            token
+          end
+        end
+
+        def clear!
+          @mutex.synchronize do
+            @registry.clear
+            @last_refreshed_at.clear
+          end
+        end
+
+        private
+
+        def lock_for(provider)
+          @mutex.synchronize { @registry[provider] ||= Mutex.new }
+        end
+      end
+    end
+  end
+end

data/lib/contractful/contract/config.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Contractful
+  module Contract
+    # Class-level configuration for contract-first clients.
+    #
+    # An instance lives on each class that includes {Contractful::Contract}
+    # (as <tt>@__contract_config</tt>) and is read by walking the superclass
+    # chain: scalar settings use nearest-definition-wins, while callbacks and
+    # contracts accumulate down the chain (see {DSL::ClassMethods}).
+    class Config
+      # Contract name (Symbol) => Definition
+      attr_reader :contracts
+
+      # { before_request: [...], after_response: [...] }
+      attr_reader :callbacks
+
+      # Scalars are nil until explicitly set, so that "unset" can be
+      # distinguished from every meaningful value (including false/{}).
+      attr_accessor :base_url
+      attr_reader :default_headers, :strict_params, :payload_style, :auth
+      attr_reader :idempotency_header, :idempotency_generator
+
+      def initialize
+        @contracts = {}
+        @callbacks = { before_request: [], after_response: [] }
+        @base_url = nil
+        @default_headers = nil
+        @strict_params = nil
+        @payload_style = nil
+        @auth = nil
+        @idempotency_header = nil
+        @idempotency_generator = nil
+      end
+
+
+      def default_headers=(headers)
+        unless headers.is_a?(Hash)
+          raise InvalidDefinition,
+                "default_headers must be a Hash, got #{headers.inspect}"
+        end
+        @default_headers = headers
+      end
+
+      def strict_params=(flag)
+        @strict_params = flag ? true : false
+      end
+
+      def payload_style=(style)
+        unless %i[json form query].include?(style.to_sym)
+          raise InvalidDefinition,
+                "invalid payload_style #{style.inspect} " \
+                '(expected :json, :form or :query)'
+        end
+        @payload_style = style.to_sym
+      end
+
+      def auth=(value)
+        unless value.nil? || value.is_a?(Auth) || value.equal?(false)
+          raise InvalidDefinition,
+                'auth must be a Contractful::Contract::Auth or false, ' \
+                "got #{value.inspect}"
+        end
+        @auth = value
+      end
+
+      def idempotency_header=(name)
+        unless name.is_a?(String) && !name.empty?
+          raise InvalidDefinition,
+                'idempotency_header must be a non-empty String, ' \
+                "got #{name.inspect}"
+        end
+        @idempotency_header = name
+      end
+
+      def idempotency_generator=(generator)
+        unless generator.respond_to?(:call)
+          raise InvalidDefinition,
+                'idempotency_generator must respond to #call, ' \
+                "got #{generator.inspect}"
+        end
+        @idempotency_generator = generator
+      end
+
+      def add_callback(kind, block)
+        raise InvalidDefinition, "unknown callback kind #{kind.inspect}" unless @callbacks.key?(kind)
+        raise InvalidDefinition, "callback #{kind} requires a block" unless block.is_a?(Proc)
+
+        @callbacks[kind] << block
+      end
+    end
+  end
+end

data/lib/contractful/contract/definition.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module Contractful
+  module Contract
+    # The definition of a single API operation — one "contract".
+    #
+    # A Definition is built from a request line (<tt>'POST /repos/:owner/:repo/issues'</tt>)
+    # plus an optional DSL block that is +instance_eval+'d against the
+    # definition object itself, so every statement in the block is a method
+    # call on the definition:
+    #
+    #   contract :create_issue, 'POST /repos/:owner/:repo/issues' do
+    #     param :owner, String, required: true
+    #     param :title, String, required: true
+    #     param :labels, Array, default: []
+    #   end
+    #
+    # Path placeholders (+:owner+, +:repo+) are automatically synthesized as
+    # required params unless they were explicitly declared.
+    class Definition
+      # A placeholder is +:name+. A colon written directly after a placeholder
+      # starts a literal suffix instead (group 2), so custom verbs such as
+      # '/things/:id:archive' (the Google-style '{id}:archive') keep their colon.
+      PATH_PLACEHOLDER = /:([a-zA-Z_][a-zA-Z0-9_]*)((?::[a-zA-Z_][a-zA-Z0-9_]*)?)/
+
+      VALID_VERBS = %i[get head post put patch delete options].freeze
+
+      # Symbol aliases for response body types. +:json+ means "must parse as
+      # JSON" without constraining the shape; +Array+/+Hash+ also parse and
+      # additionally check the parsed shape.
+      RESPONSE_TYPES = {
+        array: Array,
+        hash: Hash,
+        string: String,
+        json: :json
+      }.freeze
+
+      attr_reader :name, :verb, :path_template, :params, :description, :response_statuses, :response_type, :response_verifier, :response_fields
+      # Per-contract strict-params override (nil = inherit the class setting).
+      attr_reader :strict
+      # Contract-level auth opt-out (nil = inherit, false = disabled).
+      attr_reader :auth
+      # Idempotent flag (nil = not flagged).
+      attr_reader :idempotent
+      # Pagination declaration (nil = not paginated), see {Pagination}.
+      attr_reader :pagination
+
+      def initialize(name, verb, path_template, description: nil, &block)
+        @name = name.to_sym
+        @verb = verb.to_s.downcase.to_sym
+        @path_template = path_template.dup
+        @description = description
+        @params = {}
+        @payload_style = nil
+        @strict = nil
+        @response_fields = {}
+        @auth = nil
+        @idempotent = nil
+        @pagination = nil
+
+        validate_verb!
+        validate_path_template!
+        synthesize_path_params!
+
+        # The DSL block is instance_eval'd against the definition, so every
+        # statement inside it is a method call on this object. It runs after
+        # path-param synthesis so explicit declarations win.
+        instance_eval(&block) if block
+      end
+
+      # --- DSL surface (evaluated inside the contract block) -----------------
+
+      # Declare a parameter. See {Param} for the supported options.
+      def param(name, type = nil, **options)
+        key = name.to_sym
+        param = Param.new(key, type, **options)
+        if param.location && path_param_names.include?(key)
+          raise InvalidDefinition,
+                "path parameter :#{key} cannot also be a #{param.location} param for :#{@name}"
+        end
+
+        @params[key] = param
+      end
+
+      # Declare the payload style for non-query params:
+      # +:json+ (default for POST/PUT/PATCH), +:form+ or +:query+.
+      def payload_style(style = nil)
+        return @payload_style if style.nil?
+
+        unless %i[json form query].include?(style.to_sym)
+          raise InvalidDefinition,
+                "invalid payload_style #{style.inspect} for :#{@name} " \
+                '(expected :json, :form or :query)'
+        end
+        @payload_style = style.to_sym
+      end
+
+      # Per-contract strict-params override. Calling this inside a contract
+      # block wins over the class-level `strict_params` macro; generated
+      # (resource) contracts use it to stay open for free-form attributes.
+      def strict_params(flag = true)
+        @strict = flag ? true : false
+      end
+
+      # Declare the expected responses: one or more status codes (Integers or
+      # Ranges) and an optional body +type+ (Array, Hash, String, any class or
+      # the symbols :array/:hash/:string/:json).
+      #
+      # When the declared statuses include error codes (4xx/5xx), the default
+      # contractful exception behavior is suppressed for this contract and
+      # every response is judged by the contract instead; a status outside
+      # the declared set raises {UnexpectedResponse}.
+      def responds(*statuses, type: nil)
+        if statuses.empty?
+          raise InvalidDefinition,
+                "responds requires at least one status for :#{@name}"
+        end
+        statuses.each do |status|
+          next if valid_status?(status)
+
+          raise InvalidDefinition,
+                "invalid status #{status.inspect} for :#{@name} " \
+                '(expected an Integer or an Integer Range)'
+        end
+        @response_statuses = statuses.freeze
+        @response_type = normalize_response_type(type) if type
+      end
+
+      # Declare pagination for this collection contract. The pagination
+      # params (cursor/offset/limit) must also be declared as regular
+      # contract params. See {Pagination} for the styles and options.
+      def paginated(**options)
+        @pagination = Pagination.normalize!(options)
+      end
+
+      # Flag this contract as idempotent: the client will inject an
+      # idempotency key header on every call (default 'Idempotency-Key',
+      # see the class-level +idempotency_header+ / +idempotency_generator+),
+      # making automatic retries safe for non-GET operations.
+      def idempotent(flag = NO_DEFAULT)
+        return @idempotent if flag.equal?(NO_DEFAULT)
+
+        @idempotent = flag ? true : false
+      end
+
+      # Opt this contract out of the class-level auth: `auth false`. Called
+      # with no arguments it returns the current setting (nil = inherit,
+      # false = disabled).
+      def auth(flag = NO_DEFAULT)
+        return @auth if flag.equal?(NO_DEFAULT)
+
+        unless flag.equal?(false)
+          raise InvalidDefinition,
+                'contract-level auth only accepts false to opt out of the ' \
+                "class auth scheme; got #{flag.inspect}"
+        end
+        @auth = false
+      end
+
+      # Declare a field of the response payload. See {ResponseField} for the
+      # open-schema semantics: +required+ and +type+ bind, everything else is
+      # additive data. Response fields require the body to be a JSON object.
+      def response_field(name, type = nil, **options)
+        if @response_type.equal?(String)
+          raise InvalidDefinition,
+                'response_field cannot be used with a String response type ' \
+                "for :#{@name}"
+        end
+        key = name.to_sym
+        @response_fields[key] = ResponseField.new(key, type, **options)
+      end
+
+      # Register a custom assertion block. It receives the response (and the
+      # JSON-parsed body when declared with two parameters); a falsey return
+      # value raises {UnexpectedResponse}. Raising inside the block
+      # propagates untouched.
+      def verify_response(&block)
+        unless block
+          raise InvalidDefinition,
+                "verify_response requires a block for :#{@name}"
+        end
+        @response_verifier = block
+      end
+
+      # --- path handling -----------------------------------------------------
+
+      # Symbols referenced as +:placeholders+ in the path template.
+      def path_param_names
+        @path_param_names ||=
+          @path_template.scan(PATH_PLACEHOLDER).map { |m| m[0].to_sym }
+      end
+
+      # Expand the path template with (already coerced) +params+.
+      #
+      # @return [Array(String, Hash)] the expanded path and the remaining
+      #   params that were not consumed by placeholders
+      def expand_path(params)
+        remaining = params.dup
+        expanded = @path_template.gsub(PATH_PLACEHOLDER) do
+          key = Regexp.last_match(1).to_sym
+          suffix = Regexp.last_match(2)
+          unless remaining.key?(key)
+            raise MissingParam,
+                  "path param :#{key} is required by #{@path_template.inspect} " \
+                  'but was not provided'
+          end
+          escape_path_segment(remaining.delete(key)) + suffix
+        end
+        [expanded, remaining]
+      end
+
+      def escape_path_segment(value)
+        URI.encode_www_form_component(value.to_s).gsub('+', '%20')
+      end
+
+      # --- introspection -----------------------------------------------------
+
+      # One-line description, e.g. <tt>"POST /repos/:owner/:repo/issues (params: :owner, :repo, :title) responds 200, 404 => Hash"</tt>.
+      def describe
+        parts = ["#{verb.to_s.upcase} #{path_template}"]
+        parts << "(params: #{@params.keys.map { |k| ":#{k}" }.join(', ')})" if @params.any?
+        parts << "(fields: #{@response_fields.keys.map { |k| ":#{k}" }.join(', ')})" if @response_fields.any?
+        parts << 'idempotent' if @idempotent
+        parts << 'paginated' if @pagination
+        if @response_statuses
+          rendered = @response_statuses.map { |s| s.is_a?(Range) ? s.inspect : s.to_s }
+          response_part = "responds #{rendered.join(', ')}"
+          response_part << " => #{response_type_name}" if @response_type
+          parts << response_part
+        end
+        parts.join(' ')
+      end
+
+      def inspect
+        "#<Contractful::Contract::Definition #{describe}>"
+      end
+
+      # Human-readable name of the declared response body type (also used by
+      # the Executor when building violation messages).
+      def response_type_name
+        case @response_type
+        when :json then 'JSON'
+        when String then 'String'
+        else @response_type.name || 'anonymous class'
+        end
+      end
+
+      private
+
+      def validate_verb!
+        return if VALID_VERBS.include?(@verb)
+
+        raise InvalidDefinition,
+              "unsupported HTTP verb #{verb.to_s.inspect} for :#{@name} " \
+              "(supported: #{VALID_VERBS.join(', ')})"
+        
+      end
+
+      def valid_status?(status)
+        status.is_a?(Integer) ||
+          (status.is_a?(Range) && status.min.is_a?(Integer) && status.max.is_a?(Integer))
+      end
+
+      def normalize_response_type(type)
+        return RESPONSE_TYPES[type] if type.is_a?(Symbol) && RESPONSE_TYPES.key?(type)
+
+        return type if type.is_a?(Class)
+
+        raise InvalidDefinition,
+              "unsupported response type #{type.inspect} for :#{@name} " \
+              '(expected a Class or :array/:hash/:string/:json)'
+      end
+
+      def validate_path_template!
+        return if @path_template.start_with?('/')
+
+        raise InvalidDefinition,
+              "path template #{@path_template.inspect} for :#{@name} must " \
+              'start with "/" (it is resolved against the base URL)'
+        
+      end
+
+      # Every +:placeholder+ in the path template is implicitly a required
+      # String param unless the user declared it explicitly.
+      def synthesize_path_params!
+        path_param_names.each do |key|
+          next if @params.key?(key)
+
+          @params[key] = Param.new(key, nil, required: true,
+                                             description: 'path parameter (auto-synthesized)')
+        end
+      end
+    end
+  end
+end