spree_api 6.0.0.rc1 → 6.0.0.rc3

data/app/services/spree/api/v3/request_schema.rb

@@ -0,0 +1,430 @@
+module Spree
+  module Api
+    module V3
+      # What one write endpoint accepts, declared once. The controller permits
+      # from it, the API reference documents it, and the SDK request types are
+      # generated from the reference, so the three cannot disagree.
+      #
+      #   request_params :product do |body|
+      #     body.attribute :name, :string, required: true, on: :create
+      #     body.attribute :status, :string, choices: Spree::Product::STATUSES, open: true
+      #     body.attribute :category_ids, :array, of: :id
+      #     body.attribute :metadata, :hash
+      #     body.attribute :prices, :array, of: Spree::Api::V3::PriceRequestSchema
+      #     body.attribute :options, :array do |option|
+      #       option.attribute :name, :string, required: true
+      #     end
+      #   end
+      #
+      # The vocabulary is the `preference` one: a type symbol, `of:` for what
+      # an `:array` holds, `choices:` for a closed list (`open: true` when
+      # extensions may extend it), `:hash` for any keys. `required: true` is
+      # required on both actions; add `on: :create` to require it when
+      # creating only. `only: :create` (or `:update`) accepts the field on one
+      # action alone. `permit: false` documents a field the controller reads
+      # from the raw params itself. `format:` documents a string's format
+      # (`email`, `uri`). `deprecated: 'Use country_code. Removed in 6.1.'`
+      # keeps a field working while the API reference and the SDK types flag it.
+      class RequestSchema
+        KINDS = {
+          string: { type: :string },
+          integer: { type: :integer },
+          # Measurements a client sends as JSON numbers (weights, dimensions,
+          # coordinates). Money is never a number: use `decimal`.
+          number: { type: :number },
+          # Amounts, rates and quantities with decimals travel as canonical
+          # decimal strings, never JSON numbers (see Spree::Money::Rounding).
+          decimal: { type: :string, format: :decimal, pattern: '^-?\d+(\.\d+)?$' },
+          boolean: { type: :boolean },
+          date: { type: :string, format: :date },
+          datetime: { type: :string, format: :'date-time' },
+          id: { type: :string },
+          any: {},
+          # ISO codes, from the closed lists below.
+          country: { type: :string },
+          currency: { type: :string },
+          locale: { type: :string }
+        }.freeze
+
+        # The ISO lists a `country` or `currency` field takes, published once
+        # per API as a named component — the same `CountryCode` and
+        # `CurrencyCode` types the serializers declare, so a value read from
+        # a response is the type a request takes.
+        CODE_LISTS = {
+          country: ['CountryCode', -> { Spree::IsoData.country_codes }],
+          currency: ['CurrencyCode', -> { Spree::Money::Rounding::CURRENCY_CODES }],
+          locale: ['LocaleCode', -> { Spree::Locales::ALL }]
+        }.freeze
+
+        ACTIONS = %i[create update].freeze
+
+        OPEN_LIST_NOTE = 'The values listed are the built-in ones; extensions may add more.'.freeze
+
+        class Field
+          attr_reader :name, :kind, :array, :required, :nullable, :description, :example, :enum, :open, :only, :schema,
+                      :permit, :format, :deprecated
+
+          def initialize(name, kind, array: false, required: false, nullable: false, description: nil,
+                         example: nil, enum: nil, open: false, only: nil, schema: nil, permit: true, format: nil,
+                         deprecated: nil)
+            raise ArgumentError, "deprecated: says what to use instead (#{name})" if deprecated == true
+
+            raise ArgumentError, "open: needs an enum: list of the built-in values (#{name})" if open && enum.nil?
+
+            unless required.in?([true, false, :create])
+              raise ArgumentError, "required: must be true, false or :create (#{name})"
+            end
+            raise ArgumentError, "only: must be :create or :update (#{name})" if only && !only.in?(ACTIONS)
+
+            @name = name.to_sym
+            @kind = kind
+            @array = array
+            @required = required
+            @nullable = nullable
+            @description = description
+            @example = example
+            @enum = enum&.map(&:to_s)
+            @open = open
+            @only = only
+            @schema = schema
+            @permit = permit
+            @format = format
+            @deprecated = deprecated
+          end
+
+          # @param action [Symbol, nil]
+          def accepted_on?(action)
+            only.nil? || action.nil? || only == action
+          end
+
+          # @param action [Symbol, nil]
+          def required_on?(action)
+            required == true || (required == :create && action == :create)
+          end
+
+          # This field, required on `on` (`:create`) or always. A field
+          # already required always stays required always.
+          #
+          # @param on [Symbol, nil] `:create`, or nil for every action
+          # @return [Field]
+          def required_copy(on)
+            copy = dup
+            copy.instance_variable_set(:@required, required == true ? true : on || true)
+            copy
+          end
+
+          # A hash of any keys, such as `metadata` or `provider_settings`.
+          def free_object?
+            kind == :object && schema.nil?
+          end
+        end
+
+        attr_reader :name, :fields
+
+        # The types an attribute takes: the scalars above, plus `:hash` (any
+        # keys), `:object` (a block or a `shape:`) and `:array` (`of:` a type
+        # or a shape, or a block of fields).
+        TYPES = (KINDS.keys + %i[hash object array]).freeze
+
+        # A shape shared between several endpoints (a price, an address),
+        # published as its own component so each SDK has one type for it.
+        #
+        # @param name [String] the component name, such as `PriceParams`
+        # @return [RequestSchema]
+        def self.shape(name, &block)
+          raise ArgumentError, "a shape's name ends in Params (#{name})" unless name.to_s.end_with?('Params')
+
+          new(name, &block)
+        end
+
+        # A shape several endpoints share is a class in app/request_schemas,
+        # declared the way a model declares its attributes:
+        #
+        #   class Spree::Api::V3::PriceRequestSchema < Spree::Api::V3::RequestSchema
+        #     publishes 'PriceParams'
+        #
+        #     attribute :currency, :currency, required: true
+        #   end
+        #
+        # A subclass starts from its parent's attributes, so the Admin API's
+        # address extends the shared one. Without `publishes` the class is a
+        # set of attributes other declarations include rather than a type of
+        # its own.
+        class << self
+          # @param name [String] the component name, ending in `Params`
+          def publishes(name)
+            raise ArgumentError, "a shape's name ends in Params (#{name})" unless name.to_s.end_with?('Params')
+            raise ArgumentError, "#{self.name}: `publishes` goes before the attributes" if @definition
+
+            @published_name = name.to_s
+          end
+
+          # @return [RequestSchema] what the class declares
+          def definition
+            @definition ||= new(@published_name).tap do |schema|
+              schema.include_attributes(superclass) if superclass < RequestSchema
+            end
+          end
+
+          # @param value [RequestSchema, Class] an instance or a declared class
+          # @return [RequestSchema, nil]
+          def resolve(value)
+            value.is_a?(Class) ? value.definition : value
+          end
+
+          %i[attribute include_attributes require_attributes external_references].each do |method|
+            define_method(method) { |*args, **options, &block| definition.public_send(method, *args, **options, &block) }
+          end
+        end
+
+        # @param name [String, Symbol, nil] the resource, `product` publishing
+        #   `ProductCreateParams` and `ProductUpdateParams`; or a name ending
+        #   in `Params`, published as given for every action
+        # @yieldparam schema [RequestSchema] the schema, to declare attributes on
+        def initialize(name = nil)
+          @name = name&.to_s
+          @fields = {}
+          yield self if block_given?
+        end
+
+        # Declares one attribute of the body.
+        #
+        # @param name [Symbol]
+        # @param type [Symbol] one of TYPES
+        # @param of [Symbol, Class, RequestSchema, nil] what an `:array` holds:
+        #   a scalar type, or a shared shape
+        # @param shape [Class, RequestSchema, nil] what an `:object` holds
+        # @param as [String, nil] publishes a block's object (or the objects
+        #   of an `:array`) as a component of this name
+        # @param choices [Array, nil] the values the attribute takes
+        # @param required [Boolean]
+        # @param on [Symbol, nil] `:create` to require it only when creating
+        # @yieldparam schema [RequestSchema] a nested object's attributes
+        def attribute(name, type, of: nil, shape: nil, as: nil, choices: nil, required: false, on: nil, **options, &block)
+          raise ArgumentError, "#{name}: unknown type #{type.inspect}; use one of #{TYPES.join(', ')}" unless TYPES.include?(type)
+          raise ArgumentError, "#{name}: `on:` scopes `required: true` and is `:create`" if on && (!required || on != :create)
+
+          options = options.merge(required: on || required, enum: choices)
+          nested = nested_schema(type, of: of, shape: shape, as: as, &block)
+
+          case type
+          when :array then add_array(name, of, nested, options)
+          when :object
+            raise ArgumentError, "#{name}: an :object needs a block or `shape:`; use :hash for any keys" unless nested
+
+            add(Field.new(name, :object, schema: nested, **options))
+          when :hash then add(Field.new(name, :object, **options))
+          else add(Field.new(name, type, **options))
+          end
+        end
+
+        # The identities a record has in external systems, which the Admin API
+        # reads from the raw params (Admin::Concerns::ExternalReferences).
+        def external_references
+          attribute :external_references, :hash, permit: false, description: <<~TEXT.squish
+            Identities the record has in external systems, keyed by system: the same
+            `{ system: external_id }` map the Admin API renders, so what you read can be
+            sent straight back. Systems you do not name keep the reference they have.
+            A list of `{ system, external_id }` entries is accepted too.
+          TEXT
+        end
+
+        # Adds the attributes of another schema, for endpoints that extend a
+        # shared set.
+        #
+        # @param other [RequestSchema, Class]
+        def include_attributes(other)
+          RequestSchema.resolve(other).fields.each_value { |field| add(field) }
+        end
+
+        # Marks attributes this schema took from another as required, for an
+        # endpoint whose model needs what the shared set leaves optional.
+        #
+        # @param names [Array<Symbol>]
+        # @param on [Symbol, nil] `:create` to require them only when creating
+        # @return [void]
+        def require_attributes(*names, on: nil)
+          raise ArgumentError, '`on:` is :create' if on && on != :create
+
+          names.each do |name|
+            field = fields.fetch(name) { raise ArgumentError, "#{name} is not an attribute of this schema" }
+            fields[name] = field.required_copy(on)
+          end
+          @permit_lists = nil
+        end
+
+        # The `params.permit` list for an action.
+        #
+        # @param action [Symbol, String, nil] `create` or `update`; nil
+        #   accepts every field
+        # @return [Array<Symbol, Hash>]
+        def permit_list(action = nil)
+          action = action&.to_sym
+          (@permit_lists ||= {})[action] ||= build_permit_list(action).freeze
+        end
+
+        # The JSON Schema of the request body for an action.
+        #
+        # @param action [Symbol, String, nil]
+        # @return [Hash]
+        def json_schema(action = nil)
+          action = action&.to_sym
+          fields = fields_for(action)
+          required = fields.select { |field| field.required_on?(action) }.map { |field| field.name.to_s }
+
+          schema = { type: :object, properties: fields.to_h { |field| [field.name, property_schema(field)] } }
+          schema[:required] = required if required.any?
+          schema
+        end
+
+        # The component name published for an action.
+        #
+        # @param action [Symbol, String]
+        # @return [String]
+        def component_name(action)
+          return name if name.end_with?('Params')
+
+          "#{name.camelize}#{action.to_s.camelize}Params"
+        end
+
+        # Every named shape this schema reaches, nested ones included.
+        #
+        # @return [Array<RequestSchema>]
+        def shapes
+          fields.each_value.flat_map do |field|
+            next [] unless field.schema
+
+            nested = field.schema.shapes
+            shape?(field.schema) ? [field.schema, *nested] : nested
+          end.uniq
+        end
+
+        # The ISO code lists this schema's fields reach, nested ones included,
+        # as the components they publish.
+        #
+        # @return [Hash{String => Hash}]
+        def code_lists
+          fields.each_value.each_with_object({}) do |field, lists|
+            lists.merge!(field.schema.code_lists) if field.schema
+            next unless CODE_LISTS.key?(field.kind)
+
+            name, values = CODE_LISTS[field.kind]
+            lists[name] = { type: :string, enum: values.call }
+          end
+        end
+
+        def shape?(schema)
+          schema.name.present?
+        end
+
+        private
+
+        def nested_schema(type, of:, shape:, as:, &block)
+          return RequestSchema.resolve(shape) if shape
+          return RequestSchema.resolve(of) if of.is_a?(Class) || of.is_a?(RequestSchema)
+          return unless block
+
+          as ? RequestSchema.shape(as, &block) : RequestSchema.new(&block)
+        end
+
+        def add_array(name, of, nested, options)
+          return add(Field.new(name, :object, schema: nested, array: true, **options)) if nested
+
+          unless of.is_a?(Symbol) && KINDS.key?(of)
+            raise ArgumentError, "#{name}: an :array needs `of:` a scalar type or a shape, or a block of attributes"
+          end
+          # Rails permits a list of scalars, never a list of any-key hashes.
+          if of == :any && options.fetch(:permit, true)
+            raise ArgumentError, "#{name}: a list of :any values cannot be permitted; declare its items or use `permit: false`"
+          end
+
+          add(Field.new(name, of, array: true, **options))
+        end
+
+        def add(field)
+          raise ArgumentError, "#{field.name} is declared twice" if fields.key?(field.name)
+
+          @permit_lists = nil
+          fields[field.name] = field
+        end
+
+        def build_permit_list(action)
+          scalars = []
+          nested = []
+
+          fields_for(action).each do |field|
+            next unless field.permit
+
+            if field.schema
+              nested << { field.name => field.schema.permit_list }
+            elsif field.free_object?
+              nested << { field.name => {} }
+            elsif field.kind == :any
+              # A value of any JSON type: a scalar, a list or a hash.
+              scalars << field.name
+              nested << { field.name => [] } << { field.name => {} }
+            elsif field.array
+              nested << { field.name => [] }
+            else
+              scalars << field.name
+            end
+          end
+
+          scalars + nested
+        end
+
+
+        def fields_for(action)
+          fields.values.select { |field| field.accepted_on?(action) }
+        end
+
+        def property_schema(field)
+          item = item_schema(field)
+          description = [field.description, (OPEN_LIST_NOTE if field.open), deprecation_note(field)].compact.join(' ').presence
+          documentation = { description: description, example: field.example }.compact
+          documentation[:deprecated] = true if field.deprecated
+
+          if field.array
+            schema = { type: :array, items: item }.merge(documentation)
+            schema[:nullable] = true if field.nullable
+            return schema
+          end
+
+          # A $ref ignores the keys beside it, so a described or nullable
+          # reference wraps it.
+          if item.key?(:$ref) && (documentation.any? || field.nullable)
+            item = { allOf: [item] }
+          end
+
+          item = item.merge(documentation)
+          item[:nullable] = true if field.nullable
+          item
+        end
+
+        def deprecation_note(field)
+          "Deprecated: #{field.deprecated}" if field.deprecated
+        end
+
+        def item_schema(field)
+          return { '$ref': "#/components/schemas/#{CODE_LISTS[field.kind].first}" } if CODE_LISTS.key?(field.kind)
+
+          if field.schema
+            return { '$ref': "#/components/schemas/#{field.schema.name}" } if shape?(field.schema)
+
+            return field.schema.json_schema
+          end
+          return { type: :object, additionalProperties: true } if field.free_object?
+
+          schema = KINDS.fetch(field.kind).dup
+          schema[:format] = field.format if field.format
+          return schema unless field.enum
+          return schema.merge(enum: field.enum) unless field.open
+
+          # The same open list the serializers publish (`enum_type_name`):
+          # clients autocomplete the built-in values and still accept any other.
+          { anyOf: [schema.merge(enum: field.enum), schema] }
+        end
+      end
+    end
+  end
+end

