permittable 0.13.1 → 0.15.0

data/lib/permittable/column_guard.rb

@@ -48,12 +48,11 @@ module Permittable
       return false unless schema_reachable?(klass)
 
       fields.flatten.compact.each do |field|
-        unless klass.column_names.include?(field.to_s)
-          raise ArgumentError, ignored_column_message(label, klass, field) if ignored_column?(klass, field)
+        column = backing_column(klass, field)
+        unless klass.column_names.include?(column)
+          raise ArgumentError, ignored_column_message(label, klass, column) if ignored_column?(klass, column)
 
-          raise ArgumentError,
-                "#{label}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
-                "#{column_migration_hint(klass, field, types)}"
+          raise ArgumentError, missing_column_message(label, klass, field, column, types)
         end
 
         ensure_column_type!(label, klass, field, types, allowed, transformed: transformed) if check_types
@@ -61,6 +60,114 @@ module Permittable
       true
     end
 
+    # `alias_attribute :title, :name` makes `title` an attribute assignment
+    # accepts, backed by `name`'s column, so the existence check, the
+    # ignored_columns check and the type check all look at the target. Aliases
+    # may chain; the walk stops at a name it has seen, so a cycle cannot hang a
+    # class body. A duck-typed model without `attribute_aliases` (or whose
+    # reader returns nil) has none.
+    def resolve_alias(klass, field)
+      name = field.to_s
+      aliases = attribute_aliases_of(klass)
+      seen = [name]
+      while (target = aliases[name])
+        break if seen.include?(target.to_s)
+
+        name = target.to_s
+        seen << name
+      end
+      name
+    end
+
+    def attribute_aliases_of(klass)
+      klass.respond_to?(:attribute_aliases) ? Hash(klass.attribute_aliases) : {}
+    end
+
+    # The column a field is stored in: its alias target's, or for a store
+    # accessor (`store_accessor :settings, :theme`) the column of its store,
+    # `settings`, itself resolved when the store is an alias. The field is then
+    # a key inside that column, not a column of its own, so the column's type
+    # says nothing about it (see ensure_column_type!). The guard accepts it for
+    # the reason it accepts an alias or an enum: assignment takes it and the
+    # data lands in a column. `virtual: true` stays the opt-out for what no
+    # column holds. That is also why the store column itself must exist.
+    def backing_column(klass, field)
+      name = resolve_alias(klass, field)
+      store = stored_attribute_store(klass, name)
+      store ? resolve_alias(klass, store) : name
+    end
+
+    # The store (the column holding the hash) a `store_accessor` field lives
+    # in, nil when `name` is a plain attribute. A real column of the same name
+    # wins: it is the attribute Rails reads. A duck-typed model without
+    # `stored_attributes` has none.
+    #
+    # `stored_attributes` lists the raw keys (`{settings: [:theme]}`), but the
+    # accessor is named by `prefix:`/`suffix:` too (`settings_theme`), so the
+    # name is accepted only when the model really has a store accessor's writer
+    # under it, which is what assignment calls (see store_accessor_writer?). A
+    # writer from anywhere else is an ordinary attribute, not a
+    # store key. The store is then the one whose key the name is built from,
+    # the longest key first and one whose name the accessor mentions next.
+    # Rails does not record which prefix built which accessor, so two stores
+    # sharing a key are ambiguous, and the guess may check the other's column.
+    def stored_attribute_store(klass, name)
+      return unless klass.respond_to?(:stored_attributes)
+      return if klass.column_names.include?(name) || !store_accessor_writer?(klass, "#{name}=")
+
+      pairs = Hash(klass.stored_attributes).flat_map { |store, keys| keys.map { |key| [store, key.to_s] } }
+      pairs.select { |_store, key| name.include?(key) }
+           .min_by { |store, key| [-key.length, name.include?(store.to_s) ? 0 : 1] }&.first
+    end
+
+    # Whether `writer` is a store accessor's, whatever the model has layered on
+    # it. The accessor is defined by active_record/store.rb itself, so the
+    # method chain is walked through `super` (an override in the model, a
+    # subclass, a prepended or later-included module calls through to it) until
+    # a method defined in that file turns up. That holds across Rails versions:
+    # the module holding the accessors is `_store_accessors_module` on 6.1
+    # through 8.1 and a `GeneratedStoreMethods` constant on main, which a
+    # lookup of either would miss. An ordinary writer (`attr_accessor`, an
+    # attribute-API or column writer) is defined elsewhere.
+    STORE_SOURCE = %r{/active_record/store\.rb\z}
+
+    def store_accessor_writer?(klass, writer)
+      return false unless klass.method_defined?(writer)
+
+      method = klass.instance_method(writer)
+      while method
+        return true if method.source_location&.first.to_s.match?(STORE_SOURCE)
+
+        method = method.super_method
+      end
+      false
+    end
+
+    def missing_column_message(label, klass, field, column, types)
+      store = stored_attribute_store(klass, resolve_alias(klass, field))
+      return store_column_message(label, klass, field, store, column) if store
+
+      if column == field.to_s
+        return "#{label}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
+               "#{column_migration_hint(klass, field, types)}"
+      end
+
+      # An alias: the migration must add the column the alias points at,
+      # not one named for the alias, which would still leave this check failing.
+      "#{label}: '#{field}' is an alias of '#{column}', which does not exist in the database " \
+        "(table: #{klass.table_name})." \
+        "#{column_migration_hint(klass, column, types.is_a?(Hash) ? types[field.to_sym] : types)}"
+    end
+
+    # The store column is gone (dropped, or never migrated), so the accessor
+    # reads and writes nothing. That is the column the migration is for, not
+    # a column named after the accessor, which would shadow it.
+    def store_column_message(label, klass, field, store, column)
+      "#{label}: '#{field}' is a store_accessor of :#{store} on #{model_expr(klass)}, " \
+        "but the table has no '#{column}' column (table: #{klass.table_name}). " \
+        "Add the '#{column}' column that holds it, or declare the field virtual: true if the app handles it itself."
+    end
+
     # The type half of the drift guard, opt-in via Permittable
     # .check_column_types. It compares GROUPS rather than exact types (see
     # TYPE_GROUPS) and stays silent unless both sides are known, so it can
