end_point_blank 0.6.0 → 0.12.0

data/lib/end_point_blank/access_tokens.rb

@@ -2,6 +2,7 @@
 
 require 'singleton'
 require "time"
+require_relative "target_url"
 
 module EndPointBlank
   # Thread-safe singleton holding this process's access tokens, one per
@@ -13,9 +14,17 @@ module EndPointBlank
   # environment that URL belongs to, and subsequent calls anywhere under that
   # base URL reuse the entry.
   #
+  # Every public entry point strips the caller's URL to scheme, host, port
+  # and path first ({TargetUrl.strip}), so userinfo, a query or a fragment
+  # never reaches intake, a cache or failure key, or a log line. A URL that
+  # cannot be parsed into an http or https URL with a host is refused
+  # without a request (sc-1469).
+  #
   # Lookup is a plain exact-or-path-prefix comparison, with the longest match
-  # winning. The SDK deliberately does not normalize: intake owns that rule,
-  # and a miss costs one extra request rather than a wrong answer.
+  # winning. Beyond {TargetUrl.strip} (which also lowercases the scheme and
+  # host, as intake does) the SDK deliberately does not normalize: intake
+  # owns that rule, and a miss costs one extra request rather than a wrong
+  # answer.
   #
   # A lookup has to scan the keys, and the fast path deliberately does not
   # take the mutex, so every write **replaces** the entries Hash instead of
@@ -38,24 +47,120 @@ module EndPointBlank
     # How long to hold a token whose expiry the intake sent unreadably.
     DEFAULT_LIFETIME = 3600
 
+    # How many distinct base URLs to remember a failure for.
+    #
+    # DO NOT REMOVE THIS BOUND. A failure record is cleared only by a
+    # SUCCESSFUL mint, and the headline failure this whole class now
+    # distinguishes -- a revoked credential -- is precisely the case where a
+    # successful mint never comes. Every call fails, forever, so a service
+    # walking /orders/1, /orders/2, /orders/3 would record one entry per
+    # resource URL and clear none of them: an unbounded leak inside a gem
+    # embedded in someone else's long-lived process. It is the same trap the
+    # token cache avoids by keying on the environment intake resolves to
+    # rather than on the caller's URL (see the class comment), and the
+    # failure path must not reintroduce it.
+    #
+    # The cap is enforced on INSERT, not only on a successful mint, for the
+    # same reason. Hashes are insertion-ordered, so the oldest record is the
+    # one that goes. A caller only ever asks about a URL it just called, so
+    # a bound this size is never in practice the reason an answer is missing.
+    MAX_FAILURES = 64
+
+    # Why the last mint for a base URL did not produce a token.
+    #
+    # Immutable and frozen (a Data), so it can be published straight out of
+    # {AccessTokens#last_failure} without a copy and without any chance of a
+    # caller editing the record the cache is holding.
+    Failure = Data.define(:base_url, :outcome, :status, :reason, :at) do
+      # 401. Permanent until the API credential itself is re-issued.
+      def credential_rejected?
+        outcome == :credential_rejected
+      end
+
+      # Any other 4xx -- intake's 400 and 422. Permanent, but the credential
+      # is fine: the request or the environment registration is not.
+      def request_rejected?
+        outcome == :request_rejected
+      end
+
+      # 5xx, any other unexpected non-2xx, and a 2xx that carried nothing the
+      # cache could use (no token, or no base_url to key one under; an
+      # empty string is neither).
+      def server_error?
+        outcome == :server_error
+      end
+
+      # No usable HTTP status was obtained at all: timeout, refused
+      # connection, DNS failure. Note what is NOT here -- a body that would
+      # not parse is classified by the status that carried it.
+      def transport_error?
+        outcome == :transport_error
+      end
+    end
+
     def initialize
       @mutex = Mutex.new
       @entries = {}
+      @failures = {}
     end
 
     def self.token(base_url)
       instance.token(base_url)
     end
 
+    def self.last_failure(base_url)
+      instance.last_failure(base_url)
+    end
+
+    def self.token_result(base_url)
+      instance.token_result(base_url)
+    end
+
     # Retrieve a token covering base_url, generating one if no usable entry
     # covers it.
