end_point_blank 0.6.1 → 0.13.0

data/lib/end_point_blank/commands/generate_access_token.rb

@@ -2,34 +2,267 @@
 
 require 'excon'
 require "json"
+require "openssl"
+require "socket"
+require "timeout"
 require_relative 'http'
+require_relative "../configuration_error"
+require_relative "../target_url"
 
 module EndPointBlank
   module Commands
+    # The outcome of one attempt to mint an access token, with enough of the
+    # intake's answer attached that a caller can decide what to do about it.
+    #
+    # intake's access-token endpoint answers 201 on success, 400 for a bad
+    # request (an invalid token_ttl, a missing base_url), 401 for a rejected
+    # credential, 422 when the target or source application cannot be resolved
+    # or the mint itself failed, and 5xx for a genuine fault. Those are not
+    # interchangeable: 401 needs the credential re-issued, 400/422 need the
+    # request or the registration fixed, and 5xx or a dead socket just needs
+    # trying again. Collapsing them -- which is what returning a bare Hash or
+    # nil does -- is what made every failure look the same to a caller.
+    #
+    # A Data is deeply appropriate here: it is immutable and frozen, so a
+    # result can be handed across threads, cached, or logged without anyone
+    # being able to edit the verdict after the fact.
+    AccessTokenResult = Data.define(:outcome, :status, :payload) do
+      # A token really was minted: a 2xx whose body parsed and carries both a
+      # non-empty token and the non-empty base_url to cache it under. Nothing
+      # else is a success, so a caller that branches on this can read the
+      # token straight off the payload without checking again that there is
+      # one -- and a check that is not there is a check nobody can forget.
+      def success?
+        outcome == :success
+      end
+
+      # 401. Permanent until the API credential itself changes.
+      def credential_rejected?
+        outcome == :credential_rejected
+      end
+
+      # Any other 4xx -- in practice intake's 400 and 422. Permanent too, but
+      # the credential is fine; the request or the registration is not.
+      def request_rejected?
+        outcome == :request_rejected
+      end
+
+      # 5xx, any other unexpected non-2xx, and a 2xx that carried nothing
+      # usable -- unreadable, or missing the token, or missing the base_url
+      # there is no way to cache a token without. Empty counts as missing;
+      # see .usable_string?.
+      def server_error?
+        outcome == :server_error
+      end
+
+      # No answer at all: timeout, refused connection, DNS failure -- any
+      # case where no usable HTTP status was obtained. Transient.
+      #
+      # Note what is NOT here: a body we could not read. That is classified
+      # by the status that carried it, because the status is the part with
+      # the remedy in it.
+      def transport_error?
+        outcome == :transport_error
+      end
+
+      # The direct complement of #success?, and deliberately the only
+      # predicate here that spans more than one outcome. There is no
+      # #retriable? on purpose: a single retry/no-retry boolean would fold
+      # five honest names back into two, and it is one more thing that can
+      # answer wrongly for a 400 or a 422. A caller that wants a retry policy
+      # writes it against the outcome it can see.
+      def failure?
+        !success?
+      end
+
+      # True when payload carries everything a mint needs: a token, and the
+      # base URL to cache it under.
+      #
+      # The single definition of what counts as a mint, and it sits here next
+      # to the outcomes rather than in the cache that consumes them, so a
+      # second layer cannot form its own opinion and end up disagreeing with
+      # the outcome it was handed. EndPointBlank::AccessTokens asks this
+      # instead of re-deriving it, and words its failure log line from the
+      # same predicate.
+      def self.minted?(payload)
+        payload.is_a?(Hash) && usable_string?(payload[:token]) && usable_string?(payload[:base_url])
+      end
+
+      # True when value is something there is actually anything to be had
+      # from.
+      #
+      # Spelled out rather than left to a bare `payload[:token] &&`, which is
+      # what this replaced: "" is truthy in Ruby, so an empty token sailed
+      # through as a success, and an empty base_url became a cache key no
+      # lookup could ever match. Neither is ever legitimate -- intake's token
+      # and base_url are both NOT NULL -- so either one means a broken server.
+      def self.usable_string?(value)
+        value.is_a?(String) && !value.empty?
+      end
+    end
+
     module GenerateAccessTokenMethods
