spree_api 5.6.1 → 6.0.0.beta2

data/app/controllers/spree/api/v3/admin/translations_controller.rb

@@ -50,20 +50,25 @@ module Spree
           end
 
           # Per-parent scope check: reading a product's translations needs
-          # `read_products`, a category's `read_categories`, etc.
+          # `read_products`, a category's `read_categories`, etc. The parent
+          # class resolves to its owning catalog resource (an option type's
+          # translations ride the `products` permission), falling back to the
+          # pluralized route segment for classes outside the catalog.
           def scoped_resource_name
-            parent_lookup&.segment&.pluralize&.to_sym
+            return unless parent_lookup
+
+            Spree::Translations.permission_resource_name(parent_lookup.klass)
           end
 
           # Translatable by class hierarchy, not strict equality, so a subclass
-          # instance (e.g. Spree::Category < Spree::Taxon) passes when its base
+          # instance (e.g. Spree::Category < Spree::Category) passes when its base
           # is registered.
           def ensure_translatable!
             # Compare by class NAME, not object identity: in dev the registry is
             # populated at boot, but the model constants are reloaded on edits,
             # so `is_a?(registered_class)` fails against a stale class object even
             # when @parent's live class (or an ancestor) matches by name. Walk the
-            # ancestor names so a subclass (Spree::Category < Spree::Taxon) passes.
+            # ancestor names so a subclass (Spree::Category < Spree::Category) passes.
             registered = Spree.translatable_resources.map(&:name).to_set
             translatable = @parent.class.ancestors.any? { |ancestor| registered.include?(ancestor.name) }
             raise ActiveRecord::RecordNotFound unless translatable
@@ -78,7 +83,7 @@ module Spree
           def parent_route_map
             @parent_route_map ||= Spree.translatable_resources.each_with_object({}) do |klass, m|
               m[klass.model_name.element.to_s] = klass.name
-            end.merge('category' => 'Spree::Taxon')
+            end.merge('category' => 'Spree::Category')
           end
 
           def parent_lookup

data/app/controllers/spree/api/v3/admin/translations_coverage_controller.rb

