permittable 0.13.1 → 0.15.0

data/lib/permittable.rb

@@ -218,7 +218,11 @@ module Permittable
   extend ActiveSupport::Concern
 
   LABEL = "Permittable".freeze
-  SCALAR_TYPES = %i[string integer float decimal boolean date datetime].freeze
+  SCALAR_TYPES = %i[string integer float decimal boolean date datetime file].freeze
+  # An upload, as multipart params carry it. It is a scalar in strong params'
+  # sense (an upload object is permitted), but it is never cast, and a
+  # request's String can never be one.
+  FILE_TYPE = :file
   # Not a scalar: an opaque hash whose shape is deliberately undeclared, for
   # the json/jsonb column a contract has to be able to carry.
   JSON_TYPE = :json
@@ -640,15 +644,14 @@ module Permittable
 
   included do
     class_attribute :permittable_contracts, instance_accessor: false, default: []
-
-    rescue_from InvalidParameters, with: :render_invalid_parameters if respond_to?(:rescue_from)
-    # Registered here, at the include, and not at the first `permit_params`:
-    # the README documents `skip_before_action :enforce_params_contract`, and
-    # Rails raises when it is asked to skip a callback that is not defined
-    # yet. The cost is the order: this check runs before any callback
-    # declared after the include (see the README's "Per-request locales"),
-    # so a locale switch that must cover it is a `prepend_around_action`.
-    before_action :enforce_params_contract if respond_to?(:before_action)
+    # Whether the gem itself ever registered its rescue_from / before_action
+    # for this class (a subclass inherits the answer). Asking the callback
+    # chain instead would bring back a check the app took out with
+    # `skip_before_action :enforce_params_contract`.
+    class_attribute :permittable_rescue_registered, :permittable_callback_registered,
+                    instance_accessor: false, default: false
+
+    permittable_register_hooks
   end
 
   # Strict params-shaped coercion, shared by request-time validation and
@@ -746,6 +749,7 @@ module Permittable
     end
 
     def cast(type, value)
+      return cast_file(value) if type == FILE_TYPE
       return [:error, "invalid_type"] unless scalar_shaped?(value)
       return public_send("cast_#{type}", value) unless value.is_a?(String)
       # Bytes that are not valid in the String's OWN encoding are not text in
@@ -819,6 +823,17 @@ module Permittable
       value.dup.force_encoding(Encoding::UTF_8).scrub
     end
 
+    # Exactly the upload objects ActionController::Parameters permits as
+    # scalars (its PERMITTED_SCALAR_TYPES): what Rails' multipart parser
+    # builds, and what rack-test sends. Each constant is looked up at call
+    # time, so the gem loads and a standalone Contract works without
+    # ActionDispatch or rack-test. The object is handed back as it came.
+    def cast_file(value)
+      upload = (defined?(ActionDispatch::Http::UploadedFile) && value.is_a?(ActionDispatch::Http::UploadedFile)) ||
+               (defined?(Rack::Test::UploadedFile) && value.is_a?(Rack::Test::UploadedFile))
+      upload ? [:ok, value] : [:error, "invalid_type"]
+    end
+
     # Arrays, hashes, and nested ActionController::Parameters
     # (`?age[]=1`, `?age[x]=1`) can never satisfy a scalar type.
     def scalar_shaped?(value)
@@ -1018,8 +1033,21 @@ module Permittable
         date ? [:ok, date] : [:error, "invalid_type"]
       when Date then [:ok, value]
       when String
+        # A bare ISO date ("2026-09-05", the common case) carries no zone, T
+        # or offset, so it skips every check for one.
+        plain = PLAIN_ISO_DATE.match?(value)
+        return cast_date_instant(value) if !plain && (ISO_DATE_AT_OFFSET.match?(value) || ISO_DATE_T.match?(value))
+
         found = Date._parse(value)
         return [:error, "invalid_type"] unless complete_date?(found)
