Support for page refreshes and broadcasting

app/channels/turbo/streams/broadcasts.rb

@@ -33,6 +33,10 @@ def broadcast_prepend_to(*streamables, **opts)
     broadcast_action_to(*streamables, action: :prepend, **opts)
   end
 
+  def broadcast_refresh_to(*streamables, **opts)
+    broadcast_stream_to(*streamables, content: turbo_stream_refresh_tag)
+  end
+
   def broadcast_action_to(*streamables, action:, target: nil, targets: nil, attributes: {}, **rendering)
     broadcast_stream_to(*streamables, content: turbo_stream_action_tag(action, target: target, targets: targets, template:
       rendering.delete(:content) || rendering.delete(:html) || (rendering[:render] != false && rendering.any? ? render_format(:html, **rendering) : nil),
@@ -64,6 +68,12 @@ def broadcast_prepend_later_to(*streamables, **opts)
     broadcast_action_later_to(*streamables, action: :prepend, **opts)
   end
 
+  def broadcast_refresh_later_to(*streamables, request_id: Turbo.current_request_id, **opts)
+    refresh_debouncer_for(*streamables, request_id: request_id).debounce do
+      Turbo::Streams::BroadcastStreamJob.perform_later stream_name_from(streamables), content: turbo_stream_refresh_tag(request_id: request_id, **opts)
+    end
+  end
+
   def broadcast_action_later_to(*streamables, action:, target: nil, targets: nil, attributes: {}, **rendering)
     Turbo::Streams::ActionBroadcastJob.perform_later \
       stream_name_from(streamables), action: action, target: target, targets: targets, attributes: attributes, **rendering
@@ -81,6 +91,9 @@ def broadcast_stream_to(*streamables, content:)
     ActionCable.server.broadcast stream_name_from(streamables), content
   end
 
+  def refresh_debouncer_for(*streamables, request_id: nil) # :nodoc:
+    Turbo::ThreadDebouncer.for("turbo-refresh-debouncer-#{stream_name_from(streamables.including(request_id))}")
+  end
 
   private
     def render_format(format, **rendering)

app/controllers/concerns/turbo/request_id_tracking.rb

@@ -0,0 +1,12 @@
+module Turbo::RequestIdTracking
+  extend ActiveSupport::Concern
+
+  included do
+    around_action :turbo_tracking_request_id
+  end
+
+  private
+    def turbo_tracking_request_id(&block)
+      Turbo.with_request_id(request.headers["X-Turbo-Request-Id"], &block)
+    end
+end

app/helpers/turbo/drive_helper.rb

@@ -26,4 +26,12 @@ def turbo_exempts_page_from_preview
   def turbo_page_requires_reload
     provide :head, tag.meta(name: "turbo-visit-control", content: "reload")
   end
+
+  def turbo_refreshes_with(method: :replace, scroll: :reset)
+    raise ArgumentError, "Invalid refresh option '#{method}'" unless method.in?(%i[ replace morph ])
+    raise ArgumentError, "Invalid scroll option '#{scroll}'" unless scroll.in?(%i[ reset preserve ])
+
+    provide :head, tag.meta(name: "turbo-refresh-method", content: method)
+    provide :head, tag.meta(name: "turbo-refresh-scroll", content: scroll)
+  end
 end

app/helpers/turbo/streams/action_helper.rb

@@ -24,7 +24,7 @@ module Turbo::Streams::ActionHelper
   #   # => <turbo-stream action="remove" target="special_message_1"></turbo-stream>
   #
   def turbo_stream_action_tag(action, target: nil, targets: nil, template: nil, **attributes)
-    template = action.to_sym == :remove ? "" : tag.template(template.to_s.html_safe)
+    template = action.to_sym.in?(%i[ remove refresh ]) ? "" : tag.template(template.to_s.html_safe)
 
     if target = convert_to_turbo_stream_dom_id(target)
       tag.turbo_stream(template, **attributes, action: action, target: target)
@@ -35,6 +35,10 @@ def turbo_stream_action_tag(action, target: nil, targets: nil, template: nil, **
     end
   end
 
+  def turbo_stream_refresh_tag(request_id: Turbo.current_request_id, **attributes)
+    turbo_stream_action_tag(:refresh, **{ "request-id": request_id }.compact, **attributes)
+  end
+
   private
     def convert_to_turbo_stream_dom_id(target, include_selector: false)
       if Array(target).any? { |value| value.respond_to?(:to_key) }

app/jobs/turbo/streams/broadcast_stream_job.rb

@@ -0,0 +1,7 @@
+class Turbo::Streams::BroadcastStreamJob < ActiveJob::Base
+  discard_on ActiveJob::DeserializationError
+
+  def perform(stream, content:)
+    Turbo::StreamsChannel.broadcast_stream_to(stream, content: content)
+  end
+end

app/models/concerns/turbo/broadcastable.rb

@@ -75,9 +75,32 @@
 # In addition to the four basic actions, you can also use <tt>broadcast_render</tt>,
 # <tt>broadcast_render_to</tt> <tt>broadcast_render_later</tt>, and <tt>broadcast_render_later_to</tt>
 # to render a turbo stream template with multiple actions.
+#
+# == Suppressing broadcasts
+#
+# Sometimes, you need to disable broadcasts in certain scenarios. You can use <tt>.suppressing_turbo_broadcasts</tt> to create
+# execution contexts where broadcasts are disabled:
+#
+#   class Message < ApplicationRecord
+#     after_create_commit :update_message
+#
+#     private
+#       def update_message
+#         broadcast_replace_to(user, :message, target: "message", renderable: MessageComponent.new)
+#       end
+#   end
+#
+#   Message.suppressing_turbo_broadcasts do
+#     Message.create!(board: board) # This won't broadcast the replace action
+#   end
 module Turbo::Broadcastable
   extend ActiveSupport::Concern
 
+  included do
+    thread_mattr_accessor :suppressed_turbo_broadcasts, instance_accessor: false
+    delegate :suppressed_turbo_broadcasts?, to: "self.class"
+  end
+
   module ClassMethods
     # Configures the model to broadcast creates, updates, and destroys to a stream name derived at runtime by the
     # <tt>stream</tt> symbol invocation. By default, the creates are appended to a dom id target name derived from
@@ -112,10 +135,34 @@ def broadcasts(stream = model_name.plural, inserts_by: :append, target: broadcas
       after_destroy_commit -> { broadcast_remove }
     end
 
+    # Configures the model to broadcast a "page refresh" on creates, updates, and destroys to a stream
+    # name derived at runtime by the <tt>stream</tt> symbol invocation.
+    def broadcasts_refreshes_to(stream)
+      after_commit -> { broadcast_refresh_later_to(stream.try(:call, self) || send(stream)) }
+    end
+
+    # Same as <tt>#broadcasts_refreshes_to</tt>, but the designated stream for page refreshes is automatically set to
+    # the current model.
+    def broadcasts_refreshes
+      after_commit -> { broadcast_refresh_later }
+    end
+
     # All default targets will use the return of this method. Overwrite if you want something else than <tt>model_name.plural</tt>.
     def broadcast_target_default
       model_name.plural
     end
+
+    # Executes +block+ preventing both synchronous and asynchronous broadcasts from this model.
+    def suppressing_turbo_broadcasts(&block)
+      original, self.suppressed_turbo_broadcasts = self.suppressed_turbo_broadcasts, true
+      yield
+    ensure
+      self.suppressed_turbo_broadcasts = original
+    end
+
+    def suppressed_turbo_broadcasts?
+      suppressed_turbo_broadcasts
+    end
   end
 
   # Remove this broadcastable model from the dom for subscribers of the stream name identified by the passed streamables.
@@ -124,7 +171,7 @@ def broadcast_target_default
   #   # Sends <turbo-stream action="remove" target="clearance_5"></turbo-stream> to the stream named "identity:2:clearances"
   #   clearance.broadcast_remove_to examiner.identity, :clearances
   def broadcast_remove_to(*streamables, target: self)
-    Turbo::StreamsChannel.broadcast_remove_to(*streamables, target: target)
+    Turbo::StreamsChannel.broadcast_remove_to(*streamables, target: target) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_remove_to</tt>, but the designated stream is automatically set to the current model.
@@ -143,7 +190,7 @@ def broadcast_remove
   #   # to the stream named "identity:2:clearances"
   #   clearance.broadcast_replace_to examiner.identity, :clearances, partial: "clearances/other_partial", locals: { a: 1 }
   def broadcast_replace_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_replace_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_replace_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_replace_to</tt>, but the designated stream is automatically set to the current model.
@@ -162,7 +209,7 @@ def broadcast_replace(**rendering)
   #   # to the stream named "identity:2:clearances"
   #   clearance.broadcast_update_to examiner.identity, :clearances, partial: "clearances/other_partial", locals: { a: 1 }
   def broadcast_update_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_update_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_update_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_update_to</tt>, but the designated stream is automatically set to the current model.
@@ -215,7 +262,7 @@ def broadcast_after_to(*streamables, target:, **rendering)
   #   clearance.broadcast_append_to examiner.identity, :clearances, target: "clearances",
   #     partial: "clearances/other_partial", locals: { a: 1 }
   def broadcast_append_to(*streamables, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_append_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_append_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_append_to</tt>, but the designated stream is automatically set to the current model.
@@ -236,21 +283,29 @@ def broadcast_append(target: broadcast_target_default, **rendering)
   #   clearance.broadcast_prepend_to examiner.identity, :clearances, target: "clearances",
   #     partial: "clearances/other_partial", locals: { a: 1 }
   def broadcast_prepend_to(*streamables, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_prepend_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_prepend_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_prepend_to</tt>, but the designated stream is automatically set to the current model.
   def broadcast_prepend(target: broadcast_target_default, **rendering)
     broadcast_prepend_to self, target: target, **rendering
   end
 
+  def broadcast_refresh_to(*streamables)
+    Turbo::StreamsChannel.broadcast_refresh_to *streamables unless suppressed_turbo_broadcasts?
+  end
+
+  def broadcast_refresh
+    broadcast_refresh_to self
+  end
+
   # Broadcast a named <tt>action</tt>, allowing for dynamic dispatch, instead of using the concrete action methods. Examples:
   #
   #   # Sends <turbo-stream action="prepend" target="clearances"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
   #   # to the stream named "identity:2:clearances"
   #   clearance.broadcast_action_to examiner.identity, :clearances, action: :prepend, target: "clearances"
   def broadcast_action_to(*streamables, action:, target: broadcast_target_default, attributes: {}, **rendering)
-    Turbo::StreamsChannel.broadcast_action_to(*streamables, action: action, target: target, attributes: attributes, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_action_to(*streamables, action: action, target: target, attributes: attributes, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_action_to</tt>, but the designated stream is automatically set to the current model.
@@ -261,7 +316,7 @@ def broadcast_action(action, target: broadcast_target_default, attributes: {}, *
 
   # Same as <tt>broadcast_replace_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_replace_later_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_replace_later_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_replace_later_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_replace_later_to</tt>, but the designated stream is automatically set to the current model.
@@ -271,7 +326,7 @@ def broadcast_replace_later(**rendering)
 
   # Same as <tt>broadcast_update_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_update_later_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_update_later_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_update_later_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_update_later_to</tt>, but the designated stream is automatically set to the current model.
@@ -281,7 +336,7 @@ def broadcast_update_later(**rendering)
 
   # Same as <tt>broadcast_append_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_append_later_to(*streamables, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_append_later_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_append_later_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_append_later_to</tt>, but the designated stream is automatically set to the current model.
@@ -291,17 +346,25 @@ def broadcast_append_later(target: broadcast_target_default, **rendering)
 
   # Same as <tt>broadcast_prepend_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_prepend_later_to(*streamables, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_prepend_later_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_prepend_later_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_prepend_later_to</tt>, but the designated stream is automatically set to the current model.
   def broadcast_prepend_later(target: broadcast_target_default, **rendering)
     broadcast_prepend_later_to self, target: target, **rendering
   end
 
+  def broadcast_refresh_later_to(*streamables)
+    Turbo::StreamsChannel.broadcast_refresh_later_to(*streamables, request_id: Turbo.current_request_id) unless suppressed_turbo_broadcasts?
+  end
+
+  def broadcast_refresh_later
+    broadcast_refresh_later_to self
+  end
+
   # Same as <tt>broadcast_action_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_action_later_to(*streamables, action:, target: broadcast_target_default, attributes: {}, **rendering)
-    Turbo::StreamsChannel.broadcast_action_later_to(*streamables, action: action, target: target, attributes: attributes, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_action_later_to(*streamables, action: action, target: target, attributes: attributes, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_action_later_to</tt>, but the designated stream is automatically set to the current model.
@@ -337,7 +400,7 @@ def broadcast_render(**rendering)
   # desireable for model callbacks, certainly not if those callbacks are inside of a transaction. Most of the time you should
   # be using `broadcast_render_later_to`, unless you specifically know why synchronous rendering is needed.
   def broadcast_render_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_render_to(*streamables, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_render_to(*streamables, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>broadcast_action_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
@@ -348,7 +411,7 @@ def broadcast_render_later(**rendering)
   # Same as <tt>broadcast_render_later</tt> but run with the added option of naming the stream using the passed
   # <tt>streamables</tt>.
   def broadcast_render_later_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_render_later_to(*streamables, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_render_later_to(*streamables, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
 
 
@@ -361,7 +424,7 @@ def broadcast_rendering_with_defaults(options)
       options.tap do |o|
         # Add the current instance into the locals with the element name (which is the un-namespaced name)
         # as the key. This parallels how the ActionView::ObjectRenderer would create a local variable.
-        o[:locals] = (o[:locals] || {}).reverse_merge!(model_name.element.to_sym => self)
+        o[:locals] = (o[:locals] || {}).reverse_merge!(model_name.element.to_sym => self, request_id: Turbo.current_request_id).compact
 
         if o[:html] || o[:partial]
           return o

app/models/turbo/debouncer.rb

@@ -0,0 +1,24 @@
+class Turbo::Debouncer
+  attr_reader :delay, :scheduled_task
+
+  DEFAULT_DELAY = 0.5
+
+  def initialize(delay: DEFAULT_DELAY)
+    @delay = delay
+    @scheduled_task = nil
+  end
+
+  def debounce(&block)
+    scheduled_task&.cancel unless scheduled_task&.complete?
+    @scheduled_task = Concurrent::ScheduledTask.execute(delay, &block)
+  end
+
+  def wait
+    scheduled_task.wait(wait_timeout)
+  end
+
+  private
+    def wait_timeout
+      delay + 1
+    end
+end

app/models/turbo/thread_debouncer.rb

@@ -0,0 +1,28 @@
+# A decorated debouncer that will store instances in the current thread clearing them
+# after the debounced logic triggers.
+class Turbo::ThreadDebouncer
+  delegate :wait, to: :debouncer
+
+  def self.for(key, delay: Turbo::Debouncer::DEFAULT_DELAY)
+    Thread.current[key] ||= new(key, Thread.current, delay: delay)
+  end
+
+  private_class_method :new
+
+  def initialize(key, thread, delay: )
+    @key = key
+    @debouncer = Turbo::Debouncer.new(delay: delay)
+    @thread = thread
+  end
+
+  def debounce
+    debouncer.debounce do
+      yield.tap do
+        thread[key] = nil
+      end
+    end
+  end
+
+  private
+    attr_reader :key, :debouncer, :thread
+end

lib/turbo-rails.rb

@@ -5,6 +5,8 @@ module Turbo
 
   mattr_accessor :draw_routes, default: true
 
+  thread_mattr_accessor :current_request_id
+
   class << self
     attr_writer :signed_stream_verifier_key
 
@@ -15,5 +17,12 @@ def signed_stream_verifier
     def signed_stream_verifier_key
       @signed_stream_verifier_key or raise ArgumentError, "Turbo requires a signed_stream_verifier_key"
     end
+
+    def with_request_id(request_id)
+      old_request_id, self.current_request_id = self.current_request_id, request_id
+      yield
+    ensure
+      self.current_request_id = old_request_id
+    end
   end
 end

lib/turbo/engine.rb

@@ -46,6 +46,12 @@ class Engine < Rails::Engine
       end
     end
 
+    initializer "turbo.request_id_tracking" do
+      ActiveSupport.on_load(:action_controller) do
+        include Turbo::RequestIdTracking
+      end
+    end
+
     initializer "turbo.broadcastable" do
       ActiveSupport.on_load(:active_record) do
         include Turbo::Broadcastable