@@ -68,18 +175,23 @@ module Permittable
     # :datetime after the column became a string, say.
     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]
+      target = resolve_alias(klass, field)
+      column = klass.columns_hash[target]
       return unless declared && column
 
       ensure_not_array_column!(label, klass, field, declared, column)
 
       wanted = TYPE_GROUPS[declared.to_sym]
-      enum = enum_attribute?(klass, field)
+      # An enum is keyed by the name it was declared on, which may be the
+      # alias (`enum :phase` over `alias_attribute :phase, :status`) or the
+      # target it points at.
+      enum_name = [field.to_s, target].find { |name| enum_attribute?(klass, name) }
+      enum = !enum_name.nil?
       # Checked before the column's type, which an enum's contract does not
       # depend on: see ensure_enum_contract!.
       if enum && wanted == :text
-        return ensure_enum_contract!(label, klass, field, declared, allowed && allowed[field.to_sym],
-                                     transformed: Array(transformed).include?(field.to_sym))
+        return ensure_enum_contract!(label, klass, enum_name, declared, allowed && allowed[field.to_sym],
+                                     transformed: Array(transformed).include?(field.to_sym), shown: field.to_s)
       end
 
       # `column.type` is nil for a SQL type the adapter does not recognise
@@ -95,7 +207,8 @@ module Permittable
       # On an enum, `virtual: true` would be the wrong advice: it switches
       # off the existence check too, and the field IS backed by this column.
       fix = if enum
-              "'#{field}' is an enum on #{model_expr(klass)}: declare it :string, in: #{enum_keys_expr(klass, field)}."
+              "#{enum_subject(enum_name, field)} is an enum on #{model_expr(klass)}: " \
+                "declare it :string, in: #{enum_keys_expr(klass, enum_name)}."
             else
               "Change the contract to match the column, migrate the column to match the contract, " \
                 "or declare the field virtual: true if it is not backed by this column."
@@ -153,7 +266,7 @@ module Permittable
     # 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, transformed: false)
