spree_api 6.0.2 → 6.0.3

data/lib/spree/api/admin_document.rb

@@ -0,0 +1,284 @@
+module Spree
+  module Api
+    # The Admin API's OpenAPI document as agents read it: core's `admin.yaml`
+    # merged with the `openapi/admin.yaml` each extension ships in its gem.
+    #
+    # An extension documents its admin endpoints the way core does — rswag
+    # integration specs, generated into a file — so its operations reach
+    # agents, API docs and SDKs from the same contract. Nothing registers the
+    # file: an engine that has one is read.
+    #
+    # Loaded once, lazily: core's document alone is well over a megabyte, and
+    # an installation with no agent client should never pay for parsing it.
+    #
+    # See docs/plans/6.0-agent-tools-from-openapi.md.
+    module AdminDocument
+      FILTER_TABLES = 'x-spree-filter-tables'.freeze
+
+      # Where an extension keeps its generated document, relative to its root.
+      EXTENSION_PATH = File.join('openapi', 'admin.yaml')
+
+      HTTP_VERBS = %w[get post put patch delete head options].freeze
+
+      class << self
+        # @return [Hash] the merged document
+        def document
+          @document ||= load_document
+        end
+
+        # Operations or components two documents describe differently. The
+        # first document keeps them — core's, then extensions in load order —
+        # and the later one's are left out rather than silently replacing an
+        # endpoint or failing every tool; the contract spec fails on any.
+        #
+        # @return [Array<String>]
+        def conflicts
+          document
+          @conflicts
+        end
+
+        # Which document an operation came from, so a contract spec can check
+        # an extension against its own operations only.
+        #
+        # @param path [String] the OpenAPI path, e.g. `/api/v3/admin/quotes/{id}/send`
+        # @param verb [String, Symbol]
+        # @return [String, nil] the engine's name, or `spree_api` for core
+        def source_of(path, verb)
+          document
+          @sources[[path, verb.to_s.downcase]]
+        end
+
+        # Forgets the parsed document only when a document file changed, so a
+        # code reload in development does not re-parse a megabyte of generated
+        # YAML that no edit to Ruby could have changed.
+        #
+        # @return [void]
+        def refresh!
+          current = signature
+          reset! unless current == @signature
+          @signature = current
+        end
+
+        # Forgets the parsed document, so the next reader loads it again.
+        #
+        # @return [void]
+        def reset!
+          @document = nil
+          @sources = nil
+          @conflicts = nil
+        end
+
+        # Core's generated document: `docs/` in a source checkout, or the copy
+        # the release packs into the gem. Resolved lazily: the engine class
+        # does not exist yet while this file loads.
+        #
+        # @return [Pathname]
+        def core_path
+          source = Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')
+          source.exist? ? source : Spree::Api::Engine.root.join(EXTENSION_PATH)
+        end
+
+        # Every other engine that ships a document, and the application
+        # itself, which may add admin endpoints of its own.
+        #
+        # @return [Hash{String => Pathname}] engine name => document
+        def extension_paths
+          engines = Rails.application.railties.grep(Rails::Engine) + [Rails.application]
+          engines.each_with_object({}) do |engine, paths|
+            next if engine.is_a?(Spree::Api::Engine)
+
+            path = engine.root&.join(EXTENSION_PATH)
+            next unless path&.exist?
+            next if path.expand_path == core_path.expand_path
+
+            paths[engine.engine_name] = path
+          end
+        end
+
+        # A request body is declared once per endpoint and published as a
+        # component, so the operation carries a `$ref` to it rather than the
+        # properties themselves. A body that builds on a shared shape is an
+        # `allOf` of that shape and its own fields, read as one object.
+        # Followed a few hops, which is as deep as the generated document
+        # nests them.
+        #
+        # @param schema [Hash, nil] a schema that may be a reference
+        # @return [Hash, nil] the schema it names
+        def resolve_schema(schema, depth = 0)
+          return unless schema.is_a?(Hash)
+          return if depth > 3
+          return merge_all_of(schema['allOf'], depth) if schema.key?('allOf')
+          return schema unless schema.key?('$ref')
+
+          resolve_schema(component(schema['$ref']), depth + 1)
+        end
+
+        # The schema with every reference replaced by what it names, all the
+        # way down, so it can be handed to a client that has no document to
+        # look `$ref`s up in. A reference that leads back to itself stops at
+        # an untyped object rather than recursing.
+        #
+        # @param schema [Object]
+        # @return [Object]
+        def inline(schema, seen = [])
+          case schema
+          when Array
+            schema.map { |item| inline(item, seen) }
+          when Hash
+            return inline_reference(schema, seen) if schema.key?('$ref')
+            return inline(merge_all_of(schema['allOf'], 0), seen) if schema.key?('allOf')
+
+            schema.transform_values { |value| inline(value, seen) }
+          else
+            schema
+          end
+        end
+
+        # A parameter, followed through a `$ref` to `components/parameters`.
+        #
+        # @param parameter [Hash]
+        # @return [Hash, nil]
+        def resolve_parameter(parameter)
+          return parameter unless parameter.is_a?(Hash) && parameter.key?('$ref')
+
+          document.dig('components', 'parameters', parameter['$ref'].to_s.split('/').last)
+        end
+
+        private
+
+        def signature
+          ([core_path] + extension_paths.values).map { |path| [path.to_s, (File.mtime(path) if File.exist?(path))] }
+        end
+
+        def inline_reference(schema, seen)
+          reference = schema['$ref']
+          return { 'type' => 'object' } if seen.include?(reference)
+
+          target = component(reference)
+          target ? inline(target, seen + [reference]) : { 'type' => 'object' }
+        end
+
+        def component(reference)
+          name = reference.to_s.split('/').last
+          document.dig('components', 'schemas', name)
+        end
+
+        def merge_all_of(parts, depth)
+          parts.filter_map { |part| resolve_schema(part, depth + 1) }.each_with_object({}) do |part, merged|
+            merged['properties'] = (merged['properties'] || {}).merge(part['properties'] || {})
+            merged['required'] = (merged['required'] || []) | Array(part['required'])
+          end
+        end
+
+        def load_document
+          @sources = {}
+          @conflicts = []
+          merged = read(core_path)
+          record_sources(merged, 'spree_api')
+          @core_filter_tables = merged.dig('components', FILTER_TABLES).to_h.keys.to_set
+
+          extension_paths.each do |engine, path|
+            merge!(merged, read(path), engine)
+          end
+
+          merged
+        end
+
+        # A document that is missing or does not parse is not a boot failure:
+        # its operations are simply not offered, which is the safe direction.
+        def read(path)
+          return {} unless File.exist?(path)
+
+          document = YAML.unsafe_load_file(path)
+          return document if valid?(document)
+
+          Rails.logger.warn("[Spree] the admin API document #{path} is not an OpenAPI document; it is ignored")
+          {}
+        rescue StandardError => e
+          Rails.logger.warn("[Spree] could not read the admin API document #{path}: #{e.class}: #{e.message}")
+          {}
+        end
+
+        # An OpenAPI document whose operations are objects: anything else
+        # would raise in a reader that digs into it, on every agent request.
+        def valid?(document)
+          document.is_a?(Hash) && document.key?('openapi') &&
+            Array(document['paths']).all? { |path, item| path.is_a?(String) && valid_path_item?(item) } &&
+            (document['components'].nil? || document['components'].is_a?(Hash))
+        end
+
+        def valid_path_item?(item)
+          item.is_a?(Hash) && item.all? do |key, operation|
+            next true unless HTTP_VERBS.include?(key)
+
+            operation.is_a?(Hash) && valid_request_body?(operation['requestBody'])
+          end
+        end
+
+        # The catalog digs `content`, `application/json` and `schema`, so each
+        # is an object where present.
+        def valid_request_body?(body)
+          return true if body.nil?
+          return false unless body.is_a?(Hash)
+          return true if body['content'].nil?
+          return false unless body['content'].is_a?(Hash)
+
+          json = body['content']['application/json']
+          json.nil? || (json.is_a?(Hash) && (json['schema'].nil? || json['schema'].is_a?(Hash)))
+        end
+
+        def conflict(message)
+          @conflicts << message
+          Rails.logger.error("[Spree] admin API documents conflict: #{message}")
+        end
+
+        def record_sources(document, engine)
+          Array(document['paths']).each do |path, operations|
+            operations.each_key { |verb| @sources[[path, verb.to_s]] = engine if HTTP_VERBS.include?(verb.to_s) }
+          end
+        end
+
+        def merge!(merged, addition, engine)
+          merged['paths'] ||= {}
+          Array(addition['paths']).each do |path, operations|
+            existing = merged['paths'][path] ||= {}
+            operations.each do |key, value|
+              # Path-level keys (`parameters`) describe the path, not an
+              # operation, and two documents for one path share them.
+              next existing[key] ||= value unless HTTP_VERBS.include?(key)
+
+              if existing.key?(key)
+                conflict("#{key.upcase} #{path} is documented by both #{@sources[[path, key]]} and #{engine}")
+                next
+              end
+
+              existing[key] = value
+              @sources[[path, key]] = engine
+            end
+          end
+
+          components = merged['components'] ||= {}
+          Array(addition['components']).each do |section, definitions|
+            next unless definitions.is_a?(Hash)
+
+            existing = components[section] ||= {}
+            definitions.each do |name, definition|
+              # An extension's document carries the filter tables of the core
+              # records its filters reach, as the extension's own app filters
+              # them, so its SDK types are complete. Another gem there may
+              # change one (an extra scope); core's definition stands.
+              next if section == FILTER_TABLES && @core_filter_tables.include?(name)
+
+              if existing.key?(name) && existing[name] != definition
+                conflict("the #{name} #{section.singularize} is defined differently by #{engine} and an earlier document")
+                next
+              end
+
+              existing[name] = definition
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/agent_operations.rb

