Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Derive the agent resource map from the admin controllers

Damian Legawiecf6057e79c25d
diff --git a/spree/api/lib/spree/api/agent_resource_map.rb b/spree/api/lib/spree/api/agent_resource_map.rb
new file mode 100644
index 0000000000..ad3e4438d7
--- /dev/null
+++ b/spree/api/lib/spree/api/agent_resource_map.rb
@@ -0,0 +1,205 @@
+module Spree
+ module Api
+ # Fills {Spree::AgentTools::ResourceMap} from the Admin API's own
+ # controllers.
+ #
+ # Nothing here is a list. Every admin resource controller already declares
+ # the model it serves, the serializer it renders, the permission scope it
+ # rides and the workflow it writes through — so the map an agent reads is
+ # the API surface by construction, and a resource cannot drift from the
+ # endpoint that serves it. A controller that gains an attribute gains it
+ # for agents in the same commit.
+ #
+ # The one fact a controller does not carry is where the record lives in the
+ # dashboard, which is only used to link to it, so those are kept here.
+ #
+ # See docs/plans/6.0-mcp-server.md.
+ module AgentResourceMap
+ # Dashboard routes, for results that link to the record rather than
+ # describing where to find it. Store-relative: the panel prefixes the
+ # current store segment.
+ DASHBOARD_PATHS = {
+ 'products' => '/products/%<id>s',
+ 'categories' => '/products/categories/%<id>s',
+ 'collections' => '/products/collections/%<id>s',
+ 'price_lists' => '/products/price-lists/%<id>s',
+ 'orders' => '/orders/%<id>s',
+ 'customers' => '/customers/%<id>s',
+ 'companies' => '/companies/%<id>s',
+ 'sellers' => '/sellers/%<id>s',
+ 'promotions' => '/promotions/%<id>s',
+ 'channels' => '/settings/channels',
+ 'markets' => '/settings/markets',
+ 'payment_methods' => '/settings/payment-methods',
+ 'delivery_profiles' => '/settings/delivery-profiles',
+ 'stock_locations' => '/settings/stock-locations',
+ 'tax_categories' => '/settings/tax-categories',
+ 'tax_rates' => '/settings/tax-rates',
+ 'product_types' => '/settings/product-types',
+ 'commission_rates' => '/settings/commission-rates',
+ 'roles' => '/settings/roles',
+ 'return_reasons' => '/settings/reasons',
+ 'allowed_origins' => '/settings/allowed-origins',
+ 'imports' => '/settings/imports'
+ }.freeze
+
+ # Resources whose controller writes through a Tier 1 service rather
+ # than a workflow. Order editing, fees, discounts, addresses, stock
+ # levels and store credits reach agents when those paths become
+ # workflows (the 6.1 order-change substrate covers most of them), never
+ # through a generic write that would bypass the orchestration the
+ # service performs. See docs/plans/6.0-mcp-server.md, "What is not
+ # exposed at 6.0".
+ SERVICE_WRITTEN_MODELS = %w[
+ Spree::Order
+ Spree::Return
+ Spree::Exchange
+ Spree::Claim
+ Spree::StockLevel
+ Spree::StoreCredit
+ Spree::Refund
+ Spree::Payment
+ Spree::ShippingLabel
+ Spree::StockMovement
+ Spree::StockReservation
+ Spree::SellerPayout
+ Spree::SellerTransfer
+ Spree::Delivery
+ ].freeze
+
+ # Resources withheld whatever their controller says, because their
+ # serializer carries a live credential or a bearer instrument. Every
+ # tool result reaches a model and, for a hosted client, a third party.
+ #
+ # api_keys, integrations, webhook_endpoints — plaintext tokens,
+ # provider credentials and the secret that signs deliveries.
+ # gift_cards — the code IS the instrument: whoever reads it can spend
+ # the balance. A balance tool that never emits a code could be added.
+ WITHHELD_MODELS = %w[
+ Spree::ApiKey
+ Spree::Integration
+ Spree::WebhookEndpoint
+ Spree::GiftCard
+ ].freeze
+
+ class << self
+ # Walks every admin resource controller and registers what it serves.
+ #
+ # @param map [Class] defaults to the core resource map
+ # @return [Integer] how many resources were registered
+ def install(map: Spree::AgentTools::ResourceMap)
+ map.reset!
+
+ controllers.each do |controller|
+ entry = derive(controller)
+ next if entry.nil?
+
+ map.register(**entry)
+ end
+
+ map.all.size
+ end
+
+ # Every admin resource controller in the application, the abstract
+ # bases excluded. Eager-loaded first: in development only the
+ # controllers already used would otherwise be known, and the map would
+ # differ between a fresh boot and a warm one.
+ #
+ # @return [Array<Class>]
+ def controllers
+ Rails.application.eager_load! unless Rails.application.config.eager_load
+
+ Spree::Api::V3::Admin::ResourceController.descendants.reject(&:abstract?).sort_by(&:name)
+ end
+
+ # What one controller contributes, or nil when it serves nothing an
+ # agent can address.
+ #
+ # @param controller [Class]
+ # @return [Hash, nil]
+ def derive(controller)
+ instance = controller.allocate
+ model = safely(instance, :model_class)
+ return if model.nil? || WITHHELD_MODELS.include?(model.name)
+
+ scope = controller._scoped_resource
+ return if scope.blank?
+
+ serializer = safely(instance, :serializer_class)
+ return if serializer.nil?
+
+ key = key_for(model)
+ return unless store_scoped?(model)
+
+ create_workflow = workflow_key(instance, :create_workflow)
+ update_workflow = workflow_key(instance, :update_workflow)
+
+ {
+ key: key,
+ model_name: model.name,
+ permission: "read_#{scope}",
+ serializer_name: serializer.name,
+ dashboard_path: DASHBOARD_PATHS[key],
+ write_permission: write_permission_for(model, scope, create_workflow, update_workflow),
+ writable_attributes: AgentWriteSchemas.attribute_names(key),
+ create_workflow_key: create_workflow,
+ update_workflow_key: update_workflow
+ }
+ end
+
+ private
+
+ # A resource is generically writable only when the Admin API writes it
+ # by saving the record, and it documents what a write may set. A
+ # workflow-written resource keeps its workflow key instead (so the
+ # refusal can name the tool), and a service-written one is not
+ # writable at all.
+ def write_permission_for(model, scope, create_workflow, update_workflow)
+ return if SERVICE_WRITTEN_MODELS.include?(model.name)
+ return if create_workflow.present? || update_workflow.present?
+
+ "write_#{scope}"
+ 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
+ # deliberate choice (customers are global by design and say so);
+ # inheriting the fallback is an accident, and a missing resource is
+ # better than a leaking one.
+ def store_scoped?(model)
+ return false unless model.respond_to?(:for_store)
+ return true if model.method(:for_store).owner != Spree::Base.singleton_class
+
+ !model.for_store(Spree::Store.new).equal?(model)
+ rescue StandardError
+ false
+ end
+
+ # The workflow a controller writes through, as its dotted key, so a
+ # generic write can name the tool that does the job instead.
+ def workflow_key(instance, method_name)
+ workflow = safely(instance, method_name)
+ workflow.respond_to?(:workflow_key) ? workflow.workflow_key : nil
+ end
+
+ # A controller may raise from any of these — `model_class` is
+ # NotImplementedError on an abstract one, `permitted_attributes` reads
+ # request state on a few — and one such controller must not take the
+ # whole map down at boot.
+ def safely(instance, method_name)
+ instance.send(method_name)
+ rescue StandardError, NotImplementedError
+ nil
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/lib/spree/api/agent_write_schemas.rb b/spree/api/lib/spree/api/agent_write_schemas.rb
new file mode 100644
index 0000000000..ae0f97b820
--- /dev/null
+++ b/spree/api/lib/spree/api/agent_write_schemas.rb
@@ -0,0 +1,91 @@
+module Spree
+ module Api
+ # The writable attribute schema for each admin resource, read from the
+ # generated OpenAPI document.
+ #
+ # Not from the controllers: most of them declare their writable attributes
+ # inside `permitted_params`, where the list is a `params.permit` call that
+ # cannot be read without a request. `admin.yaml` already carries the same
+ # list — generated from the integration specs, reviewed as a diff on every
+ # API change — with the types, descriptions and examples a model needs to
+ # fill a form in correctly. Reading it means the generic write tools offer
+ # exactly the documented endpoint and nothing else.
+ #
+ # Loaded once, lazily: the document is well over a megabyte, and an
+ # installation with no agent client should never pay for parsing it.
+ module AgentWriteSchemas
+ # A collection endpoint under the admin namespace: `/api/v3/admin/markets`
+ # but not `/api/v3/admin/markets/{id}` or a nested child.
+ COLLECTION_PATH = %r{\A/api/v3/admin/(?<key>[a-z0-9_]+)\z}
+
+ class << self
+ # The writable properties for one resource.
+ #
+ # @param key [String] the resource key, e.g. "markets"
+ # @return [Hash] JSON Schema properties, empty when the resource has no
+ # documented write
+ def for(key)
+ schemas[key.to_s] || {}
+ end
+
+ # @return [Array<String>] the attribute names a write may set
+ def attribute_names(key)
+ self.for(key).keys
+ end
+
+ # @return [void]
+ def reset!
+ @schemas = nil
+ end
+
+ # Where the generated document lives, relative to this engine. Resolved
+ # lazily: the engine class does not exist yet while this file loads.
+ #
+ # @return [Pathname]
+ def spec_path
+ Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')
+ end
+
+ private
+
+ def schemas
+ @schemas ||= load_schemas
+ end
+
+ # A missing or unparseable document is not a boot failure: the generic
+ # write tools simply offer nothing, which is the safe direction. An
+ # installation running from the packaged gems has no docs/ directory at
+ # all.
+ def load_schemas
+ path = spec_path
+ return {} unless File.exist?(path)
+
+ document = YAML.unsafe_load_file(path)
+ extract(document)
+ rescue StandardError => e
+ Rails.logger.warn("[Spree] could not read admin API write schemas: #{e.class}: #{e.message}")
+ {}
+ end
+
+ def extract(document)
+ Array(document['paths']).to_h.each_with_object({}) do |(path, operations), result|
+ match = COLLECTION_PATH.match(path)
+ next if match.nil?
+
+ properties = write_properties(operations)
+ result[match[:key]] = properties if properties.present?
+ end
+ end
+
+ # The create body where there is one, because it documents every
+ # settable attribute; an update body usually repeats a subset.
+ def write_properties(operations)
+ body = operations.dig('post', 'requestBody', 'content', 'application/json', 'schema')
+ body ||= operations.dig('patch', 'requestBody', 'content', 'application/json', 'schema')
+
+ body.is_a?(Hash) ? body['properties'].presence : nil
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/lib/spree/api/engine.rb b/spree/api/lib/spree/api/engine.rb
index ed018c4ee1..ebe14dd849 100644
--- a/spree/api/lib/spree/api/engine.rb
+++ b/spree/api/lib/spree/api/engine.rb
@@ -2,6 +2,8 @@ require 'rails/engine'
require_relative 'dependencies'
require_relative 'configuration'
+require_relative 'agent_write_schemas'
+require_relative 'agent_resource_map'
module Spree
module Api
@@ -19,6 +21,14 @@ module Spree
app.middleware.insert_before Rack::Runtime, Spree::Api::Middleware::RequestSizeLimit
end
+ # The resources agents may read and write are derived from the admin
+ # controllers themselves (see Spree::Api::AgentResourceMap). Rebuilt on
+ # every reload, because a controller edited in development changes what
+ # the map should say.
+ config.to_prepare do
+ Spree::Api::AgentResourceMap.install
+ end
+
# Add API event subscribers
config.after_initialize do
Spree.subscribers << Spree::WebhookEventSubscriber