+      # What a request that never completed raises: Excon's own errors (its
+      # timeouts and socket failures among them), and the socket, SSL and
+      # timeout errors underneath, in case one arrives unwrapped. Only these
+      # are a :transport_error.
+      TRANSPORT_ERRORS = [
+        Excon::Error, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Timeout::Error
+      ].freeze
+
       module ClassMethods
         def configuration
           EndPointBlank::Configuration.instance
         end
 
+        # Mint an access token, reporting what actually happened.
+        #
+        # @param base_url [String] the URL a token is wanted for. Its
+        #   userinfo, query and fragment are never sent ({TargetUrl.strip}).
+        # @return [AccessTokenResult] never nil. A URL that cannot be parsed
+        #   into an http or https URL with a host is :request_rejected with no
+        #   status, and nothing is sent.
+        # @raise [ConfigurationError] when client_id or client_secret is
+        #   missing; nothing is sent.
+        # @raise [StandardError] anything raised while minting that is not
+        #   one of {TRANSPORT_ERRORS}; see the rescue below.
+        def token_result(base_url) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          # Defensive: AccessTokens already strips, but this is callable on
+          # its own and must not put a raw URL in the request body either.
+          target = TargetUrl.strip(base_url)
+          if target.nil?
+            EndPointBlank.logger.error "Access token not requested: the URL could not be parsed " \
+                                       "into an http or https URL with a host (not shown)"
+            return AccessTokenResult.new(outcome: :request_rejected, status: nil, payload: nil)
+          end
+
+          response = post_token_request(target)
+
+          status = response.status
+          EndPointBlank.logger.info "Authentication response: #{status}"
+
+          # parse_payload never raises, so nothing between here and the
+          # classification can throw away a status we already hold.
+          payload = parse_payload(response.body)
+
+          # The invariant, enforced in exactly one place: :transport_error
+          # means no usable HTTP status was obtained. Anything that is not a
+          # real status code leaves here rather than reaching classification,
+          # so no other branch has to keep re-deciding what a missing status
+          # means. The payload still rides along, because `token` below is
+          # published API and has always handed back whatever it could parse.
+          return transport_error(payload) unless status.is_a?(Integer)
+
+          AccessTokenResult.new(outcome: outcome_for(status, payload), status: status, payload: payload)
+        rescue ConfigurationError
+          # Missing client credentials are not a transport error: nothing was
+          # sent, and retrying cannot help. Let it be seen (sc-1469).
+          raise
+        rescue *TRANSPORT_ERRORS => e
+          # Reached only when the request never completed, so there is no
+          # status to classify on. Anything else raised above is a bug, not
+          # an unreachable intake, and calling it a transport error would
+          # send the reader off to check the network: it propagates, and
+          # Authorization.header reports it as "the token request failed
+          # unexpectedly" with the exception as its cause (sc-1469).
+          EndPointBlank.logger.error "Error occurred during authentication: #{e.message}\n #{e.backtrace.join("\n")}"
+          transport_error
+        end
+
+        # Mint an access token.
+        #
+        # The body-or-nil accessor, where a body means a token was actually
+        # minted. Anything else answers nil: a 401 or 422 whose body explains
+        # the refusal, and a 2xx that parsed into something with no usable
+        # token in it.
+        #
+        # Returning those bodies would hand the caller a truthy value for a
+        # request that produced no token -- the failure {token_result} exists
+        # to remove, one layer down. Nothing is lost:
+        # `token_result(base_url).payload` is exactly what this used to
+        # return, now alongside the outcome that explains it.
+        #
+        # @param base_url [String] the URL a token is wanted for.
+        # @return [Hash, nil] symbol-keyed response body when a token was
+        #   minted, otherwise nil.
+        # @raise [StandardError] whatever {token_result} raises, as itself.
         def token(base_url)
+          result = token_result(base_url)
+
+          result.success? ? result.payload : nil
+        end
+
+        private
+
+        def post_token_request(base_url)
           body = {base_url: base_url}
           if configuration.token_ttl
             body[:token_ttl] = configuration.token_ttl
           end