+    def ensure_enum_contract!(label, klass, field, declared, listed, transformed: false, shown: field)
       problem =
         if listed.nil?
           "declared :#{declared} without an in:"
@@ -170,11 +283,19 @@ module Permittable
         end
 
       raise ArgumentError,
-            "#{label}: '#{field}' is an enum on #{model_expr(klass)}, #{problem} (table: #{klass.table_name}). " \
+            "#{label}: #{enum_subject(field, shown)} is an enum on #{model_expr(klass)}, #{problem} (table: #{klass.table_name}). " \
             "A value outside the enum would pass the contract and then raise on assignment. " \
             "Declare it with in: #{enum_keys_expr(klass, field)}."
     end
 
+    # The field as an enum error names it: `'phase'`, or `'state' (an alias of
+    # 'status')` when the enum is declared on the alias's target.
+    def enum_subject(enum_name, shown)
+      return "'#{shown}'" if enum_name.to_s == shown.to_s
+
+      "'#{shown}' (an alias of '#{enum_name}')"
+    end
+
     def enum_values(klass, field)
       mapping = klass.defined_enums[field.to_s]
       mapping.keys.map(&:to_s) + mapping.values.grep(String)

data/lib/permittable/contract.rb

@@ -140,7 +140,10 @@ module Permittable
     end
 
     # The request-body schema for this contract — JSON Schema draft 2020-12,
-    # identical to what the OpenAPI exporter emits for a controller rule.
+    # what the OpenAPI exporter emits for a controller rule, less what only an
+    # HTTP request carries (the form keys a rootless `unknown: :error` body
+    # lists, the route's path parameters, a multipart body's flat part names):
+    # a contract exempts none of those.
     def json_schema
       JsonSchema.rule(rule)
     end

data/lib/permittable/error_envelope.rb

@@ -61,12 +61,29 @@ module Permittable
         # 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)
+        type = json_media_type?(response_media_type(controller)) ? nil : "application/json"
+        render_json(controller, { success: false, error: error }, status: status, content_type: type)
       end
     end
 
+    # `render json:`, or — for a bare ActionController::Metal that never
+    # included ActionController::Rendering, and so has no `render` — the same
+    # response written through Metal's own status=, content_type= and
+    # response_body=. `render json:` calls `to_json` on a Hash, so the bytes
+    # are the same. A controller with `render` always takes the first path.
+    def render_json(controller, payload, status:, content_type: nil)
+      if !controller.respond_to?(:render) && controller.respond_to?(:response_body=)
+        controller.status = status
+        controller.content_type = content_type if content_type
+        controller.response_body = [payload.to_json]
+        return
+      end
+
+      options = { json: payload, status: status }
+      options[:content_type] = content_type if content_type
+      controller.render(**options)
+    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)
@@ -160,7 +177,7 @@ module Permittable
       instance = request_path(controller)
       problem[:instance] = instance if instance
       problem[:errors] = details if details && !details.empty?
-      controller.render(json: problem, status: status, content_type: PROBLEM_MEDIA_TYPE)
+      render_json(controller, problem, status: status, content_type: PROBLEM_MEDIA_TYPE)
     end
 
     # RFC 9457: an absent `type` means "about:blank", so that is the honest

data/lib/permittable/json_schema.rb

@@ -67,7 +67,12 @@ module Permittable
       decimal: { "type" => %w[string number], "format" => "decimal" },
       boolean: { "type" => "boolean" },
       date: { "type" => "string", "format" => "date" },
-      datetime: { "type" => "string", "format" => "date-time" }
+      datetime: { "type" => "string", "format" => "date-time" },
+      # OpenAPI 3.1 / JSON Schema 2020-12 describe a file as a string with a
+      # contentMediaType (`format: binary` is the 3.0 spelling, which 3.1
+      # dropped). It rides in a multipart/form-data body, see
+      # OpenApi.body_media_type.
+      file: { "type" => "string", "contentMediaType" => "application/octet-stream" }
     }.freeze
 
     # Request-body schema for one rule from `permittable_contracts` /