@@ -0,0 +1,150 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Translation coverage across a whole resource type: per-locale totals
+        # plus a paginated page of records carrying how many of their fields are
+        # translated in each locale. Drives the centralized Translations page.
+        #
+        # Registry-driven like the rest of this surface — `resource_type` names
+        # any member of Spree.translatable_resources, so a new translatable
+        # model needs no code here.
+        class TranslationsCoverageController < ResourceController
+          # GET /api/v3/admin/translations?resource_type=product
+          def index
+            records = collection
+            locales = translatable_locales
+
+            render json: {
+              data: {
+                'resource_type' => Spree::Translations.public_resource_type(model_class),
+                'default_locale' => current_store.default_locale,
+                'locales' => locales,
+                'field_count' => model_class.public_translatable_fields.size,
+                'search_field' => search_field,
+                'coverage' => Spree::Translations.coverage_for(scope, model_class, locales),
+                'records' => serialize_records(records, locales)
+              },
+              meta: collection_meta(records)
+            }
+          end
+
+          protected
+
+          # Resolved from the required `resource_type` param. An unknown or
+          # untranslatable type is a 404 rather than a 500 from a nil class.
+          def model_class
+            @model_class ||=
+              Spree::Translations.resource_class(params[:resource_type]) ||
+              raise(ActiveRecord::RecordNotFound, "Unknown translatable resource type: #{params[:resource_type]}")
+          end
+
+          # Reading a product's coverage needs `read_products`, a category's
+          # `read_categories` — the same per-parent rule the per-resource
+          # translations endpoint applies.
+          def scoped_resource_name
+            return :settings if params[:resource_type].blank?
+
+            Spree::Translations.permission_resource_name(model_class)
+          end
+
+          # Store-scoped by the model itself, then ability-filtered the way the
+          # admin base class does so a host app's record-level rules still bind.
+          # Memoized: `index` reaches this for the paginated page and again for
+          # the store-wide totals, and rebuilding it re-runs the ability filter
+          # each time.
+          def scope
+            @scope ||= model_class.translatable_scope(current_store).
+                       accessible_by(current_ability, ability_action_for_request)
+          end
+
+          # Coverage itself reads the translation tables in one grouped query,
+          # so nothing needs eager-loading for it. The per-row label is a
+          # different matter: it is normally answered from the record's own
+          # column, but `always_use_translations` sends even the default locale
+          # through the translation table, which without a preload is a query
+          # per row.
+          def collection_includes
+            Spree.always_use_translations? ? [:translations] : []
+          end
+
+          # The grid sends a plain `search` term and lets the server choose the
+          # predicate, since which one a model whitelists varies (`name` on
+          # products and categories, nothing usable on collections).
+          def ransack_params
+            term = params[:search].presence
+            field = search_field
+            return super unless term && field
+
+            super.to_h.merge(field => term)
+          end
+
+          private
+
+          # The Ransack predicate the client may filter this grid by, or nil
+          # when the model whitelists nothing usable. Reported rather than
+          # assumed: `name` is ransackable on products and categories but not
+          # on collections, and a client guessing `name_cont` either errors or
+          # silently returns the unfiltered list.
+          #
+          # @return [String, nil]
+          # The predicate the grid filters by. It has to match the column the
+          # grid DISPLAYS, which is the record's first public translatable
+          # field — for an option type that is `label`, while `name` holds a
+          # slug. Searching `name` there means typing the visible label
+          # ("Shirt Size") returns nothing.
+          #
+          # Falls back to `name` when the displayed column is not ransackable,
+          # since Ransack's defaults always carry it.
+          #
+          # @return [String, nil]
+          def search_field
+            return @search_field if defined?(@search_field)
+
+            attributes = model_class.ransackable_attributes
+            column = displayed_column
+            field = [column, 'name'].compact.find { |candidate| attributes.include?(candidate) }
+            @search_field = field && "#{field}_cont"
+          end
+
+          # The internal column behind the record's displayed label, resolving
+          # any public-name alias.
+          #
+          # @return [String, nil]
+          def displayed_column
+            public_field = model_class.public_translatable_fields.first
+            return if public_field.nil?
+
+            (model_class.translatable_field_aliases[public_field] || public_field).to_s
+          end
+
+          def translatable_locales
+            Spree::Translations.non_default_locales(current_store)
+          end
+
+          # Each record carries its identifying label (whatever its first
+          # translatable field is — `name` for most, `label` for option types)
+          # read in the default locale, so the grid needs no second request.
+          def serialize_records(records, locales)
+            counts = Spree::Translations.translated_counts(records, model_class, locales)
+            label_field = model_class.public_translatable_fields.first
+
+            Mobility.with_locale(current_store.default_locale) do
+              records.map do |record|
+                {
+                  'id' => record.prefixed_id,
+                  'label' => record.public_send(label_field),
+                  'locales' => locales.index_with { |locale| counts.dig(record.id, locale).to_i }
+                }
+              end
+            end
+          end
+
+          def action_kind
+            'read'
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/variants_controller.rb

@@ -15,15 +15,22 @@ module Spree
             Spree.api.admin_variant_serializer
           end
 
+          # Chains onto the base scope rather than replacing it: building the
+          # relation from scratch dropped `scope_includes`, so every listed
+          # variant fell back to per-row price and stock queries.
           def scope
-            current_store.variants.eligible.accessible_by(current_ability, ability_action_for_request)
+            super.eligible.accessible_by(current_ability, ability_action_for_request)
           end
 
+          # `active_stock_reservations` rides along with the stock levels:
+          # without it the quantifier falls back to a SUM per variant, which
+          # is the whole cost of listing variants.
           def scope_includes
             [
-              :prices, stock_items: :stock_location,
-              option_values: :option_type,
-              primary_media: [attachment_attachment: :blob]
+              :prices,
+              { stock_levels: [:stock_location, :active_stock_reservations] },
+              { option_values: :option_type },
+              { primary_media: [{ attachment_attachment: :blob }, { poster_attachment: :blob }] }
             ]
           end
         end

