permittable 0.13.0 → 0.14.0

data/lib/permittable/open_api.rb

@@ -91,6 +91,54 @@ module Permittable
       @concern_methods ||= Permittable.public_instance_methods(false).map(&:to_s).freeze
     end
 
+    # Gems whose public methods are the framework's own: the ones a controller
+    # gets from the modules Rails mixes in (Rendering, Head, Callbacks, ViewPaths,
+    # Rescuable, ...) and from the class attributes those define on it.
+    FRAMEWORK_GEMS = %w[actionpack actionview activesupport activemodel railties].freeze
+
+    # Rails reads a controller's internal methods off its nearest abstract
+    # class: ActionController::Base includes all of those modules, so they are
+    # internal on a Base or API controller, but ActionController::Metal includes
+    # none, so on one built directly on it every public method of an included
+    # module is an action_methods entry. A method is the framework's when it
+    # is defined in one of its gems, by whichever module or class_attribute
+    # put it on the controller; a method the app defines, in the class or in a
+    # concern of its own, stays an action. So does one a superclass declares in
+    # its own file, even a framework controller's (Rails::HealthController#show):
+    # a method defined elsewhere in a gem, such as the class_attribute readers
+    # an app's parent class gets from the modules it includes, is not one.
+    def framework_method?(controller, action)
+      return false unless controller.respond_to?(:instance_method)
+
+      method = controller.instance_method(action)
+      file = method.source_location&.first
+      return false if file.nil? || framework_roots.none? { |root| file.start_with?(root) }
+
+      !declared_by_superclass?(method, controller, file)
+    rescue NameError
+      false
+    end
+
+    # Whether `method` is written in the file that defines its owner, a class
+    # other than the controller itself. An anonymous owner has no such file.
+    def declared_by_superclass?(method, controller, file)
+      owner = method.owner
+      owner.is_a?(Class) && owner != controller && !owner.name.nil? &&
+        Object.const_source_location(owner.name)&.first == file
+    end
+
+    # Resolved lazily, like concern_methods: the gems load after this file.
+    # Real paths, which is what source_location reports: a gem's own path is
+    # only expanded, so one reached through a symlink would never match.
+    def framework_roots
+      @framework_roots ||= FRAMEWORK_GEMS.filter_map do |name|
+        path = Gem.loaded_specs[name]&.full_gem_path or next
+        File.join(File.realpath(path), "")
+      rescue SystemCallError
+        File.join(path, "")
+      end.freeze
+    end
+
     # Shared `components` for any document referencing Permittable responses.
     #
     # Unlike a rule's monitor mode — which the exporter reads only from the
@@ -153,12 +201,158 @@ 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"
       {
         "required" => !!(rule[:root] || rule[:fields].any? { |f| f[:required] }),
-        "content" => { "application/json" => { "schema" => JsonSchema.rule(rule) } }
+        "content" => { media_type => { "schema" => schema } }
       }
     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.
@@ -176,7 +370,8 @@ module Permittable
       return explicit unless contracts.any? { |rule| rule[:actions].empty? }
       return explicit + ["*"] unless controller.respond_to?(:action_methods)
 
-      explicit + (controller.action_methods.map(&:to_s).sort - explicit - concern_methods)
+      actions = controller.action_methods.map(&:to_s).sort - explicit - concern_methods
+      explicit + actions.reject { |action| framework_method?(controller, action) }
     end
 
     def operation_for(controller, action)
@@ -270,7 +465,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
 
@@ -371,9 +571,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
@@ -495,14 +695,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" }
@@ -512,8 +720,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
@@ -541,6 +749,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.
@@ -561,7 +779,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
@@ -570,7 +789,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
@@ -757,6 +976,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
@@ -769,6 +991,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
@@ -780,12 +1003,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

data/lib/permittable/rspec.rb

@@ -453,7 +453,11 @@ module Permittable
           # proc cannot rewrite the spec's own literal (the same reason
           # validate_authored_value! copies before normalizing).
           own = expected.is_a?(String) ? expected.dup : expected
-          status, value = Coercion.cast(field[:type], Coercion.apply_normalize(field[:normalize], own))
+          normalized = Coercion.apply_normalize(field[:normalize], own)
+          # Absent on a nullable field is the nil a contract stores for it.
+          return nil if field[:nullable] && Coercion.absent_value?(normalized)
+
+          status, value = Coercion.cast(field[:type], normalized)
           status == :ok ? value : expected
         when :array
           return expected unless expected.is_a?(Array)
@@ -749,7 +753,7 @@ module Permittable
         mirror_csrf_key(host)
         host.permittable_contracts = [rule.merge(mode: :enforce).freeze]
         instance = host.new
-        instance.params = @params
+        instance.params = request_params
         violations = instance.permittable_violations(action)
         result = violations.empty? ? instance.permitted_params(action) : nil
         [violations, result]
@@ -772,6 +776,52 @@ module Permittable
         host.define_method(:permittable_action_name) { action }
       end
 
+      # What a controller reads as `params`: the payload after the
+      # normalization every request goes through, ActionDispatch's Utils.
+      # Under the default perform_deep_munge it removes nil
+      # from every array, so a JSON `{"tags": ["a", null]}` reaches the
+      # contract as ["a"], and `length:` never counts the null. Handing the
+      # raw payload over made reject_params(tags: ["a", nil]) pass for a
+      # request that is a 200. An app that turned perform_deep_munge off
+      # still sees the null, because the setting is read, not assumed.
+      # A copy goes in: the normalizer rewrites arrays in place, and the
+      # payload belongs to the spec. The copy stringifies Symbol keys, which
+      # the normalizer's HashWithIndifferentAccess does anyway but only after
+      # it has read a Symbol :tempfile key as an upload, a key a request
+      # (String keys only) never has. A Parameters payload is unwrapped first
+      # so it is normalized like the Hash it wraps.
+      def request_params
+        utils = request_utils
+        return @params unless utils
+
+        payload = @params.respond_to?(:to_unsafe_h) ? @params.to_unsafe_h : @params
+        utils.normalize_encode_params(copy_payload(payload))
+      end
+
+      # Rails main moved the class from ActionDispatch::Request::Utils to
+      # ActionDispatch::Http::Utils. nil only when ActionDispatch is not
+      # loaded at all (a non-Rails stand-in controller); once it is, a rename
+      # this does not know raises instead of silently skipping the
+      # normalization, which would bring the false greens back.
+      def request_utils
+        return unless defined?(ActionDispatch)
+
+        if defined?(ActionDispatch::Http::Utils) then ActionDispatch::Http::Utils
+        elsif defined?(ActionDispatch::Request::Utils) then ActionDispatch::Request::Utils
+        else
+          raise "Permittable's matchers cannot find Rails' parameter normalizer: neither " \
+                "ActionDispatch::Http::Utils nor ActionDispatch::Request::Utils is defined"
+        end
+      end
+
+      def copy_payload(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.is_a?(Symbol) ? key.to_s : key, copy_payload(item)] }
+        when Array then value.map { |item| copy_payload(item) }
+        else value
+        end
+      end
+
       def run_contract
         result = @subject.call(@params)
         [result.violations, result.params]

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.13.0".freeze
+  VERSION = "0.14.0".freeze
 end