-    # @param base_url [String] the URL you are about to call, with any query
-    #   string and fragment removed. It is sent verbatim; intake normalizes it
+    #
+    # When this answers nil and the caller wants to know why, it must not ask
+    # {last_failure} afterwards if it needs the reason for THIS call: the
+    # mutex is already released by then, so another thread's successful mint
+    # may have cleared the record, or its own failed mint overwritten it.
+    # {token_result} hands back the reason captured under the mutex instead.
+    #
+    # @param base_url [String] the URL you are about to call. Its userinfo,
+    #   query and fragment are removed and its scheme and host lowercased
+    #   ({TargetUrl.strip}); the rest is sent as-is, and intake normalizes it
     #   and matches it against registered base URLs by longest path prefix.
     # @return [String, nil] The access token string, or nil if generation
     #   failed -- which includes a response that carried a token but no
     #   base_url.
+    # @raise [StandardError] anything the mint raises that is not a
+    #   transport error, as itself; see {token_result}.
     def token(base_url)
+      result = token_result(base_url)
+      result.is_a?(Failure) ? nil : result
+    end
+
+    # {token}, but answering the {Failure} for this call instead of nil.
+    #
+    # The Failure is the one recorded inside the mutex by this call's own
+    # mint, so it describes this call and nothing else. {last_failure} is a
+    # shared, per-URL slot read after the lock is gone; between the two,
+    # another thread can clear it (a successful mint for the same URL) or
+    # replace it (its own failed mint), and a caller building an error from
+    # it would report someone else's reason, or none (sc-1469).
+    #
+    # @param base_url [String] the URL you are about to call; see {token}.
+    # @return [String, Failure] the access token string, or why this call
+    #   could not obtain one. A URL that cannot be parsed into an http or
+    #   https URL with a host answers a :request_rejected Failure with no
+    #   status and no base_url, and nothing is sent to intake or recorded.
+    # @raise [StandardError] anything {Commands::GenerateAccessToken.token_result}
+    #   raises -- a ConfigurationError, or a bug that is not a transport
+    #   error -- as itself; nothing is recorded for it. Only
+    #   {Authorization.header} turns it into a TokenUnavailableError.
+    def token_result(base_url)
+      base_url = TargetUrl.strip(base_url)
+      return unparseable_url_failure if base_url.nil?
+
       entry = match(base_url)
       return entry[:token] if usable?(entry)
 
@@ -64,17 +169,27 @@ module EndPointBlank
         entry = match(base_url)
         return entry[:token] if usable?(entry)
 
-        payload = Commands::GenerateAccessToken.token(base_url)
+        result = Commands::GenerateAccessToken.token_result(base_url)
+        payload = result.payload
 
-        # The key is what intake resolved to, and only that. There is no
-        # fallback to the requested URL: that would key on the resource the
-        # caller happened to ask about, so a service walking /orders/1,
-        # /orders/2, /orders/3 would mint and store a token per resource, and
-        # nothing here evicts. Without a base URL the right application
-        # cannot be found, so no token is handed back either.
-        key = payload && payload[:base_url]
+        # What counts as a mint is decided once, in AccessTokenResult, next to
+        # the status it depends on -- so this layer and a caller reading the
+        # outcome can never disagree about whether a token exists. #success?
+        # already means "a 2xx carrying a usable token and the base_url to
+        # cache it under", so both are simply read below rather than tested
+        # again here; a 2xx missing either arrives already classified as a
+        # server error and takes the failure branch, exactly as a 500 does.
+        #
+        # Only a 2xx mints: a 4xx that happened to echo a token back is a
+        # broken server, not a credential, and is never cached.
+        if result.success?
+          # The key is what intake resolved to, and only that. There is no
+          # fallback to the requested URL: that would key on the resource the
+          # caller happened to ask about, so a service walking /orders/1,
+          # /orders/2, /orders/3 would mint and store a token per resource,
+          # and nothing here evicts.
+          key = payload[:base_url]
 
-        if payload && payload[:token] && key
           # The match that led here may have resolved under a different key
           # than the one intake just returned -- an environment's base URL
           # can change to a shorter path in the portal. Drop that stale key
@@ -90,6 +205,7 @@ module EndPointBlank
           )
           new_entries = new_entries.reject { |k, _| k == stale } if stale && stale != key
           @entries = new_entries.freeze
+          clear_failure(base_url, key)
           payload[:token]
         else
           # A failed refresh must not leave an expiring token behind claiming
@@ -100,16 +216,54 @@ module EndPointBlank
           stale = match_key(base_url, @entries)
           @entries = @entries.reject { |k, _| k == stale }.freeze if stale
 
