permittable 0.11.0 → 0.12.0

data/lib/permittable/audit.rb

@@ -378,18 +378,24 @@ module Permittable
     # entries; what was ignored follows in sections of its own, then any
     # ignore entry that matched nothing — `unmatched` defaults to checking
     # Permittable.audit_ignore, the list `entries` defaults to.
+    #
+    # With no routed action at all there is no table or summary, but the
+    # stale and unmatched sections still follow: that is when a contract no
+    # route reaches, or an ignore entry naming nothing, most needs saying.
     def format(entries, stale: {}, unmatched: unmatched_ignores(entries))
-      return "Permittable audit: no routed actions to report.\n" if entries.empty?
-
-      ignored, entries = entries.partition(&:ignored?)
-      out = entries.group_by(&:controller).map { |key, group| controller_block(key, group) }
-      out << summary_lines(summary(entries), rows: entries.length)
+      ignored, audited = entries.partition(&:ignored?)
+      out = entries.empty? ? ["Permittable audit: no routed actions to report."] : table_lines(audited)
       out << stale_lines(stale) unless stale.empty?
       out << ignored_lines(ignored) unless ignored.empty?
       out << unmatched_lines(unmatched) unless unmatched.empty?
       "#{out.join("\n")}\n"
     end
 
+    def table_lines(entries)
+      entries.group_by(&:controller).map { |key, group| controller_block(key, group) } <<
+        summary_lines(summary(entries), rows: entries.length)
+    end
+
     def controller_block(key, group)
       rows = group.map do |entry|
         "  #{entry.verb.to_s.upcase.ljust(6)} #{entry.path.ljust(34)} #{entry.action.ljust(12)} #{status(entry)}"

data/lib/permittable/authored_values.rb

@@ -1,21 +1,34 @@
 module Permittable
-  # The request walker, pointed at an authored array `default:`/`example:`
-  # at class load — the same permittable_check_array a request goes
-  # through, so the two cannot drift apart. Two seams are overridden:
+  # The request walker, pointed at an authored array or `:json`
+  # `default:`/`example:` at class load — the same permittable_check_array
+  # and permittable_check_json a request goes through, so the two cannot
+  # drift apart. Two seams are overridden:
   #
   #   * the field WHOSE default:/example: is being validated does not run
   #     its own `transform:` — see permittable_transform below for exactly
   #     which field that is and why. A SUB-FIELD's own transform: still
   #     runs, so what gets stored is what an equivalent request would
-  #     produce.
+  #     produce — for a default:, and, under a transforming array, only
+  #     where an array-level validate: reads its output. An example: is
+  #     read `as_sent`, which is what gets stored: no transform at any
+  #     depth, no sub-field default filled in and no array-level validate:.
+  #     When an array-level validate: exists somewhere in it, it is read
+  #     once more first, like a default, to VALIDATE it as a request would
+  #     be (see ContractBuilder, which decides). An example documents what a
+  #     client SENDS, so it must not be read through app code that reshapes
+  #     the value into what the action receives.
   #   * violations carry no `message:` — they become an ArgumentError for
   #     the contract's author, not a response for a client, and I18n may not
   #     be loaded yet.
   class AuthoredValues
     include Permittable
 
-    def self.read_array(field, value)
-      new.read_array(field, value)
+    def self.read_array(field, value, as_sent: false)
+      new.read_array(field, value, as_sent: as_sent)
+    end
+
+    def self.read_json(field, value)
+      new.read_json(field, value)
     end
 
     def self.summary(violations)
@@ -23,13 +36,24 @@ module Permittable
     end
 
     # [value as a request would get it, violations]
-    def read_array(field, value)
+    def read_array(field, value, as_sent: false)
       violations = []
       @field = field
+      @as_sent = as_sent
+      @read_by_validate = fields_under_validate(field) if field[:transform]
       read = permittable_check_array(field, value, path: field[:name].to_s, unknown: :ignore, violations: violations)
       [read, violations]
     end
 
