nfe-io 0.3.1 → 1.0.0

data/lib/nfe/http/net_http.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "openssl"
+require "zlib"
+require "stringio"
+
+module Nfe
+  module Http
+    # Default, zero-dependency HTTP transport built on the Ruby standard library
+    # (+net/http+, +uri+, +openssl+, +zlib+, +stringio+). It satisfies the
+    # {Nfe::Http::Transport} contract: it returns 4xx/5xx as ordinary
+    # {Nfe::Http::Response} objects, raises only {Nfe::ApiConnectionError} (or its
+    # subclass {Nfe::TimeoutError}) on network failure, and never follows a
+    # redirect or 202.
+    #
+    # Connections are pooled per origin (<tt>"host:port"</tt>) and kept alive for
+    # TCP/TLS reuse. The pool is guarded by a +Mutex+ and follows a
+    # checkout/check-in model: a connection is removed from the idle list while a
+    # request is in flight and only returned afterwards. A single instance is
+    # therefore safe to share across threads (Rails/Sidekiq/Puma): two in-flight
+    # requests never share the same socket, and a connection broken by a network
+    # error is closed instead of being returned to the pool.
+    #
+    # TLS is always enforced for +https+ origins with
+    # +OpenSSL::SSL::VERIFY_PEER+; verification is never disabled. An optional
+    # +ca_file+ provides an escape hatch for a legacy CA store.
+    class NetHttp
+      # Seconds an idle pooled connection is kept open for reuse.
+      KEEP_ALIVE_TIMEOUT = 30
+
+      def initialize(default_open_timeout: 10, default_read_timeout: 60, ca_file: nil)
+        @default_open_timeout = default_open_timeout
+        @default_read_timeout = default_read_timeout
+        @ca_file = ca_file
+        @pool = {}
+        @mutex = Mutex.new
+      end
+
+      # Executes +request+ and returns an {Nfe::Http::Response}. Raises
+      # {Nfe::TimeoutError} on open/read timeout and {Nfe::ApiConnectionError} on
+      # any other network-level failure.
+      def call(request)
+        uri = URI.parse(request.url)
+        key = origin_key(uri)
+        http = nil
+        begin
+          # checkout starts the connection (http.start), which can itself raise a
+          # network error (e.g. ECONNREFUSED) — keep it inside the rescue.
+          http = checkout(key, uri, request)
+          net_response = http.request(build_net_request(uri, request))
+          checkin(key, http)
+          build_response(net_response)
+        rescue Timeout::Error => e
+          # Net::OpenTimeout and Net::ReadTimeout both descend from Timeout::Error.
+          discard(http) if http
+          raise Nfe::TimeoutError, e.message
+        rescue SocketError, SystemCallError, OpenSSL::SSL::SSLError,
+               Net::HTTPBadResponse, IOError => e
+          # IOError covers EOFError; SystemCallError covers all Errno::* errors.
+          discard(http) if http
+          raise Nfe::ApiConnectionError, e.message
+        end
+      end
+
+      private
+
+      # Removes an idle connection for +key+ from the pool (or builds a fresh,
+      # started one) and hands it to the caller. While the connection is in flight
+      # it is owned exclusively by this call and absent from the pool, so no other
+      # thread can use the same socket concurrently. Timeouts are applied per call.
+      def checkout(key, uri, request)
+        http = @mutex.synchronize { (@pool[key] ||= []).pop } || build_connection(uri)
+        apply_timeouts(http, request)
+        http.start unless http.started?
+        http
+      end
+
+      # Returns a healthy connection to the idle list for reuse.
+      def checkin(key, http)
+        @mutex.synchronize { (@pool[key] ||= []) << http }
+      end
+
+      # Closes a connection broken by a network error so it is never reused.
+      def discard(http)
+        http.finish if http.started?
+      rescue IOError, SystemCallError
+        # Socket already torn down; nothing left to close.
+      end
+
+      def build_connection(uri)
+        http = Net::HTTP.new(uri.host.to_s, uri.port)
+        http.keep_alive_timeout = KEEP_ALIVE_TIMEOUT
+        configure_tls(http, uri)
+        http
+      end
+
+      def configure_tls(http, uri)
+        return unless uri.scheme == "https"
+
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.ca_file = @ca_file if @ca_file
+      end
+
+      def apply_timeouts(http, request)
+        http.open_timeout = request.open_timeout || @default_open_timeout
+        http.read_timeout = request.read_timeout || @default_read_timeout
+      end
+
+      def origin_key(uri)
+        "#{uri.host}:#{uri.port}"
+      end
+
+      # Builds the appropriate Net::HTTP request object, copying headers and body
+      # from the {Nfe::Http::Request} and defaulting +Accept-Encoding: gzip+ when
+      # the caller has not set it.
+      def build_net_request(uri, request)
+        net_request = request_class(request.method).new(uri)
+        request.headers.each { |name, value| net_request[name.to_s] = value }
+        net_request["Accept-Encoding"] = "gzip" unless accept_encoding_set?(request.headers)
+        net_request.body = request.body unless request.body.nil?
+        net_request
+      end
+
+      def accept_encoding_set?(headers)
+        headers.any? { |name, _| name.to_s.downcase == "accept-encoding" }
+      end
+
+      def request_class(method)
+        case method.to_s.upcase
+        when "GET"    then Net::HTTP::Get
+        when "POST"   then Net::HTTP::Post
+        when "PUT"    then Net::HTTP::Put
+        when "DELETE" then Net::HTTP::Delete
+        when "HEAD"   then Net::HTTP::Head
+        else raise Nfe::ApiConnectionError, "Unsupported HTTP method: #{method}"
+        end
+      end
+
+      # Maps a Net::HTTPResponse into an {Nfe::Http::Response}: integer status,
+      # lowercase headers (multi-value joined with ", "), and a binary body. A
+      # gzip body is inflated transparently. Redirects and 202 are not followed.
+      def build_response(net_response)
+        status = net_response.code.to_i
+        headers = normalize_headers(net_response)
+        body = (net_response.body || "").dup.force_encoding(Encoding::ASCII_8BIT)
+        body, headers = decompress(body, headers)
+        Nfe::Http::Response.new(status: status, headers: headers, body: body)
+      end
+
+      def normalize_headers(net_response)
+        headers = {} #: Hash[String, String]
+        net_response.each_capitalized do |name, value|
+          key = name.downcase
+          headers[key] = headers.key?(key) ? "#{headers[key]}, #{value}" : value
+        end
+        headers
+      end
+
+      # Inflates a gzip body and drops the now-stale +content-encoding+ and
+      # +content-length+ headers. On a malformed stream the raw body is kept and a
+      # warning is emitted, never raising.
+      def decompress(body, headers)
+        return [body, headers] unless headers["content-encoding"].to_s.downcase.include?("gzip")
+
+        inflated = Zlib::GzipReader.new(StringIO.new(body)).read.to_s.force_encoding(Encoding::ASCII_8BIT)
+        cleaned = headers.dup
+        cleaned.delete("content-encoding")
+        cleaned.delete("content-length")
+        [inflated, cleaned]
+      rescue Zlib::Error => e
+        warn("Nfe::Http::NetHttp: failed to inflate gzip response body: #{e.message}")
+        [body, headers]
+      end
+    end
+  end
+end