-          EndPointBlank.logger.error "Failed to generate access token for #{base_url}: #{failure_reason(payload)}"
-          nil
+          record_failure(base_url, result)
         end
       end
     end
 
-    # Discard every held token
+    # Why the last attempt to mint a token for base_url failed, or nil if the
+    # last attempt succeeded -- or if there has never been one.
+    #
+    # Additive: nothing else changed shape for this. `token` still answers
+    # with a token String or nil, so an existing caller sees no difference;
+    # one that wants to know whether to give up or try again asks here.
+    #
+    # Scope: one record per base URL, keyed on the URL as it was passed to
+    # `token` (stripped) rather than on whatever intake resolved it to -- a
+    # failed mint often has no resolved base URL to speak of, and the caller
+    # has only the URL it asked with. The map is bounded; see MAX_FAILURES.
+    #
+    # Reads @failures exactly the way `match` reads @entries: one atomic read
+    # of the ivar, no mutex, and every write inside the mutex REPLACES the
+    # Hash rather than mutating it. A reader therefore iterates (or here,
+    # indexes) a snapshot nobody can change underneath it, and can never see
+    # a half-built map. Being a frozen Data, the Failure handed back needs no
+    # defensive copy.
+    #
+    # @param base_url [String] the URL that was asked about; stripped the
+    #   same way {token_result} strips it before keying the record.
+    # @return [Failure, nil]
+    def last_failure(base_url)
+      base_url = TargetUrl.strip(base_url)
+      return nil if base_url.nil?
+
+      @failures[base_url]
+    end
+
+    # How many failure records are held. Exposed so the MAX_FAILURES bound is
+    # testable without reaching into the ivars.
+    # @return [Integer]
+    def failure_count
+      @failures.size
+    end
+
+    # Discard every held token, and every record of why one could not be held
     # @return [nil]
     def clear
-      @mutex.synchronize { @entries = {}.freeze }
+      @mutex.synchronize do
+        @entries = {}.freeze
+        @failures = {}.freeze
+      end
     end
 
     # Discard the held token, but only if it is still the one the caller had
@@ -138,7 +292,7 @@ module EndPointBlank
     # @param base_url [String] the URL to check coverage for
     # @return [Boolean]
     def exists?(base_url)
-      entry = match(base_url)
+      entry = match(TargetUrl.strip(base_url))
       !entry.nil? && entry[:expired_at] > Time.now + PRESENCE_WINDOW
     end
 
@@ -155,7 +309,7 @@ module EndPointBlank
     # stale-entry cleanup on a successful one.
     #
     # Deliberately not a port of intake's matcher: no normalization on either
-    # side. A caller that passes a non-canonical URL simply misses and mints
+    # side beyond {TargetUrl.strip}. A caller that passes a non-canonical URL simply misses and mints
     # again, which costs one HTTP call and is never a wrong answer.
     #
     # Takes entries as an explicit argument, rather than reading @entries
@@ -184,19 +338,84 @@ module EndPointBlank
       !entry.nil? && entry[:expired_at] > Time.now + REFRESH_WINDOW
     end
 