+        return cast_date_instant(value, found) if names_an_instant?(found)
+
+        # No time found, but a zone or offset may have been dropped
+        # ("5/9/2026 -0500", "2026-09-05 EST") or an hour with it
+        # ("2026-09-05T10"), which :datetime refuses or reads the same way.
+        if !plain && (dropped = dropped_tail(value, found))
+          return date_at_midnight(*dropped)
+        end
 
         # Built from the components rather than re-running Date.parse, which
         # would parse the same string a second time — and Date.parse is the
@@ -1038,6 +1066,36 @@ module Permittable
       found.key?(:year) && found.key?(:mon) && found.key?(:mday)
     end
 
+    # A time of day or a zone, as opposed to a bare calendar date.
+    def names_an_instant?(found)
+      %i[hour min sec sec_fraction zone offset].any? { |part| found.key?(part) }
+    end
+
+    # A String that carries a time or a zone is the instant it names, read
+    # exactly as :datetime reads it (a zoneless one as UTC, an impossible
+    # time or an offset Ruby cannot honour refused) and then as a Time is
+    # read: a date only at midnight UTC. Keeping just the calendar day
+    # accepted "T25:00:00Z" and "+24:00", and turned "T23:30:00-05:00",
+    # which is the next day in UTC, into the day before.
+    #
+    # The Date is built from the components, like a date-only String's,
+    # because Time#to_date reads the proleptic Gregorian day in the Julian
+    # calendar before 1582 ("1500-01-01T00:00:00Z" became 1499-12-23).
+    #
+    # `found` is the String's Date._parse, when the caller has it and has
+    # ruled out the ISO forms cast_datetime reads without one; :datetime's
+    # reading of it is then the same, with one parse fewer.
+    def cast_date_instant(value, found = nil)
+      date_at_midnight(*(found ? cast_parsed_datetime(value, found) : cast_datetime(value)))
+    end
+
+    # The Date of an instant read from a String when it is midnight UTC.
+    def date_at_midnight(status, instant)
+      return [:error, "invalid_type"] unless status == :ok && instant == instant.beginning_of_day
+
+      [:ok, Date.new(instant.year, instant.month, instant.day)]
+    end
+
     # The date a Time or DateTime IS, or nil: its UTC date when it is
     # exactly midnight UTC. That is the instant ActiveSupport compares a
     # Date as, and the one :datetime reads a Date as, so the two types map
@@ -1102,16 +1160,30 @@ module Permittable
         # converts by day number, so "1500-01-01" became 1500-01-10 — unless
         # the host had loaded ActiveSupport's DateTime#to_time, which
         # converts by component. Gregorian, both agree.
-        found = Date._parse(value)
-        return [:error, "invalid_type"] unless complete_date?(found) && honoured_zone?(found)
+        if (iso = ISO_DATE_AT_OFFSET.match(value)) then return midnight_at_offset(*iso.captures)
+        elsif ISO_DATE_T.match?(value) then return [:error, "invalid_type"]
+        end
 
-        [:ok, DateTime.parse(value, true, Date::GREGORIAN).to_time.utc]
+        cast_parsed_datetime(value, Date._parse(value))
       else [:error, "invalid_type"]
       end
     rescue ArgumentError, RangeError
       [:error, "invalid_type"]
     end
 
+    # cast_datetime's reading of a String once Date._parse has `found` its
+    # parts, shared with cast_date_instant so a :date need not parse twice.
+    def cast_parsed_datetime(value, found)
+      return [:error, "invalid_type"] unless complete_date?(found) && honoured_zone?(found)
+
+      dropped = dropped_tail(value, found)
+      return dropped if dropped
+
+      [:ok, DateTime.parse(value, true, Date::GREGORIAN).to_time.utc]
+    rescue ArgumentError, RangeError
+      [:error, "invalid_type"]
+    end
+
     # A zone the parser could not turn into an offset — an offset of a day
     # or more ("+24:00", "-99:00", "+99") or an abbreviation it does not
     # know ("XYZ") — is reported as a zone with no offset, or with one
