weft-sdk 0.25.0 → 0.32.5

data/lib/weft/error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Weft
+  # Normalized buyer API error.
+  #
+  # The generated OpenAPI model already owns Weft::Error. This exception uses
+  # RequestError so the model and the raised error can both exist.
+  #
+  # `charge` says whether the failed call can have created a charge. 'none'
+  # covers this call only: an earlier call under the same idempotency key can
+  # still have paid. After 'possible', retry only with the same idempotency key
+  # and request.
+  class RequestError < StandardError
+    # Codes Weft raises before it signs a payment in that call. Same list as the
+    # TypeScript reference.
+    PRE_SIGN_FETCH_CODES = %w[
+      EXCEEDED_MAX_COST MERCHANT_RETURNED_NON_402 INSUFFICIENT_BALANCE
+      DENYLISTED_RECIPIENT WALLET_ENVIRONMENT_MISMATCH UNSUPPORTED_ASSET
+      INVALID_REQUEST UNKNOWN_PARAMETER INVALID_URL INVALID_MAX_COST_USD
+      UNSUPPORTED_METHOD INVALID_BODY INVALID_HEADERS INVALID_IDEMPOTENCY_KEY
+    ].freeze
+
+    attr_reader :status, :code, :request_id, :retryable, :details, :charge
+
+    # @api private
+    def self.fetch_charge(status, code)
+      pre_sign = PRE_SIGN_FETCH_CODES.include?(code) || code.to_s.start_with?('POLICY_VIOLATION_')
+      status.between?(400, 499) && pre_sign ? 'none' : 'possible'
+    end
+
+    def initialize(status:, code:, message:, request_id: nil, retryable: false, details: nil, charge: 'possible')
+      super(message)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @retryable = retryable
+      @details = details
+      @charge = charge
+    end
+  end
+end

data/lib/weft/facilitator/client.rb

@@ -1,88 +1,300 @@
-require 'net/http'
+# frozen_string_literal: true
+
 require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'handshake'
+require_relative 'json_wire'
+require_relative 'settlement'
 
 module Weft
   module Facilitator
-    DEFAULT_URL = 'https://x402.weft.network'.freeze
-    DEFAULT_ENV = 'X402_FACILITATOR_URL'.freeze
+    DEFAULT_URL = 'https://x402.weft.network'
+    DEFAULT_ENV = 'X402_FACILITATOR_URL'
+    PATH_KEYS = %w[verify settle supported bazaar].freeze
+    SUPPORTED_RETRIES = 3
+    DEFAULT_TIMEOUT_MS = 30_000
+
+    module_function
+
+    def resolve_url(config = nil)
+      url = config_url(config)
+      return url unless url.nil? || url.empty?
+
+      env = ENV.fetch(DEFAULT_ENV, nil)
+      return env unless env.nil? || env.empty?
+
+      DEFAULT_URL
+    end
+
+    def validate_url(url)
+      if url.nil? || url.strip.empty?
+        raise ArgumentError, 'Invalid URL: URL cannot be empty'
+      end
+      return if url.start_with?('http://') || url.start_with?('https://')
+
+      raise ArgumentError,
+            "Invalid URL format: URL must start with http:// or https://, got: #{url}"
+    end
+
+    def config_url(config)
+      return nil unless config.is_a?(Hash)
+      return config['url'] if config.key?('url')
+      return config[:url] if config.key?(:url)
+
+      nil
+    end
+
+    def merge_seller_wins(derived, seller)
+      merged = derived.dup
+      (seller || {}).each do |name, value|
+        merged.delete_if { |existing, _| existing.to_s.casecmp?(name.to_s) }
+        merged[name.to_s] = value
+      end
+      merged
+    end
+
+    def assert_path_keyed_auth_headers(headers)
+      return unless headers.is_a?(Hash)
+
+      header_object = lambda do |value|
+        value.is_a?(Hash)
+      end
+      has_path_key = PATH_KEYS.any? { |key| header_object.call(headers[key] || headers[key.to_sym]) }
+      looks_flat = !has_path_key && headers.values.any? { |value| !header_object.call(value) }
+      return unless looks_flat
+
+      raise ArgumentError,
+            'createAuthHeaders must return an object keyed by facilitator path, ' \
+            'e.g. { verify: { Authorization: "..." }, settle: { ... }, ' \
+            'supported: { ... } }, but received a flat headers object.'
+    end
+
+    # /supported is also the identity handshake: a call with a valid key makes
+    # the facilitator record an sdk_handshake. A seller that builds the
+    # middleware per request would otherwise handshake per request, so the
+    # result is shared per process for each (url, handshake headers) key. A
+    # success is reused for TTL_S; a failure for FAILURE_FLOOR_S, so an outage
+    # cannot turn construction rate into facilitator request rate. Concurrent
+    # callers share one call. Ruby keeps the state across fork: a worker forked
+    # after the call reuses it, a worker forked before makes its own one call.
+    module SharedSupported
+      TTL_S = 6 * 60 * 60
+      FAILURE_FLOOR_S = 30
+      CONSTRUCTION_WARN_THRESHOLD = 10
+
+      Entry = Struct.new(:mutex, :at, :value, :error)
+
+      @entries = {}
+      @mutex = Mutex.new
+      @constructions = 0
+      @clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+      class << self
+        # Replaceable clock in seconds. Tests use it.
+        attr_accessor :clock
+
+        def fetch(key)
+          entry = @mutex.synchronize { @entries[key] ||= Entry.new(Mutex.new) }
+          entry.mutex.synchronize do
+            age = entry.at && (@clock.call - entry.at)
+            raise entry.error if entry.error && age < FAILURE_FLOOR_S
+            return entry.value if entry.error.nil? && entry.at && age < TTL_S
+
+            begin
+              value = yield
+              entry.value = value
+              entry.error = nil
+              value
+            rescue StandardError => e
+              entry.value = nil
+              entry.error = e
+              raise
+            ensure
+              entry.at = @clock.call
+            end
+          end
+        end
+
+        # Warn once per process when the middleware is built over and over.
+        def note_construction
+          count = @mutex.synchronize { @constructions += 1 }
+          return unless count == CONSTRUCTION_WARN_THRESHOLD + 1
+
+          warn "[weft] the payment middleware was constructed more than #{CONSTRUCTION_WARN_THRESHOLD} " \
+               'times. Construct it once at startup and reuse it; do not build it per request.'
+        end
+
+        # Forget every shared result and the construction count. Tests use it.
+        def reset!
+          @mutex.synchronize do
+            @entries = {}
+            @constructions = 0
+          end
+        end
+      end
+    end
 
     class Client