data/lib/nfe/http/redactor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Http
+    # Replaces the values of sensitive headers with +"[REDACTED]"+ before they
+    # reach a log line, so an API key, bearer token, or idempotency key never
+    # appears verbatim in transport logs.
+    #
+    # A header is considered sensitive when its (case-insensitive) name is one of
+    # +x-nfe-apikey+, +authorization+, +idempotency-key+, or matches
+    # <tt>/secret|apikey|token/i</tt>. Benign headers are returned unchanged.
+    module Redactor
+      REDACTED = "[REDACTED]"
+
+      # Exact (case-insensitive) header names that are always redacted.
+      SENSITIVE_NAMES = %w[x-nfe-apikey authorization idempotency-key].freeze
+
+      # Substring pattern matched against header names.
+      SENSITIVE_PATTERN = /secret|apikey|token/i
+
+      module_function
+
+      # Returns a new Hash with the values of sensitive keys replaced by
+      # +"[REDACTED]"+. The input hash is never mutated; benign keys keep their
+      # original value and casing.
+      def headers(hash)
+        return hash unless hash.respond_to?(:each_pair)
+
+        redacted = {} #: Hash[untyped, untyped]
+        hash.each_pair { |key, value| redacted[key] = sensitive?(key) ? REDACTED : value }
+        redacted
+      end
+
+      # Returns +true+ when a header named +key+ must have its value redacted.
+      def sensitive?(key)
+        name = key.to_s.downcase
+        SENSITIVE_NAMES.include?(name) || SENSITIVE_PATTERN.match?(name)
+      end
+    end
+  end
+end

