motion 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7839c6a006522aecfde98e996d77d5af65d3f50a3472d54a84bb9c59c13b2a88
-  data.tar.gz: 3011e0696be6a98232276b35310953939cca6f88d13e85c253f2004b98cc059e
+  metadata.gz: '0967eb2e920b41cf8800a494bcc514bdf4d7cbdf9811a1425a09bf80e99b65d9'
+  data.tar.gz: 8c36032ff83ebd1cdb5c4fb4cd7ff0c668deee2b6bf3384027b0c715cc50d53c
 SHA512:
-  metadata.gz: 7195a8b10a5785ea41b46958b886d06ed8e19cd376879d3c1a1d7c14e5ef7be403df16b55f59d1276c1b7111d4268b6280f8d7326cc3e5f6e31aac555376e6c6
-  data.tar.gz: 3f2df4a07139f7ac39fb2733ae3f7ccaf20d9cffd8a8e7c34b1b7e6dd9112fc69de20129e592fe4dacf7dfff5a0c12f15aab896dcea854ab093c795ab69df71d
+  metadata.gz: 499f1fb69d65d04b5439ccf6eb32fac722edff716d5bbd710c8e35b6f68ff5e5e821b02a38e046889a8a08c2bf78efdf87eb2e684c76e1c36cb6a22990c171f7
+  data.tar.gz: 517e4f3b96279f8f8b4fd21c8e5eb441d4fceee1005bea476b655f3bb673a61d45a57d81667d378a60fa7b8c05f597393d6c6d87e994678adec73aa2cda188cd

data/lib/generators/motion/templates/motion.js