@@ -218,7 +223,7 @@ module Permittable
         # applies here too — a :decimal in: member is otherwise always
         # exported as a string, so a numerically-exported default: is no
         # longer a member of its own enum's exported list. in_published (a
-        # :date/:datetime member kept in its authored String form, see
+        # :datetime member kept in its authored String form, see
         # Coercion.published_in_member) takes precedence over the cast
         # members when both apply.
         schema["enum"] = (field[:in_published] || allowed).map { |v| json_value(v, decimal: :number) }
@@ -359,7 +364,8 @@ module Permittable
     # takes. A nullable :string keeps the floor it has always had (stricter
     # than the server, the safe direction); the other types start without.
     def blank_floor?(field)
-      field[:required] && (field[:type] == :string || !field[:nullable])
+      # A :file is no string at the wire: a 0-byte upload is accepted.
+      field[:required] && field[:type] != :file && (field[:type] == :string || !field[:nullable])
     end
 
     def apply_pattern!(schema, regexp)

data/lib/permittable/open_api.rb

@@ -201,12 +201,173 @@ module Permittable
     end
 
     def rule_request_body(rule)
+      media_type = body_media_type(rule)
+      schema = JsonSchema.rule(rule)
+      schema = form_schema(schema, rule) if media_type == "multipart/form-data"
+      allow_form_keys!(schema) if media_type != "multipart/form-data" && rule[:unknown] == :error && !rule[:root]
       {
         "required" => !!(rule[:root] || rule[:fields].any? { |f| f[:required] }),
-        "content" => { "application/json" => { "schema" => JsonSchema.rule(rule) } }
+        "content" => { media_type => { "schema" => schema } }
       }
     end
 