data/lib/nfe/http/request.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Nfe
+  module Http
+    # Immutable value object describing a single outbound HTTP request.
+    #
+    # A +Request+ is transport-agnostic: it carries everything a transport needs
+    # to perform one HTTP call, including its own +base_url+ (enabling multi-host
+    # routing) and optional per-call timeout overrides. Headers, query, and body
+    # are supplied verbatim; the transport is responsible for wire encoding.
+    #
+    #   request = Nfe::Http::Request.new(
+    #     method: "GET",
+    #     base_url: "https://api.nfse.io",
+    #     path: "/v2/companies/abc/productinvoices",
+    #     query: { environment: "Production", limit: 50 }
+    #   )
+    #   request.url # => ".../productinvoices?environment=Production&limit=50"
+    #
+    # The +method+ member intentionally exposes the HTTP verb as +request.method+;
+    # it shadows +Object#method+, which the value object never relies on.
+    class Request < Data.define(
+      :method, :base_url, :path, :headers, :query, :body,
+      :open_timeout, :read_timeout, :idempotency_key
+    )
+      # @param method [String] HTTP method (e.g. "GET", "POST").
+      # @param base_url [String] origin + optional prefix (e.g. "https://api.nfse.io").
+      # @param path [String] request path (e.g. "/v2/companies").
+      # @param headers [Hash] request headers, sent verbatim by the transport.
+      # @param query [Hash] query parameters; array values become repeated keys.
+      # @param body [String, nil] raw request body, or nil.
+      # @param open_timeout [Numeric, nil] per-call connect timeout override.
+      # @param read_timeout [Numeric, nil] per-call read timeout override.
+      # @param idempotency_key [String, nil] optional key; makes a POST retry-eligible.
+      def initialize(method:, base_url:, path:, headers: {}, query: {}, body: nil,
+                     open_timeout: nil, read_timeout: nil, idempotency_key: nil)
+        super
+      end
+
+      # Composes the final URL from +base_url+, +path+, and the URL-encoded +query+.
+      #
+      # A trailing slash on +base_url+ is stripped. When +query+ is non-empty the
+      # encoded form is appended with "?" (or "&" when +path+ already contains a
+      # "?"). Array query values are emitted as repeated keys.
+      #
+      # @return [String]
+      def url
+        base = base_url.chomp("/") + path
+        return base if query.nil? || query.empty?
+
+        separator = base.include?("?") ? "&" : "?"
+        "#{base}#{separator}#{URI.encode_www_form(query)}"
+      end
+
+      # Whether this request is safe to retry.
+      #
+      # @return [Boolean] true for GET/HEAD/PUT/DELETE (case-insensitive) or any
+      #   request carrying a non-nil +idempotency_key+.
+      def idempotent?
+        return true unless idempotency_key.nil?
+
+        %w[GET HEAD PUT DELETE].include?(method.to_s.upcase)
+      end
+    end
+  end
+end

data/lib/nfe/http/response.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Http
+    # Immutable value object describing a single HTTP response.
+    #
+    # A +Response+ carries the raw status code, normalized headers (lowercase
+    # string keys), and a binary-safe body. HTTP errors (4xx/5xx) are returned as
+    # ordinary responses — never raised — so the retry decorator and
+    # {Nfe::ErrorFactory} can act on the status. Redirects and 202 are not
+    # followed by the transport; the +Location+ header is preserved here.
+    #
+    #   response = Nfe::Http::Response.new(status: 200, headers: { "content-type" => "application/json" }, body: "{}")
+    #   response.success?               # => true
+    #   response.header("Content-Type") # => "application/json"
+    class Response < Data.define(:status, :headers, :body)
+      # @param status [Integer] HTTP status code.
+      # @param headers [Hash{String=>String}] lowercase-keyed response headers.
+      # @param body [String, nil] ASCII-8BIT response body, or nil.
+      def initialize(status:, headers: {}, body: nil)
+        super
+      end
+
+      # Case-insensitive header lookup.
+      #
+      # @param name [String] header name in any casing.
+      # @return [String, nil] the header value, or nil when absent.
+      def header(name)
+        headers[name.downcase]
+      end
+
+      # @return [Boolean] true when the status is in the 2xx range.
+      def success?
+        (200..299).cover?(status)
+      end
+
+      # @return [String, nil] the +Location+ header, or nil.
+      def location
+        header("location")
+      end
+    end
+  end
+end