data/app/controllers/spree/api/v3/admin/webhook_endpoints_controller.rb

@@ -66,7 +66,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:name, :url, :active, subscriptions: [])
+            params.permit(*model_additional_permitted_attributes, :name, :url, :active, subscriptions: [])
           end
         end
       end

data/app/controllers/spree/api/v3/base_controller.rb

@@ -7,7 +7,6 @@ module Spree
 
         include ActiveStorage::SetCurrent
         include CanCan::ControllerAdditions
-        include Spree::Core::ControllerHelpers::StrongParameters
         include Spree::Core::ControllerHelpers::Store
         include Spree::Api::V3::LocaleAndCurrency
         include Spree::Api::V3::JwtAuthentication
@@ -19,37 +18,96 @@ module Spree
         include Spree::Api::V3::Idempotent
         include Pagy::Method
 
-        RATE_LIMIT_RESPONSE = -> {
-          limit = Spree::Api::Config[:rate_limit_per_key]
-          window = Spree::Api::Config[:rate_limit_window]
-          body = { error: { code: 'rate_limit_exceeded', message: 'Too many requests. Please retry later.' } }
-          headers = {
-            'Content-Type' => 'application/json',
-            'Retry-After' => window.to_s,
-            'X-RateLimit-Limit' => limit.to_s,
-            'X-RateLimit-Remaining' => '0'
-          }
-          [429, headers, [body.to_json]]
-        }
+        RATE_LIMIT_RESPONSE = -> { render_rate_limited }
+
+        # One global budget per caller (see RateLimitHeaders for the bucket
+        # rules); the two declarations are mutually exclusive so a request
+        # only ever counts against one ceiling.
+        rate_limit to: Spree::Api::Config[:rate_limit_per_secret_key], within: Spree::Api::Config[:rate_limit_window].seconds,
+                   store: Rails.cache,
+                   scope: RateLimitHeaders::RATE_LIMIT_SCOPE,
+                   by: :rate_limit_bucket,
+                   with: RATE_LIMIT_RESPONSE,
+                   if: :secret_key_request?
 
         rate_limit to: Spree::Api::Config[:rate_limit_per_key], within: Spree::Api::Config[:rate_limit_window].seconds,
                    store: Rails.cache,
-                   by: -> { request.headers['X-Spree-Api-Key'] || request.remote_ip },
-                   with: RATE_LIMIT_RESPONSE
+                   scope: RateLimitHeaders::RATE_LIMIT_SCOPE,
+                   by: :rate_limit_bucket,
+                   with: RATE_LIMIT_RESPONSE,
+                   unless: :secret_key_request?
+
+        # Cross-store leak tripwire, active in development/test only:
+        # registered ahead of the authentication callbacks so resource
+        # lookups run inside the guarded window. Deliberately global lookups
+        # (credential searches) opt out with Spree::StoreScopeGuard.skip.
+        around_action { |_controller, action| Spree::StoreScopeGuard.watch(&action) }
 
         # Optional JWT authentication by default
         before_action :authenticate_user
 
         protected
 
+        # Refuses a throttled request. Must render (not return a value) —
+        # Rails runs `with:` responders via instance_exec inside a
+        # before_action, where only render/redirect halts the chain. Headers
+        # are set here because a halted chain skips after_actions, so
+        # RateLimitHeaders never runs for a 429. Endpoint throttles pass the
+        # +limit+ that actually tripped so the header reports their ceiling,
+        # not the API-wide one.
+        def render_rate_limited(limit: rate_limit_ceiling)
+          response.headers['Retry-After'] = Spree::Api::Config[:rate_limit_window].to_s
+          response.headers['X-RateLimit-Limit'] = limit.to_s
+          response.headers['X-RateLimit-Remaining'] = '0'
+          render json: { error: { code: 'rate_limit_exceeded', message: 'Too many requests. Please retry later.' } },
+                 status: :too_many_requests
+        end
+
+        # Guest authorization for a specific order or cart. Defined here
+        # because Store::BaseController and Store::ResourceController anchor
+        # parallel inheritance branches — both need it.
+        def order_token
+          request.headers['x-spree-token']
+        end
+
+        # Renders a failed service/workflow Result: validation errors become a
+        # 422 field-error payload, anything else a plain service error. Shared
+        # by both APIs — Store endpoints surface workflow failures (a rejected
+        # return, a vetoed cart add) the same way Admin ones do.
+        def render_result_error(result)
+          error = result.error
+          errors = error.respond_to?(:value) ? error.value : error
+
+          if errors.is_a?(ActiveModel::Errors)
+            render_validation_error(errors)
+          else
+            render_service_error(error)
+          end
+        end
+
         # Override to use current_user from JWT authentication