data/app/services/spree/webhooks/deliver_webhook.rb

@@ -90,10 +90,14 @@ module Spree
         http_options = { open_timeout: TIMEOUT, read_timeout: TIMEOUT, verify_mode: ssl_verify_mode }
 
         # SSRF protection is disabled in development so webhooks can reach
-        # localhost / host.docker.internal (the storefront running on the host).
-        if Rails.env.development?
+        # localhost / host.docker.internal (the storefront running on the host),
+        # and for hosts the operator explicitly trusts
+        # (Spree::Api::Config.webhooks_allowed_internal_hosts).
+        if Rails.env.development? || Spree::WebhookEndpoint.allowed_internal_host?(@delivery.url)
           uri = URI.parse(@delivery.url)
-          http = Net::HTTP.new(uri.host, uri.port)
+          # No proxy, as SsrfFilter: an egress proxy from the environment would
+          # carry this in-cluster (or localhost) request out of the network.
+          http = Net::HTTP.new(uri.hostname, uri.port, nil)
           http.use_ssl = uri.scheme == 'https'
           http_options.each { |k, v| http.send(:"#{k}=", v) }
 

data/config/initializers/typelizer.rb

@@ -75,7 +75,7 @@ Rails.application.config.after_initialize do
     # serializer this branch inherits references them, so their types still
     # have to exist in the package.
     store_nested_for_seller = %w[
-      Address Category CustomField OptionType OptionValue Price PriceHistory Seller
+      Category CustomField OptionType OptionValue Seller
     ].to_set
 
     config.writer(:seller) do |c|