data/lib/nfe/http/retry_policy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Http
+    # Immutable retry policy describing exponential backoff with symmetric
+    # jitter. Consumed by {RetryingTransport} to decide how long to wait between
+    # attempts.
+    #
+    # +max_retries+ is the number of *retries* after the initial attempt, so a
+    # policy with +max_retries: 3+ makes at most four HTTP attempts.
+    #
+    # Use the {.default} factory for the recommended settings, or {.none} to
+    # disable retries entirely (exactly one HTTP attempt).
+    class RetryPolicy < Data.define(:max_retries, :base_delay, :max_delay, :jitter)
+      # Recommended defaults: 3 retries, 1s base, 30s cap, +/-30% jitter.
+      def self.default
+        new(max_retries: 3, base_delay: 1.0, max_delay: 30.0, jitter: 0.3)
+      end
+
+      # No retries: exactly one HTTP attempt, zero delay.
+      def self.none
+        new(max_retries: 0, base_delay: 0.0, max_delay: 0.0, jitter: 0.0)
+      end
+
+      # Delay in seconds before the given (1-based) retry +attempt+.
+      #
+      # Computes +min(max_delay, base_delay * 2**(attempt - 1))+ then applies
+      # symmetric jitter, with the final value capped at +max_delay+.
+      #
+      # @param attempt [Integer] 1-based retry index.
+      # @return [Float]
+      def delay_for(attempt)
+        base = [base_delay * (2**(attempt - 1)), max_delay].min
+        jittered = base * (1 - jitter + (2 * jitter * rand))
+        [jittered, max_delay].min
+      end
+    end
+  end
+end