-        # @return [Spree.user_class]
+        # @return [Spree.customer_class]
         def spree_current_user
           current_user
         end
 
         alias try_spree_current_user spree_current_user
 
+        # Who performed this request, for the associations that record it —
+        # `canceler`, `approver`, `created_by` and their siblings. Answers the
+        # signed-in user here; the Admin branch prefers the authenticating
+        # secret key, because a key-made write must record the key rather than
+        # nobody (see docs/plans/6.0-action-actors.md).
+        #
+        # Deliberately not `current_api_key || current_user` at this level: on
+        # a Store API request the key is the storefront's publishable one, and
+        # a customer's own action is not the storefront's.
+        #
+        # @return [Object, nil] a member of Spree.actor_classes
+        def current_actor
+          try_spree_current_user
+        end
+
         # CanCanCan ability
         # @return [Spree::Ability]
         def current_ability

data/app/controllers/spree/api/v3/resource_controller.rb

@@ -32,23 +32,40 @@ module Spree
         end
 
         # POST /api/v3/resource
+        #
+        # A controller whose resource is written through a workflow declares it
+        # with `create_workflow` and gets this action unchanged — same
+        # authorization, same rendering. Without one the record saves directly.
         def create
           @resource = build_resource
           authorize_resource!(@resource, :create)
 
-          if @resource.save
+          return save_and_render(@resource, status: :created) if create_workflow.nil?
+
+          result = create_workflow.call(**create_workflow_arguments)
+
+          if result.success?
+            @resource = result.value
             render json: serialize_resource(@resource), status: :created
           else
-            render_errors(@resource.errors)
+            render_result_error(result)
           end
         end
 
         # PATCH /api/v3/resource/:id
         def update
-          if @resource.update(permitted_params)
+          if update_workflow.nil?
+            @resource.assign_attributes(permitted_params)
+            return save_and_render(@resource)
+          end
+
+          result = update_workflow.call(**update_workflow_arguments)
+
+          if result.success?
+            @resource = result.value
             render json: serialize_resource(@resource)
           else
-            render_errors(@resource.errors)
+            render_result_error(result)
           end
         end
 
@@ -107,26 +124,127 @@ module Spree
         end
 
         # Builds a new resource, using parent association when @parent is set
+        # The workflow that writes this resource, or nil to save the record
+        # directly. Declaring one is all a controller needs to do — `create`
+        # and `update` keep their authorization and rendering.
+        #
+        # @return [#call, nil]
+        def create_workflow
+          nil
+        end
+
+        # @return [#call, nil]
+        def update_workflow
+          nil
+        end
+
+        # Keywords passed to `create_workflow`. The default suits a workflow
+        # taking `store:` and `attributes:`; override for anything else.
+        #
+        # @return [Hash]
+        def create_workflow_arguments
+          { store: current_store, attributes: permitted_params }
+        end
+
+        # Keywords passed to `update_workflow`, keyed by the resource's own
+        # name — `product:`, `price_list:` — which is how the workflows in
+        # app/workflows name their subject. `element` rather than `singular`,
+        # which would carry the `spree_` prefix.
+        #
+        # @return [Hash]
+        def update_workflow_arguments
+          { model_class.model_name.element.to_sym => @resource, attributes: permitted_params }
+        end
+
+        def save_and_render(resource, status: :ok)
+          if resource.save
+            render json: serialize_resource(resource), status: status
+          else
+            render_errors(resource.errors)
+          end
+        end
+
+        # Builds the record a create writes, through its owner's association so
+        # tenancy comes from where the record was built rather than from an
+        # attribute assigned afterwards.
+        #
+        # A workflow-written resource gets the bare scoped record: the workflow
+        # assigns the payload itself, and assigning it here would only be for
+        # the authorization check — which reads the record's owner, not its
+        # attributes — while raising on any bulk payload the model has no
+        # setter for (`product_ids`, `variants`).
         def build_resource
