omg-actionpack 8.0.0.alpha1

data/lib/action_controller/metal/conditional_get.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+require "active_support/core_ext/object/try"
+require "active_support/core_ext/integer/time"
+
+module ActionController
+  module ConditionalGet
+    extend ActiveSupport::Concern
+
+    include Head
+
+    included do
+      class_attribute :etaggers, default: []
+    end
+
+    module ClassMethods
+      # Allows you to consider additional controller-wide information when generating
+      # an ETag. For example, if you serve pages tailored depending on who's logged in
+      # at the moment, you may want to add the current user id to be part of the ETag
+      # to prevent unauthorized displaying of cached pages.
+      #
+      #     class InvoicesController < ApplicationController
+      #       etag { current_user&.id }
+      #
+      #       def show
+      #         # Etag will differ even for the same invoice when it's viewed by a different current_user
+      #         @invoice = Invoice.find(params[:id])
+      #         fresh_when etag: @invoice
+      #       end
+      #     end
+      def etag(&etagger)
+        self.etaggers += [etagger]
+      end
+    end
+
+    # Sets the `etag`, `last_modified`, or both on the response, and renders a `304
+    # Not Modified` response if the request is already fresh.
+    #
+    # #### Options
+    #
+    # `:etag`
+    # :   Sets a "weak" ETag validator on the response. See the `:weak_etag` option.
+    #
+    # `:weak_etag`
+    # :   Sets a "weak" ETag validator on the response. Requests that specify an
+    #     `If-None-Match` header may receive a `304 Not Modified` response if the
+    #     ETag matches exactly.
+    #
+    # :   A weak ETag indicates semantic equivalence, not byte-for-byte equality, so
+    #     they're good for caching HTML pages in browser caches. They can't be used
+    #     for responses that must be byte-identical, like serving `Range` requests
+    #     within a PDF file.
+    #
+    # `:strong_etag`
+    # :   Sets a "strong" ETag validator on the response. Requests that specify an
+    #     `If-None-Match` header may receive a `304 Not Modified` response if the
+    #     ETag matches exactly.
+    #
+    # :   A strong ETag implies exact equality -- the response must match byte for
+    #     byte. This is necessary for serving `Range` requests within a large video
+    #     or PDF file, for example, or for compatibility with some CDNs that don't
+    #     support weak ETags.
+    #
+    # `:last_modified`
+    # :   Sets a "weak" last-update validator on the response. Subsequent requests
+    #     that specify an `If-Modified-Since` header may receive a `304 Not
+    #     Modified` response if `last_modified` <= `If-Modified-Since`.
+    #
+    # `:public`
+    # :   By default the `Cache-Control` header is private. Set this option to
+    #     `true` if you want your application to be cacheable by other devices, such
+    #     as proxy caches.
+    #
+    # `:cache_control`
+    # :   When given, will overwrite an existing `Cache-Control` header. For a list
+    #     of `Cache-Control` directives, see the [article on
+    #     MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Contr
+    #     ol).
+    #
+    # `:template`
+    # :   By default, the template digest for the current controller/action is
+    #     included in ETags. If the action renders a different template, you can
+    #     include its digest instead. If the action doesn't render a template at
+    #     all, you can pass `template: false` to skip any attempt to check for a
+    #     template digest.
+    #
+    #
+    # #### Examples
+    #
+    #     def show
+    #       @article = Article.find(params[:id])
+    #       fresh_when(etag: @article, last_modified: @article.updated_at, public: true)
+    #     end
+    #
+    # This will send a `304 Not Modified` response if the request specifies a
+    # matching ETag and `If-Modified-Since` header. Otherwise, it will render the
+    # `show` template.
+    #
+    # You can also just pass a record:
+    #
+    #     def show
+    #       @article = Article.find(params[:id])
+    #       fresh_when(@article)
+    #     end
+    #
+    # `etag` will be set to the record, and `last_modified` will be set to the
+    # record's `updated_at`.
+    #
+    # You can also pass an object that responds to `maximum`, such as a collection
+    # of records:
+    #
+    #     def index
+    #       @articles = Article.all
+    #       fresh_when(@articles)
+    #     end
+    #
+    # In this case, `etag` will be set to the collection, and `last_modified` will
+    # be set to `maximum(:updated_at)` (the timestamp of the most recently updated
+    # record).
+    #
+    # When passing a record or a collection, you can still specify other options,
+    # such as `:public` and `:cache_control`:
+    #
+    #     def show
+    #       @article = Article.find(params[:id])
+    #       fresh_when(@article, public: true, cache_control: { no_cache: true })
+    #     end
+    #
+    # The above will set `Cache-Control: public, no-cache` in the response.
+    #
+    # When rendering a different template than the controller/action's default
+    # template, you can indicate which digest to include in the ETag:
+    #
+    #     before_action { fresh_when @article, template: "widgets/show" }
+    #
+    def fresh_when(object = nil, etag: nil, weak_etag: nil, strong_etag: nil, last_modified: nil, public: false, cache_control: {}, template: nil)
+      response.cache_control.delete(:no_store)
+      weak_etag ||= etag || object unless strong_etag
+      last_modified ||= object.try(:updated_at) || object.try(:maximum, :updated_at)
+
+      if strong_etag
+        response.strong_etag = combine_etags strong_etag,
+          last_modified: last_modified, public: public, template: template
+      elsif weak_etag || template
+        response.weak_etag = combine_etags weak_etag,
+          last_modified: last_modified, public: public, template: template
+      end
+
+      response.last_modified = last_modified if last_modified
+      response.cache_control[:public] = true if public
+      response.cache_control.merge!(cache_control)
+
+      head :not_modified if request.fresh?(response)
+    end
+
+    # Sets the `etag` and/or `last_modified` on the response and checks them against
+    # the request. If the request doesn't match the provided options, it is
+    # considered stale, and the response should be rendered from scratch. Otherwise,
+    # it is fresh, and a `304 Not Modified` is sent.
+    #
+    # #### Options
+    #
+    # See #fresh_when for supported options.
+    #
+    # #### Examples
+    #
+    #     def show
+    #       @article = Article.find(params[:id])
+    #
+    #       if stale?(etag: @article, last_modified: @article.updated_at)
+    #         @statistics = @article.really_expensive_call
+    #         respond_to do |format|
+    #           # all the supported formats
+    #         end
+    #       end
+    #     end
+    #
+    # You can also just pass a record:
+    #
+    #     def show
+    #       @article = Article.find(params[:id])
+    #
+    #       if stale?(@article)
+    #         @statistics = @article.really_expensive_call
+    #         respond_to do |format|
+    #           # all the supported formats
+    #         end
+    #       end
+    #     end
+    #
+    # `etag` will be set to the record, and `last_modified` will be set to the
+    # record's `updated_at`.
+    #
+    # You can also pass an object that responds to `maximum`, such as a collection
+    # of records:
+    #
+    #     def index
+    #       @articles = Article.all
+    #
+    #       if stale?(@articles)
+    #         @statistics = @articles.really_expensive_call
+    #         respond_to do |format|
+    #           # all the supported formats
+    #         end
+    #       end
+    #     end
+    #
+    # In this case, `etag` will be set to the collection, and `last_modified` will
+    # be set to `maximum(:updated_at)` (the timestamp of the most recently updated
+    # record).
+    #
+    # When passing a record or a collection, you can still specify other options,
+    # such as `:public` and `:cache_control`:
+    #
+    #     def show
+    #       @article = Article.find(params[:id])
+    #
+    #       if stale?(@article, public: true, cache_control: { no_cache: true })
+    #         @statistics = @articles.really_expensive_call
+    #         respond_to do |format|
+    #           # all the supported formats
+    #         end
+    #       end
+    #     end
+    #
+    # The above will set `Cache-Control: public, no-cache` in the response.
+    #
+    # When rendering a different template than the controller/action's default
+    # template, you can indicate which digest to include in the ETag:
+    #
+    #     def show
+    #       super if stale?(@article, template: "widgets/show")
+    #     end
+    #
+    def stale?(object = nil, **freshness_kwargs)
+      fresh_when(object, **freshness_kwargs)
+      !request.fresh?(response)
+    end
+
+    # Sets the `Cache-Control` header, overwriting existing directives. This method
+    # will also ensure an HTTP `Date` header for client compatibility.
+    #
+    # Defaults to issuing the `private` directive, so that intermediate caches must
+    # not cache the response.
+    #
+    # #### Options
+    #
+    # `:public`
+    # :   If true, replaces the default `private` directive with the `public`
+    #     directive.
+    #
+    # `:must_revalidate`
+    # :   If true, adds the `must-revalidate` directive.
+    #
+    # `:stale_while_revalidate`
+    # :   Sets the value of the `stale-while-revalidate` directive.
+    #
+    # `:stale_if_error`
+    # :   Sets the value of the `stale-if-error` directive.
+    #
+    # `:immutable`
+    # :   If true, adds the `immutable` directive.
+    #
+    #
+    # Any additional key-value pairs are concatenated as directives. For a list of
+    # supported `Cache-Control` directives, see the [article on
+    # MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).
+    #
+    # #### Examples
+    #
+    #     expires_in 10.minutes
+    #     # => Cache-Control: max-age=600, private
+    #
+    #     expires_in 10.minutes, public: true
+    #     # => Cache-Control: max-age=600, public
+    #
+    #     expires_in 10.minutes, public: true, must_revalidate: true
+    #     # => Cache-Control: max-age=600, public, must-revalidate
+    #
+    #     expires_in 1.hour, stale_while_revalidate: 60.seconds
+    #     # => Cache-Control: max-age=3600, private, stale-while-revalidate=60
+    #
+    #     expires_in 1.hour, stale_if_error: 5.minutes
+    #     # => Cache-Control: max-age=3600, private, stale-if-error=300
+    #
+    #     expires_in 1.hour, public: true, "s-maxage": 3.hours, "no-transform": true
+    #     # => Cache-Control: max-age=3600, public, s-maxage=10800, no-transform=true
+    #
+    def expires_in(seconds, options = {})
+      response.cache_control.delete(:no_store)
+      response.cache_control.merge!(
+        max_age: seconds,
+        public: options.delete(:public),
+        must_revalidate: options.delete(:must_revalidate),
+        stale_while_revalidate: options.delete(:stale_while_revalidate),
+        stale_if_error: options.delete(:stale_if_error),
+        immutable: options.delete(:immutable),
+      )
+      options.delete(:private)
+
+      response.cache_control[:extras] = options.map { |k, v| "#{k}=#{v}" }
+      response.date = Time.now unless response.date?
+    end
+
+    # Sets an HTTP 1.1 `Cache-Control` header of `no-cache`. This means the resource
+    # will be marked as stale, so clients must always revalidate.
+    # Intermediate/browser caches may still store the asset.
+    def expires_now
+      response.cache_control.replace(no_cache: true)
+    end
+
+    # Cache or yield the block. The cache is supposed to never expire.
+    #
+    # You can use this method when you have an HTTP response that never changes, and
+    # the browser and proxies should cache it indefinitely.
+    #
+    # *   `public`: By default, HTTP responses are private, cached only on the
+    #     user's web browser. To allow proxies to cache the response, set `true` to
+    #     indicate that they can serve the cached response to all users.
+    def http_cache_forever(public: false)
+      expires_in 100.years, public: public, immutable: true
+
+      yield if stale?(etag: request.fullpath,
+                      last_modified: Time.new(2011, 1, 1).utc,
+                      public: public)
+    end
+
+    # Sets an HTTP 1.1 `Cache-Control` header of `no-store`. This means the resource
+    # may not be stored in any cache.
+    def no_store
+      response.cache_control.replace(no_store: true)
+    end
+
+    private
+      def combine_etags(validator, options)
+        [validator, *etaggers.map { |etagger| instance_exec(options, &etagger) }].compact
+      end
+  end
+end