-          auth = Authorization.header
-          response = Excon.post(configuration.access_token_url,
-            headers: {'Authorization' => auth, 'Content-Type' => 'application/json'},
+          auth = Authorization.intake_header
+          Excon.post(configuration.access_token_url,
+            headers: EndPointBlank::Commands::Http.headers(auth),
             body: body.to_json,
             **EndPointBlank::Commands::Http::TIMEOUT_OPTIONS
           )
-          EndPointBlank.logger.info "Authentication response: #{response.status}"
-          parsed_body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
-          parsed_body.transform_keys(&:to_sym)
-        rescue => e
-          EndPointBlank.logger.error "Error occurred during authentication: #{e.message}\n #{e.backtrace.join("\n")}"
+        end
+
+        def transport_error(payload = nil)
+          AccessTokenResult.new(outcome: :transport_error, status: nil, payload: payload)
+        end
+
+        # Returns the symbolized body, or nil when it cannot be read. Total:
+        # it never raises, deliberately, so that a body it cannot make sense
+        # of can never cost us the status that body arrived under.
+        #
+        # A body we cannot parse is still reported rather than swallowed:
+        # before this, one blanket `rescue` turned a JSON::ParserError into
+        # the same silent nil as a dead socket. The message keeps its original
+        # prefix so any log alerting built on the old line still matches.
+        def parse_payload(body)
+          parsed = body.is_a?(String) ? JSON.parse(body) : body
+          parsed.transform_keys(&:to_sym)
+        rescue StandardError => e
+          EndPointBlank.logger.error "Error occurred during authentication: #{e.message} (response body was not JSON)"
           nil
         end
+
+        # Classify on the HTTP status FIRST; the body only ever refines the
+        # answer, and only for a 2xx.
+        #
+        # :transport_error means exactly one thing -- no usable HTTP status
+        # was obtained -- so it is not reachable from here. Do not
+        # reintroduce parse-first classification: a 401 whose body will not
+        # parse is still a rejected credential, and filing it under a name
+        # that reads as transient invites the forever-retry this exists to
+        # end. That is not hypothetical. The SDK
+        # reaches intake through Caddy, and any proxy, WAF or ALB in front of
+        # the app can answer 401 with an HTML error page intake never
+        # generated -- the credential really is rejected and the body really
+        # is unparseable, at the same time.
+        #
+        # The one thing the body decides, and only ever on a 2xx: whether a
+        # token was actually minted. A 2xx that is unreadable, or carries no
+        # token, or a token with no base_url to cache it under, is a broken
+        # server, and it is truthful to say so with the real 2xx status
+        # attached -- intake's base_url is NOT NULL and it answers 422 rather
+        # than minting when the URL resolves to nothing, so a 2xx without one
+        # cannot be anything else.
+        #
+        # Calling such a response a success instead would hand back a result
+        # whose #success? is true and whose token is absent, leaving every
+        # caller a re-check to remember -- which is exactly the check that
+        # gets forgotten. The payload rides along on the failure either way,
+        # so the specific reason survives for the log line and `token` still
+        # answers with precisely the body it always did.
+        def outcome_for(status, payload)
+          case status
+          when 200..299 then AccessTokenResult.minted?(payload) ? :success : :server_error
+          when 401 then :credential_rejected
+          when 400..499 then :request_rejected
+          else :server_error # 5xx, and any 3xx, which Excon does not follow.
+          end
+        end
       end
 
       def self.included(base)

data/lib/end_point_blank/commands/http.rb

@@ -1,4 +1,5 @@
 require 'excon'
+require_relative '../version'
 
 module EndPointBlank
   module Commands
@@ -16,13 +17,31 @@ module EndPointBlank
       # Merge this into any `Excon.post`/`Excon.new` call in the lib.
       TIMEOUT_OPTIONS = { connect_timeout: CONNECT_TIMEOUT, read_timeout: READ_TIMEOUT }.freeze
 
+      # The x-epb-sdk value sent on every call to intake: ruby/<version>, the
+      # version of this gem as loaded (sc-1463). intake ignores it today; it is
+      # there so intake can record the oldest version seen per credential for
+      # the move gate. That gate's minimum Ruby version is the release that
+      # turns derive_base_url_from_client_id on by default, not the one that
+      # added this header: with the option at its default, this version keeps
+      # calling in.endpointblank.com after its organization moves.
+      def self.sdk_header
+        "ruby/#{EndPointBlank::VERSION}"
+      end
+
+      # The headers for every call to intake. Use this for any
+      # `Excon.post`/`Excon.new` call in the lib, so x-epb-sdk cannot be left
+      # off one of them.
+      def self.headers(auth)
+        { 'Authorization' => auth, 'Content-Type' => 'application/json', 'x-epb-sdk' => sdk_header }
+      end
+
       def self.post(url, auth, body)
         attempt = 0
         begin
           attempt += 1
           Excon.post(
             url,
-            headers: { 'Authorization' => auth, 'Content-Type' => 'application/json' },
+            headers: headers(auth),
             body: body.to_json,
             **TIMEOUT_OPTIONS
           )

data/lib/end_point_blank/configuration.rb

@@ -11,19 +11,108 @@ module EndPointBlank
   class Configuration
     include Singleton
 
+    # Seconds an authorization decision stays cached when cache_ttl is never
+    # assigned. See {#cache_ttl=}.
+    DEFAULT_CACHE_TTL = 300
+
+    DEFAULT_BASE_URL = "https://in.endpointblank.com"
+
+    # sc-1463: an organization's intake answers at
+    # https://<slug>.in.endpointblank.com. See {#base_url}.
+    DERIVED_BASE_URL_SUFFIX = ".in.endpointblank.com"
+
+    # app_portal's Organizations.Slug.valid?/1: a domain label of up to 20
+    # [a-z0-9-] characters that starts and ends alphanumeric, then "-" and 6
+    # random characters. Copied, not loosened.
+    CLIENT_ID_SLUG = /\A[a-z0-9](?:[a-z0-9-]{0,18}[a-z0-9])?-[a-z0-9]{6}\z/
+
     attr_writer :client_id, :client_secret, :base_url, :log_base_url, :app_name, :env_name
 
     attr_accessor :worker_count, :log_mode,
-                  :version_finder, :application_version, :token_ttl, :cache_ttl,
+                  :version_finder, :application_version, :token_ttl,
                   :masking_rules, :mask_hook, :logger, :trust_proxy_headers
 
+    attr_reader :cache_ttl, :derive_base_url_from_client_id
+
     def initialize
       @worker_count = 4
       @token_ttl = nil
-      @cache_ttl = 300
+      self.cache_ttl = DEFAULT_CACHE_TTL
       @masking_rules = []
       @mask_hook = nil
       @trust_proxy_headers = true
+      @derive_base_url_from_client_id = false
+    end
+
+    # Sets the authorization decision cache's TTL, in whole seconds.
+    #
+    # sc-970 sets one rule for this setting across every EndPointBlank SDK:
+    #
+    # - never assigned: the default, {DEFAULT_CACHE_TTL} (300) seconds;
+    # - 0: the cache is disabled;
+    # - a positive Integer: that many seconds;
+    # - anything else -- an explicit nil, a negative number, or a non-Integer
+    #   such as "300" or 3.5 -- raises ArgumentError here, at configure time,
+    #   and leaves the previous value in place. It is never deferred to the
+    #   first cache read or store, and never quietly read as "disabled" or
+    #   as "use the default".
+    #
+    # @raise [ArgumentError] if value is not a non-negative Integer
+    def cache_ttl=(value)
+      unless value.is_a?(Integer) && !value.negative?
+        raise ArgumentError,
+              "EndPointBlank::Configuration#cache_ttl must be a non-negative Integer number of " \
+              "seconds, got #{value.inspect}. To use the default of #{DEFAULT_CACHE_TTL} seconds, " \
+              "omit the cache_ttl setting entirely; set it to 0 to disable the cache."
+      end
+
+      @cache_ttl = value
+    end
+
+    # Whether {#base_url} may derive the intake hostname from a slug-prefixed
+    # {#client_id} when no base URL is set (sc-1463). Defaults to false,
+    # because *.in.endpointblank.com has no DNS or TLS in production yet; it
+    # will default to true in a later release.
+    #
+    # Only true or false: a String "true" from an env var must not quietly
+    # leave derivation off, and nothing else has a sensible reading. Like
+    # {#cache_ttl=}, anything else raises here, at configure time, and
+    # leaves the previous value in place.
+    #
+    # @raise [ArgumentError] if value is not true or false
+    def derive_base_url_from_client_id=(value)
+      unless [true, false].include?(value)
+        raise ArgumentError,
+              "EndPointBlank::Configuration#derive_base_url_from_client_id must be true or false, " \
+              "got #{value.inspect}."
+      end
+
+      @derive_base_url_from_client_id = value
+    end
+
+    # The organization slug a client_id names, or nil for one without it
+    # (issued before sc-1463).
+    #
+    # The same rule as app_portal's Credentials.client_id_slug/1 and every
+    # other EndPointBlank SDK: the part before the first "." must have the
+    # exact shape of an organization slug, and something must follow the
+    # dot. "Contains a ." is not enough, because app_portal has always
+    # accepted a typed client_id, so a legacy "my.client" can exist and must
+    # keep calling the default intake.
+    #
+    # @param client_id [Object] anything; only a String can carry a slug
+    # @return [String, nil]
+    def self.client_id_slug(client_id)
+      return nil unless client_id.is_a?(String)
+      # Total, like Elixir's: split and match? raise on invalid bytes or on an
+      # encoding that is not ASCII-compatible (UTF-16), and neither can be a
+      # credential that authenticates.
+      return nil unless client_id.valid_encoding? && client_id.encoding.ascii_compatible?
+
+      slug, random = client_id.split(".", 2)
+      return nil if random.nil? || random.empty?
+
+      CLIENT_ID_SLUG.match?(slug) ? slug : nil
     end
 
     # Returns the configured client id, falling back to the
@@ -39,9 +128,11 @@ module EndPointBlank
     end
 
     # Returns the configured base URL, falling back to the
-    # ENDPOINTBLANK_BASE_URL environment variable, then a built-in default.
+    # ENDPOINTBLANK_BASE_URL environment variable, then -- only while
+    # {#derive_base_url_from_client_id} is on -- the hostname derived from a
+    # slug-prefixed {#client_id}, then a built-in default.
     def base_url
-      @base_url || ENV["ENDPOINTBLANK_BASE_URL"] || "https://in.endpointblank.com"
+      @base_url || ENV["ENDPOINTBLANK_BASE_URL"] || derived_base_url || DEFAULT_BASE_URL
     end
 
     # Returns the configured log base URL, falling back to the
@@ -104,5 +195,21 @@ module EndPointBlank
     def env_name
       @env_name || ENV["ENDPOINTBLANK_ENV"]
     end
+
+    private
+
+    # sc-1463: a new client_id is "<organization slug>.<random>", and that
+    # organization's intake answers at https://<slug>.in.endpointblank.com.
+    # Only while derive_base_url_from_client_id is on: *.in.endpointblank.com
+    # has no DNS or TLS in production yet, so it defaults off, and off means
+    # today's default for every client_id. Logs are not derived: whether they
+    # get a per-organization hostname is still open, so log_base_url keeps its
+    # own default.
+    def derived_base_url
+      return nil unless @derive_base_url_from_client_id == true
+
+      slug = self.class.client_id_slug(client_id)
+      slug && "https://#{slug}#{DERIVED_BASE_URL_SUFFIX}"
+    end
   end
 end

data/lib/end_point_blank/configuration_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  # Reopened with the same superclass in end_point_blank.rb; declared here too
+  # so this file can be required on its own.
+  class Error < StandardError; end
+
+  # Raised when a setting the SDK cannot work without is missing -- today, a
+  # nil or empty client_id or client_secret when the SDK builds the Basic
+  # header for a call to its own intake.
+  #
+  # Loud on purpose (sc-1469). Before sc-1469 the header was built with
+  # `client_id + ":" + client_secret`, which raised on a nil; interpolation
+  # does not, and would quietly send `Basic Og==` (base64 of ":") on every
+  # call, which intake rejects as a bad credential -- a misconfiguration
+  # dressed up as a revoked one.
+  class ConfigurationError < Error; end
+end