permittable 0.7.0 → 0.9.0

data/lib/permittable/open_api.rb

@@ -11,11 +11,38 @@ module Permittable
   # Everything the exporter cannot know is left visible rather than guessed:
   # actions covered only by a catch-all rule on a host without
   # `action_methods` appear under the "*" key with `x-permittable-catch-all`,
-  # and operations with no matching route land in `x-permittable-controllers`
-  # instead of being dropped silently.
+  # and operations with no matching route — or whose path+verb slot another
+  # controller already claimed, which a document cannot represent twice —
+  # land in `x-permittable-controllers` instead of being dropped silently.
   module OpenAPI
     module_function
 
+    # One violation, in whichever shape the app renders — the same
+    # { param:, code: } entry rides in the envelope's `details` and the
+    # problem document's `errors`.
+    VIOLATION_SCHEMA = {
+      "type" => "object",
+      "properties" => {
+        "param" => {
+          "type" => "string",
+          "description" => "Fully-qualified parameter path, e.g. user.address.zip or line_items[1].sku"
+        },
+        "code" => {
+          "type" => "string",
+          "description" => "missing / invalid_type / inclusion / format / length / depth / unknown / " \
+                           "invalid, or a contract-specific symbol"
+        },
+        # Present only when the field declares `message:` or the app has
+        # I18n copy for the code; a violation without one keeps the bare
+        # { param:, code: } shape, so this is not required.
+        "message" => {
+          "type" => "string",
+          "description" => "Human-readable copy for this violation, when the contract or I18n supplies it"
+        }
+      },
+      "required" => %w[param code]
+    }.freeze
+
     # The error envelope rendered by render_invalid_parameters (see
     # ErrorEnvelope): code/details are present on every violation this gem
     # raises, message always.
@@ -28,24 +55,7 @@ module Permittable
           "properties" => {
             "message" => { "type" => "string" },
             "code" => { "type" => "string", "enum" => ["invalid_parameters"] },
-            "details" => {
-              "type" => "array",
-              "items" => {
-                "type" => "object",
-                "properties" => {
-                  "param" => {
-                    "type" => "string",
-                    "description" => "Fully-qualified parameter path, e.g. user.address.zip or line_items[1].sku"
-                  },
-                  "code" => {
-                    "type" => "string",
-                    "description" => "missing / invalid_type / inclusion / format / length / unknown / invalid, " \
-                                     "or a contract-specific symbol"
-                  }
-                },
-                "required" => %w[param code]
-              }
-            }
+            "details" => { "type" => "array", "items" => VIOLATION_SCHEMA }
           },
           "required" => %w[message]
         }
@@ -53,6 +63,25 @@ module Permittable
       "required" => %w[success error]
     }.freeze
 
+    # RFC 9457 Problem Details, the shape rendered when
+    # `Permittable.error_format = :problem`. `type` and `instance` are
+    # URI-references; `errors` is the field-violation extension member.
+    PROBLEM_SCHEMA = {
+      "type" => "object",
+      "properties" => {
+        "type" => {
+          "type" => "string", "format" => "uri-reference",
+          "description" => "Problem type URI — \"about:blank\" unless the app sets Permittable.problem_base_uri"
+        },
+        "title" => { "type" => "string", "enum" => ["Invalid parameters", "Malformed request"] },
+        "status" => { "type" => "integer", "enum" => [400, 422] },
+        "detail" => { "type" => "string" },
+        "instance" => { "type" => "string", "format" => "uri-reference" },
+        "errors" => { "type" => "array", "items" => VIOLATION_SCHEMA }
+      },
+      "required" => %w[title status]
+    }.freeze
+
     # Instance methods the concern itself adds to every including controller;
     # action_methods reports them as actions (they are public by design), but
     # they are never routed and must not be documented as endpoints. Resolved
@@ -62,9 +91,15 @@ module Permittable
     end
 
     # Shared `components` for any document referencing Permittable responses.