@@ -0,0 +1,300 @@
+module Spree
+  module Api
+    # Fills {Spree::AgentTools::OperationCatalog} from the merged Admin API
+    # document ({AdminDocument}) and the routes behind it.
+    #
+    # Every write operation that is not a resource's plain create, update or
+    # destroy becomes a tool — cancel, capture, approve, send — unless its
+    # spec opts it out with a reason. CRUD stays with the generic tools, and a
+    # read becomes a tool only when its spec opts it in. Nothing here is a
+    # list of tools: an endpoint that gains an rswag spec is a tool in the
+    # same commit, core's or an extension's.
+    #
+    # See docs/plans/6.0-agent-tools-from-openapi.md.
+    module AgentOperations
+      WRITE_VERBS = %w[post patch put delete].freeze
+      CRUD_ACTIONS = %w[index show create update destroy].freeze
+      ADMIN_PREFIX = '/api/v3/admin/'.freeze
+
+      # The opt-out and opt-in marks an rswag spec sets (see the `agent_tool`
+      # spec helper), and the reason an opt-out must carry.
+      AGENT_KEY = 'x-spree-agent'.freeze
+      REASON_KEY = 'x-spree-agent-reason'.freeze
+
+      # The line `admin_scope` appends to a description. It is for the
+      # rendered docs; a tool is already offered only to a key holding it.
+      SCOPE_NOTE = /^\*\*Required scope:\*\*.*$/
+
+      class << self
+        # Registers this walk as how the catalog fills itself, and marks it
+        # stale so the next reader gets a fresh one.
+        #
+        # @return [void]
+        def stale!
+          Spree::AgentTools::OperationCatalog.deriver = -> { install }
+          Spree::AgentTools::OperationCatalog.stale!
+          Spree::AgentTools::OperationTool.clear_cache!
+          AdminDocument.refresh!
+          AgentWriteSchemas.reset!
+        end
+
+        # @param catalog [Module] defaults to the core catalog
+        # @return [Integer] how many operations were registered
+        def install(catalog: Spree::AgentTools::OperationCatalog)
+          catalog.reset!
+          @models = {}
+
+          by_route = candidates.index_by { |candidate| [candidate[:verb], candidate[:path]] }
+          included = by_route.values.select { |candidate| disposition(candidate) == :included }
+          listed = resolve_collisions(included.filter_map { |candidate| safe_entry_for(candidate) })
+          listed.each { |entry| catalog.register(**entry) }
+          register_aliases(catalog, by_route, listed.to_set { |entry| entry[:name] })
+
+          listed.size
+        end
+
+        # Every admin operation in the document, with the route and
+        # controller it resolves to. Public for the contract spec, which
+        # reports the operations that resolve to nothing.
+        #
+        # @return [Array<Hash>]
+        def candidates
+          routes = route_index
+
+          Array(AdminDocument.document['paths']).flat_map do |path, operations|
+            next [] unless path.is_a?(String) && path.start_with?(ADMIN_PREFIX) && operations.is_a?(Hash)
+
+            operations.filter_map do |verb, operation|
+              next unless operation.is_a?(Hash) && (WRITE_VERBS + ['get']).include?(verb)
+
+              { path: path, verb: verb, operation: operation, route: routes[[verb, path]],
+                path_parameters: Array(operations['parameters']) }
+            end
+          end
+        end
+
+        # Whether an operation becomes a listed tool, and if not, why.
+        #
+        # @param candidate [Hash]
+        # @return [Symbol] :included, :crud, :read, :opted_out, :unrouted,
+        #   :unscoped or :withheld
+        def disposition(candidate)
+          return :unrouted if candidate[:route].nil?
+
+          controller = candidate[:route][:controller]
+          return :unscoped if controller.nil? || scope_of(controller).blank?
+          return :withheld if withheld?(controller)
+
+          flag = candidate[:operation][AGENT_KEY]
+          return :opted_out if flag == false
+
+          if candidate[:verb] == 'get'
+            flag == true ? :included : :read
+          elsif CRUD_ACTIONS.include?(candidate[:route][:action])
+            # A create that is really an action — receiving stock against a
+            # transfer — names its tool explicitly, and is then offered as one.
+            candidate[:operation]['operationId'].present? ? :included : :crud
+          else
+            :included
+          end
+        end
+
+        # Every admin route, with its path in OpenAPI form, from the engine's
+        # routes — where an extension's admin routes are drawn too. Public for
+        # the contract spec, which checks each against the document.
+        #
+        # @return [Array<Hash>] `{verb:, path:, controller:, action:}`
+        def admin_routes
+          Spree::Core::Engine.routes.routes.flat_map do |route|
+            controller_path = route.defaults[:controller].to_s
+            next [] unless controller_path.start_with?('spree/api/v3/admin')
+
+            path = route.path.spec.to_s.sub('(.:format)', '').gsub(/:([a-z_]+)/, '{\1}')
+            route.verb.to_s.split('|').map do |verb|
+              { verb: verb.downcase, path: path, controller: controller_class(controller_path),
+                action: route.defaults[:action].to_s }
+            end
+          end
+        end
+
+        # The tool name an operation gets: its `operationId`, or the resource
+        # and the action.
+        #
+        # @return [String]
+        def tool_name(candidate)
+          candidate[:operation]['operationId'].presence ||
+            "#{resource_key(candidate[:route][:controller])}_#{candidate[:route][:action]}"
+        end
+
+        private
+
+        # One operation the catalog cannot read is left out and logged, rather
+        # than taking every other tool down with it: validating a document's
+        # shape up front cannot foresee every way a generated file goes wrong.
+        def safe_entry_for(candidate)
+          entry_for(candidate)
+        rescue StandardError => e
+          Rails.logger.error("[Spree] agent tool for #{candidate[:verb].upcase} #{candidate[:path]} left out: " \
+                             "#{e.class}: #{e.message}")
+          nil
+        end
+
+        def entry_for(candidate)
+          operation = candidate[:operation]
+          controller = candidate[:route][:controller]
+          name = tool_name(candidate)
+          read = candidate[:verb] == 'get'
+          # A read takes its arguments as query parameters, a write as its body.
+          body = read ? query_schema(Array(candidate[:path_parameters]) + Array(operation['parameters'])) : request_body(operation)
+
+          {
+            name: name,
+            verb: candidate[:verb],
+            path: candidate[:path],
+            summary: operation['summary'].to_s,
+            description: description_for(operation),
+            permission: "#{scope_kind(controller, candidate[:route][:action])}_#{scope_of(controller)}",
+            resource_key: resource_key(controller),
+            path_params: candidate[:path].scan(/\{([a-z_]+)\}/).flatten,
+            path_descriptions: path_descriptions(candidate[:path_parameters] + Array(operation['parameters'])),
+            body_properties: body.fetch('properties', {}),
+            body_required: Array(body['required']),
+            legacy_parameters: Spree::AgentTools::LegacyTools.parameters_for(name, candidate[:verb], candidate[:path])
+          }
+        end
+
+        # A 6.0.0 tool whose name is no longer derived — it pointed at a
+        # create, or carried its workflow's name — stays callable through
+        # 6.0.x, unlisted, under that name.
+        def register_aliases(catalog, by_route, listed_names)
+          # The catalog is still being filled, so the names already offered
+          # are passed in rather than read back from it.
+          Spree::AgentTools::LegacyTools::TOOLS.each do |old, tool|
+            next if listed_names.include?(old)
+
+            candidate = by_route[[tool[:verb], tool[:path]]]
+            next unless candidate && %i[included crud].include?(disposition(candidate))
+
+            entry = safe_entry_for(candidate)
+            catalog.register_alias(**entry, name: old, legacy_parameters: tool[:parameters]) if entry
+          end
+        end
+
+        # Two operations deriving one name: the shallower path keeps it, and
+        # the contract spec fails so the other gets an `operationId`.
+        def resolve_collisions(entries)
+          entries.group_by { |entry| entry[:name] }.map do |name, claimants|
+            next claimants.first if claimants.one?
+
+            kept = claimants.min_by { |entry| [entry[:path].count('{'), entry[:path].length] }
+            Rails.logger.warn("[Spree] agent tool #{name} is derived by #{claimants.size} operations; " \
+                              "#{kept[:verb].upcase} #{kept[:path]} keeps it")
+            kept
+          end
+        end
+
+        # The summary, then the description's opening paragraph: what the
+        # operation does, in the words its spec already reviews.
+        def description_for(operation)
+          prose = operation['description'].to_s.gsub(SCOPE_NOTE, '').strip
+          paragraph = prose.split(/\n\s*\n/).first.to_s.squish
+
+          [operation['summary'].to_s.strip.delete_suffix('.'), paragraph].compact_blank.join('. ')
+        end
+
+        # Path-level parameters first, so an operation's own description of a
+        # segment wins.
+        def path_descriptions(parameters)
+          parameters.map { |parameter| AdminDocument.resolve_parameter(parameter) }.each_with_object({}) do |parameter, result|
+            next unless parameter.is_a?(Hash) && parameter['in'] == 'path'
+
+            result[parameter['name']] = parameter['description'] if parameter['description'].present?
+          end
+        end
+
+        # Path-level parameters first, so an operation's own one of the same
+        # name wins.
+        def query_schema(parameters)
+          parameters = parameters.map { |parameter| AdminDocument.resolve_parameter(parameter) }.
+                       select { |parameter| parameter.is_a?(Hash) && parameter['in'] == 'query' }.
+                       reverse.uniq { |parameter| parameter['name'] }.reverse
+          properties = parameters.to_h do |parameter|
+            [parameter['name'], json_schema(AdminDocument.inline(parameter['schema'] || {}).merge(
+              { 'description' => parameter['description'] }.compact
+            ))]
+          end
+
+          { 'properties' => properties, 'required' => parameters.select { |p| p['required'] }.map { |p| p['name'] } }
+        end
+
+        def request_body(operation)
+          content = operation['requestBody'].is_a?(Hash) ? operation['requestBody']['content'] : nil
+          schema = content.is_a?(Hash) ? content.dig('application/json', 'schema') : nil
+          schema ? json_schema(AdminDocument.inline(schema)) : {}
+        end
+
+        # OpenAPI 3.0 marks a nullable field with `nullable: true`; JSON
+        # Schema, which a client validates arguments against, says it with a
+        # type list.
+        def json_schema(schema)
+          case schema
+          when Array then schema.map { |item| json_schema(item) }
+          when Hash
+            converted = schema.except('nullable').transform_values { |value| json_schema(value) }
+            if schema['nullable'] == true && converted['type'].is_a?(String)
+              converted['type'] = [converted['type'], 'null']
+            end
+            converted
+          else schema
+          end
+        end
+
+        # [verb, OpenAPI path] => the action behind it.
+        def route_index
+          admin_routes.each_with_object({}) do |route, index|
+            index[[route[:verb], route[:path]]] ||= route.slice(:controller, :action)
+          end
+        end
+
+        def controller_class(controller_path)
+          "#{controller_path}_controller".camelize.safe_constantize
+        end
+
+        def scope_of(controller)
+          controller.try(:_scoped_resource)
+        end
+
+        # The scope kind the endpoint itself demands for an action — `read`
+        # for the controller's read actions, `write` otherwise — so a tool is
+        # offered to exactly the keys the endpoint will let through.
+        def scope_kind(controller, action)
+          instance = controller.allocate
+          reads = instance.respond_to?(:read_actions, true) ? instance.send(:read_actions) : %w[index show]
+          Array(reads).map(&:to_s).include?(action) ? 'read' : 'write'
+        rescue StandardError, NotImplementedError
+          'write'
+        end
+
+        # Controllers whose records carry a live credential — the ones the
+        # resource map withholds — offer no tools either: an action on an API
+        # key or a webhook endpoint answers with the secret.
+        def withheld?(controller)
+          model = model_for(controller)
+          model && AgentResourceMap::WITHHELD_MODELS.include?(model.name)
+        end
+
+        # Keyed the way the resource map keys the model, so a tool's
+        # resource_key finds its entry there.
+        def resource_key(controller)
+          model = model_for(controller)
+          model ? AgentResourceMap.key_for(model) : controller.controller_name
+        end
+
+        # Once per controller per derivation: every operation it serves asks.
+        def model_for(controller)
+          (@models ||= {}).fetch(controller) { @models[controller] = AgentResourceMap.model_for(controller) }
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/agent_resource_map.rb