@@ -1125,6 +1197,153 @@ module Permittable
       !offset.nil? && offset.abs < 86_400
     end
 
+    # An ISO date followed by an offset or Z and no time of day
+    # ("2026-09-05-05:00", "2026-09-05 +05:00", "20260905Z"): XSD xs:date and
+    # Java's ISO_DATE, for midnight at that offset. Date._parse does not read
+    # it so — it takes "-05:00" for the TIME 05:00 and drops the sign, or
+    # drops "-0500" altogether — so the instant is built from the captures.
+    # Only the whole String counts, so a plain "2026-09-05" (which ends in
+    # "-05") never matches, and costs nothing more than the match.
+    ISO_DATE_AT_OFFSET = /\A\s*(\d{4})(-?)(\d{2})\2(\d{2})\s*(Z|z|[+-]\d{2}(?::?\d{2})?)\s*\z/
+
+    # An ISO date followed by a "T" and no time ("2026-09-05T",
+    # "20260905T-0500"). Ruby reads a lone letter as a military zone, T as
+    # -07:00, or drops it with whatever follows, so it is refused rather
+    # than read as some instant the client did not write.
+    ISO_DATE_T = /\A\s*\d{4}(-?)\d{2}\1\d{2}[Tt](?!\s*\d)/
+
+    # An ISO date and nothing else, which none of the above can match.
+    PLAIN_ISO_DATE = /\A\s*\d{4}-?\d{2}-?\d{2}\s*\z/
+
+    # A signed number at the end of a String, and whether a space sets it
+    # apart from what comes before ("5/9/2026 -0500" but not "2026-09-05").
+    SIGNED_TAIL = /(\s)?[+-]\d+(?::\d+)*\s*\z/
+    private_constant :ISO_DATE_AT_OFFSET, :ISO_DATE_T, :PLAIN_ISO_DATE, :SIGNED_TAIL
+
+    # The captures of ISO_DATE_AT_OFFSET as the instant they name, held to
+    # the rule any other offset is (honoured_zone?): "+24:00" and "-99:00"
+    # are refused, and so are minutes past 59 ("+05:99"), which the parser
+    # reports with no offset. Date.new checks the day ("2026-02-30Z"), which
+    # Time.utc would roll over into March.
+    def midnight_at_offset(year, _dash, mon, mday, zone)
+      year, mon, mday = [year, mon, mday].map { |part| Integer(part, 10) }
+      offset = zone_offset(zone)
+      return [:error, "invalid_type"] unless honoured_zone?(zone: zone, offset: offset)
+
+      Date.new(year, mon, mday, Date::GREGORIAN)
+      [:ok, Time.utc(year, mon, mday) - offset]
+    end
+
+    # "Z", "+05", "-0530" or "+05:30" in seconds east of UTC, or nil when
+    # the minutes are not minutes.
+    def zone_offset(zone)
+      return 0 if zone.casecmp?("z")
+
+      hours = Integer(zone[1, 2], 10)
+      minutes = Integer(zone[3..].delete(":").rjust(1, "0"), 10)
+      return if minutes > 59
+
+      (zone.start_with?("-") ? -1 : 1) * ((hours * 3600) + (minutes * 60))
+    end
+
+    # An ISO date, then a "T": what follows is an ISO time, so a parse that
+    # found no hour ("2026-09-05T10", "T1030", "T10Z") dropped it.
+    ISO_DATE_T_START = /\A\s*\d{4}(-?)\d{2}\1\d{2}[Tt]/
+
+    # Trailing words, set apart by a space: a zone name ("EST", "Eastern
+    # Standard Time", "W. Europe Standard Time") or a day or era word. The
+    # first word has two letters or more, or one and a ".", as a lone letter
+    # is a military zone or the ISO "T".
+    ZONE_NAME_TAIL = /(?<=\s)[[:alpha:]](?:\.|[[:alpha:]]+)[[:alpha:].]*(?:\s+[[:alpha:].]+)*\z/
+
+    # An era word at the start of such a tail: the parser reads it with the
+    # date ("Sep 5 2026 BC" is the year -2025), so it is not what follows.
+    ERA_WORD = /\A(?:a\.?\s?d\.?|c\.?\s?e\.?|b\.?\s?c\.?(?:\s?e\.?)?)(?:\s+|\z)/i
+
+    # What ends a date the way git, `date` and Time#to_s write it, with the
+    # offset after the year: "Sat Sep 5 10:00:00 2026", "Sep 5 10:00 2026".
+    TIME_THEN_YEAR = /\d:\d{2}(?::\d{2}(?:[.,]\d+)?)?\s+\d{4}\s*\z/
+    private_constant :ZONE_NAME_TAIL, :ERA_WORD, :TIME_THEN_YEAR
+
+    # What Date._parse did with the END of a date or date-time String when it
+    # dropped or misplaced it, as nil when it did neither, or the result
+    # ([:ok, instant] or [:error, "invalid_type"]) the String must be given:
+    #
+    # - an hour after an ISO "T" it did not find ("2026-09-05T10");
+    # - a trailing offset taken for a time of day ("Sep 5 2026 -05:00",
+    #   "2026-09-05 10 -05:00", "2026-09-05 UTC-05:00") or dropped without a
+    #   trace ("5/9/2026 -0500", "12:00 2026-09-05 -05:00"), outside the ISO
+    #   form midnight_at_offset reads. An offset after "10:00:00 2026" is the
+    #   exception: that is git's and ctime's format, which puts it after the
+    #   year, so it is read, like a zone name;
+    # - a trailing zone NAME, which it reads only next to a time of day:
+    #   "2026-09-05 EST" is midnight at -05:00 and "Sat Sep 5 10:00:00 2026
+    #   EST" 10:00 there. A name it does not know is refused like any other
+    #   zone (honoured_zone?), and so is ANY other word after a complete date
+    #   ("2026-09-05 noon"), since all it can be is a zone. A day name and an
+    #   era word are what the parser reads as part of the date, not a zone.
+    #
+    # The tail is the culprit when the parser found no zone and the String
+    # without it names the same date (and time). Only a String that ends in a
+    # signed number or a word is parsed again, so a plain "2026-09-05" is not.
+    def dropped_tail(value, found)
+      return [:error, "invalid_type"] if !found.key?(:hour) && ISO_DATE_T_START.match?(value)
+      return if found.key?(:zone)
+
+      if (tail = SIGNED_TAIL.match(value))
+        return unless tail[1] || found.key?(:hour)
+
+        rest = Date._parse(tail.pre_match)
+        return unless same_date?(rest, found)
+
+        git_style = tail[1] && found.key?(:hour) && TIME_THEN_YEAR.match?(tail.pre_match) && same_time?(rest, found)
+        git_style ? instant_in_zone(tail.pre_match, tail[0].strip) : [:error, "invalid_type"]
+      elsif (tail = ZONE_NAME_TAIL.match(value))
+        pre = tail.pre_match
+        text = tail[0]
+        if (era = ERA_WORD.match(text))
+          pre += era[0]
+          text = era.post_match
+        end
+        return if text.empty?
+
+        rest = Date._parse(pre)
+        return unless same_date?(rest, found)
+
+        zone = Date._parse("00:00 #{text}")
+        return unless zone.key?(:zone) # a day name
+        # A single letter is a military zone, which is no zone here: alone it
+        # is nothing ("2026-09-05 a", "A."), but the rest of an initial-led
+        # name Ruby did not know ("W. Europe") is dropped, so it is refused
+        # like any other word it does not know.
+        return text.match?(/\A[[:alpha:]]\.?\z/) ? nil : [:error, "invalid_type"] if zone[:zone].length == 1
+        # The hour the tail made the parser lose ("2026-09-05 10 EST").
+        return [:error, "invalid_type"] unless same_time?(rest, found)
+
+        instant_in_zone(pre, text)
+      end
+    end
+
+    # The wall clock `date` names, as it is read in the zone `text` names:
+    # [:ok, instant], or an error when Ruby cannot honour the zone.
+    def instant_in_zone(date, text)
+      zone = Date._parse("00:00 #{text}")
+      return [:error, "invalid_type"] unless zone.key?(:zone) && honoured_zone?(zone)
+
+      [:ok, DateTime.parse(date, true, Date::GREGORIAN).to_time.utc - zone[:offset]]
+    end
+
+    def same_time?(rest, found)
+      TIME_PARTS.all? { |part| rest[part] == found[part] }
+    end
+
+    TIME_PARTS = %i[hour min sec sec_fraction].freeze
+    private_constant :TIME_PARTS
+
+    def same_date?(rest, found)
+      complete_date?(rest) && rest.values_at(:year, :mon, :mday) == found.values_at(:year, :mon, :mday)
+    end
+
     # Presets only make sense on String input; a non-String value (JSON
     # numbers, booleans) skips normalization and goes straight to the cast.
     #