+    # [:ok, value as a request would get it] or [:error, code]. A request's
+    # hash reaches permittable_check_json indifferent, as every Hash inside
+    # the walker's params is, so the authored one is made so first, the way
+    # the walker reads a nested hash. permittable_check_json then hands
+    # `validate:` a deep copy, as it does a request's, and returns that copy.
+    def read_json(field, value)
+      permittable_check_json(field, ActiveSupport::HashWithIndifferentAccess.new(value))
+    end
+
     def summary(violations)
       permittable_violation_summary(violations)
     end
@@ -45,17 +69,67 @@ module Permittable
     # identical value silently diverge (and the exported OpenAPI default,
     # which reads this same value, documents one the server never produces).
     #
-    # When @field itself has a transform:, its result is discarded anyway
-    # (validate_array_authored_value! stores the value AS AUTHORED instead —
-    # see its comment), so nothing inside its subtree is worth reading
-    # transformed: suppressing every nested call too keeps that walk free of
-    # app code, exactly as a scalar default's cast-only check already is.
+    # When @field itself has a transform:, it never runs here either way and
+    # its result is discarded anyway (validate_array_authored_value! stores
+    # the value AS AUTHORED instead — see its comment). A sub-field's
+    # transform: output is another matter: a request runs it, then the
+    # array-level `validate:` on that result, and only then the array's own
+    # transform. So a `validate:` that reads `i[:tags].is_a?(Array)` must be
+    # handed the transformed `tags`, or a contract every request satisfies
+    # fails at class load. But a transform: is app code (`Account.find`), so
+    # under such an array it runs ONLY where its output is consumed: for a
+    # field below an array declaring `validate:` (the walked array counts),
+    # not merely somewhere in the same subtree, where a `validate:` on a
+    # sibling branch reads nothing of it. Without an own transform: of its
+    # own, @field's read is what gets stored, so every sub-field's runs.
+    #
+    # `as_sent` (the stored read of an example:) runs none, at any depth.
     def permittable_transform(field, value)
-      return value if @field[:transform] || field.equal?(@field)
+      return value if @as_sent || field.equal?(@field)
+      return value if @field[:transform] && !@read_by_validate.key?(field)
 
       super
     end
 
+    # The fields below `field` whose output an array's `validate:` sees: all
+    # those under an array that declares one, counting `field` itself, by
+    # identity (the walker hands the very field hashes it was given).
+    def fields_under_validate(field, found = {}.compare_by_identity, under_validate: false)
+      under_validate ||= field[:kind] == :array && field[:validate]
+      Array(field[:fields]).each do |sub|
+        found[sub] = true if under_validate
+        fields_under_validate(sub, found, under_validate: under_validate)
+      end
+      found
+    end
+
+    # Nor does it run an array-level validate:, which expects the transformed
+    # sub-fields a request hands it. The validating read has already run it
+    # on exactly those, so the stored read, which would hand it the
+    # untransformed ones, must not (it could raise on a shape it never sees).
+    def permittable_array_validator(field)
+      super unless @as_sent
+    end
+
+    # What a client sends has no defaults filled in: an omitted sub-field
+    # stays omitted, at any depth, so the published example does not show a
+    # value (`cents: 0`) that no client sends. The walker fills them in; drop
+    # exactly what it filled, by the walker's own absence rule.
+    def permittable_check_hash(fields, hash, **)
+      result = super
+      return result unless @as_sent
+
+      fields.each do |field|
+        key = field[:name].to_s
+        next unless field.key?(:default)
+        next unless permittable_absent?(permittable_normalized(field, hash[key]), hash, key)
+        next if permittable_explicit_null?(field, hash, key)
+
+        result.delete(key)
+      end
+      result
+    end
+
     def permittable_violation(_field, param, code)
       { param: param, code: code.to_s }
     end

data/lib/permittable/column_guard.rb

@@ -28,13 +28,23 @@ module Permittable
       date: :temporal, datetime: :temporal, time: :temporal, timestamp: :temporal, timestamptz: :temporal
     }.freeze
 