@@ -142,6 +142,15 @@ module Spree
             transform_values { |pairs| pairs.map(&:last).min_by { |path| [path.count(':'), path.length] } }
         end
 
+        # The controller served at the shallowest path, which is where a tool
+        # dispatches: for a record it is the show path, else the collection.
+        def shallowest_candidate(candidates)
+          candidates.min_by do |entry|
+            path = Array(entry[:api_paths]).to_h.values_at(:show, :index).compact.first.to_s
+            [path.empty? ? Float::INFINITY : path.count(':'), path.length]
+          end
+        end
+
         def api_paths_for(controller)
           candidates = Spree::Core::Engine.routes.routes.filter_map do |route|
             next unless route.defaults[:controller] == controller.controller_path
@@ -190,6 +199,24 @@ module Spree
           }
         end
 
+        # The plural the resource is addressed by, taken from the model so two
+        # controllers serving the same model (a nested one and a top-level one)
+        # agree on it. The operation catalog keys its tools the same way.
+        #
+        # @param model [Class]
+        # @return [String]
+        def key_for(model)
+          model.model_name.element.pluralize
+        end
+
+        # The model a controller serves, or nil for one that serves none.
+        #
+        # @param controller [Class]
+        # @return [Class, nil]
+        def model_for(controller)
+          safely(controller.allocate, :model_class)
+        end
+
         private
 
         # What the controller does with its own collection. A controller that
@@ -228,6 +255,11 @@ module Spree
             # withdrawn, and only when the controllers disagree about the
             # scope guarding it.
             narrowest.merge(
+              # The serializer of the controller the tools actually reach:
+              # the one whose path won below. `narrowest` is chosen on
+              # permission, which left `products` described by the catalog
+              # membership serializer and `expand: ["variants"]` refused.
+              serializer_name: shallowest_candidate(candidates)[:serializer_name],
               create_workflow_key: candidates.filter_map { |entry| entry[:create_workflow_key] }.first,
               update_workflow_key: candidates.filter_map { |entry| entry[:update_workflow_key] }.first,
               write_permission: contested ? nil : narrowest[:write_permission],
@@ -299,13 +331,6 @@ module Spree
           false
         end
 
-        # The plural the resource is addressed by, taken from the model so two
-        # controllers serving the same model (a nested one and a top-level one)
-        # agree on it.
-        def key_for(model)
-          model.model_name.element.pluralize
-        end
-
         # `Spree::Base.for_store` falls back to the bare class for a model with
         # no Store association, which would hand this store's agent every
         # store's rows. A model that defines its own `for_store` has made a