From 94050d7dde3e718b0613599838b4cbd9d517fbff Mon Sep 17 00:00:00 2001
From: Petrik <petrik@deheus.net>
Date: Mon, 21 Feb 2022 20:40:44 +0100
Subject: [PATCH] Move PermissionsPolicy docs to
 ActionDispatch::HTTP::PermissionsPolicy [ci-skip]

As most of the PermissionsPolicy is defined in
ActionDispatch::HTTP::PermissionsPolicy, it should include most of the
documentation. ActionController::Metal::PermissionsPolicy should
describe controller overrides.

This PR also makes the documentation more similar to the
ActionDispatch::HTTP::ContentSecurityPolicy documentation.

Note:
The Feature-Policy header has been renamed to Permissions-Policy
in the specification. The Permissions-Policy requires a different
implementation and isn't yet supported by all browsers. To avoid
having to rename this middleware in the future we use the new
name for the middleware but keep the old header name in the
documentation for now.

Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>
---
 .../metal/permissions_policy.rb               | 45 ++++++++-----------
 .../http/permissions_policy.rb                | 16 +++++++
 2 files changed, 34 insertions(+), 27 deletions(-)

diff --git a/actionpack/lib/action_controller/metal/permissions_policy.rb b/actionpack/lib/action_controller/metal/permissions_policy.rb
index dff1c065f5..bf2ede48bf 100644
--- a/actionpack/lib/action_controller/metal/permissions_policy.rb
+++ b/actionpack/lib/action_controller/metal/permissions_policy.rb
@@ -1,37 +1,28 @@
 # frozen_string_literal: true
 
 module ActionController # :nodoc:
-  # HTTP Permissions Policy is a web standard for defining a mechanism to
-  # allow and deny the use of browser permissions in its own context, and
-  # in content within any <iframe> elements in the document.
-  #
-  # Full details of HTTP Permissions Policy specification and guidelines can
-  # be found at MDN:
-  #
-  # https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy
-  #
-  # Examples of usage:
-  #
-  #   # Global policy
-  #   Rails.application.config.permissions_policy do |f|
-  #     f.camera      :none
-  #     f.gyroscope   :none
-  #     f.microphone  :none
-  #     f.usb         :none
-  #     f.fullscreen  :self
-  #     f.payment     :self, "https://secure.example.com"
-  #   end
-  #
-  #   # Controller level policy
-  #   class PagesController < ApplicationController
-  #     permissions_policy do |p|
-  #       p.geolocation "https://example.com"
-  #     end
-  #   end
   module PermissionsPolicy
     extend ActiveSupport::Concern
 
     module ClassMethods
+      # Overrides parts of the globally configured Feature-Policy
+      # header:
+      #
+      #   class PagesController < ApplicationController
+      #     permissions_policy do |policy|
+      #       policy.geolocation "https://example.com"
+      #     end
+      #   end
+      #
+      # Options can be passed similar to +before_action+. For example, pass
+      # <tt>only: :index</tt> to override the header on the index action only:
+      #
+      #   class PagesController < ApplicationController
+      #     permissions_policy(only: :index) do |policy|
+      #       policy.camera :self
+      #     end
+      #   end
+      #
       def permissions_policy(**options, &block)
         before_action(options) do
           if block_given?
diff --git a/actionpack/lib/action_dispatch/http/permissions_policy.rb b/actionpack/lib/action_dispatch/http/permissions_policy.rb
index 69fcef84db..5666ad0acb 100644
--- a/actionpack/lib/action_dispatch/http/permissions_policy.rb
+++ b/actionpack/lib/action_dispatch/http/permissions_policy.rb
@@ -3,6 +3,22 @@
 require "active_support/core_ext/object/deep_dup"
 
 module ActionDispatch # :nodoc:
+  # Configures the HTTP
+  # {Feature-Policy}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy]
+  # response header to specify which browser features the current document and
+  # its iframes can use.
+  #
+  # Example global policy:
+  #
+  #   Rails.application.config.permissions_policy do |policy|
+  #     policy.camera      :none
+  #     policy.gyroscope   :none
+  #     policy.microphone  :none
+  #     policy.usb         :none
+  #     policy.fullscreen  :self
+  #     policy.payment     :self, "https://secure.example.com"
+  #   end
+  #
   class PermissionsPolicy
     class Middleware
       CONTENT_TYPE = "Content-Type"