-          resource = if @parent.present?
-                       @parent.send(parent_association).build(permitted_params)
-                     else
-                       model_class.new(permitted_params)
-                     end
-          resource.store = current_store if resource.respond_to?(:store_id) && resource.store_id.blank?
-          resource.created_by = try_spree_current_user if resource.respond_to?(:created_by_id)
+          resource = resource_scope.new
+          resource.assign_attributes(permitted_params) if create_workflow.nil?
+          resource.created_by = creator_for(resource) if resource.respond_to?(:created_by_id)
           resource
         end
 
+        # The actor to stamp on a new record, or nil when this model cannot
+        # hold it. `created_by` is polymorphic on the order operations and
+        # still admin-user-only elsewhere until 6.1, so a key-authenticated
+        # create of a gift card records nobody rather than raising — the same
+        # thing it recorded before keys became actors.
+        def creator_for(resource)
+          actor = current_actor
+          return actor if actor.nil?
+
+          association = resource.class.reflect_on_association(:created_by)
+          return actor if association.nil? || association.polymorphic?
+
+          actor.is_a?(association.klass) ? actor : nil
+        end
+
+        # The relation a new record is built on: a nested resource's parent
+        # association, the store's own association for this model, or the
+        # class itself for genuinely global data (countries, roles).
+        #
+        # @return [ActiveRecord::Relation, Class]
+        def resource_scope
+          return @parent.send(parent_association) if @parent.present?
+          return model_class unless store_association
+
+          current_store.public_send(store_association)
+        end
+
+        # The store association a new record of this model builds on, or nil
+        # when there is none it can build through.
+        #
+        # Found by asking the reflections which association actually points at
+        # this model rather than by inflecting its name, so a model whose
+        # association is not the plural of its own name still resolves. Two
+        # cases yield nil and build on the class instead, taking their tenancy
+        # from the record they belong to: a doubly-nested has_many :through
+        # (Store#prices, through variants through products) is readonly, and
+        # genuinely global data (countries, roles) has no store association.
+        #
+        # @return [Symbol, nil]
+        def store_association
+          reflections = current_store.class.reflect_on_all_associations(:has_many).select do |reflection|
+            !reflection.nested? && reflection.klass == model_class
+          rescue NameError
+            # A reflection naming a class this installation does not load.
+            false
+          end
+          return reflections.first&.name if reflections.one?
+
+          # More than one association reaches this model — a deprecated twin
+          # such as `shipments` beside `fulfillments` — so the conventional
+          # name decides which one a create belongs on.
+          conventional = model_class.model_name.element.pluralize.to_sym
+          reflections.find { |reflection| reflection.name == conventional }&.name
+        end
+
         # Finds a single resource within scope using prefixed ID
         def find_resource
           scope.find_by_prefix_id!(params[:id])
         end
 
-        # Authorize resource with CanCanCan
-        def authorize_resource!(resource = @resource, action = action_name.to_sym)
-          authorize!(action, resource)
-        end
+        # Per-record authorization hook. A no-op in the shared base: the Store
+        # API's resources are reachable only through owner-scoped queries, so
+        # loading one already proves the caller may act on it. The Admin API
+        # overrides this with a CanCanCan check.
+        def authorize_resource!(resource = @resource, action = action_name.to_sym); end
 
         # Returns ransack-filtered, sorted and paginated collection
         # ar_lazy_preload handles automatic association preloading