@@ -17,7 +17,15 @@ export default createClient({
   // made available at `Motion::Event#extra_data`:
   //
   //    getExtraDataForEvent(event) {},
+
+  // By default, the Motion client automatically disconnects all components when
+  // it detects the browser navigating away to a new page. This is done to
+  // prevent flashes of new content in components with broadcasts because of
+  // some action being taken by the controller that the user is navigating to
+  // (like submitting a form). If you do not want or need this functionally, you
+  // can turn it off:
   //
+  //    shutdownBeforeUnload: false,
 
   // The data attributes used by Motion can be customized, but these values must
   // also be updated in the Ruby initializer:
@@ -25,6 +33,5 @@ export default createClient({
   //    keyAttribute: "data-motion-key",
   //    stateAttribute: "data-motion-state",
   //    motionAttribute: "data-motion",
-  //
 
 });

data/lib/generators/motion/templates/motion.rb

@@ -5,13 +5,16 @@ Motion.configure do |config|
   # version of your application. By default, the commit hash from git is used,
   # but depending on your deployment, this may not be available in production.
   #
-  # If you are sure that git is available in your production enviorment, you can
-  # uncomment this line:
+  # Motion automatically calculates your revision by hashing the contents of
+  # files in `revision_paths` The defaults revision paths are:
+  # rails paths, bin, and Gemfile.lock.
   #
-  #     config.revision = `git rev-parse HEAD`.chomp
+  # To change or add to your revision paths, uncomment this line:
   #
-  # If git is not available in your production enviorment, you must identify
-  # your application version some other way:
+  #     config.revision_paths += w(additional_path another_path)
+  #
+  # If you prefer to use git or an environmental variable for the revision
+  # in production, define the revision directly below.
   #
   #     config.revision =
   #       ENV.fetch("MY_DEPLOYMENT_NUMBER") { `git rev-parse HEAD`.chomp }
@@ -27,14 +30,29 @@ Motion.configure do |config|
   #     config.renderer_for_connection_proc = ->(websocket_connection) do
   #       ApplicationController.renderer.new(
   #         websocket_connection.env.slice(
-  #           Rack::HTTP_COOKIE,
-  #           Rack::RACK_SESSION,
+  #           Rack::HTTP_COOKIE,  # Cookies
+  #           Rack::RACK_SESSION, # Session
+  #           'warden'            # Warden (needed for `current_user` in Devise)
   #         )
   #       )
   #     end
 
+  # This proc will be invoked by Motion when an unhandled error occurs. By
+  # default, an error is logged to the application's default logger but no
+  # additional action is taken. If you are using an error tracking tool like
+  # Bugsnag, Sentry, Honeybadger, or Rollbar, you can provide a proc which
+  # notifies that as well:
+  #
+  #     config.error_notification_proc = ->(error, message) do
+  #       Bugsnag.notify(error) do |report|
+  #         report.add_tab(:motion, {
+  #           message: message
+  #         })
+  #       end
+  #     end
+
   # The data attributes used by Motion can be customized, but these values must
-  # also be updated in the Ruby initializer:
+  # also be updated in the JavaScript client configuration:
   #
   #     config.key_attribute = "data-motion-key"
   #     config.state_attribute = "data-motion-state"

data/lib/motion.rb

@@ -5,6 +5,7 @@ require "motion/errors"
 
 module Motion
   autoload :ActionCableExtentions, "motion/action_cable_extentions"
+  autoload :Callback, "motion/callback"
   autoload :Channel, "motion/channel"
   autoload :Component, "motion/component"
   autoload :ComponentConnection, "motion/component_connection"
@@ -14,6 +15,7 @@ module Motion
   autoload :LogHelper, "motion/log_helper"
   autoload :MarkupTransformer, "motion/markup_transformer"
   autoload :Railtie, "motion/railtie"
+  autoload :RevisionCalculator, "motion/revision_calculator"
   autoload :Serializer, "motion/serializer"
   autoload :TestHelpers, "motion/test_helpers"
 
@@ -41,6 +43,10 @@ module Motion
     config.renderer_for_connection_proc.call(websocket_connection)
   end
 
+  def self.notify_error(error, message)
+    config.error_notification_proc&.call(error, message)
+  end
+
   # This method only exists for testing. Changing configuration while Motion is
   # in use is not supported. It is only safe to call this method when no
   # components are currently mounted.

data/lib/motion/action_cable_extentions.rb

@@ -4,10 +4,16 @@ require "motion"
 
 module Motion
   module ActionCableExtentions
+    autoload :DeclarativeNotifications,
+      "motion/action_cable_extentions/declarative_notifications"
+
     autoload :DeclarativeStreams,
       "motion/action_cable_extentions/declarative_streams"
 
     autoload :LogSuppression,
       "motion/action_cable_extentions/log_suppression"
+
+    autoload :Synchronization,
+      "motion/action_cable_extentions/synchronization"
   end
 end

data/lib/motion/action_cable_extentions/declarative_notifications.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  module ActionCableExtentions
+    # Provides a `periodically_notify(broadcasts, to:)` API that can be used to
+    # declaratively specify when a handler should be called.
+    module DeclarativeNotifications
+      include Synchronization
+
+      def initialize(*)
+        super
+
+        # The current set of declarative notifications
+        @_declarative_notifications = {}
+
+        # The active timers for the declarative notifications
+        @_declarative_notifications_timers = {}
+
+        # The method we are routing declarative notifications to
+        @_declarative_notifications_target = nil
+      end
+
+      def declarative_notifications
+        @_declarative_notifications
+      end
+
+      def periodically_notify(notifications, via:)
+        (@_declarative_notifications.to_a - notifications.to_a)
+          .each do |notification, _interval|
+            _shutdown_declarative_notifcation_timer(notification)
+          end
+
+        (notifications.to_a - @_declarative_notifications.to_a)
+          .each do |notification, interval|
+            _setup_declarative_notifcation_timer(notification, interval)
+          end
+
+        @_declarative_notifications = notifications
+        @_declarative_notifications_target = via
+      end
+
+      private
+
+      def stop_periodic_timers
+        super
+
+        @_declarative_notifications.clear
+        @_declarative_notifications_timers.clear
+        @_declarative_notifications_target = nil
+      end
+
+      # The only public interface in ActionCable for defining periodic timers is
+      # exposed at the class level. Looking at the source though, it is easy to
+      # see that new timers can be setup with `start_periodic_timer`. To ensure
+      # that we do not leak any timers, it is important to store these instances
+      # in `active_periodic_timers` so that ActionCable cleans them up for us
+      # when the channel shuts down. Also, periodic timers are not supported by
+      # the testing adapter, so we have to skip all of this in unit tests (it
+      # _will_ be covered in systems tests though).
+      #
+      # See `ActionCable::Channel::PeriodicTimers` for details.
+      def _setup_declarative_notifcation_timer(notification, interval)
+        return if _stubbed_connection? ||
+          @_declarative_notifications_timers.include?(notification)
+
+        callback = proc do
+          synchronize_entrypoint! do
+            _handle_declarative_notifcation(notification)
+          end
+        end
+
+        timer = start_periodic_timer(callback, every: interval)
+
+        @_declarative_notifications_timers[notification] = timer
+        active_periodic_timers << timer
+      end
+
+      def _stubbed_connection?
+        defined?(ActionCable::Channel::ConnectionStub) &&
+          connection.is_a?(ActionCable::Channel::ConnectionStub)
+      end
+
+      def _shutdown_declarative_notifcation_timer(notification, *)
+        timer = @_declarative_notifications_timers.delete(notification)
+        return unless timer
+
+        timer.shutdown
+        active_periodic_timers.delete(timer)
+      end
+
+      def _handle_declarative_notifcation(notification)
+        return unless @_declarative_notifications_target &&
+          @_declarative_notifications.include?(notification)
+
+        send(@_declarative_notifications_target, notification)
+      end
+    end
+  end
+end

data/lib/motion/action_cable_extentions/declarative_streams.rb

@@ -6,19 +6,13 @@ module Motion
   module ActionCableExtentions
     # Provides a `streaming_from(broadcasts, to:)` API that can be used to
     # declaratively specify what `broadcasts` the channel is interested in
-    # receiving and `to` what method they should be routed. Additionally,
-    # this module extends the "at most one executor at a time" property that
-    # naturally comes with actions to the streams that it sets up as well.
+    # receiving and `to` what method they should be routed.
     module DeclarativeStreams
+      include Synchronization
+
       def initialize(*)
         super
 
-        # Allowing actions to be bound to streams (as this module provides)
-        # introduces the possibiliy of multiple threads accessing user code at
-        # the same time. Protect user code with a Monitor so we only have to
-        # worry about that here.
-        @_declarative_stream_monitor = Monitor.new
-
         # Streams that we are currently interested in
         @_declarative_streams = Set.new
 
@@ -30,19 +24,6 @@ module Motion
         @_declarative_stream_proxies = Set.new
       end
 
-      # Synchronize all ActionCable entry points (after initialization).
-      def subscribe_to_channel(*)
-        @_declarative_stream_monitor.synchronize { super }
-      end
-
-      def unsubscribe_from_channel(*)
-        @_declarative_stream_monitor.synchronize { super }
-      end
-
-      def perform_action(*)
-        @_declarative_stream_monitor.synchronize { super }
-      end
-
       # Clean up declarative streams when all streams are stopped.
       def stop_all_streams
         super
@@ -73,32 +54,17 @@ module Motion
         # TODO: I feel like the fact that we have to specify the coder here is
         # a bug in ActionCable. It should be the default for this karg.
         stream_from(broadcast, coder: ActiveSupport::JSON) do |message|
-          _handle_incoming_broadcast_to_declarative_stream(broadcast, message)
-        rescue Exception => exception # rubocop:disable Lint/RescueException
-          # It is very, very important that we do not allow an exception to
-          # escape here as the internals of ActionCable will stop processing
-          # the broadcast.
-
-          _handle_exception_in_declarative_stream(broadcast, exception)
+          synchronize_entrypoint! do
+            _handle_incoming_broadcast_to_declarative_stream(broadcast, message)
+          end
         end
       end
 
       def _handle_incoming_broadcast_to_declarative_stream(broadcast, message)
-        @_declarative_stream_monitor.synchronize do
-          return unless @_declarative_stream_target &&
-            @_declarative_streams.include?(broadcast)
-
-          send(@_declarative_stream_target, broadcast, message)
-        end
-      end
+        return unless @_declarative_stream_target &&
+          @_declarative_streams.include?(broadcast)
 
-      def _handle_exception_in_declarative_stream(broadcast, exception)
-        logger.error(
-          "There was an exception while handling a broadcast to #{broadcast}" \
-          "on #{self.class}:\n" \
-          "  #{exception.class}: #{exception.message}\n" \
-          "#{exception.backtrace.map { |line| "    #{line}" }.join("\n")}"
-        )
+        send(@_declarative_stream_target, broadcast, message)
       end
     end
   end

data/lib/motion/action_cable_extentions/synchronization.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  module ActionCableExtentions
+    module Synchronization
+      def initialize(*)
+        super
+
+        @_monitor = Monitor.new
+      end
+
+      # Additional entrypoints added by other modules should wrap any entry
+      # points that they add with this.
+      def synchronize_entrypoint!(&block)
+        @_monitor.synchronize(&block)
+      end
+
+      # Synchronize all standard ActionCable entry points.
+      def subscribe_to_channel(*)
+        synchronize_entrypoint! { super }
+      end
+
+      def unsubscribe_from_channel(*)
+        synchronize_entrypoint! { super }
+      end
+
+      def perform_action(*)
+        synchronize_entrypoint! { super }
+      end
+    end
+  end
+end

data/lib/motion/callback.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  class Callback
+    attr_reader :broadcast
+
+    NAMESPACE = "motion:callback"
+    private_constant :NAMESPACE
+
+    def self.broadcast_for(component, method)
+      [
+        NAMESPACE,
+        component.stable_instance_identifier_for_callbacks,
+        method
+      ].join(":")
+    end
+
+    def initialize(component, method)
+      @broadcast = self.class.broadcast_for(component, method)
+
+      component.stream_from(broadcast, method)
+    end
+
+    def ==(other)
+      other.is_a?(Callback) &&
+        other.broadcast == broadcast
+    end
+
+    def call(message = nil)
+      ActionCable.server.broadcast(broadcast, message)
+    end
+  end
+end

data/lib/motion/channel.rb

@@ -6,6 +6,7 @@ require "motion"
 
 module Motion
   class Channel < ActionCable::Channel::Base
+    include ActionCableExtentions::DeclarativeNotifications
     include ActionCableExtentions::DeclarativeStreams
     include ActionCableExtentions::LogSuppression
 
@@ -56,14 +57,23 @@ module Motion
       synchronize
     end
 
+    def process_periodic_timer(timer)
+      component_connection.process_periodic_timer(timer)
+      synchronize
+    end
+
     private
 
     def synchronize
-      streaming_from(component_connection.broadcasts, to: :process_broadcast)
-
       component_connection.if_render_required do |component|
         transmit(renderer.render(component))
       end
+
+      streaming_from component_connection.broadcasts,
+        to: :process_broadcast
+
+      periodically_notify component_connection.periodic_timers,
+        via: :process_periodic_timer
     end
 
     def handle_error(error, context)

data/lib/motion/component.rb

@@ -5,8 +5,10 @@ require "active_support/concern"
 require "motion"
 
 require "motion/component/broadcasts"
+require "motion/component/callbacks"
 require "motion/component/lifecycle"
 require "motion/component/motions"
+require "motion/component/periodic_timers"
 require "motion/component/rendering"
 
 module Motion
@@ -14,8 +16,10 @@ module Motion
     extend ActiveSupport::Concern
 
     include Broadcasts
+    include Callbacks
     include Lifecycle
     include Motions
+    include PeriodicTimers
     include Rendering
   end
 end

data/lib/motion/component/broadcasts.rb

@@ -3,6 +3,7 @@
 require "active_support/concern"
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/object/to_param"
+require "active_support/core_ext/hash/except"
 
 require "motion"
 
@@ -11,6 +12,31 @@ module Motion
     module Broadcasts
       extend ActiveSupport::Concern
 
+      # Analogous to `module_function` (available on both class and instance)
+      module ModuleFunctions
+        def stream_from(broadcast, handler)
+          self._broadcast_handlers =
+            _broadcast_handlers.merge(broadcast.to_s => handler.to_sym).freeze
+        end
+
+        def stop_streaming_from(broadcast)
+          self._broadcast_handlers =
+            _broadcast_handlers.except(broadcast.to_s).freeze
+        end
+
+        def stream_for(model, handler)
+          stream_from(broadcasting_for(model), handler)
+        end
+
+        def stop_streaming_for(model)
+          stop_streaming_from(broadcasting_for(model))
+        end
+
+        def broadcasts
+          _broadcast_handlers.keys
+        end
+      end
+
       included do
         class_attribute :_broadcast_handlers,
           instance_reader: false,
@@ -20,26 +46,19 @@ module Motion
       end
 
       class_methods do
+        include ModuleFunctions
+
         def broadcast_to(model, message)
           ActionCable.server.broadcast(broadcasting_for(model), message)
         end
 
-        def stream_from(broadcast, handler)
-          self._broadcast_handlers =
-            _broadcast_handlers.merge(broadcast.to_s => handler.to_sym).freeze
-        end
-
-        def stream_for(model, handler)
-          stream_from(broadcasting_for(model), handler)
-        end
-
         def broadcasting_for(model)
           serialize_broadcasting([name, model])
         end
 
         private
 
-        # Taken from ActionCable::Channel::Broadcasting
+        # This definition is copied from ActionCable::Channel::Broadcasting
         def serialize_broadcasting(object)
           if object.is_a?(Array)
             object.map { |m| serialize_broadcasting(m) }.join(":")
@@ -51,31 +70,26 @@ module Motion
         end
       end
 
-      def broadcasts
-        _broadcast_handlers.keys
-      end
+      include ModuleFunctions
 
       def process_broadcast(broadcast, message)
         return unless (handler = _broadcast_handlers[broadcast])
 
-        send(handler, message)
-      end
-
-      def broadcast_to(model, message)
-        self.class.broadcast_to(model, message)
+        _run_action_callbacks(context: handler) do
+          if method(handler).arity.zero?
+            send(handler)
+          else
+            send(handler, message)
+          end
+        end
       end
 
-      def stream_from(broadcast, handler)
-        self._broadcast_handlers =
-          _broadcast_handlers.merge(broadcast.to_s => handler.to_sym).freeze
-      end
+      private
 
-      def stream_for(model, handler)
-        stream_from(self.class.broadcasting_for(model), handler)
+      def broadcasting_for(model)
+        self.class.broadcasting_for(model)
       end
 
-      private
-
       attr_writer :_broadcast_handlers
 
       def _broadcast_handlers