-    # Why a mint produced no usable token, for the log.
-    def failure_reason(payload)
-      return "no response" unless payload.is_a?(Hash)
-      return payload[:error] if payload[:error]
+    # What {token_result} answers for a URL {TargetUrl.strip} refused. Not
+    # logged and not recorded: there is no stripped URL to key or name it
+    # by, and the raw one may carry a secret.
+    def unparseable_url_failure
+      Failure.new(base_url: nil, outcome: :request_rejected, status: nil,
+                  reason: "the URL could not be parsed, so no token was requested", at: Time.now)
+    end
+
+    # Log the failure and remember it, and return the Failure recorded.
+    # Runs inside the mutex.
+    #
+    # The 401 gets its own line, and it is loud: it is the one failure that
+    # will not clear on its own, and the one whose remedy is a human action.
+    # Folding it into the generic line -- which is what happened before -- let
+    # a revoked credential scroll past looking exactly like a blip.
+    def record_failure(base_url, result)
+      reason = failure_reason(result)
+
+      if result.credential_rejected?
+        EndPointBlank.logger.error(
+          "ACCESS TOKEN CREDENTIAL REJECTED for #{base_url}: intake answered 401 (#{reason}). " \
+          "This will not recover by retrying -- re-issue the API credential and update " \
+          "client_id/client_secret."
+        )
+      else
+        EndPointBlank.logger.error "Failed to generate access token for #{base_url}: #{reason}"
+      end
+
+      failures = @failures.reject { |k, _| k == base_url }
+      # Bounded on insert, oldest evicted first -- see MAX_FAILURES for why
+      # this cannot be left to the clear-on-success path. Hash#shift removes
+      # the oldest insertion, and `failures` is a fresh copy no other thread
+      # can see yet, so mutating it here is safe; only the finished, frozen
+      # Hash is published to @failures.
+      failures.shift while failures.size >= MAX_FAILURES
+      failure = Failure.new(base_url: base_url, outcome: result.outcome, status: result.status,
+                            reason: reason, at: Time.now)
+      @failures = failures.merge(base_url => failure).freeze
+      failure
+    end
+
+    # A success wipes the record, so `last_failure` never reports a problem
+    # that has already resolved itself. Both keys go: the URL the caller
+    # asked with, and the canonical one intake resolved it to, which a later
+    # call may well ask about instead. Runs inside the mutex, and replaces
+    # rather than mutates, like every other write here.
+    def clear_failure(base_url, key)
+      return if @failures.empty?
+
+      @failures = @failures.reject { |k, _| k == base_url || k == key }.freeze
+    end
+
+    # Why a mint produced no usable token, in words, for the log and for
+    # {Failure#reason}.
+    def failure_reason(result)
+      payload = result.payload
+
+      return "no response" if result.transport_error?
+      return payload[:error] if payload.is_a?(Hash) && payload[:error]
+      return "unreadable response body (HTTP #{result.status})" if payload.nil?
+
+      # A 2xx is classified as a server error when it carried nothing usable,
+      # so the outcome alone does not say which way it was useless. Say it
+      # here: this is the only place the distinction still exists. The wording
+      # comes from the same predicate that refused to call the response a
+      # mint, so this line cannot claim a token the classification did not
+      # find -- an empty one included, which reads as a token to Ruby and to
+      # nobody else.
+      if (200..299).cover?(result.status)
+        return "no token in response" unless Commands::AccessTokenResult.usable_string?(payload[:token])
 
-      if payload[:token]
         # Distinct from a rejected request: intake's base_url is NOT NULL, and
         # it answers 422 rather than minting when the caller's URL resolves to
         # no environment. A token with no base_url is a broken server.
         return "response carried a token but no base_url"
       end
 
-      "no token in response"
+      "HTTP #{result.status}"
     end
 
     # Time.parse raises on anything it cannot read — an ArgumentError for a

data/lib/end_point_blank/authorization.rb

@@ -1,6 +1,9 @@
 #!/bin/ruby
 
 require 'base64'
+require_relative "token_unavailable_error"
+require_relative "configuration_error"
+require_relative "target_url"
 
 module EndPointBlank
   module AuthorizationMethods
@@ -9,23 +12,104 @@ module EndPointBlank
         EndPointBlank::Configuration.instance
       end
 
-      # Builds an outbound Authorization header value.
-      # @param base_url [String, nil] the URL you are about to call, with any
-      #   query string and fragment removed. If given, a token covering it is
-      #   used (minting one if necessary) and returned as a Bearer header.
-      #   Called with no argument this is the Basic form -- which is what the
-      #   calls to intake itself use, since intake already holds this
-      #   service's own credential.
-      # @return [String] "Bearer <token>" or "Basic <credentials>"
-      def header(base_url = nil)
-        token = nil
-        token = EndPointBlank::AccessTokens.token(base_url) if base_url
-
-        if token
-          "Bearer " + token
-        else
-          "Basic " + Base64.encode64(configuration.client_id + ":" + configuration.client_secret).gsub("\n", "")
+      # Builds the Authorization header for an outbound call to a provider.
+      #
+      # Always a Bearer token, never this service's own credentials: a client
+      # must never send its client_id/client_secret to a provider or to the
+      # provider's intake (sc-1469). When no token can be obtained -- the mint
+      # was rejected (401, 400/422), intake failed (5xx), or it could not be
+      # reached at all (timeout, refused connection) -- this raises rather
+      # than falling back to Basic.
+      #
+      # @param base_url [String] the URL you are about to call. A token
+      #   covering it is used, minting one if necessary. Its userinfo, query
+      #   and fragment are removed first ({TargetUrl.strip}): they are never
+      #   sent to intake, logged, or kept on the error.
+      # @return [String] "Bearer <token>"
+      # @raise [ArgumentError] when base_url is nil or empty, or cannot be
+      #   parsed into an http or https URL with a host; nothing is sent
+      #   anywhere. There is no no-target form any more: the old `header`
+      #   with no argument returned Basic credentials, and the calls to
+      #   intake itself now use {intake_header}.
+      # @raise [TokenUnavailableError] when no token can be obtained; its
+      #   `failure` says why. Anything unexpected raised while minting is
+      #   reported the same way, as a :transport_error with that exception
+      #   as `cause`.
+      # @raise [ConfigurationError] when client_id or client_secret is
+      #   missing; nothing is sent.
+      def header(base_url) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        if base_url.nil? || base_url.to_s.empty?
+          raise ArgumentError,
+                "EndPointBlank::Authorization.header needs the URL you are about to call; " \
+                "outbound calls to a provider are only ever authorized with a Bearer token"
         end