data/lib/action_controller/metal/content_security_policy.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionController # :nodoc:
+  module ContentSecurityPolicy
+    extend ActiveSupport::Concern
+
+    include AbstractController::Helpers
+    include AbstractController::Callbacks
+
+    included do
+      helper_method :content_security_policy?
+      helper_method :content_security_policy_nonce
+    end
+
+    module ClassMethods
+      # Overrides parts of the globally configured `Content-Security-Policy` header:
+      #
+      #     class PostsController < ApplicationController
+      #       content_security_policy do |policy|
+      #         policy.base_uri "https://www.example.com"
+      #       end
+      #     end
+      #
+      # Options can be passed similar to `before_action`. For example, pass `only:
+      # :index` to override the header on the index action only:
+      #
+      #     class PostsController < ApplicationController
+      #       content_security_policy(only: :index) do |policy|
+      #         policy.default_src :self, :https
+      #       end
+      #     end
+      #
+      # Pass `false` to remove the `Content-Security-Policy` header:
+      #
+      #     class PostsController < ApplicationController
+      #       content_security_policy false, only: :index
+      #     end
+      def content_security_policy(enabled = true, **options, &block)
+        before_action(options) do
+          if block_given?
+            policy = current_content_security_policy
+            instance_exec(policy, &block)
+            request.content_security_policy = policy
+          end
+
+          unless enabled
+            request.content_security_policy = nil
+          end
+        end
+      end
+
+      # Overrides the globally configured `Content-Security-Policy-Report-Only`
+      # header:
+      #
+      #     class PostsController < ApplicationController
+      #       content_security_policy_report_only only: :index
+      #     end
+      #
+      # Pass `false` to remove the `Content-Security-Policy-Report-Only` header:
+      #
+      #     class PostsController < ApplicationController
+      #       content_security_policy_report_only false, only: :index
+      #     end
+      def content_security_policy_report_only(report_only = true, **options)
+        before_action(options) do
+          request.content_security_policy_report_only = report_only
+        end
+      end
+    end
+
+    private
+      def content_security_policy?
+        request.content_security_policy
+      end
+
+      def content_security_policy_nonce
+        request.content_security_policy_nonce
+      end
+
+      def current_content_security_policy
+        request.content_security_policy&.clone || ActionDispatch::ContentSecurityPolicy.new
+      end
+  end
+end