data/lib/nfe/http/retrying_transport.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Http
+    # Transport decorator that retries transient failures on idempotent
+    # requests. Wraps any +inner+ transport (any object responding to
+    # +call(request)+) and applies a {RetryPolicy}.
+    #
+    # Retries happen on HTTP 429, HTTP 500-599, and network errors
+    # ({Nfe::ApiConnectionError}, including {Nfe::TimeoutError}) -- but ONLY
+    # when {Request#idempotent?} is true. A +POST+ without an +idempotency_key+
+    # is never retried, so an invoice is never re-issued automatically.
+    #
+    # An integer +Retry-After+ header (seconds) overrides the computed backoff,
+    # clamped to the policy's +max_delay+.
+    #
+    # When a duck-typed +logger+ (responding to +info+/+warn+/+error+) is
+    # supplied, the decorator logs request start (+info+), retries (+warn+), and
+    # final failures (+error+). Sensitive headers are redacted via
+    # {Redactor.headers} and request/response BODIES are never logged. Every log
+    # call is wrapped in +rescue StandardError+ so logging can never break the
+    # request.
+    class RetryingTransport
+      # @param inner    [#call] the wrapped transport
+      # @param policy   [RetryPolicy] backoff policy
+      # @param sleep_fn [#call] injectable sleep, called with seconds
+      # @param logger   [#info, #warn, #error, nil] optional duck-typed logger
+      def initialize(inner:, policy: RetryPolicy.default, sleep_fn: ->(seconds) { Kernel.sleep(seconds) }, logger: nil)
+        @inner = inner
+        @policy = policy
+        @sleep_fn = sleep_fn
+        @logger = logger
+      end
+
+      # Execute +request+ through the inner transport, retrying transient
+      # failures on idempotent requests. Returns an {Nfe::Http::Response}; on a
+      # non-retryable network failure (or after exhausting retries) re-raises
+      # the last {Nfe::ApiConnectionError}.
+      def call(request)
+        log_start(request)
+        attempt = 0
+
+        loop do
+          begin
+            response = @inner.call(request)
+          rescue Nfe::ApiConnectionError => e
+            attempt += 1
+            unless retry_again?(attempt, request)
+              log_final_error(request, error: e)
+              raise
+            end
+            delay = @policy.delay_for(attempt)
+            log_retry(request, attempt: attempt, delay: delay, error: e)
+            @sleep_fn.call(delay)
+            next
+          end
+
+          unless retryable_status?(response.status) && retry_again?(attempt + 1, request)
+            log_final_error(request, response: response) unless response.success?
+            return response
+          end
+
+          attempt += 1
+          delay = delay_for_response(attempt, response)
+          log_retry(request, attempt: attempt, delay: delay, status: response.status)
+          @sleep_fn.call(delay)
+        end
+      end
+
+      # True for statuses that warrant a retry: 429 and 5xx.
+      def retryable_status?(status)
+        status == 429 || (500..599).cover?(status)
+      end
+
+      private
+
+      # An +attempt+ (1-based retry index) is permitted when it does not exceed
+      # the configured maximum and the request is idempotent.
+      def retry_again?(attempt, request)
+        attempt <= @policy.max_retries && request.idempotent?
+      end
+
+      # Honor an integer +Retry-After+ (seconds), clamped to +max_delay+;
+      # otherwise fall back to the policy backoff.
+      def delay_for_response(attempt, response)
+        retry_after = parse_retry_after(response)
+        return [retry_after.to_f, @policy.max_delay].min if retry_after
+
+        @policy.delay_for(attempt)
+      end
+
+      def parse_retry_after(response)
+        raw = response.header("retry-after")
+        return nil if raw.nil?
+        return nil unless raw.to_s.match?(/\A\d+\z/)
+
+        raw.to_i
+      end
+
+      def log_start(request)
+        return unless @logger
+
+        safe_log do
+          @logger.info("nfe-io request: #{request.method.to_s.upcase} #{request.url} " \
+                       "headers=#{Redactor.headers(request.headers).inspect}")
+        end
+      end
+
+      def log_retry(request, attempt:, delay:, status: nil, error: nil)
+        return unless @logger
+
+        reason = error ? "error=#{error.class}" : "status=#{status}"
+        safe_log do
+          @logger.warn("nfe-io retry ##{attempt} in #{delay}s: " \
+                       "#{request.method.to_s.upcase} #{request.url} #{reason}")
+        end
+      end
+
+      def log_final_error(request, response: nil, error: nil)
+        return unless @logger
+
+        detail = if error
+                   "error=#{error.class}"
+                 elsif response
+                   "status=#{response.status} body=#{truncate(response.body)}"
+                 else
+                   "unknown failure"
+                 end
+        safe_log do
+          @logger.error("nfe-io request failed: #{request.method.to_s.upcase} #{request.url} #{detail}")
+        end
+      end
+
+      def truncate(body, limit = 256)
+        return "" if body.nil?
+
+        string = body.to_s
+        string.bytesize > limit ? "#{string.byteslice(0, limit)}...(truncated)" : string
+      end
+
+      # Logging must never break the request.
+      def safe_log
+        yield
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/nfe/http/transport.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Http
+    # Transport contract: any object that turns a {Nfe::Http::Request} into a
+    # {Nfe::Http::Response}.
+    #
+    # The SDK routes every HTTP call through an object responding to
+    # +call(request)+. The default implementation is {Nfe::Http::NetHttp} (zero
+    # external dependencies), but any duck-typed object satisfying this contract
+    # may be substituted — a logging decorator, a retrying decorator, or an
+    # in-memory fake for tests.
+    #
+    # == Contract
+    #
+    # An implementation of +call(request)+:
+    #
+    # * SHALL accept a {Nfe::Http::Request} and return a {Nfe::Http::Response}.
+    # * SHALL return HTTP 4xx and 5xx outcomes as a +Response+ carrying that
+    #   status — it SHALL NOT raise for them. The retry decorator and
+    #   {Nfe::ErrorFactory} act on the status code.
+    # * SHALL raise ONLY {Nfe::ApiConnectionError} (or its subclass
+    #   {Nfe::TimeoutError}) on network failures — connection refused, DNS,
+    #   TLS, read/connect timeouts.
+    # * SHALL NOT follow HTTP 202 responses or redirects automatically; it
+    #   SHALL preserve the raw status and the +Location+ header so the caller
+    #   can implement the async Pending/Issued contract.
+    # * SHALL normalize response header keys to lowercase strings and return a
+    #   binary-safe (ASCII-8BIT) body.
+    #
+    # Mix this module in to inherit the +NotImplementedError+ default, or simply
+    # define +call+ on any object (duck typing).
+    module Transport
+      # Perform the request.
+      #
+      # @param request [Nfe::Http::Request]
+      # @return [Nfe::Http::Response]
+      # @raise [NotImplementedError] unless overridden.
+      def call(request)
+        raise NotImplementedError, "#{self.class} must implement #call(request)"
+      end
+    end
+  end
+end

data/lib/nfe/http/user_agent.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Nfe
+  module Http
+    # Builds the +User-Agent+ string sent with every outgoing request.
+    #
+    # The format is
+    # <tt>NFE.io Ruby Client v<sdk-version> ruby/<ruby-version> (<platform>)</tt>,
+    # optionally followed by a caller-supplied suffix (e.g. the host
+    # application's name configured via +Nfe::Configuration#user_agent_suffix+).
+    #
+    # Injection of the resulting header onto a request is performed by the
+    # +Client+/+AbstractResource+ layer (see the +add-client-core+ change); the
+    # transport itself only transmits whatever +User-Agent+ the +Request+ carries.
+    module UserAgent
+      module_function
+
+      # Returns the User-Agent string. When +suffix+ is a non-empty string it is
+      # appended after a single space.
+      def build(suffix = nil)
+        base = "NFE.io Ruby Client v#{Nfe::VERSION} ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+        return base if suffix.nil? || suffix.to_s.empty?
+
+        "#{base} #{suffix}"
+      end
+    end
+  end
+end