end_point_blank 0.12.0 → 0.13.0

data/lib/end_point_blank/management/resources/base.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "../page"
+
+module EndPointBlank
+  module Management
+    # The management API's resources, each reached from a {Client} (or a
+    # {ManagedClient} view) rather than built directly.
+    #
+    # Every method answers what the API sent, decoded from JSON into Hashes
+    # with String keys: a single resource's +data+, a {Page} for a list, and
+    # <tt>{"id" => ..., "deleted" => true}</tt> for a delete. Optional keyword
+    # arguments left nil are not sent.
+    module Resources
+      # Shared plumbing: paths, list pages and auto-paging.
+      class Base
+        MAX_LIMIT = 100
+
+        def initialize(transport, prefix = "")
+          @transport = transport
+          @prefix = prefix
+        end
+
+        def inspect
+          "#<#{self.class.name} prefix=#{@prefix.inspect}>"
+        end
+
+        # One path segment, percent-escaped. An empty id is refused, so it can
+        # never turn a "get one" into a "list all"; so is an id of dots only
+        # (".", ".."), a dot-segment that any proxy or URL normalizer may
+        # resolve into a different route (DELETE /clients/c1/grants/.. into
+        # DELETE /clients/c1). Percent-encoding the dots would not help:
+        # normalizers decode %2E first. Real ids are UUIDs.
+        def self.escape(segment)
+          value = segment.to_s
+          raise ArgumentError, "an id must be a non-empty String" if value.empty?
+          raise ArgumentError, "an id must not be only dots" if value.each_char.all?(".")
+
+          value.b.gsub(/[^A-Za-z0-9\-._~]/n) { |char| format("%%%02X", char.ord) }
+        end
+
+        private
+
+        # "/segment/escaped-id/..." under this resource's prefix. Every
+        # argument is one path segment (see {.escape}).
+        def path(*segments)
+          @prefix + segments.map { |segment| "/#{escape(segment)}" }.join
+        end
+
+        def escape(segment)
+          self.class.escape(segment)
+        end
+
+        def get_data(path, query = nil)
+          data(@transport.request("GET", path, query: query))
+        end
+
+        def post_data(path, body, idempotency_key)
+          data(@transport.request("POST", path, body: body, idempotency_key: idempotency_key))
+        end
+
+        def patch_data(path, body)
+          data(@transport.request("PATCH", path, body: body))
+        end
+
+        def delete_data(path)
+          data(@transport.request("DELETE", path))
+        end
+
+        def data(body)
+          body.is_a?(Hash) && body.key?("data") ? body["data"] : body
+        end
+
+        # One page of a list. +filters+ with a nil value are not sent.
+        def list_page(path, limit, after, filters = {})
+          check_limit(limit)
+          query = compact(filters.merge(limit: limit, after: after))
+          Page.from_body(@transport.request("GET", path, query: query))
+        end
+
+        # Every item of a list, fetching pages as it goes. With a block,
+        # yields each item and answers nil; without one, answers an
+        # Enumerator (lazy: no request is made until it is iterated).
+        def each_item(path, limit, filters = {}, &block)
+          check_limit(limit)
+          enumerator = Enumerator.new { |yielder| each_page_item(yielder, path, limit, filters) }
+          return enumerator unless block
+
+          enumerator.each(&block)
+          nil
+        end
+
+        def each_page_item(yielder, path, limit, filters)
+          after = nil
+          loop do
+            page = list_page(path, limit, after, filters)
+            page.each { |item| yielder << item }
+            break unless page.next_page?
+
+            after = page.next_cursor
+          end
+        end
+
+        def check_limit(limit)
+          return if limit.nil?
+          return if limit.is_a?(Integer) && limit.between?(1, MAX_LIMIT)
+
+          raise ArgumentError, "limit must be an Integer from 1 to #{MAX_LIMIT}, got #{limit.inspect}"
+        end
+
+        def compact(hash)
+          hash.reject { |_key, value| value.nil? }
+        end
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/resources/clients.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module EndPointBlank
+  module Management
+    module Resources
+      # +/clients+: the organizations you serve as their provider, as client
+      # invites (pending and accepted), and managed clients you run for your
+      # customers.
+      #
+      # A client: <tt>{"id", "name", "status" ("pending"/"accepted"),
+      # "invite_code" (write keys, while pending), "accepted_at", "managed",
+      # "claimed_at", "client_organization", "inserted_at", "updated_at"}</tt>;
+      # {#get} adds +contacts+ and +pre_assignments+.
+      class Clients < Base
+        # GET /clients. @return [Page]
+        def list(limit: nil, after: nil)
+          list_page(path("clients"), limit, after)
+        end
+
+        # Every client, across pages. @return [Enumerator, nil]
+        def each(limit: nil, &block)
+          each_item(path("clients"), limit, &block)
+        end
+
+        # GET /clients/:id. @return [Hash]
+        def get(id)
+          get_data(path("clients", id))
+        end
+
+        # POST /clients.
+        #
+        # @param contacts [Array<Hash>, nil] your contacts to share, each
+        #   <tt>{email:, first_name:, last_name:, title: nil, phone_number: nil}</tt>
+        # @param packages [Array<Hash>, nil] API packages to assign when the
+        #   client accepts, each <tt>{api_package_id:, environment_id:}</tt>
+        # @param grants [Array<Hash>, nil] direct grants to make when it
+        #   accepts, each <tt>{target_application_id:, environment_id:,
+        #   target_endpoint_id: nil}</tt>
+        # @param managed [Boolean, nil] true creates a managed client (no
+        #   packages or grants with it; assign those afterwards)
+        # @return [Hash] the new client; +invite_code+ is what the client
+        #   accepts with
+        # rubocop:disable Metrics/ParameterLists
+        def create(name:, contacts: nil, packages: nil, grants: nil, managed: nil, idempotency_key: nil)
+          body = compact(name: name, contacts: contacts, packages: packages, grants: grants, managed: managed)
+          post_data(path("clients"), body, idempotency_key)
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # Invites a client: {#create} without +managed+.
+        def invite(name:, contacts: nil, packages: nil, grants: nil, idempotency_key: nil)
+          create(name: name, contacts: contacts, packages: packages, grants: grants,
+                 idempotency_key: idempotency_key)
+        end
+
+        # Creates a managed client: {#create} with <tt>managed: true</tt>. Set
+        # it up with {Client#for_managed_client}.
+        def create_managed(name:, contacts: nil, idempotency_key: nil)
+          create(name: name, contacts: contacts, managed: true, idempotency_key: idempotency_key)
+        end
+
+        # DELETE /clients/:id. Refused with +managed_client_has_credentials+
+        # for a managed client that still holds credentials.
+        # @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("clients", id))
+        end
+
+        # POST /clients/:client_id/claim_invites: emails your customer an
+        # invite to claim a managed client.
+        # @return [Hash] <tt>{"client_id", "email", "sent_at", "expires_at"}</tt>
+        def claim_invite(client_id, email:, idempotency_key: nil)
+          post_data(path("clients", client_id, "claim_invites"), { email: email }, idempotency_key)
+        end
+      end
+
+      # +/clients/:client_id/packages+: the API packages a client holds from
+      # you, or (on a pending invite) is set up to get when it accepts.
+      #
+      # An assignment: <tt>{"id", "api_package_id", "api_package_name",
+      # "environment_id", "status" ("active"/"pending"/"refused"), "refusal",
+      # "inserted_at", "updated_at"}</tt>.
+      class PackageAssignments < Base
+        # @return [Page]
+        def list(client_id, limit: nil, after: nil)
+          list_page(path("clients", client_id, "packages"), limit, after)
+        end
+
+        # @return [Enumerator, nil]
+        def each(client_id, limit: nil, &block)
+          each_item(path("clients", client_id, "packages"), limit, &block)
+        end
+
+        # POST /clients/:client_id/packages. Refused with e.g.
+        # +nothing_published_in_environment+ or +already_assigned+.
+        # @return [Hash] the assignment
+        def create(client_id, api_package_id:, environment_id:, idempotency_key: nil)
+          post_data(path("clients", client_id, "packages"),
+                    { api_package_id: api_package_id, environment_id: environment_id }, idempotency_key)
+        end
+        alias assign create
+
+        # PATCH /clients/:client_id/packages/:id: move the assignment to
+        # another environment. @return [Hash]
+        def update(client_id, id, environment_id:)
+          patch_data(path("clients", client_id, "packages", id), { environment_id: environment_id })
+        end
+
+        # DELETE /clients/:client_id/packages/:id. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(client_id, id)
+          delete_data(path("clients", client_id, "packages", id))
+        end
+        alias unassign delete
+      end
+
+      # +/clients/:client_id/grants+: the grants a client holds directly from
+      # you (package-derived grants are managed through {PackageAssignments}).
+      #
+      # A grant: <tt>{"id", "client_organization_id", "target_application_id",
+      # "target_endpoint_id", "all_endpoints", "environment_id",
+      # "also_granted_by_api_package_ids", "synced_at", "status", "refusal",
+      # "inserted_at", "updated_at"}</tt>.
+      class Grants < Base
+        # @return [Page]
+        def list(client_id, limit: nil, after: nil)
+          list_page(path("clients", client_id, "grants"), limit, after)
+        end
+
+        # @return [Enumerator, nil]
+        def each(client_id, limit: nil, &block)
+          each_item(path("clients", client_id, "grants"), limit, &block)
+        end
+
+        # POST /clients/:client_id/grants. Leave +target_endpoint_id+ nil to
+        # grant every endpoint of the application. @return [Hash] the grant
+        def create(client_id, target_application_id:, environment_id:, target_endpoint_id: nil, idempotency_key: nil)
+          body = compact(target_application_id: target_application_id, target_endpoint_id: target_endpoint_id,
+                         environment_id: environment_id)
+          post_data(path("clients", client_id, "grants"), body, idempotency_key)
+        end
+
+        # DELETE /clients/:client_id/grants/:id. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(client_id, id)
+          delete_data(path("clients", client_id, "grants", id))
+        end
+        alias revoke delete
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/retry_policy.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module EndPointBlank
+  module Management
+    # Decides whether a failed management API request is sent again, and
+    # after how long. See {Transport} for the rules.
+    class RetryPolicy
+      RETRYABLE_STATUSES = [500, 502, 503, 504].freeze
+
+      # GET and DELETE are idempotent; POST always carries an Idempotency-Key.
+      # PATCH is neither, so a 5xx or a lost answer to one is never re-sent.
+      RETRYABLE_METHODS = %w[GET DELETE POST].freeze
+
+      # Wait before retrying a 409 in progress that has no Retry-After header.
+      IN_PROGRESS_WAIT = 1
+      # Wait before retrying a 429 that has no Retry-After header (app_portal
+      # always sends one; a proxy's 429 may not).
+      RATE_LIMITED_WAIT = 1
+      # First backoff for a 5xx or a request with no answer; doubles per attempt.
+      BACKOFF_BASE = 0.5
+
+      attr_reader :max_retries, :max_retry_wait
+
+      def initialize(max_retries:, max_retry_wait:)
+        @max_retries = max_retries
+        @max_retry_wait = max_retry_wait
+      end
+
+      # Seconds to wait before attempt number +attempt+ + 1 (0 is the first
+      # retry), or nil when +error+ must be raised now.
+      def delay(method, error, attempt)
+        return nil if attempt >= max_retries
+
+        seconds = wanted_wait(method, error, attempt)
+        # A wait longer than max_retry_wait is not waited out.
+        seconds && seconds <= max_retry_wait ? seconds : nil
+      end
+
+      private
+
+      def wanted_wait(method, error, attempt)
+        return error.retry_after || RATE_LIMITED_WAIT if error.status == 429
+        return in_progress_wait(method, error) if error.code?(ErrorCodes::IDEMPOTENCY_REQUEST_IN_PROGRESS)
+        return nil unless server_side_failure?(error) && RETRYABLE_METHODS.include?(method)
+
+        error.retry_after || backoff(attempt)
+      end
+
+      # Only a POST carries the key the first request is still running under.
+      def in_progress_wait(method, error)
+        method == "POST" ? error.retry_after || IN_PROGRESS_WAIT : nil
+      end
+
+      def server_side_failure?(error)
+        error.code?(ErrorCodes::CONNECTION_ERROR) || RETRYABLE_STATUSES.include?(error.status)
+      end
+
+      def backoff(attempt)
+        [BACKOFF_BASE * (2**attempt), max_retry_wait].min
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/transport.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "excon"
+require "json"
+require "uri"
+require_relative "../version"
+require_relative "error"
+require_relative "retry_policy"
+require_relative "idempotency_key"
+require_relative "url_path"
+
+module EndPointBlank
+  module Management
+    # The HTTP layer under {Client}: one request to the management API, with
+    # its headers, its Idempotency-Key and its retries. Built on Excon, the
+    # HTTP library the rest of this gem already uses.
+    #
+    # Retries (at most +max_retries+ after the first attempt, each wait passed
+    # to +sleeper+):
+    #
+    # - 429 +rate_limited+, any method: after Retry-After seconds. Nothing was
+    #   done, so even a PATCH is safe to send again. A Retry-After longer than
+    #   +max_retry_wait+ is not waited out; the error is raised instead.
+    # - 409 +idempotency_request_in_progress+ (POST only): shortly, with the
+    #   same key, so the first request's answer is replayed once it finishes.
+    # - 5xx (+internal_server_error+, +audit_unavailable+,
+    #   +intake_unavailable+, or a proxy's 502/503/504) and requests that never
+    #   got an answer: for GET and DELETE, which are idempotent, and for POST,
+    #   which always carries an Idempotency-Key. Never for PATCH.
+    #
+    # Every POST carries an Idempotency-Key (a random UUID v4 unless the
+    # caller passed one), and every retry of it sends the same key.
+    #
+    # 409 +idempotency_replay_unavailable+ is never retried: the first POST
+    # succeeded and its answer held a secret shown only once.
+    class Transport
+      API_PREFIX = "/api/v1"
+
+      attr_reader :base_url
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(api_key:, base_url:, max_retries:, max_retry_wait:, connect_timeout:, read_timeout:,
+                     sleeper:, excon_options: {})
+        @api_key = api_key
+        @base_url = base_url
+        @base_path = UrlPath.strip_trailing_slashes(URI.parse(base_url).path)
+        @retry_policy = RetryPolicy.new(max_retries: max_retries, max_retry_wait: max_retry_wait)
+        @connect_timeout = connect_timeout
+        @read_timeout = read_timeout
+        @sleeper = sleeper
+        @excon_options = excon_options
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Sends one API request and answers its decoded JSON body (nil for an
+      # empty body). +path+ is under /api/v1, e.g. "/organization".
+      #
+      # @raise [Error] for any answer outside 2xx, once retries are spent
+      def request(method, path, query: nil, body: nil, idempotency_key: nil)
+        method = method.to_s.upcase
+        idempotency_key = IdempotencyKey.resolve(method, idempotency_key)
+        attempt = 0
+
+        loop do
+          result = attempt_request(method, path, query, body, idempotency_key)
+          return result unless result.is_a?(Error)
+
+          wait_before_retry(method, path, result, attempt)
+          attempt += 1
+        end
+      end
+
+      def self.user_agent
+        "end_point_blank-ruby/#{EndPointBlank::VERSION} (management)"
+      end
+
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect}>"
+      end
+
+      private
+
+      # The decoded body on success, or the Error to raise or retry on.
+      def attempt_request(method, path, query, body, idempotency_key)
+        response = perform(method, path, query, body, idempotency_key)
+        return Error.from_response(**error_fields(response, method, path)) unless success?(response)
+
+        decode(response, method, path)
+      rescue Excon::Error::StubNotFound
+        raise
+      rescue Excon::Error => e
+        connection_error(e, method, path)
+      end
+
+      def perform(method, path, query, body, idempotency_key)
+        connection = Excon.new(base_url, connect_timeout: @connect_timeout, read_timeout: @read_timeout,
+                                         write_timeout: @read_timeout, persistent: false, **@excon_options)
+        params = { method: method, path: "#{@base_path}#{API_PREFIX}#{path}",
+                   headers: headers(body, idempotency_key) }
+        params[:query] = query if query && !query.empty?
+        params[:body] = JSON.generate(body) unless body.nil?
+        connection.request(params)
+      end
+
+      def headers(body, idempotency_key)
+        headers = {
+          "Authorization" => "Bearer #{@api_key}",
+          "Accept" => "application/json",
+          "User-Agent" => self.class.user_agent
+        }
+        headers["Content-Type"] = "application/json" unless body.nil?
+        headers["Idempotency-Key"] = idempotency_key if idempotency_key
+        headers
+      end
+
+      def success?(response)
+        (200..299).cover?(response.status)
+      end
+
+      def decode(response, method, path)
+        text = response.body.to_s
+        return nil if text.strip.empty?
+
+        JSON.parse(text)
+      rescue JSON::ParserError
+        Error.new("The management API answered HTTP #{response.status} with a body that is not JSON.",
+                  code: ErrorCodes::INVALID_RESPONSE, status: response.status, http_method: method, path: path)
+      end
+
+      def error_fields(response, method, path)
+        { status: response.status, headers: response.headers, body: response.body,
+          http_method: method, path: path }
+      end
+
+      def connection_error(error, method, path)
+        detail = redact("#{error.class.name}: #{error.message}")
+        Error.new("Could not reach the management API at #{base_url} (#{detail}).",
+                  code: ErrorCodes::CONNECTION_ERROR, http_method: method, path: path)
+      end
+
+      # Sleeps before the next attempt, or raises +error+ when it is not to
+      # be retried.
+      def wait_before_retry(method, path, error, attempt)
+        delay = @retry_policy.delay(method, error, attempt)
+        raise error if delay.nil?
+
+        log_retry(method, path, error, delay)
+        @sleeper.call(delay)
+      end
+
+      # Method, path, status and code only: never headers, query or bodies,
+      # which carry the key, ids and credential secrets.
+      def log_retry(method, path, error, delay)
+        EndPointBlank.logger.debug(
+          "[EndPointBlank] management API #{method} #{path} answered " \
+          "#{error.status || "no response"} (#{error.code}); retrying in #{delay}s"
+        )
+      end
+
+      def redact(text)
+        return text if @api_key.nil? || @api_key.empty?
+
+        text.gsub(@api_key, "[REDACTED]")
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/url_path.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  module Management
+    # URL string helpers for the management client.
+    module UrlPath
+      SLASH = "/".ord
+
+      # +text+ without trailing slashes. One backward scan over the bytes, not
+      # a regex, so its cost is linear however the input is shaped.
+      def self.strip_trailing_slashes(text)
+        stop = text.bytesize
+        stop -= 1 while stop.positive? && text.getbyte(stop - 1) == SLASH
+        text.byteslice(0, stop)
+      end
+    end
+  end
+end