+    # Under `unknown: :error` the runtime still exempts Rails' form keys
+    # (FORM_KEYS) at the top of a rootless contract, so a JSON body carrying
+    # `authenticity_token` or `_method` (a form's fields sent as JSON, a record
+    # echoed back) is accepted, and the body schema must not forbid it. They
+    # stay in as free, never-required properties, as the multipart body lists
+    # them (see form_schema). A name the contract declares keeps its own
+    # schema. A `root:` rule needs none of this: the keys sit outside the root,
+    # in a wrapper that is permissive already. The plain JsonSchema.rule and
+    # Contract#json_schema describe the contract, not an HTTP body, and a
+    # standalone Contract exempts no form key, so they do not list them.
+    def allow_form_keys!(schema)
+      Permittable::FORM_KEYS.each { |key| schema["properties"][key] ||= {} }
+    end
+
+    # A multipart body is not one JSON object: each part is a form field, and
+    # Rails reads the part NAMES. `user[avatar]` is the avatar of the `user`
+    # hash and a repeated `docs[]` is an array, so the schema's properties
+    # carry those names, flat, instead of nesting `user` as a single part
+    # (which a client would send as one JSON part, unable to hold the file).
+    # An array of hashes is sent in the indexed form Rails' fields_for renders
+    # (`items[0][photo]`, `items[1][photo]`, which the runtime reads), so its
+    # leaves are `patternProperties` with an anchored pattern each. What a
+    # flat body cannot say, a container's own `required`, bounds, `nullable`,
+    # `desc:` and `validate:` marker, rides in `x-permittable-form-groups`,
+    # keyed by the container's bracket name.
+    #
+    # Under `unknown: :error` the flat body refuses every other name, which
+    # covers each nesting level at once (`user[address][bogus]` is no listed
+    # name). It must then also list what the server still accepts: a
+    # nullable container's null (`user[docs]=""`), the keys of a :json
+    # field (`user[extra][any]`), and, for a `root:` rule, any part outside
+    # the root, which the runtime never reads; a rootless rule instead gets
+    # the form keys (FORM_KEYS) the runtime exempts at the top level.
+    def form_schema(json_schema, rule)
+      root = rule[:root] && rule[:root].to_s
+      form = { properties: {}, patterns: {}, required: [], groups: {}, strict: rule[:unknown] == :error }
+      flatten_form(json_schema, [], true, form, skip_group: root)
+      if form[:strict] && root
+        form[:patterns]["^(?!#{form_escape(root)}(?:\\[|$))"] = {}
+      elsif form[:strict]
+        form[:patterns]["^(?:#{Permittable::FORM_KEYS.map { |key| form_escape(key) }.join('|')})$"] = {}
+      end
+      schema = { "type" => "object", "properties" => form[:properties] }
+      schema["patternProperties"] = form[:patterns] unless form[:patterns].empty?
+      schema["additionalProperties"] = false if form[:strict]
+      schema["required"] = form[:required] unless form[:required].empty?
+      schema["x-permittable-form-groups"] = form[:groups] unless form[:groups].empty?
+      schema["x-permittable-finalize"] = true if rule[:finalize]
+      schema
+    end
+
+    GROUP_KEYS = %w[minItems maxItems description x-permittable-custom-validation].freeze
+
+    # `path` is the part name as segments: a key, or :index for the number
+    # an array of hashes' element carries. A path with no :index is a plain
+    # property name; one with an :index becomes a pattern. `required` is
+    # relative to the element inside an array of hashes: patterns cannot
+    # carry it, but a group inside the element (`items[][info]`) can.
+    def flatten_form(schema, path, required, form, skip_group: nil)
+      if form_container?(schema, "object")
+        form_group!(schema, path, required, form, skip_group)
+        schema["properties"].each do |key, child|
+          flatten_form(child, path + [key], required && schema.fetch("required", []).include?(key), form,
+                       skip_group: skip_group)
+        end
+      elsif form_container?(schema, "array") && form_container?(schema["items"], "object")
+        form_group!(schema, path, required, form, skip_group)
+        flatten_form(schema["items"], path + [:index], true, form, skip_group: skip_group)
+      else
+        if Array(schema["type"]).include?("array")
+          schema, required = form_list(schema, path, required, form)
+          path += [""]
+        end
+        form[:patterns]["#{form_pattern(path).delete_suffix('$')}\\["] = {} if form[:strict] && form_opaque?(schema)
+        form_leaf!(schema, path, required, form)
+      end
+    end
+
+    def form_opaque?(schema)
+      Array(schema["type"]).include?("object") && !schema.key?("properties")
+    end
+
+    # The part a nullable container's null is sent as: an empty string.
+    def form_null!(path, form)
+      form_leaf!({ "const" => "" }, path, false, form) if form[:strict]
+    end
+
+    # A nullable array's null is an empty part named without the `[]`
+    # (`docs=""`); `docs[]=""` is an empty array. So the `docs[]` leaf loses
+    # "null" and the group entry, under the name the null is sent as, says so,
+    # and carries `required` too: listing `docs[]` as required would refuse
+    # the null, which sends no `docs[]` part. Returns [leaf schema, required].
+    def form_list(schema, path, required, form)
+      types = Array(schema["type"])
+      return [schema, required] unless types.include?("null")
+
+      form[:groups][form_name(path.map { |k| k == :index ? "" : k })] = { "required" => required, "nullable" => true }
+      form_null!(path, form)
+      types -= ["null"]
+      [schema.merge("type" => types.one? ? types.first : types), false]
+    end
+
+    def form_leaf!(schema, path, required, form)
+      if path.include?(:index)
+        form[:patterns][form_pattern(path)] = schema
+      else
+        name = form_name(path)
+        form[:properties][name] = schema
+        form[:required] << name if required
+      end
+    end
+
+    def form_name(path)
+      path.each_with_index.map { |key, i| i.zero? ? key.to_s : "[#{key}]" }.join
+    end
+
+    def form_pattern(path)
+      body = path.each_with_index.map do |key, i|
+        text = key == :index ? '\\d+' : form_escape(key)
+        i.zero? ? text : "\\[#{text}\\]"
+      end
+      "^#{body.join}$"
+    end
+
+    def form_escape(key)
+      key.to_s.gsub(JsonSchema::EcmaPattern::SYNTAX_ESCAPE) { |c| "\\#{c}" }
+    end
+
+    def form_group!(schema, path, required, form, skip_group)
+      return if path.empty? || path == [skip_group] || path.last == :index
+
+      group = { "required" => required }
+      if Array(schema["type"]).include?("null")
+        group["nullable"] = true
+        form_null!(path, form)
+      end
+      GROUP_KEYS.each { |key| group[key] = schema[key] if schema.key?(key) }
+      form[:groups][form_name(path.map { |k| k == :index ? "" : k })] = group
+    end
+
+    def form_container?(schema, kind)
+      return false unless schema.is_a?(Hash) && Array(schema["type"]).include?(kind)
+
+      kind == "array" ? schema.key?("items") : schema["properties"].is_a?(Hash)
+    end
+
+    # An upload cannot travel in JSON, so a rule with a :file field anywhere
+    # in it describes a multipart/form-data body; every other rule stays
+    # application/json.
+    def body_media_type(rule)
+      rule[:fields].any? { |f| file_field?(f) } ? "multipart/form-data" : "application/json"
+    end
+
+    def file_field?(field)
+      field[:type] == :file || field[:of] == :file || (field[:fields] || []).any? { |f| file_field?(f) }
+    end
+
     # { action => operation } for every action the controller's contracts
     # cover, resolved through permit_rule_for so last-matching-rule-wins holds
     # in the documentation exactly as it does at request time.