data/config/routes.rb

@@ -255,6 +255,8 @@ Spree::Core::Engine.add_routes do
         # Self-service profile updates (e.g. the admin's own UI language)
         patch 'me', to: 'me#update'
 
+        resource :updates, only: :show
+
         # Store Settings
         resource :store, only: [:show, :update], controller: 'store' do
           get :data_sources
@@ -299,8 +301,8 @@ Spree::Core::Engine.add_routes do
         resources :roles, only: [:index, :show, :create, :update, :destroy]
         resources :permissions, only: [:index]
 
-        # Direct Uploads (Active Storage)
-        resources :direct_uploads, only: [:create]
+        # File uploads — see docs/plans/6.0-uploads-and-file-ownership.md
+        resources :files, only: [:create]
 
         # CSV Exports — see docs/plans/5.5-admin-spa-csv-export.md
         resources :exports, only: [:index, :show, :create, :destroy] do
@@ -961,7 +963,7 @@ Spree::Core::Engine.add_routes do
         # Registry data — which carriers a tracking number can be pinned to.
         resources :tracking_carriers, only: [:index]
 
-        resources :direct_uploads, only: [:create]
+        resources :files, only: [:create]
 
         # CSV of what this seller sold, or of their catalogue. Created, polled
         # and downloaded — no index, since a seller has no history page to