+    #
+    # Unlike a rule's monitor mode — which the exporter reads only from the
+    # contract, never from runtime configuration — the error FORMAT has no
+    # per-contract declaration to read: it is one app-wide setting, and an
+    # export runs inside the app that made it. Reading it is what keeps the
+    # documented response shape from drifting from the rendered one.
     def components
       {
-        "schemas" => { "PermittableInvalidParameters" => ERROR_SCHEMA },
+        "schemas" => { "PermittableInvalidParameters" => error_schema },
         "responses" => {
           "PermittableBadRequest" => error_response(
             "The root: key is missing or not an object — the request envelope itself is malformed."
@@ -76,11 +111,23 @@ module Permittable
       }
     end
 
+    def problem_format?
+      Permittable.error_format == :problem
+    end
+
+    def error_schema
+      problem_format? ? PROBLEM_SCHEMA : ERROR_SCHEMA
+    end
+
+    def error_media_type
+      problem_format? ? ErrorEnvelope::PROBLEM_MEDIA_TYPE : "application/json"
+    end
+
     def error_response(description)
       {
         "description" => description,
         "content" => {
-          "application/json" => {
+          error_media_type => {
             "schema" => { "$ref" => "#/components/schemas/PermittableInvalidParameters" }
           }
         }
@@ -157,12 +204,17 @@ module Permittable
     def document(controllers:, info: {}, routes: nil)
       paths = {}
       unrouted = {}
-      controllers.each do |controller|
+      slots = []
+      targets = route_targets(routes)
+      # A class listed twice would find every slot its first pass claimed and
+      # land under x-permittable-controllers, colliding with itself there.
+      controllers.uniq(&:object_id).each do |controller|
         operations = operations_for(controller)
         next if operations.empty?
 
-        place_operations(controller, operations, routes, paths, unrouted)
+        slots.concat(place_operations(controller, operations, targets, paths, unrouted))
       end
+      assign_unique_operation_ids(slots)
       doc = {
         "openapi" => "3.1.0",
         "info" => { "title" => "Permittable contracts", "version" => VERSION }.merge(info),
@@ -173,38 +225,226 @@ module Permittable
       doc
     end
 
-    def place_operations(controller, operations, routes, paths, unrouted)
+    # Where one operation sits in the document: a path+verb slot under
+    # `paths`, or an action under x-permittable-controllers (verb nil).
+    # `holder[field]` is the placed operation; `id` its natural operationId;
+    # `owner` the [controller key, action] it documents.
+    OperationSlot = Struct.new(:holder, :field, :verb, :id, :owner)
+
+    # { [controller, action] => [[path, verb], ...] }, in route order. Built
+    # once, with each verb normalised once: matching every operation against
+    # every route made placement quadratic in the size of the route set. A
+    # route declared twice names one slot, so it is kept once — not counted
+    # as an operation colliding with itself.
+    def route_targets(routes)
+      return {} if routes.nil?
+
+      routes.group_by { |route| [route[:controller].to_s, route[:action].to_s] }
+            .transform_values { |matching| matching.map { |route| [route[:path], verb_of(route)] }.uniq }
+    end
+
+    # Places every operation and returns the slots it filled, in placement
+    # order (controller, action, route), for assign_unique_operation_ids.
+    def place_operations(controller, operations, targets, paths, unrouted)
       key = controller_key(controller) || controller.inspect
-      operations.each do |action, operation|
-        matched = routes_for(routes, key, action)
-        if matched.empty?
-          (unrouted[key] ||= {})[action] = operation
+      operations.each_with_object([]) do |(action, operation), slots|
+        owner = [key, action]
+        # A path+verb pair carries exactly one operation, so a slot another
+        # controller already claimed is not written over: the loser stays
+        # visible under x-permittable-controllers, where an operation with no
+        # route at all lands, rather than disappearing from the document.
+        free = action == "*" ? [] : targets.fetch(owner, []).reject { |path, verb| paths.dig(path, verb) }
+        if free.empty?
+          holder = (unrouted[key] ||= {})
+          slots << OperationSlot.new(holder, action, nil, operation["operationId"], owner) unless holder.key?(action)
+          holder[action] = operation
         else
-          matched.each { |route| (paths[route[:path]] ||= {})[route[:verb].to_s.downcase] = operation }
+          free.each do |path, verb|
+            holder = (paths[path] ||= {})
+            holder[verb] = with_path_parameters(operation, path)
+            slots << OperationSlot.new(holder, verb, verb, operation["operationId"], owner)
+          end
         end
       end
     end
 
-    def routes_for(routes, controller_key, action)
-      return [] if routes.nil? || action == "*"
+    # OpenAPI requires operationId to be unique across the document, and
+    # client generators name a method after it — a duplicate is an invalid
+    # document and, in practice, two methods with one name. One operation is
+    # placed at every slot its routes reach: the separate PATCH and PUT
+    # routes `resources` draws to update, or one `via: [:patch, :put]` route;
+    # with the optional-segment expansion, one route's several paths; with
+    # `via: :all` routes, which are documented under each verb, five verbs.
+    # And `key.tr("/", "_")` folds admin/users and admin_users into one id.
+    #
+    # Renaming the scheme would rename every generated client method, so an
+    # id that is already unique never changes. Every slot's natural id is
+    # known before any is renamed and all of them are reserved, so a suffix
+    # can never take a name that is another operation's own id — that
+    # operation would otherwise be renamed for a collision it never had.
+    # Within a colliding group the first slot keeps the plain id. Another
+    # takes its verb (users_update_put) when that verb differs from the plain
+    # id's and the suffixed id is free; otherwise it is numbered
+    # (posts_create_2 for a second POST, users_update_2 for a second PATCH).
+    # The suffix names how the slot differs from the plain one, so a verb
+    # the two share would say nothing true.
+    #
+    # Unrouted operations take part: x-permittable-controllers is in the same
+    # document and feeds the same generators. They yield the plain id to a
+    # routed operation, though, since `paths` is what a client calls.
+    def assign_unique_operation_ids(slots)
+      slots = slots.select(&:id)
+      taken = slots.to_set(&:id)
+      next_number = Hash.new(2)
+      slots.group_by(&:id).each_value do |group|
+        next if group.one?
 
-      routes.select { |r| r[:controller].to_s == controller_key && r[:action].to_s == action }
+        plain, *renamed = collision_order(group)
+        renamed.each do |slot|
+          by_verb = "#{slot.id}_#{slot.verb}"
+          by_verb = nil if slot.verb.nil? || slot.verb == plain.verb || taken.include?(by_verb)
+          unique = by_verb || numbered_id(slot.id, taken, next_number)
+          taken << unique
+          # The same operation object may sit at other slots under its own
+          # id, so the rename goes on a copy; merge keeps the key order.
+          slot.holder[slot.field] = slot.holder[slot.field].merge("operationId" => unique)
+        end
+      end
     end
 
+    # Routed before unrouted, then placement order: controller, action, route.
+    # Within one operation a PUT sorts after its PATCH, because
+    # `match via: [:put, :patch]` lists PUT first where `resources` lists
+    # PATCH first, and without this one pair of routes would name the PATCH
+    # method two ways. Across operations the order alone decides: a PATCH in
+    # a later controller does not take the plain id from an earlier PUT.
+    def collision_order(group)
+      patched = group.select { |slot| slot.verb == "patch" }.to_set(&:owner)
+      first_at = {}
+      group.each_with_index { |slot, index| first_at[slot.owner] ||= index }
+      group.each_with_index.sort_by do |slot, index|
+        put_after_patch = slot.verb == "put" && patched.include?(slot.owner) ? 1 : 0
+        [slot.verb ? 0 : 1, first_at[slot.owner], put_after_patch, index]
+      end.map(&:first)
+    end
+
+    # The next free "#{id}_n", n from 2. The counter per id means no number
+    # is tried twice for one id, which keeps the pass linear.
+    def numbered_id(id, taken, next_number)
+      number = next_number[id]
+      number += 1 while taken.include?("#{id}_#{number}")
+      next_number[id] = number + 1
+      "#{id}_#{number}"
+    end
+
+    def verb_of(route)
+      route[:verb].to_s.downcase
+    end
+
+    # OpenAPI 3.1 requires every variable in a path template to be declared as
+    # a path parameter — a document templating {id} without declaring it is
+    # invalid, which every member route produced. The route set does not say
+    # what an :id is and the exporter does not guess: a path segment arrives as
+    # a string, so that is what it is documented as.
+    def with_path_parameters(operation, path)
+      variables = path.scan(/\{(\w+)\}/).flatten
+      return operation if variables.empty?
+
+      parameters = variables.map do |name|
+        { "name" => name, "in" => "path", "required" => true, "schema" => { "type" => "string" } }
+      end
+      # Inserted ahead of requestBody, where a reader of the document expects
+      # it; emission stays deterministic either way.
+      operation.each_with_object({}) do |(key, value), out|
+        out["parameters"] = parameters if key == "requestBody"
+        out[key] = value
+      end
+    end
+
+    # What a `via: :all` route answers, in the "|"-joined form Journey uses
+    # for a route with several verbs.
+    ALL_VERBS = "GET|POST|PUT|PATCH|DELETE".freeze
+
     # { controller:, action:, verb:, path: } descriptors from a Rails
     # application's route set. Duck-typed against Journey routes (each one
     # responds to requirements / verb / path.spec) so it stays unit-testable
-    # without Rails; Rails path params (:id) become OpenAPI templates ({id}).
+    # without Rails; Rails path params become OpenAPI templates — both the
+    # `:id` form and the `*rest` wildcard, which is a real route shape
+    # (`get "files/*path"`) and is not a valid OpenAPI template left as-is.
+    #
+    # An optional group is expanded into the concrete paths it stands for:
+    # parentheses are not valid in an OpenAPI path template, so leaving
+    # `scope "(:locale)"` as `(/{locale})/posts` made the whole document fail
+    # validation. Each variant is its own descriptor, so each path's variables
+    # are required there — which, for that path, they are.
+    #
+    # Each descriptor also carries `route:`, the index of the route it came
+    # from, so a reader counting routes rather than paths (Audit.summary) can
+    # tell one route's expanded variants from a second route that happens to
+    # reach the same action. The exporter ignores it.
     def rails_routes(app)
-      app.routes.routes.filter_map do |route|
+      descriptors = app.routes.routes.each_with_index.flat_map do |route, index|
         requirements = route.requirements
         verb = route.verb.to_s
-        next if requirements[:controller].nil? || requirements[:action].nil? || verb.empty?
+        next [] if requirements[:controller].nil? || requirements[:action].nil?
+
+        # `match ..., via: :all` leaves the verb EMPTY rather than listing
+        # them, and skipping it hid an action that takes POST bodies from the
+        # audit entirely. Expand it into the verbs it actually answers.
+        verb = ALL_VERBS if verb.empty?
 
-        path = route.path.spec.to_s.sub("(.:format)", "").gsub(/:(\w+)/) { "{#{Regexp.last_match(1)}}" }
-        { controller: requirements[:controller], action: requirements[:action],
-          verb: verb.split("|").first.downcase, path: path }
+        path = route.path.spec.to_s.sub("(.:format)", "").gsub(/[:*](\w+)/) { "{#{Regexp.last_match(1)}}" }
+        # One route can answer several verbs (`match via: [:patch, :put]`, and
+        # the PATCH|PUT pair resources generates); documenting only the first
+        # dropped the others from the export entirely.
+        verb.split("|").map do |single|
+          { controller: requirements[:controller], action: requirements[:action],
+            verb: single.downcase, path: path, route: index }
+        end
+      end
+      descriptors.flat_map do |descriptor|
+        optional_variants(descriptor[:path]).map { |variant| descriptor.merge(path: variant) }
+      end
+    end
+
+    # Every concrete path an optionally-grouped template stands for:
+    # `/archive(/{year}(/{month}))` → `/archive`, `/archive/{year}`,
+    # `/archive/{year}/{month}`. Rails fills groups left to right, so
+    # `/x(/{a})(/{b})` with one segment present is always `/x/{a}` — the
+    # `/x/{b}` variant is the same URL under another name, and OpenAPI forbids
+    # two templates differing only in variable names. Variants are built with
+    # each group present first, so the one Rails would match is the one kept;
+    # the list is then reversed, which puts every group's ABSENT variant
+    # first at every nesting level. That order matters to the operationId
+    # dedupe (assign_unique_operation_ids, which numbers colliding ids in
+    # route order): the variants of one route share an operation, and it is
+    # that dedupe, not this expansion, that makes their ids unique. Absent
+    # first means `/posts` keeps `posts_create` and `/{locale}/posts` takes
+    # the suffix.
+    def optional_variants(path)
+      variants, = expand_optional_groups(path, 0)
+      variants.map { |variant| variant.empty? ? "/" : variant }
+              .uniq { |variant| variant.gsub(/\{\w+\}/, "{}") }
+              .reverse
+    end
+
+    # Walks the template from `pos` to the matching `)` (or the end),
+    # returning the variants of that stretch and the position after it.
+    def expand_optional_groups(path, pos)
+      variants = [+""]
+      while pos < path.length
+        char = path[pos]
+        if char == "("
+          inner, pos = expand_optional_groups(path, pos + 1)
+          variants = variants.product(inner + [""]).map(&:join)
+        elsif char == ")"
+          return [variants, pos + 1]
+        else
+          variants.each { |variant| variant << char }
+          pos += 1
+        end
       end
+      [variants, pos]
     end
 
     def controller_key(controller)

data/lib/permittable/railtie.rb

@@ -32,6 +32,7 @@ module Permittable
     rake_tasks do
       load File.expand_path("tasks/openapi.rake", __dir__)
       load File.expand_path("tasks/generate.rake", __dir__)
+      load File.expand_path("tasks/audit.rake", __dir__)
     end
   end
 end