@@ -319,7 +480,12 @@ module Permittable
       routes.select { |route| OPENAPI_VERBS.include?(verb_of(route)) }
             .group_by { |route| [route[:controller].to_s, route[:action].to_s] }
             .transform_values do |matching|
-              matching.map { |route| [route[:path], verb_of(route), route[:template]] }.uniq
+              matching.group_by { |route| [route[:path], verb_of(route), route[:template]] }.map do |slot, same|
+                # Several routes can reach one slot (a constrained one ahead
+                # of a plain one): a name leaves the body only if every one
+                # of them fills it.
+                [*slot, same.map { |route| Array(route[:defaults]) }.reduce(:&)]
+              end
             end
     end
 
@@ -420,9 +586,9 @@ module Permittable
           slots << OperationSlot.new(holder, action, nil, operation["operationId"], owner) unless holder.key?(action)
           holder[action] = operation
         else
-          free.each do |path, verb, template|
+          free.each do |path, verb, template, defaults|
             holder = (paths[path] ||= {})
-            placed = with_path_parameters(operation, path, controller.permit_rule_for(action), template || path)
+            placed = with_path_parameters(operation, path, controller.permit_rule_for(action), template || path, defaults)
             holder[verb] = template ? placed.merge("x-permittable-path" => template) : placed
             slots << OperationSlot.new(holder, verb, verb, operation["operationId"], owner, path)
           end
@@ -544,14 +710,22 @@ module Permittable
     # `own` is the route's own spelling of the template, which differs
     # from `path` when collapse_shapes placed the route under another
     # route's spelling: the same shape, so the names pair up by position.
-    def with_path_parameters(operation, path, rule, own = path)
+    #
+    # `defaults` names what the route fills from its `defaults:` (see
+    # route_defaults). The router merges those over the body like a
+    # templated name, so they leave the body the same way, but the URL does
+    # not carry them and they are no path parameter. A name the path
+    # templates is that parameter instead: `get "o(/:id)", defaults:
+    # { id: 5 }` is a parameter on `/o/{id}` and a default only on `/o`.
+    def with_path_parameters(operation, path, rule, own = path, defaults = [])
       # A name the path templates twice (a mount and an engine route both
       # name `:id`) is declared once: OpenAPI forbids two parameters with
       # one name and location.
       variables = path.scan(/\{(\w+)\}/).flatten.uniq
-      return operation if variables.empty?
-
       own_names = own.scan(/\{(\w+)\}/).flatten
+      supplied = Array(defaults) - own_names
+      return operation if variables.empty? && supplied.empty?
+
       fields = path_fields(rule, path.scan(/\{(\w+)\}/).flatten.zip(own_names).uniq(&:first))
       parameters = variables.map do |name|
         schema = fields[name] ? path_schema(fields[name]) : { "type" => "string" }
@@ -561,8 +735,8 @@ module Permittable
       # it; emission stays deterministic either way.
       operation.each_with_object({}) do |(key, value), out|
         if key == "requestBody"