data/lib/spree/api/configuration.rb

@@ -27,6 +27,11 @@ module Spree
 
       preference :webhooks_enabled, :boolean, default: true, env: 'SPREE_WEBHOOKS_ENABLED'
       preference :webhooks_verify_ssl, :boolean, default: !Rails.env.development?, env: 'SPREE_WEBHOOKS_VERIFY_SSL'
+      # Hosts a webhook may reach even though they resolve to a private
+      # address (the SSRF guard otherwise refuses them). "host" matches that
+      # host; ".suffix" matches any host under it. See
+      # Spree::WebhookEndpoint.allowed_internal_host?.
+      preference :webhooks_allowed_internal_hosts, :array, default: [], env: 'SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS'
     end
   end
 end

data/lib/spree/api/dependencies.rb

@@ -18,10 +18,10 @@ module Spree
            product_filter_sort_option media_event return return_line_item exchange exchange_line_item claim
            claim_line_item return_reason claim_reason digital_asset export gift_card_batch import import_row
            invitation newsletter_subscriber promotion refund stock_level stock_movement stock_reservation
-           stock_transfer company company_membership company_invitation seller].freeze
+           stock_transfer company company_membership company_invitation seller file_upload file_upload_target].freeze
 
       ADMIN_SERIALIZERS =