-      def initialize(url: nil, create_headers: nil)
-        @url = resolve_url(url)
-        validate_url(@url)
+      # share_headers: the SDK handshake headers for /supported. When given,
+      # /supported is shared per process for (url, share_headers).
+      def initialize(url: nil, create_headers: nil, timeout_ms: DEFAULT_TIMEOUT_MS, share_headers: nil)
+        resolved = Facilitator.resolve_url(url.nil? ? nil : { 'url' => url })
+        Facilitator.validate_url(resolved)
+        @url = trim_trailing_slashes(resolved)
         @create_headers = create_headers
+        @timeout_ms = timeout_ms
+        @share_key = share_headers && "#{@url}\n#{JSON.generate(share_headers.sort.to_h)}"
+      end
+
+      def trim_trailing_slashes(value)
+        text = value.dup
+        text.chomp!('/') while text.end_with?('/')
+        text
       end
 
       def verify(payment_payload:, payment_requirements:)
-        post_json('/verify', {
-                    x402Version: 2,
-                    paymentPayload: payment_payload,
-                    paymentRequirements: payment_requirements
+        post_json('/verify', 'verify', {
+                    'x402Version' => payment_payload['x402Version'] || payment_payload[:x402Version] || 2,
+                    'paymentPayload' => payment_payload,
+                    'paymentRequirements' => payment_requirements
                   })
       end
 
       def settle(payment_payload:, payment_requirements:)
-        post_json('/settle', {
-                    x402Version: 2,
-                    paymentPayload: payment_payload,
-                    paymentRequirements: payment_requirements
-                  })
+        settle_once(payment_payload, payment_requirements, allow_retry: true)
       end
 
       def supported
-        get_json('/supported')
+        return fetch_supported unless @share_key
+
+        SharedSupported.fetch(@share_key) { fetch_supported }
+      end
+
+      def fetch_supported
+        last_error = nil
+        SUPPORTED_RETRIES.times do |attempt|
+          begin
+            return get_json('/supported', 'supported')
+          rescue RateLimited => e
+            last_error = e
+            sleep(e.retry_after) if attempt < SUPPORTED_RETRIES - 1
+          end
+        end
+        raise last_error || StandardError, 'Facilitator getSupported failed'
       end
+      private :fetch_supported
 
       private
 
-      def resolve_url(url)
-        return url if url && !url.empty?
+      def settle_once(payment_payload, payment_requirements, allow_retry:)
+        result = post_json('/settle', 'settle', {
+                              'x402Version' => payment_payload['x402Version'] || payment_payload[:x402Version] || 2,
+                              'paymentPayload' => payment_payload,
+                              'paymentRequirements' => payment_requirements
+                            })
+        if allow_retry && pending_result?(result)
+          return settle_once(payment_payload, payment_requirements, allow_retry: false)
+        end
 
-        env = ENV.fetch(DEFAULT_ENV, nil)
-        return env if env && !env.empty?
+        result
+      rescue SettleError => e
+        if allow_retry && pending_error?(e)
+          return settle_once(payment_payload, payment_requirements, allow_retry: false)
+        end
+        raise FacilitatorUnavailableError if SettleErrors.unavailable?(e)
 
-        DEFAULT_URL
+        raise
       end
 
-      def validate_url(url)
-        return unless url.empty? || (!url.start_with?('http://') && !url.start_with?('https://'))
+      def pending_result?(result)
+        result.is_a?(Hash) && result['success'] == false &&
+          result['errorReason'] == 'settlement_pending' && !result['transaction'].to_s.empty?
+      end
 
-        raise ArgumentError, "Invalid URL: #{url}"
+      def pending_error?(error)
+        error.error_reason == 'settlement_pending' && !error.transaction.to_s.empty?
       end
 
-      def build_headers(scope)
+      def headers_for(scope)
         headers = { 'Content-Type' => 'application/json' }
         return headers unless @create_headers
 
         custom = @create_headers.call
-        scope_headers = custom && custom[scope]
+        Facilitator.assert_path_keyed_auth_headers(custom) if custom
+        scope_headers = custom.is_a?(Hash) ? (custom[scope] || custom[scope.to_sym]) : nil
         headers.merge(scope_headers || {})
       end
 
-      def get_json(path)
-        uri = URI.join(@url, path)
-        request = Net::HTTP::Get.new(uri, build_headers('supported'))
-        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+      def get_json(path, scope)
+        uri = URI.parse("#{@url}#{path}")
+        request = Net::HTTP::Get.new(uri)
+        headers_for(scope).each { |name, value| request[name] = value }
+        response = perform(uri, request)
+        parse_response(response, scope)
+      end
+
+      def post_json(path, scope, body)
+        uri = URI.parse("#{@url}#{path}")
+        request = Net::HTTP::Post.new(uri)
+        headers_for(scope).each { |name, value| request[name] = value }
+        request.body = JsonWire.generate(body)
+        response = perform(uri, request)
+        parse_response(response, scope)
+      end
+
+      def perform(uri, request)
+        Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == 'https',
+          open_timeout: @timeout_ms / 1000.0,
+          read_timeout: @timeout_ms / 1000.0
+        ) do |http|
           http.request(request)
         end
-        parse_response(response)
       end
 
-      def post_json(path, body)
-        uri = URI.join(@url, path)
-        scope = path.include?('verify') ? 'verify' : 'settle'
-        request = Net::HTTP::Post.new(uri, build_headers(scope))
-        request.body = JSON.generate(body)
-        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
-          http.request(request)
+      def parse_response(response, scope)
+        return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
+
+        text = response.body.to_s
+        data = begin
+          JSON.parse(text)
+        rescue JSON::ParserError
+          nil
+        end
+        if scope == 'settle' && data.is_a?(Hash) && data.key?('success')
+          raise SettleError.new(response.code.to_i, data)
         end
-        parse_response(response)
+        if scope == 'verify' && data.is_a?(Hash) && data.key?('isValid')
+          raise StandardError, verify_failure_message(response.code, data)
+        end
+        raise RateLimited.new(response['retry-after']) if response.code.to_i == 429
+
+        excerpt = text.length > 200 ? "#{text[0, 200]}..." : text
+        raise StandardError, "Facilitator #{scope_name(scope)} failed (#{response.code}): #{excerpt}"
+      end
+
+      def scope_name(scope)
+        scope == 'supported' ? 'getSupported' : scope
       end
 
-      def parse_response(response)
-        raise "Facilitator request failed: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+      def verify_failure_message(code, data)
+        reason = data['invalidReason'] || 'unknown reason'
+        message = data['invalidMessage']
+        message ? "#{reason}: #{message}" : reason.to_s
+      end
+    end
+
+    class RateLimited < StandardError
+      attr_reader :retry_after
 
-        JSON.parse(response.body)
+      def initialize(header)
+        @retry_after = header.to_i
+        @retry_after = 1 if @retry_after <= 0
+        super('Facilitator getSupported failed (429)')
       end
     end
   end

data/lib/weft/facilitator/echo.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Weft
+  module Facilitator
+    module Echo
+      ADDITIVE_ARRAY_INFO_FIELDS = { 'builder-code' => ['s'] }.freeze
+      ADDITIVE_ARRAY_MAX_LENGTHS = { 'builder-code' => { 's' => 10 } }.freeze
+
+      module_function
+
+      def validate(payment_required, payment, dynamic_fields: {})
+        return { 'valid' => true } unless payment.is_a?(Hash) && payment['x402Version'] == 2
+
+        server_extensions = payment_required['extensions']
+        return { 'valid' => true } unless server_extensions.is_a?(Hash) && !server_extensions.empty?
+
+        client_extensions = payment['extensions']
+        return { 'valid' => true } unless client_extensions.is_a?(Hash) && !client_extensions.empty?
+
+        client_extensions.each do |key, echoed|
+          next unless server_extensions.key?(key)
+
+          fields = dynamic_fields[key]
+          advertised = omit_fields(extension_info(server_extensions[key]), fields)
+          echoed_info = omit_fields(extension_info(echoed), fields)
+          additive = ADDITIVE_ARRAY_INFO_FIELDS[key]
+          limits = ADDITIVE_ARRAY_MAX_LENGTHS[key]
+          next if contains_subset?(advertised, echoed_info, additive, limits)
+
+          return { 'valid' => false, 'invalidReason' => 'extension_echo_mismatch', 'extensionKey' => key }
+        end
+        { 'valid' => true }
+      end
+
+      def extension_info(value)
+        return value['info'] if value.is_a?(Hash) && value.key?('info')
+
+        value
+      end
+
+      def omit_fields(value, fields)
+        return value if fields.nil? || fields.empty? || !value.is_a?(Hash)
+
+        copy = value.dup
+        fields.each { |field| copy.delete(field) }
+        copy
+      end
+
+      def contains_subset?(expected, actual, additive = nil, max_lengths = nil, field_key = nil)
+        if field_key && additive&.include?(field_key) && (expected.is_a?(Array) || actual.is_a?(Array))
+          expected_array = comparable_array(expected)
+          actual_array = comparable_array(actual)
+          return false unless expected_array && actual_array
+
+          max = max_lengths && max_lengths[field_key]
+          return false if max && actual_array.length > max
+
+          return expected_array.all? { |item| actual_array.any? { |other| deep_equal?(item, other) } }
+        end
+        return deep_equal?(expected, actual) if expected.nil? || !expected.is_a?(Hash)
+        return false unless actual.is_a?(Hash)
+
+        expected.all? do |key, value|
+          if actual.key?(key)
+            contains_subset?(value, actual[key], additive, max_lengths, key)
+          else
+            value.nil?
+          end
+        end
+      end
+
+      def comparable_array(value)
+        return value if value.is_a?(Array)
+        return nil if value.nil? || value.is_a?(Hash)
+
+        [value]
+      end
+
+      def deep_equal?(left, right)
+        return true if left.nil? && right.nil?
+        return false if left.nil? || right.nil?
+
+        case left
+        when Hash
+          return false unless right.is_a?(Hash)
+          return false unless left.keys.map(&:to_s).sort == right.keys.map(&:to_s).sort
+
+          left.all? { |key, value| deep_equal?(value, right[key] || right[key.to_s]) }
+        when Array
+          return false unless right.is_a?(Array) && left.length == right.length
+
+          left.zip(right).all? { |item, other| deep_equal?(item, other) }
+        else
+          left == right
+        end
+      end
+    end
+  end
+end

data/lib/weft/facilitator/extensions.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative 'json_wire'
+require_relative 'product'
+
+module Weft
+  module Facilitator
+    WEFT_REQUEST_EXTENSION_KEY = 'weft.request'
+    MAX_EXTENSION_BYTES = 16 * 1024
+    WEFT_REQUEST_INFO_SCHEMA = {
+      '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+      'title' => 'Weft per-request context',
+      'description' => 'Seller-authored context for one paid request, for display only. ' \
+                       'Unauthenticated buyer input by the time it is read; key nothing on it.',
+      'type' => 'object',
+      'additionalProperties' => true
+    }.freeze
+
+    module Extensions
+      module_function
+
+      def dynamic_extension(key, sink = nil)
+        sink ||= Product.create_warn
+        Hook.new(key, sink)
+      end
+
+      def register_dynamic_extensions(server, routes)
+        keys = dynamic_keys(routes)
+        return if keys.empty?
+
+        sink = Product.create_warn
+        unless server.respond_to?(:register_extension)
+          sink.call(
+            'this @x402/core build has no registerExtension, so per-request route ' \
+            "extensions (#{keys.join(', ')}) cannot be resolved and will not ship"
+          )
+          return
+        end
+
+        keys.each { |key| server.register_extension(dynamic_extension(key, sink)) }
+      end
+
+      def dynamic_keys(routes)
+        keys = []
+        route_configs(routes).each do |config|
+          extensions = Product.read(config, 'extensions')
+          next unless extensions.is_a?(Hash)
+
+          extensions.each do |key, value|
+            keys << key.to_s if value.respond_to?(:call)
+          end
+        end
+        keys.uniq
+      end
+
+      def route_configs(routes)
+        return [] unless routes.is_a?(Hash)
+
+        configs = Product.single_route?(routes) ? [routes] : routes.values
+        configs.select { |config| config.is_a?(Hash) }
+      end
+    end
+
+    class Hook
+      attr_reader :key
+
+      def initialize(key, sink)
+        @key = key
+        @sink = sink
+      end
+
+      def enrich_payment_required_response(declaration, context)
+        return nil unless declaration.respond_to?(:call)
+
+        request = request_of(context)
+        unless request
+          @sink.call(
+            "extensions[#{@key}] is a callback but no HTTP request context " \
+            'reached it; dropping the key from the challenge',
+            "#{@key}:no-request"
+          )
+          return drop_key(context)
+        end
+
+        begin
+          resolved = declaration.call(request)
+        rescue StandardError => e
+          @sink.call(
+            "extensions[#{@key}] callback failed; dropping the key from the " \
+            "challenge: #{e.message}",
+            "#{@key}:threw"
+          )
+          return drop_key(context)
+        end
+
+        return drop_key(context) if resolved.nil?
+
+        json = JsonWire.generate(resolved)
+        if json.nil?
+          @sink.call(
+            "extensions[#{@key}] callback returned a value JSON cannot carry (a " \
+            'function, a circular reference, a BigInt or similar); dropping ' \
+            'the key from the challenge',
+            "#{@key}:unserializable"
+          )
+          return drop_key(context)
+        end
+
+        wire = JSON.parse(json)
+        unless wire.is_a?(Hash)
+          @sink.call(
+            "extensions[#{@key}] callback returned #{wire.is_a?(Array) ? 'an array' : "a #{js_type(wire)}"}; " \
+            'the x402 extensions channel carries objects, so the key is ' \
+            'dropped from the challenge',
+            "#{@key}:not-an-object"
+          )
+          return drop_key(context)
+        end
+
+        value = if @key == WEFT_REQUEST_EXTENSION_KEY
+                  { 'info' => wire, 'schema' => WEFT_REQUEST_INFO_SCHEMA }
+                else
+                  wire
+                end
+        bytes = projected_bytes(context, value) || json.bytesize
+        if bytes > MAX_EXTENSION_BYTES
+          @sink.call(
+            "extensions[#{@key}] takes the challenge's extensions to #{bytes} " \
+            "bytes, over the #{MAX_EXTENSION_BYTES}-byte facilitator relay " \
+            'cap; dropping the key so the rest of the declaration still ' \
+            'reaches settlement',
+            "#{@key}:over-cap"
+          )
+          return drop_key(context)
+        end
+
+        value
+      end
+
+      private
+
+      def request_of(context)
+        transport = read_context(context, 'transportContext')
+        return nil unless transport.is_a?(Hash)
+
+        Product.read(transport, 'request')
+      end
+
+      def drop_key(context)
+        response = read_context(context, 'paymentRequiredResponse')
+        extensions = response.is_a?(Hash) ? Product.read(response, 'extensions') : nil
+        if extensions.is_a?(Hash)
+          extensions.delete(@key)
+          extensions.delete(@key.to_sym)
+        end
+        nil
+      end
+
+      def projected_bytes(context, value)
+        response = read_context(context, 'paymentRequiredResponse')
+        extensions = response.is_a?(Hash) ? Product.read(response, 'extensions') : nil
+        projected = Product.stringify_hash(extensions || {})
+        projected[@key] = value
+        json = JsonWire.generate(projected)
+        json&.bytesize
+      end
+
+      def read_context(context, key)
+        Product.read(context, key)
+      end
+
+      def js_type(value)
+        case value
+        when String then 'string'
+        when Integer, Float then 'number'
+        when TrueClass, FalseClass then 'boolean'
+        when nil then 'object'
+        else 'object'
+        end
+      end
+    end
+  end
+end