data/lib/end_point_blank/management.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "configuration_error"
+require_relative "management/configuration"
+require_relative "management/error_codes"
+require_relative "management/error"
+require_relative "management/page"
+require_relative "management/retry_policy"
+require_relative "management/idempotency_key"
+require_relative "management/url_path"
+require_relative "management/transport"
+require_relative "management/client"
+
+module EndPointBlank
+  # The organization management API client. See {Management::Client}.
+  #
+  # Configure defaults once, e.g. in config/initializers/end_point_blank.rb,
+  # apart from the runtime's EndPointBlank.configure:
+  #
+  #   EndPointBlank::Management.configure do |m|
+  #     m.api_key = Rails.application.credentials.dig(:end_point_blank, :management_key)
+  #   end
+  #
+  #   EndPointBlank::Management.client.organization
+  module Management
+    @configuration_mutex = Mutex.new
+
+    class << self
+      # The defaults {Client.new} reads. @return [Configuration]
+      def configuration
+        @configuration_mutex.synchronize { @configuration ||= Configuration.new }
+      end
+
+      # Yields {configuration} to change the defaults.
+      def configure
+        yield configuration
+        configuration
+      end
+
+      # A new {Client} from {configuration}; +options+ override it.
+      # @return [Client]
+      def client(**options)
+        Client.new(**options)
+      end
+
+      # Back to the built-in defaults (for tests).
+      def reset_configuration!
+        @configuration_mutex.synchronize { @configuration = Configuration.new }
+      end
+    end
+  end
+end