+    # The contract type an `array ..., of:` takes for a column element type,
+    # for the array-column hint. Only scalar element types: `of:` takes no
+    # other, so a jsonb[] column gets the hint without an `of:`.
+    ARRAY_ELEMENT_TYPES = {
+      string: :string, text: :string, citext: :string, uuid: :string,
+      integer: :integer, bigint: :integer, float: :float, decimal: :decimal, boolean: :boolean,
+      date: :date, datetime: :datetime, timestamp: :datetime, timestamptz: :datetime
+    }.freeze
+
     module_function
 
     # `types:` teaches the error message: a Symbol/String applies to every
     # listed field, a Hash maps field => type. The raised ArgumentError then
     # appends a ready-to-paste migration command. `allowed:` maps field =>
-    # its `in:`, for the fields that declare one; only the enum rule reads it.
-    def ensure_columns_on!(label, klass, *fields, types: nil, check_types: false, allowed: nil)
+    # its `in:`, for the fields that declare one, and `transformed:` lists
+    # the fields that declare a `transform:`; only the enum rule reads them.
+    def ensure_columns_on!(label, klass, *fields, types: nil, check_types: false, allowed: nil, transformed: nil)
       return false unless schema_reachable?(klass)
 
       fields.flatten.compact.each do |field|
@@ -44,7 +54,7 @@ module Permittable
                 "#{column_migration_hint(klass, field, types)}"
         end
 
-        ensure_column_type!(label, klass, field, types, allowed) if check_types
+        ensure_column_type!(label, klass, field, types, allowed, transformed: transformed) if check_types
       end
       true
     end
@@ -54,16 +64,21 @@ module Permittable
     # TYPE_GROUPS) and stays silent unless both sides are known, so it can
     # only fire on a genuine cross-family mismatch — a contract still saying
     # :datetime after the column became a string, say.
-    def ensure_column_type!(label, klass, field, types, allowed = nil)
+    def ensure_column_type!(label, klass, field, types, allowed = nil, transformed: nil)
       declared = types.is_a?(Hash) ? types[field.to_sym] : types
       column = klass.columns_hash[field.to_s]
       return unless declared && column
 
+      ensure_not_array_column!(label, klass, field, declared, column)
+
       wanted = TYPE_GROUPS[declared.to_sym]
       enum = enum_attribute?(klass, field)
       # Checked before the column's type, which an enum's contract does not
       # depend on: see ensure_enum_contract!.
-      return ensure_enum_contract!(label, klass, field, declared, allowed && allowed[field.to_sym]) if enum && wanted == :text
+      if enum && wanted == :text
+        return ensure_enum_contract!(label, klass, field, declared, allowed && allowed[field.to_sym],
+                                     transformed: Array(transformed).include?(field.to_sym))
+      end
 
       # `column.type` is nil for a SQL type the adapter does not recognise
       # (a PostGIS geometry column without the extension loaded, a custom
@@ -88,6 +103,24 @@ module Permittable
             "(table: #{klass.table_name}). #{fix}"
     end
 