@@ -251,15 +369,16 @@ module Spree
           }
         end
 
-        # Base scope with store and ability
-        # When @parent is set (nested resources), uses parent association instead
+        # Base scope, store-scoped (or parent-scoped for nested resources).
+        # Deliberately free of CanCanCan: the Store API authorizes by ownership
+        # — every account controller scopes through `current_user` — while the
+        # Admin API layers `accessible_by` on top in its own subclass.
         def scope
           base_scope = if @parent.present?
                          @parent.send(parent_association)
                        else
                          model_class.for_store(current_store)
                        end
-          base_scope = base_scope.accessible_by(current_ability, ability_action_for_request) unless @parent.present?
           base_scope = base_scope.includes(scope_includes) if scope_includes.any?
           base_scope = base_scope.preload_associations_lazily
           model_class.include?(Spree::TranslatableResource) ? base_scope.i18n : base_scope
@@ -300,21 +419,20 @@ module Spree
           read_actions.include?(action_name) ? :show : :update
         end
 
-        # Authorizes the parent resource for nested controllers: a role that
-        # can view a parent can't mutate its nested collection. Call from
-        # +set_parent+ after loading the parent.
-        def authorize_parent!(parent)
-          authorize!(parent_ability_action, parent)
-        end
+        # Parent authorization hook for nested controllers. A no-op in the
+        # shared base for the same reason as +authorize_resource!+; the Admin
+        # API overrides it so a role that can only view a parent cannot mutate
+        # its nested collection.
+        def authorize_parent!(parent); end
 
         # Override to specify the association name on @parent
-        # Defaults to controller_name (e.g., 'wished_items' for WishlistItemsController)
+        # Defaults to controller_name (e.g., 'wishlist_items' for WishlistItemsController)
         def parent_association
           controller_name
         end
 
         # Override in subclass to eager load associations that don't work well
-        # with ar_lazy_preload (e.g., prices, stock_items)
+        # with ar_lazy_preload (e.g., prices, stock_levels)
         def scope_includes
           []
         end
@@ -329,25 +447,38 @@ module Spree
           raise NotImplementedError, 'Subclass must implement serializer_class'
         end
 
-        # Permit flat parameters based on model class
-        # Automatically infers attribute list from Spree::PermittedAttributes
-        # e.g., ProductsController -> Spree::PermittedAttributes.product_attributes
-        #
-        # Override in subclass for custom parameter handling
         def permitted_params
-          normalize_params(params.permit(permitted_attributes))
+          normalize_params(params.permit(*permitted_attributes))
         end
 
-        # Returns the permitted attributes list for the model
-        # Override in subclass for custom attributes
+        # This resource's writable attributes, plus anything extensions have
+        # declared on the model. Override +resource_permitted_attributes+ rather
+        # than this, so the extension union is not lost.
         def permitted_attributes
-          Spree::PermittedAttributes.public_send(permitted_attributes_key)
+          resource_permitted_attributes + model_additional_permitted_attributes
+        end
+
+        # Override in subclass to declare the resource's writable attributes.
+        def resource_permitted_attributes
+          raise NotImplementedError, 'Subclass must implement resource_permitted_attributes or permitted_params'
         end
 
-        # Infers the PermittedAttributes key from model class
-        # e.g., Spree::Product -> :product_attributes
-        def permitted_attributes_key
-          :"#{model_class.model_name.element}_attributes"
+        # Attributes extensions have declared on the model via
+        # +Spree::Product.additional_permitted_attributes += [...]+.
+        #
+        # Guarded on both sides: a controller need not define +model_class+
+        # (and one that does may raise NotImplementedError), and
+        # `Spree.base_class` is host-overridable, so the class_attribute is not
+        # guaranteed to be inherited from Spree::Base.
+        def model_additional_permitted_attributes
+          return [] unless respond_to?(:model_class, true)
+
+          model = model_class
+          return [] unless model.respond_to?(:additional_permitted_attributes)
+
+          Array(model.additional_permitted_attributes)
+        rescue NotImplementedError
+          []
         end
       end
     end