+
+        # The raw URL is not repeated in the message: it is what could not
+        # be parsed, and it may carry a secret.
+        target = TargetUrl.strip(base_url)
+        if target.nil?
+          raise ArgumentError,
+                "EndPointBlank::Authorization.header could not parse the URL it was given " \
+                "(not shown); pass an absolute http or https URL with a host"
+        end
+
+        # The reason must come from this call, captured under the cache's
+        # mutex -- not from `last_failure` read afterwards, which another
+        # thread can clear or overwrite in between.
+        begin
+          result = EndPointBlank::AccessTokens.token_result(target)
+        rescue ConfigurationError
+          raise
+        rescue StandardError
+          # A bug, not a failure intake reported: an unreachable intake
+          # arrives as a Failure, not a raise. It still becomes the one
+          # error this method documents, so a caller handling
+          # TokenUnavailableError is not met by a NoMethodError instead.
+          # Ruby sets the exception as `cause`; its message stays out of ours.
+          raise TokenUnavailableError.new(target, unexpected_failure(target), unexpected: true)
+        end
+
+        unless result.is_a?(String)
+          failure = result.is_a?(EndPointBlank::AccessTokens::Failure) ? result : nil
+          raise TokenUnavailableError.new(target, failure)
+        end
+
+        "Bearer #{result}"
+      end
+
+      # The failure {header} reports for a mint that raised. The cache
+      # records nothing for one, so there is no recorded Failure to hand on.
+      def unexpected_failure(target)
+        EndPointBlank::AccessTokens::Failure.new(
+          base_url: target, outcome: :transport_error, status: nil,
+          reason: "the token request failed unexpectedly", at: Time.now
+        )
+      end
+      private :unexpected_failure
+
+      # The Basic header for the SDK's own calls to its own intake --
+      # authenticate/authorize, token minting, endpoint updates and the
+      # log/request/response writers. intake already holds this service's
+      # credential, so presenting it there discloses nothing.
+      #
+      # @api private Not for outbound calls to a provider: use {header}.
+      # @return [String] "Basic <credentials>"
+      # @raise [ConfigurationError] when client_id or client_secret is nil or
+      #   empty. Interpolating them would silently send `Basic Og==` instead.
+      def intake_header # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        client_id = configuration.client_id
+        client_secret = configuration.client_secret
+        missing = []
+        missing << "client_id" if client_id.nil? || client_id.to_s.empty?
+        missing << "client_secret" if client_secret.nil? || client_secret.to_s.empty?
+        unless missing.empty?
+          raise ConfigurationError,
+                "EndPointBlank is missing #{missing.join(" and ")}: set it with EndPointBlank.configure " \
+                "or ENDPOINTBLANK_CLIENT_ID / ENDPOINTBLANK_CLIENT_SECRET. The SDK cannot authenticate " \
+                "to its intake without both."
+        end
+
+        "Basic #{Base64.strict_encode64("#{client_id}:#{client_secret}")}"
       end
     end
 
@@ -34,10 +118,11 @@ module EndPointBlank
     end
   end
 
-  # Generates HTTP Basic Authorization headers using client credentials.
-  # Creates a Base64-encoded string from the client_id and client_secret
-  # configured in EndPointBlank::Configuration.
-  # Use header class method to get a properly formatted "Basic {credentials}" header.
+  # Builds Authorization headers.
+  #
+  # {header} is for outbound calls to a provider and only ever answers with a
+  # Bearer token (raising {TokenUnavailableError} when none can be had);
+  # {intake_header} is the SDK's own Basic header for calls to its own intake.
   class Authorization
     include AuthorizationMethods
   end