end_point_blank 0.6.1 → 0.13.0

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module EndPointBlank
+  module Management
+    module Resources
+      # +/api_packages+: your organization's API packages, and what each one
+      # publishes (+/api_packages/:id/endpoints+).
+      #
+      # A package: <tt>{"id", "name", "organization_id", "inserted_at",
+      # "updated_at"}</tt>.
+      class ApiPackages < Base
+        # GET /api_packages. @return [Page]
+        def list(limit: nil, after: nil)
+          list_page(path("api_packages"), limit, after)
+        end
+
+        # Every API package, across pages. @return [Enumerator, nil]
+        def each(limit: nil, &block)
+          each_item(path("api_packages"), limit, &block)
+        end
+
+        # GET /api_packages/:id. @return [Hash]
+        def get(id)
+          get_data(path("api_packages", id))
+        end
+
+        # POST /api_packages. @return [Hash] the new package
+        def create(name:, idempotency_key: nil)
+          post_data(path("api_packages"), { name: name }, idempotency_key)
+        end
+
+        # PATCH /api_packages/:id (rename). @return [Hash]
+        def update(id, name:)
+          patch_data(path("api_packages", id), { name: name })
+        end
+
+        # DELETE /api_packages/:id. Refused with +api_package_assigned+ while
+        # a client holds it. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("api_packages", id))
+        end
+
+        # GET /api_packages/:id/endpoints: what the package publishes, one
+        # entry per application endpoint (or whole application) and
+        # environment. An entry: <tt>{"id", "api_package_id",
+        # "application_id", "endpoint_id", "all_endpoints", "endpoint",
+        # "environment_id", "inserted_at"}</tt>. @return [Page]
+        def list_endpoints(api_package_id, limit: nil, after: nil)
+          list_page(path("api_packages", api_package_id, "endpoints"), limit, after)
+        end
+
+        # Every entry of the package, across pages. @return [Enumerator, nil]
+        def each_endpoint(api_package_id, limit: nil, &block)
+          each_item(path("api_packages", api_package_id, "endpoints"), limit, &block)
+        end
+
+        # POST /api_packages/:id/endpoints. Leave +endpoint_id+ nil to publish
+        # every endpoint of the application.
+        #
+        # Answers the whole body, not only +data+: <tt>{"data" => entry,
+        # "warnings" => [...]}</tt>. Each warning (code
+        # +assignment_derives_nothing+) names a client assignment of the
+        # package that derives no grant.
+        #
+        # @return [Hash] <tt>{"data", "warnings"}</tt>
+        def add_endpoint(api_package_id, application_id:, environment_id:, endpoint_id: nil, idempotency_key: nil)
+          body = compact(application_id: application_id, endpoint_id: endpoint_id, environment_id: environment_id)
+          @transport.request("POST", path("api_packages", api_package_id, "endpoints"),
+                             body: body, idempotency_key: idempotency_key)
+        end
+
+        # DELETE /api_packages/:id/endpoints/:access_id. Answers the whole
+        # body, as {#add_endpoint} does.
+        #
+        # @return [Hash] <tt>{"data" => {"id", "deleted"}, "warnings" => [...]}</tt>
+        def remove_endpoint(api_package_id, access_id)
+          @transport.request("DELETE", path("api_packages", api_package_id, "endpoints", access_id))
+        end
+      end
+
+      # +GET /endpoints+: the endpoints of your organization's applications,
+      # to find the ids {ApiPackages#add_endpoint} takes.
+      #
+      # An endpoint: <tt>{"id", "application_id", "path", "action", "public",
+      # "inserted_at", "updated_at"}</tt>.
+      class Endpoints < Base
+        # @param application_id [String, nil] only this application's endpoints
+        # @param version [String, nil] only endpoints deployed in an
+        #   application version of this name
+        # @return [Page]
+        def list(application_id: nil, version: nil, limit: nil, after: nil)
+          list_page(path("endpoints"), limit, after, application_id: application_id, version: version)
+        end
+
+        # Every matching endpoint, across pages. @return [Enumerator, nil]
+        def each(application_id: nil, version: nil, limit: nil, &block)
+          each_item(path("endpoints"), limit, { application_id: application_id, version: version }, &block)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module EndPointBlank
+  module Management
+    module Resources
+      # +/applications+, and each application's environments
+      # (+/applications/:application_id/environments+, an "application
+      # environment": the application placed in an environment at a base URL).
+      #
+      # An application: <tt>{"id", "name", "public", "organization_group_id",
+      # "synced_at", "inserted_at", "updated_at"}</tt>. An application
+      # environment: <tt>{"id", "application_id", "environment_id",
+      # "base_url", ...}</tt>.
+      class Applications < Base
+        # @return [Page]
+        def list(limit: nil, after: nil)
+          list_page(path("applications"), limit, after)
+        end
+
+        # @return [Enumerator, nil]
+        def each(limit: nil, &block)
+          each_item(path("applications"), limit, &block)
+        end
+
+        # @return [Hash]
+        def get(id)
+          get_data(path("applications", id))
+        end
+
+        # POST /applications.
+        #
+        # @param environment_base_urls [Hash] environment id => base URL; at
+        #   least one is required
+        # @return [Hash] the new application
+        def create(name:, environment_base_urls:, public: nil, organization_group_id: nil, idempotency_key: nil)
+          body = compact(name: name, environment_base_urls: environment_base_urls, public: public,
+                         organization_group_id: organization_group_id)
+          post_data(path("applications"), body, idempotency_key)
+        end
+
+        # PATCH /applications/:id. Only the arguments given are sent.
+        # @return [Hash]
+        def update(id, name: nil, public: nil)
+          patch_data(path("applications", id), compact(name: name, public: public))
+        end
+
+        # DELETE /applications/:id. Refused with +has_dependents+ while grants
+        # or credentials depend on it. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("applications", id))
+        end
+
+        # GET /applications/:application_id/environments. @return [Page]
+        def list_environments(application_id, limit: nil, after: nil)
+          list_page(path("applications", application_id, "environments"), limit, after)
+        end
+
+        # @return [Enumerator, nil]
+        def each_environment(application_id, limit: nil, &block)
+          each_item(path("applications", application_id, "environments"), limit, &block)
+        end
+
+        # POST /applications/:application_id/environments: place the
+        # application in an environment at +base_url+.
+        # @return [Hash] the application environment
+        def add_environment(application_id, environment_id:, base_url:, idempotency_key: nil)
+          post_data(path("applications", application_id, "environments"),
+                    { environment_id: environment_id, base_url: base_url }, idempotency_key)
+        end
+
+        # DELETE /applications/:application_id/environments/:id, where +id+ is
+        # the application environment's id. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def remove_environment(application_id, id)
+          delete_data(path("applications", application_id, "environments", id))
+        end
+      end
+
+      # +/environments+: deployment environments.
+      #
+      # An environment: <tt>{"id", "name", "domain", "is_default", ...}</tt>.
+      class Environments < Base
+        # @return [Page]
+        def list(limit: nil, after: nil)
+          list_page(path("environments"), limit, after)
+        end
+
+        # @return [Enumerator, nil]
+        def each(limit: nil, &block)
+          each_item(path("environments"), limit, &block)
+        end
+
+        # @return [Hash]
+        def get(id)
+          get_data(path("environments", id))
+        end
+
+        # POST /environments. @return [Hash] the new environment
+        def create(name:, domain:, is_default: nil, idempotency_key: nil)
+          post_data(path("environments"), compact(name: name, domain: domain, is_default: is_default),
+                    idempotency_key)
+        end
+
+        # PATCH /environments/:id. Only the arguments given are sent. The
+        # production environment answers +protected+. @return [Hash]
+        def update(id, name: nil, domain: nil, is_default: nil)
+          patch_data(path("environments", id), compact(name: name, domain: domain, is_default: is_default))
+        end
+
+        # DELETE /environments/:id. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("environments", id))
+        end
+      end
+
+      # +/credentials+: runtime client credentials (the client_id and
+      # client_secret an SDK authenticates with).
+      #
+      # A credential: <tt>{"id", "client_id", "secret_last_4",
+      # "application_environment_id", "application_id", "environment",
+      # "previous_secret", "expired_at", "created_at", "updated_at"}</tt>.
+      # {#create} and {#rotate} add +client_secret+, the only time the secret
+      # is ever returned: store it then. This SDK never logs it.
+      class Credentials < Base
+        # @param application_environment_id [String, nil] only this
+        #   application environment's credentials
+        # @return [Page] metadata only, no secrets
+        def list(application_environment_id: nil, limit: nil, after: nil)
+          list_page(path("credentials"), limit, after, application_environment_id: application_environment_id)
+        end
+
+        # @return [Enumerator, nil]
+        def each(application_environment_id: nil, limit: nil, &block)
+          each_item(path("credentials"), limit, { application_environment_id: application_environment_id }, &block)
+        end
+
+        # @return [Hash] metadata only, no secret
+        def get(id)
+          get_data(path("credentials", id))
+        end
+
+        # POST /credentials. A retry of a create that succeeded but whose
+        # answer was lost raises +idempotency_replay_unavailable+: list the
+        # application environment's credentials instead.
+        # @return [Hash] the credential, with its one-time +client_secret+
+        def create(application_environment_id:, idempotency_key: nil)
+          post_data(path("credentials"), { application_environment_id: application_environment_id }, idempotency_key)
+        end
+
+        # POST /credentials/:id/rotate: a new secret; the old one keeps
+        # working for the grace window (see +previous_secret+).
+        # @return [Hash] the credential, with its new one-time +client_secret+
+        def rotate(id, idempotency_key: nil)
+          post_data(path("credentials", id, "rotate"), nil, idempotency_key)
+        end
+
+        # DELETE /credentials/:id: revokes the credential on intake, then
+        # removes it. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("credentials", id))
+        end
+        alias revoke delete
+      end
+    end
+  end
+end

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