@@ -1316,13 +1535,17 @@ module Permittable
     end
 
     # What an exported enum lists for one member: the cast value, re-encoded
-    # as JSON — except a :date/:datetime member authored as a String, which
-    # is published AS WRITTEN. Re-encoding a cast Time prints whole seconds,
-    # so "2026-09-05T10:00:00.25Z" was published as "…10:00:00Z", a value
-    # the server refuses. The authored String went through the very cast a
-    # request does, so the server accepts it by construction.
+    # as JSON — except a :datetime member authored as a String, which is
+    # published AS WRITTEN. Re-encoding a cast Time prints whole seconds, so
+    # "2026-09-05T10:00:00.25Z" was published as "…10:00:00Z", a value the
+    # server refuses. The authored String went through the very cast a request
+    # does, so the server accepts it by construction. A :date member is
+    # re-encoded: a Date has no digits to lose, and the String as written
+    # ("Sep 6, 2026", "2026-09-05T00:00:00Z") is a date the server reads but
+    # not one `format: date` accepts, so it is published as the YYYY-MM-DD
+    # the server compares against.
     def published_in_member(type, member, value)
-      member.is_a?(String) && %i[date datetime].include?(type) ? member : value
+      member.is_a?(String) && type == :datetime ? member : value
     end
 
     # Range#include? walks discrete ranges; cover? is the O(1) bounds check
