diff --git a/CHANGELOG b/CHANGELOG index 2c0f29c9..5bbfb5ac 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,4 +1,4 @@ -= master += 3.78.0 (2024-03-13) * Add permissions_policy plugin for setting Permissions-Policy header (jeremyevans) diff --git a/doc/release_notes/3.78.0.txt b/doc/release_notes/3.78.0.txt new file mode 100644 index 00000000..49e4e1a3 --- /dev/null +++ b/doc/release_notes/3.78.0.txt @@ -0,0 +1,99 @@ += New Features + +* A permissions_policy plugin has been added that allows you to easily set a + Permissions-Policy header for the application, which browsers can use to + determine whether to allow specific functionality on the returned page + (mainly related to which JavaScript APIs the page is allowed to use). + + You would generally call the plugin with a block to set the default policy: + + plugin :permissions_policy do |pp| + pp.camera :none + pp.fullscreen :self + pp.clipboard_read :self, 'https://example.com' + end + + Then, anywhere in the routing tree, you can customize the policy for just that + branch or action using the same block syntax: + + r.get 'foo' do + permissions_policy do |pp| + pp.camera :self + end + # ... + end + + In addition to using a block, you can also call methods on the object returned + by the method: + + r.get 'foo' do + permissions_policy.camera :self + # ... + end + + You can use the :default plugin option to set the default for all settings. + For example, to disallow all access for each setting by default: + + plugin :permissions_policy, default: :none + + The following methods are available for configuring the permissions policy, + which specify the setting (substituting _ with -): + + * accelerometer + * ambient_light_sensor + * autoplay + * bluetooth + * camera + * clipboard_read + * clipboard_write + * display_capture + * encrypted_media + * fullscreen + * geolocation + * gyroscope + * hid + * idle_detection + * keyboard_map + * magnetometer + * microphone + * midi + * payment + * picture_in_picture + * publickey_credentials_get + * screen_wake_lock + * serial + * sync_xhr + * usb + * web_share + * window_management + + All of these methods support any number of arguments, and each argument should + be one of the following values: + + :all :: Grants permission to all domains (must be only argument) + :none :: Does not allow permission at all (must be only argument) + :self :: Allows feature in current document and any nested browsing contexts + that use the same domain as the current document. + :src :: Allows feature in current document and any nested browsing contexts + that use the same domain as the src of the iframe. + String :: Specifies origin domain where access is allowed + + When calling a method with no arguments, the setting is removed from the policy instead + of being left empty, since all of these setting require at least one value. Likewise, + if the policy does not have any settings, the header will not be added. + + Calling the method overrides any previous setting. Each of the methods has +add_*+ and + +get_*+ methods defined. The +add_*+ method appends to any existing setting, and the +get_*+ method + returns the current value for the setting (this will be +:all+ if all domains are allowed, or + any array of strings/:self/:src). + + permissions_policy.fullscreen :self, 'https://example.com' + # fullscreen (self "https://example.com") + + permissions_policy.add_fullscreen 'https://*.example.com' + # fullscreen (self "https://example.com" "https://*.example.com") + + permissions_policy.get_fullscreen + # => [:self, "https://example.com", "https://*.example.com"] + + The clear method can be used to remove all settings from the policy. diff --git a/lib/roda/version.rb b/lib/roda/version.rb index da0aa227..deae6881 100644 --- a/lib/roda/version.rb +++ b/lib/roda/version.rb @@ -4,7 +4,7 @@ class Roda RodaMajorVersion = 3 # The minor version of Roda, updated for new feature releases of Roda. - RodaMinorVersion = 77 + RodaMinorVersion = 78 # The patch version of Roda, updated only for bug fixes from the last # feature release.