data/lib/end_point_blank/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EndPointBlank
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

data/lib/end_point_blank.rb

@@ -36,6 +36,7 @@ require_relative "end_point_blank/rack/headers"
 require_relative "end_point_blank/unauthorized_error"
 require_relative "end_point_blank/token_unavailable_error"
 require_relative "end_point_blank/configuration_error"
+require_relative "end_point_blank/management"
 if defined?(::Rails)
   require_relative "end_point_blank/rails/authenticated"
   require_relative "end_point_blank/rails/authorized"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: end_point_blank
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Robert A. Lasch
@@ -120,6 +120,20 @@ files:
 - lib/end_point_blank/deprecation_headers.rb
 - lib/end_point_blank/fast_json_truncator.rb
 - lib/end_point_blank/log_entry.rb
+- lib/end_point_blank/management.rb
+- lib/end_point_blank/management/client.rb
+- lib/end_point_blank/management/configuration.rb
+- lib/end_point_blank/management/error.rb
+- lib/end_point_blank/management/error_codes.rb
+- lib/end_point_blank/management/idempotency_key.rb
+- lib/end_point_blank/management/page.rb
+- lib/end_point_blank/management/resources/api_packages.rb
+- lib/end_point_blank/management/resources/applications.rb
+- lib/end_point_blank/management/resources/base.rb
+- lib/end_point_blank/management/resources/clients.rb
+- lib/end_point_blank/management/retry_policy.rb
+- lib/end_point_blank/management/transport.rb
+- lib/end_point_blank/management/url_path.rb
 - lib/end_point_blank/masking.rb
 - lib/end_point_blank/middleware/rack/report_interaction.rb
 - lib/end_point_blank/rack/env_store.rb