+    # A PostgreSQL array column reports its ELEMENT type as `type`, so
+    # `optional :tags, :string` over `t.string :tags, array: true` sits in
+    # the same group as the column and the group check passes — yet the
+    # field rejects as invalid_type every array the column stores. Only a
+    # scalar or :json field reaches this guard (an `array` field is
+    # implicitly virtual), and neither accepts an Array, so any declaration
+    # over an array column is the wrong shape.
+    def ensure_not_array_column!(label, klass, field, declared, column)
+      return unless column.respond_to?(:array?) && column.array?
+
+      element = ARRAY_ELEMENT_TYPES[column.type&.to_sym]
+      spelled = element ? "array :#{field}, of: :#{element}" : "array :#{field}"
+      raise ArgumentError,
+            "#{label}: '#{field}' is declared :#{declared} but the column is an array#{" (of :#{column.type})" if column.type} " \
+            "(table: #{klass.table_name}), so every array it stores would be rejected as invalid_type. " \
+            "Declare it `#{spelled}`, or declare the field virtual: true if it is not backed by this column."
+    end
+
     # `model:` is only duck-typed on column_names, hence the respond_to?.
     def enum_attribute?(klass, field)
       klass.respond_to?(:defined_enums) && klass.defined_enums.key?(field.to_s)
@@ -107,25 +140,31 @@ module Permittable
     # Accepted means what the enum's cast accepts: every name, plus every
     # stored value that is a String (a string-backed enum takes `"p"` for
     # `pro:` as readily as `"pro"`). An integer-backed enum's stored values
-    # are not accepted — a request carries `"0"`, which maps to nothing. A
-    # Range, or anything else without a finite list, cannot be checked, so it
-    # is refused rather than trusted.
+    # are not accepted — a request carries `"0"`, which maps to nothing —
+    # unless the field declares a `transform:`, which runs after `in:` and is
+    # how permittable:generate's TODO maps them back to names. Only the stored
+    # integers are admitted that way; the transform is app code, trusted to
+    # do what the TODO spells. A Range, or anything else without a finite
+    # list, cannot be checked, so it is refused rather than trusted.
     #
     # Only `enum` is recognised. The attribute API (`attribute :x, :datetime`
     # over a string column) is left compared against the column by choice:
     # an enum's mapping says exactly which strings are valid, an attribute
     # override says nothing a contract could be checked against.
-    def ensure_enum_contract!(label, klass, field, declared, listed)
+    def ensure_enum_contract!(label, klass, field, declared, listed, transformed: false)
       problem =
         if listed.nil?
           "declared :#{declared} without an in:"
         elsif listed.is_a?(Range) || !listed.respond_to?(:to_a)
           "declared :#{declared} with an in: that does not list its values"
         else
-          stray = listed.to_a - enum_values(klass, field)
+          accepted = enum_values(klass, field)
+          accepted += stored_integers(klass, field) if transformed
+          stray = listed.to_a - accepted
           return if stray.empty?
 
-          "declared :#{declared} with an in: listing values it would refuse: #{stray.map(&:inspect).join(', ')}"
+          "declared :#{declared} with an in: listing values it would refuse: #{stray.map(&:inspect).join(', ')}" \
+            "#{stored_integer_hint(klass, field, stray, transformed)}"
         end
 
       raise ArgumentError,
@@ -139,6 +178,16 @@ module Permittable
       mapping.keys.map(&:to_s) + mapping.values.grep(String)
     end
 
+    def stored_integers(klass, field)
+      klass.defined_enums[field.to_s].values.grep(Integer).map(&:to_s)
+    end
+
+    def stored_integer_hint(klass, field, stray, transformed)
+      return "" if transformed || !stray.intersect?(stored_integers(klass, field))
+
+      " (a stored integer is accepted only beside a transform: mapping it back to its name)"
+    end
+
     # `Order.statuses.keys` when the enum's plural reader exists, and the
     # always-valid `defined_enums["..."]` spelling when it does not (a name
     # that is not a Ruby identifier, a duck-typed model).

data/lib/permittable/contract.rb

@@ -62,10 +62,38 @@ module Permittable
           super(fields, hash, path: path, unknown: unknown, top_level: false, violations: violations)
         end
 
+        # unknown: :log warns through `logger`, and a controller gets one from
+        # ActionController. This host has none, so :log used to drop the keys
+        # without a word, exactly like :ignore. Rails.logger is read on every
+        # call, not at definition: contracts are usually constants, loaded
+        # before an app's initializers may have assigned it. With no Rails
+        # (a script, a job, a CSV import) the warning goes to $stderr rather
+        # than nowhere, since a :log that cannot log is :ignore by another
+        # name. Defining the contract does not raise for a missing logger:
+        # whether one exists is only known when the contract is called.
+        #
+        # The fallback Logger is built on every call, not memoized: #call!
+        # makes a new host per call, so an instance memo never applied, and a
+        # class-level one would capture $stderr once, hiding a later
+        # reassignment (a test's capture, a daemonized process's redirect).
+        def logger
+          return ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+          ::Logger.new($stderr)
+        end
+
         # Instrumentation payload label (anonymous classes have no name).
         def permittable_controller_name
           "Permittable::Contract"
         end
+
+        # ... and its action: the host has no action_name, so the payload's
+        # `action` (documented as a String) and the log lines that name the
+        # action would be nil. A Contract has one entry point, the same
+        # "call" #call! passes to permitted_params.
+        def permittable_action_name
+          ACTION
+        end
       end
       @host_class.permit_params(root: root, unknown: unknown, model: model, mode: :enforce, desc: desc, &)
     end
@@ -80,7 +108,10 @@ module Permittable
     # The contract's fields, which is also what makes a Contract usable as a
     # field group: `use SomeContract` inside a permit_params block splices
     # them in, so a webhook payload and a controller action can share one
-    # definition instead of two that drift.
+    # set of fields instead of two that drift. Only the fields — `use`
+    # refuses a contract that declares a finalize, which no field carries.
+    # To share both, put the fields in a `Permittable.fields` group that
+    # each side uses, and declare finalize in each.
     def fields
       rule[:fields]
     end
@@ -118,9 +149,30 @@ module Permittable
 
     def normalize_input(input)
       return {} if input.nil?
-      return input if input.is_a?(Hash) || input.respond_to?(:to_unsafe_h)
+      return input if input.respond_to?(:to_unsafe_h)
+      return unwrap_parameters(input) if input.is_a?(Hash)
 
       raise ArgumentError, "#{LABEL}: Contract#call expects a Hash (got #{input.class})"
     end
+
+    # A controller's params reach the concern as ActionController::Parameters
+    # and are converted deeply by to_unsafe_h. A service object is usually
+    # handed a slice of them inside a plain Hash — `CreateUser.call(user:
+    # params[:user])` — and nothing converted those: a Parameters value is
+    # not a Hash, so a root read it as invalid_type (400), a nested block or
+    # :json field likewise (422). Each one is converted here, the way
+    # to_unsafe_h converts the whole. Only what holds one is copied.
+    def unwrap_parameters(value)
+      case value
+      when Hash
+        unwrapped = value.transform_values { |v| unwrap_parameters(v) }
+        unwrapped.each_value.zip(value.each_value).all? { |new, old| new.equal?(old) } ? value : unwrapped
+      when Array
+        unwrapped = value.map { |v| unwrap_parameters(v) }
+        unwrapped.zip(value).all? { |new, old| new.equal?(old) } ? value : unwrapped
+      else
+        value.respond_to?(:to_unsafe_h) ? value.to_unsafe_h : value
+      end
+    end
   end
 end

data/lib/permittable/error_envelope.rb

@@ -3,7 +3,8 @@ module Permittable
   #
   # `:envelope` (the default) is the gem's original shape: the host's
   # #render_error when the controller defines one (e.g. concerns_on_rails'
-  # Respondable), otherwise the identical inline JSON.
+  # Respondable; see host_render_error for a private one), otherwise the
+  # identical inline JSON.
   #
   # `:problem` renders RFC 9457 Problem Details — `application/problem+json`
   # with type/title/status/detail/instance members and the field violations as
@@ -44,21 +45,109 @@ module Permittable
     end
 
     def render_envelope(controller, message:, status:, code: nil, details: nil)
-      if controller.respond_to?(:render_error)
-        # errors: only when there are details — a host may document its
-        # render_error contract as `(message:, status:, code:)`, and an
-        # unconditional errors: kwarg would break those implementations.
+      public_host = controller.respond_to?(:render_error)
+      host = public_host ? host_method(controller) : private_host_method(controller)
+      if public_host || host
         kwargs = { message: message, code: code, status: status }
-        kwargs[:errors] = details if details
-        controller.render_error(**kwargs)
+        kwargs[:errors] = details if details && (host.nil? || takes_errors?(host))
+        host ? host.call(**kwargs) : controller.render_error(**kwargs)
       else
         error = { message: message }
         error[:code] = code if code
         error[:details] = details if details
-        controller.render(json: { success: false, error: error }, status: status)
+        # content_type: because `render json:` only supplies application/json
+        # when the response has none yet, and `respond_to` has already set the
+        # negotiated one (text/html for a browser form, or for `Accept: */*`
+        # with html listed first). Without it this JSON body goes out as HTML.
+        # A JSON type the response already carries (a registered
+        # application/vnd.api+json, say) is the host's choice and is kept.
+        options = { json: { success: false, error: error }, status: status }
+        options[:content_type] = "application/json" unless json_media_type?(response_media_type(controller))
+        controller.render(**options)
       end
     end
 
+    # The media type (no parameters) the response already carries, or nil when
+    # it has none yet or the host has no response to ask.
+    def response_media_type(controller)
+      return nil unless controller.respond_to?(:response)
+
+      response = controller.response
+      return nil unless response
+
+      type = response.respond_to?(:media_type) ? response.media_type : response.content_type
+      return nil unless type
+
+      type.to_s.split(";").first.to_s.strip.downcase
+    end
+
+    def json_media_type?(type)
+      !type.nil? && (type == "application/json" || type.end_with?("+json"))
+    end
+
+    # The Method for the host's public render_error, or nil when the controller
+    # claims to respond (respond_to? is true) yet has no such method to
+    # inspect: one served by method_missing without respond_to_missing?.
+    # Master called it straight through with errors: included, and nil keeps
+    # doing exactly that rather than raising NameError out of the rescue_from
+    # handler.
+    def host_method(controller)
+      controller.method(:render_error)
+    rescue NameError
+      nil
+    end
+
+    # A private render_error is the usual spelling on an ApplicationController
+    # (a public method there is routable as an action in every subclass), so
+    # it is used too — but only when it is shaped like the documented keyword
+    # contract: a private `render_error(message, status)` helper written for
+    # something else was never consulted, and must not start turning every 422
+    # into a 500. Nil renders the inline shape.
+    def private_host_method(controller)
+      return nil unless controller.respond_to?(:render_error, true)
+
+      method = host_method(controller)
+      method if method && keyword_contract?(method.parameters)
+    end
+
+    # The keywords render_envelope may pass: message:, code: and status:
+    # always, errors: when the method takes it.
+    DELEGATED_KEYWORDS = %i[message code status errors].freeze
+
+    # Shaped like the documented contract: it takes message:, code: and
+    # status: (by name or through **), and requires nothing the gem does not
+    # pass — no positional argument, no keyword outside DELEGATED_KEYWORDS.
+    # `(message:, status:)` is a common private helper on an
+    # ApplicationController, and calling it with code: would raise.
+    def keyword_contract?(parameters)
+      return false if parameters.any? { |kind, _| kind == :req }
+
+      required = parameters.filter_map { |kind, name| name if kind == :keyreq }
+      return false unless (required - DELEGATED_KEYWORDS).empty?
+      return true if parameters.any? { |kind, _| kind == :keyrest }
+
+      (%i[message code status] - keyword_names(parameters)).empty?
+    end
+
+    # A rejection always carries details, so passing errors: whenever there
+    # are some passed it on every call — and a host documenting its contract
+    # as `(message:, status:, code:)`, which the README promises keeps
+    # working, raised ArgumentError out of the rescue_from handler: a 500 for
+    # every invalid request. errors: now goes only to a method that can take
+    # it: one naming it, taking **kwargs, or declaring no keywords at all
+    # (`*args`, which received it inside its trailing Hash before).
+    def takes_errors?(method)
+      parameters = method.parameters
+      return true if parameters.any? { |kind, _| kind == :keyrest }
+
+      names = keyword_names(parameters)
+      names.empty? || names.include?(:errors)
+    end
+
+    def keyword_names(parameters)
+      parameters.filter_map { |kind, name| name if %i[key keyreq].include?(kind) }
+    end
+
     # Members are emitted in the order RFC 9457 documents them, so the wire
     # format is stable and readable. `instance` is omitted rather than guessed
     # when the host cannot name the request path (a params duck, a job).

data/lib/permittable/field_group.rb

@@ -25,7 +25,8 @@ module Permittable
   #       use UserFields
   #     end
   #
-  #     # PATCH: same fields, nothing mandatory.
+  #     # PATCH: same fields, nothing mandatory, no defaults (a default
+  #     # would reset plan to "free" on every PATCH that omits it).
   #     permit_params :update, root: :user, model: User do
   #       use UserFields, optional: true
   #     end