@@ -1342,6 +1565,7 @@ module Permittable
   class ContractBuilder
     SCALAR_OPTS = %i[in format length default normalize validate virtual sensitive transform message desc example
                      nullable].freeze
+    FILE_REFUSED_OPTS = %i[in format length default normalize example].freeze
     NESTED_OPTS = %i[virtual sensitive message desc nullable].freeze
     JSON_OPTS   = %i[length max_depth default validate virtual sensitive transform message desc example
                      nullable].freeze
@@ -1393,6 +1617,7 @@ module Permittable
       name = field_name!(name)
       assert_opts!(name, opts, ARRAY_OPTS)
       required = opts.delete(:required) ? true : false
+      refuse_file_opts!(name, opts.keys & %i[default example], FILE_TYPE) if opts[:of]&.to_sym == FILE_TYPE
 
       field = { name: name, kind: :array, required: required, **opts }
       if field[:required] && field.key?(:default)
@@ -1598,6 +1823,7 @@ module Permittable
 
     def validate_scalar_opts!(field)
       name = field[:name]
+      refuse_file_opts!(name, field.keys & FILE_REFUSED_OPTS, FILE_TYPE) if field[:type] == FILE_TYPE
       if field[:required] && field.key?(:default)
         raise ArgumentError, "#{LABEL}: field :#{name} is required and cannot have a :default (default implies optional)"
       end
@@ -1666,7 +1892,7 @@ module Permittable
     end
 
     # `published` is stored only where it differs from the cast members (a