-          out["parameters"] = parameters
-          value = body_without(rule, fields.values, own_names)
+          out["parameters"] = parameters unless parameters.empty?
+          value = body_without(rule, fields.values + default_fields(rule, supplied), own_names + supplied)
         end
         out[key] = value unless value.nil?
       end
@@ -590,6 +764,16 @@ module Permittable
       end.to_h
     end
 
+    # The rootless contract's fields for the names the route's `defaults:`
+    # fill. Unlike a path parameter's, any kind of field goes: the router
+    # overwrites the body's value whatever its shape, and no parameter has to
+    # carry it.
+    def default_fields(rule, names)
+      return [] if rule[:root]
+
+      rule[:fields].select { |f| names.include?(f[:name].to_s) }
+    end
+
     # A moved field's schema as the path parameter documents it. The URL
     # always supplies the segment, so a `default:` never applies and the
     # value is never null: `nullable:` would only add "null" to the type.
@@ -610,7 +794,8 @@ module Permittable
     # produces, so the schema must not forbid it. Each name the route
     # templates therefore stays in the body as an unconstrained property,
     # any value and never required, since the value is read from the URL and
-    # nothing in the body can make the request wrong. A rooted contract
+    # nothing in the body can make the request wrong. A name the route's
+    # `defaults:` fill is treated the same. A rooted contract
     # needs none of this: its wrapper object is permissive already.
     def body_without(rule, moved, templated)
       rest = rule[:fields] - moved
@@ -619,7 +804,7 @@ module Permittable
       body = rule_request_body(moved.empty? ? rule : rule.merge(fields: rest))
       return body unless rule[:unknown] == :error && !rule[:root]
 
-      properties = body["content"]["application/json"]["schema"]["properties"]
+      properties = body["content"].values.first["schema"]["properties"]
       templated.each { |name| properties[name] ||= {} }
       body
     end
@@ -806,6 +991,9 @@ module Permittable
         if engines && (mounted = mounted_routes(route)) && visiting.none? { |above| above.equal?(mounted) }
           found = collect_routes(mounted, engines: engines, prefixes: mount_prefixes(prefixes, route), parents: Array(id),
                                           visiting: visiting, reachable: reachable && unconditional?(route))
+          # What the mount fills reaches the engine's requests too.
+          mount_defaults = route_defaults(route)
+          found = found.map { |d| d.merge(defaults: (mount_defaults + Array(d[:defaults])).uniq) } unless mount_defaults.empty?
           verbs = route.verb.to_s.downcase.split("|")
           next verbs.empty? ? found : found.select { |descriptor| verbs.include?(descriptor[:verb]) }
         end
@@ -818,6 +1006,7 @@ module Permittable
         verb = ALL_VERBS if verb.empty?
 
         variants = optional_variants(route.path.spec, requirements, prefixes)
+        defaults = route_defaults(route)
         # Read once per route; drop_shadowed reads it, then strips it.
         unconditional = reachable && unconditional?(route)
         # One route can answer several verbs (`match via: [:patch, :put]`, and
@@ -829,12 +1018,25 @@ module Permittable
           variants.map do |path, shadows|
             descriptor = { controller: requirements[:controller], action: requirements[:action],
                            verb: single.downcase, path: path, route: id, unconditional: unconditional }
+            descriptor = descriptor.merge(defaults: defaults) unless defaults.empty?
             shadows.empty? ? descriptor : descriptor.merge(shadows: shadows)
           end
         end
       end
     end
 
+    # The names a route fills from its `defaults:` (`scope`, `resources` and
+    # `mount` take them too), as strings. The router puts them into
+    # path_parameters beside the URL's own, so the client cannot set them;
+    # `controller`, `action` and `format` are the router's own keys and
+    # are left out, as the runtime leaves them out of `unknown:`. A
+    # hand-built route that cannot say fills nothing.
+    def route_defaults(route)
+      return [] unless route.respond_to?(:defaults)
+
+      route.defaults.keys.map(&:to_s) - %w[controller action format]
+    end
+
     # The Prefix of each variant of a mount's path under each of `prefixes`,
     # outermost mount first, and within a mount present before absent, which
     # is the order Rails' regexp tries them in. A variant is shadowed by every