-        %i[country state applied_promotion discount tax_line cart delivery_zone delivery_profile
+        %i[country state locale applied_promotion discount tax_line cart delivery_zone delivery_profile
            delivery_origin_group integration delivery_method_rule delivery_zone_member fee consent_record customer
            data_request newsletter_subscriber order order_group product product_type
            product_type_custom_field_definition variant price price_history custom_field custom_field_definition
@@ -38,19 +38,20 @@ module Spree
            channel order_routing_rule product_publication market delivery_method delivery_method_service
            stock_location stock_reservation delivery_rate freight_summary freight_summary_line payment_method
            credit_card store_credit store_credit_event customer_group payment_source digital_asset digital_link
-           store setup_task api_key allowed_origin webhook_endpoint webhook_event webhook_delivery invitation
+           store setup_task update_status api_key allowed_origin webhook_endpoint webhook_event webhook_delivery invitation
            invitation_acceptance_link role permission export saved_report import import_row import_mapping promotion
            promotion_action promotion_rule coupon_code price_adjustment_tier price_list price_rule
            resource_translations email_template email_template_draft email_template_revision email_template_preview
-           email_template_sample_record].freeze
+           email_template_sample_record file_upload file_upload_target].freeze
 
       SELLER_SERIALIZERS =
-        %i[profile policy team_member account invitation invitation_acceptance_link product product_type
+        %i[address country state profile policy team_member account invitation invitation_acceptance_link product product_type
            delivery_profile delivery_method delivery_method_rule delivery_zone variant media stock_level order
            order_line_item fulfillment fulfillment_item delivery delivery_rate shipping_label return
            return_line_item exchange exchange_line_item claim claim_line_item reason package_type stock_location
            requirement_custom_field tax_identifier requirement_status import import_row import_mapping
-           requirement_submission export transfer payout balance payment_split].freeze
+           requirement_submission export transfer payout balance payment_split price price_history file_upload
+           file_upload_target].freeze
 
       INJECTION_POINTS_WITH_DEFAULTS = {
         **STORE_SERIALIZERS.to_h { |name| [:"#{name}_serializer", "Spree::Api::V3::#{name.to_s.camelize}Serializer"] },

data/lib/spree/api/middleware/request_size_limit.rb

@@ -2,13 +2,24 @@ module Spree
   module Api
     module Middleware
       class RequestSizeLimit
+        # `POST /files` takes a file's bytes in the request itself, so it is
+        # held to the multipart upload limit instead, plus room for the other
+        # form fields.
+        FILE_UPLOAD_PATH = %r{\A/api/v3/(admin|seller)/files/?\z}
+        MULTIPART_ENVELOPE = 64.kilobytes
+
         def initialize(app, limit: nil)
           @app = app
           @limit = limit
         end
 
         def call(env)
-          if api_request?(env) && content_length_exceeded?(env)
+          if file_upload?(env) && chunked?(env)
+            # A chunked body has no length to check here, and these bytes pass
+            # through the application.
+            body = { error: { code: 'request_too_large', message: 'Send the file with a Content-Length header' } }
+            [411, { 'Content-Type' => 'application/json' }, [body.to_json]]
+          elsif api_request?(env) && content_length_exceeded?(env)
             body = { error: { code: 'request_too_large', message: 'Request body too large' } }
             [413, { 'Content-Type' => 'application/json' }, [body.to_json]]
           else
@@ -24,12 +35,22 @@ module Spree
 
         def content_length_exceeded?(env)
           content_length = env['CONTENT_LENGTH'].to_i
-          content_length > max_body_size
+          content_length > max_body_size(env)
         end
 
-        def max_body_size
+        def max_body_size(env)
+          return Spree::Config[:max_multipart_upload_size] + MULTIPART_ENVELOPE if file_upload?(env)
+
           @limit || Spree::Api::Config[:max_request_body_size]
         end
+
+        def chunked?(env)
+          env['CONTENT_LENGTH'].nil? && env['HTTP_TRANSFER_ENCODING'].to_s.include?('chunked')
+        end
+
+        def file_upload?(env)
+          env['REQUEST_METHOD'] == 'POST' && FILE_UPLOAD_PATH.match?(env['PATH_INFO'])
+        end
       end
     end
   end