data/lib/action_controller/metal/cookies.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionController # :nodoc:
+  module Cookies
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :cookies if defined?(helper_method)
+    end
+
+    private
+      # The cookies for the current request. See ActionDispatch::Cookies for more
+      # information.
+      def cookies # :doc:
+        request.cookie_jar
+      end
+  end
+end

data/lib/action_controller/metal/data_streaming.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+require "action_controller/metal/exceptions"
+require "action_dispatch/http/content_disposition"
+
+module ActionController # :nodoc:
+  # # Action Controller Data Streaming
+  #
+  # Methods for sending arbitrary data and for streaming files to the browser,
+  # instead of rendering.
+  module DataStreaming
+    extend ActiveSupport::Concern
+
+    include ActionController::Rendering
+
+    DEFAULT_SEND_FILE_TYPE        = "application/octet-stream" # :nodoc:
+    DEFAULT_SEND_FILE_DISPOSITION = "attachment" # :nodoc:
+
+    private
+      # Sends the file. This uses a server-appropriate method (such as `X-Sendfile`)
+      # via the `Rack::Sendfile` middleware. The header to use is set via
+      # `config.action_dispatch.x_sendfile_header`. Your server can also configure
+      # this for you by setting the `X-Sendfile-Type` header.
+      #
+      # Be careful to sanitize the path parameter if it is coming from a web page.
+      # `send_file(params[:path])` allows a malicious user to download any file on
+      # your server.
+      #
+      # Options:
+      # *   `:filename` - suggests a filename for the browser to use. Defaults to
+      #     `File.basename(path)`.
+      # *   `:type` - specifies an HTTP content type. You can specify either a string
+      #     or a symbol for a registered type with `Mime::Type.register`, for example
+      #     `:json`. If omitted, the type will be inferred from the file extension
+      #     specified in `:filename`. If no content type is registered for the
+      #     extension, the default type `application/octet-stream` will be used.
+      # *   `:disposition` - specifies whether the file will be shown inline or
+      #     downloaded. Valid values are `"inline"` and `"attachment"` (default).
+      # *   `:status` - specifies the status code to send with the response. Defaults
+      #     to 200.
+      # *   `:url_based_filename` - set to `true` if you want the browser to guess the
+      #     filename from the URL, which is necessary for i18n filenames on certain
+      #     browsers (setting `:filename` overrides this option).
+      #
+      #
+      # The default `Content-Type` and `Content-Disposition` headers are set to
+      # download arbitrary binary files in as many browsers as possible. IE versions
+      # 4, 5, 5.5, and 6 are all known to have a variety of quirks (especially when
+      # downloading over SSL).
+      #
+      # Simple download:
+      #
+      #     send_file '/path/to.zip'
+      #
+      # Show a JPEG in the browser:
+      #
+      #     send_file '/path/to.jpeg', type: 'image/jpeg', disposition: 'inline'
+      #
+      # Show a 404 page in the browser:
+      #
+      #     send_file '/path/to/404.html', type: 'text/html; charset=utf-8', disposition: 'inline', status: 404
+      #
+      # You can use other `Content-*` HTTP headers to provide additional information
+      # to the client. See MDN for a [list of HTTP
+      # headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
+      #
+      # Also be aware that the document may be cached by proxies and browsers. The
+      # `Pragma` and `Cache-Control` headers declare how the file may be cached by
+      # intermediaries. They default to require clients to validate with the server
+      # before releasing cached responses. See https://www.mnot.net/cache_docs/ for an
+      # overview of web caching and [RFC
+      # 9111](https://www.rfc-editor.org/rfc/rfc9111.html#name-cache-control) for the
+      # `Cache-Control` header spec.
+      def send_file(path, options = {}) # :doc:
+        raise MissingFile, "Cannot read file #{path}" unless File.file?(path) && File.readable?(path)
+
+        options[:filename] ||= File.basename(path) unless options[:url_based_filename]
+        send_file_headers! options
+
+        self.status = options[:status] || 200
+        self.content_type = options[:content_type] if options.key?(:content_type)
+        response.send_file path
+      end
+
+      # Sends the given binary data to the browser. This method is similar to `render
+      # plain: data`, but also allows you to specify whether the browser should
+      # display the response as a file attachment (i.e. in a download dialog) or as
+      # inline data. You may also set the content type, the file name, and other
+      # things.
+      #
+      # Options:
+      # *   `:filename` - suggests a filename for the browser to use.
+      # *   `:type` - specifies an HTTP content type. Defaults to
+      #     `application/octet-stream`. You can specify either a string or a symbol
+      #     for a registered type with `Mime::Type.register`, for example `:json`. If
+      #     omitted, type will be inferred from the file extension specified in
+      #     `:filename`. If no content type is registered for the extension, the
+      #     default type `application/octet-stream` will be used.
+      # *   `:disposition` - specifies whether the file will be shown inline or
+      #     downloaded. Valid values are `"inline"` and `"attachment"` (default).
+      # *   `:status` - specifies the status code to send with the response. Defaults
+      #     to 200.
+      #
+      #
+      # Generic data download:
+      #
+      #     send_data buffer
+      #
+      # Download a dynamically-generated tarball:
+      #
+      #     send_data generate_tgz('dir'), filename: 'dir.tgz'
+      #
+      # Display an image Active Record in the browser:
+      #
+      #     send_data image.data, type: image.content_type, disposition: 'inline'
+      #
+      # See `send_file` for more information on HTTP `Content-*` headers and caching.
+      def send_data(data, options = {}) # :doc:
+        send_file_headers! options
+        render options.slice(:status, :content_type).merge(body: data)
+      end
+
+      def send_file_headers!(options)
+        type_provided = options.has_key?(:type)
+
+        content_type = options.fetch(:type, DEFAULT_SEND_FILE_TYPE)
+        self.content_type = content_type
+        response.sending_file = true
+
+        raise ArgumentError, ":type option required" if content_type.nil?
+
+        if content_type.is_a?(Symbol)
+          extension = Mime[content_type]
+          raise ArgumentError, "Unknown MIME type #{options[:type]}" unless extension
+          self.content_type = extension
+        else
+          if !type_provided && options[:filename]
+            # If type wasn't provided, try guessing from file extension.
+            content_type = Mime::Type.lookup_by_extension(File.extname(options[:filename]).downcase.delete(".")) || content_type
+          end
+          self.content_type = content_type
+        end
+
+        disposition = options.fetch(:disposition, DEFAULT_SEND_FILE_DISPOSITION)
+        if disposition
+          headers["Content-Disposition"] = ActionDispatch::Http::ContentDisposition.format(disposition: disposition, filename: options[:filename])
+        end
+
+        headers["Content-Transfer-Encoding"] = "binary"
+      end
+  end
+end

data/lib/action_controller/metal/default_headers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionController
+  # # Action Controller Default Headers
+  #
+  # Allows configuring default headers that will be automatically merged into each
+  # response.
+  module DefaultHeaders
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def make_response!(request)
+        ActionDispatch::Response.create.tap do |res|
+          res.request = request
+        end
+      end
+    end
+  end
+end

data/lib/action_controller/metal/etag_with_flash.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionController
+  # # Action Controller Etag With Flash
+  #
+  # When you're using the flash, it's generally used as a conditional on the view.
+  # This means the content of the view depends on the flash. Which in turn means
+  # that the ETag for a response should be computed with the content of the flash
+  # in mind. This does that by including the content of the flash as a component
+  # in the ETag that's generated for a response.
+  module EtagWithFlash
+    extend ActiveSupport::Concern
+
+    include ActionController::ConditionalGet
+
+    included do
+      etag { flash if request.respond_to?(:flash) && !flash.empty? }
+    end
+  end
+end