-    # String-authored :date/:datetime member), so it is read as an override.
+    # String-authored :datetime member), so it is read as an override.
     def cast_in_members!(field, members)
       status, cast, published = Coercion.cast_in_members(field[:type], members, nullable: field[:nullable])
       unless status == :ok
@@ -1763,6 +1989,12 @@ module Permittable
     def validate_json_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
+
+      # A request sending "" for a nullable :json field is the explicit null
+      # the walker reads it as, so a blank authored value is that nil, as a
+      # nullable scalar's is (see validate_authored_value!).
+      return field[opt] = nil if field[:nullable] && Coercion.absent_value?(field[opt])
+
       raise ArgumentError, "#{LABEL}: :#{opt} for :#{field[:name]} must be a Hash" unless field[opt].is_a?(Hash)
 
       status, read = AuthoredValues.read_json(field, field[opt])
@@ -1773,6 +2005,17 @@ module Permittable
 
     # format / length / normalize reason about characters; on any other
     # type they would silently apply to a cast non-String and mislead.
+    # An upload is passed through as it came, so what shapes a String or
+    # picks a value to stand in for one has nothing to act on. `validate:`
+    # is where a size or content-type check belongs.
+    def refuse_file_opts!(name, opts, type)
+      opt = opts.first
+      return unless opt
+
+      raise ArgumentError, "#{LABEL}: :#{opt} is not supported on :#{type} fields (field :#{name} is :#{type}); " \
+                           "use validate: for a size or content-type check"
+    end
+
     def validate_string_only_opts!(field)
       return if field[:type] == :string
 
@@ -1930,9 +2173,17 @@ module Permittable
       # proc cannot rewrite the host's own literal.
       authored = field[opt].is_a?(String) ? field[opt].dup : field[opt]
       value = Coercion.apply_normalize(field[:normalize], authored)
-      status, result = Coercion.refuse_finer_than_nanosecond(
-        field[:type], Coercion.check_scalar(live_in?(field) ? field.except(:in) : field, value)
-      )
+      # The walker's absence rule: on a nullable field a value that reads as
+      # absent ("" or one normalizing to "") is the explicit nil a request
+      # sending it gets, with nothing to cast or check — as an array's
+      # nullable sub-field already reads it (see AuthoredValues).
+      status, result = if field[:nullable] && Coercion.absent_value?(value)
+                         [:ok, nil]
+                       else
+                         Coercion.refuse_finer_than_nanosecond(
+                           field[:type], Coercion.check_scalar(live_in?(field) ? field.except(:in) : field, value)
+                         )
+                       end
       raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{result})" unless status == :ok
 
       field[opt] = freeze_authored(opt == :default && field[:transform] ? field[opt] : result)
@@ -2153,6 +2404,8 @@ module Permittable
       rule = { actions: actions.flatten.map(&:to_s).freeze, root: root && root.to_sym,
                model: model_class, unknown: unknown, enforce: !!enforce, mode: mode, fields: fields,
                finalize: builder.finalizer, desc: desc&.deep_dup&.freeze }.freeze
+      permittable_register_hooks
+      permittable_ensure_runnable!(rule)
       self.permittable_contracts = permittable_contracts + [rule]
     end
 
@@ -2166,6 +2419,74 @@ module Permittable
 
     private
 
+    # Registers the rescue_from handler and the before_action the gem relies
+    # on, each once per class, as soon as the class can take them. They used
+    # to be registered at the include alone, so a bare ActionController::Metal
+    # controller that included Permittable BEFORE AbstractController::Callbacks
+    # and ActionController::Rescue never got them: an `enforce: true` rule let
+    # bad requests through, and a violation escaped as a 500. Called at the
+    # include and again at every permit_params, which is where such a class
+    # has by now been given its modules. The callback is still registered
+    # ahead of any declared after this point (see the README's "Per-request
+    # locales").
+    def permittable_register_hooks
+      if !permittable_rescue_registered && respond_to?(:rescue_from)
+        rescue_from InvalidParameters, with: :render_invalid_parameters
+        self.permittable_rescue_registered = true
+      end
+      return if permittable_callback_registered || !respond_to?(:before_action)
+
+      # Registered at the include, and not at the first `permit_params`, when
+      # the host has callbacks by then: the README documents
+      # `skip_before_action :enforce_params_contract`, and Rails raises when it
+      # is asked to skip a callback that is not defined yet. The cost is the
+      # order: this check runs before any callback declared after the include,
+      # so a locale switch that must cover it is a `prepend_around_action`.
+      before_action :enforce_params_contract
+      self.permittable_callback_registered = true
+    end
+
+    # A bare ActionController::Metal controller has neither callbacks nor
+    # rescue_from until the app includes them, and a rule that needs one of
+    # them would otherwise load and then not run: raise at class load, naming
+    # the module. Other hosts (a plain class, a duck) are left as they are.
+    # Only the rule's OWN declared mode is read, never Permittable.mode: that
+    # is usually set by an initializer, and an app must not stop booting over
+    # it. The effective mode can only add a requirement, so an action it makes
+    # monitored without a before_action is left to Audit.inert?, which reports
+    # it as not covered.
+    def permittable_ensure_runnable!(rule)
+      return unless defined?(::ActionController::Metal) && self < ::ActionController::Metal
+
+      monitored = rule[:mode] == :monitor
+      missing = []
+      missing << "AbstractController::Callbacks" if (rule[:enforce] || monitored) && !respond_to?(:before_action)
+      missing << "ActionController::Rescue" if rule[:enforce] && !monitored && !respond_to?(:rescue_from)
+      if missing.empty?
+        return unless rule[:enforce] && !monitored && permittable_rescue_inside_callbacks?
+
+        raise ArgumentError,
+              "#{LABEL}: permit_params on #{name || inspect}, an ActionController::Metal controller, cannot rescue " \
+              "this enforce: true rule: include ActionController::Rescue after AbstractController::Callbacks, " \
+              "as ActionController::Base does. Included before it, Rescue wraps only the action, so the " \
+              "before_action's InvalidParameters escapes as a 500"
+      end
+
+      raise ArgumentError,
+            "#{LABEL}: permit_params on #{name || inspect}, an ActionController::Metal controller, cannot run " \
+            "this #{monitored ? 'monitor-mode' : 'enforce: true'} rule: include #{missing.join(' and ')} " \
+            "before permit_params (ActionController::Rescue after AbstractController::Callbacks, as ActionController::Base does)"
+    end
+
+    # A module included later sits earlier in the ancestors and so runs
+    # outside the others' process_action: Rescue is only around the
+    # callbacks when it was included after them.
+    def permittable_rescue_inside_callbacks?
+      rescue_at = ancestors.index(::ActionController::Rescue)
+      callbacks_at = ancestors.index(::AbstractController::Callbacks)
+      !rescue_at.nil? && !callbacks_at.nil? && rescue_at > callbacks_at
+    end
+
     def resolve_permit_model(model)
       case model
       when nil, false then nil
@@ -2193,8 +2514,12 @@ module Permittable
     # The drift guard. Nested/array fields are implicitly virtual — only
     # scalar fields, and the opaque `:json` field standing in for a
     # json/jsonb column, map one-to-one onto columns.
+    #
+    # A :file field is an upload, which maps to an attachment (ActiveStorage's
+    # has_one_attached, Shrine) rather than a column, so it is never demanded
+    # a column, as if it were virtual: true.
     def guard_contract_columns!(model_class, fields)
-      checked = fields.select { |f| %i[scalar json].include?(f[:kind]) && !f[:virtual] }
+      checked = fields.select { |f| %i[scalar json].include?(f[:kind]) && !f[:virtual] && f[:type] != FILE_TYPE }
       return if checked.empty?
 
       types = checked.to_h { |f| [f[:name], f[:type]] }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.15.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-04 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport