motion 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c9776bff100e3017a158810f93d3c374d97e6df42b8d9ffee43bf96da624b5b
-  data.tar.gz: a0764632d832cd96b58b3ffa5c28e9598d09136b0dbe6eadc66ab074bc18d5bd
+  metadata.gz: 7645381b6b2749a4a9ba90a15c93916636e1b9edfd7b3a6a1bf7d47429fedb3f
+  data.tar.gz: 46c929b8aa2d1de8c714eb8b8db1db8524aec892576a13ad1582b7fa858565f7
 SHA512:
-  metadata.gz: b5a0955da6087872bd9ec9940b8b3a674bf6fd2782ccad6b72460255703ff810e06e3d62ea99484a6c95d6fb48883953bbdec1cb3224af2513006ba60d5f3c54
-  data.tar.gz: a0360a0b1a0422b38f5bd4f9a46ba203ed9f1d3a1a6adf6073c89ff77152c0ae5cf212d097e6ad8b864f2bf220772511887db3c1692d7c4b7be3d3f54be01ec5
+  metadata.gz: b8c99a480f51e9d818f5d22de3efbf8923155943d1815188e19332c54b8f24b909bc371abc7282d3a9caac754cf1b0aee4bb3193dad75b7f1d86a9112ed13983
+  data.tar.gz: a12e9213ba0ae38cbc5d839ae1408a5aab064be055896300f19a2296ebcd74b49922b96636bc52bd7b7aef62be9868ea47437544938f20facaad45534744bc4e

data/lib/generators/motion/component_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Motion
+  module Generators
+    class ComponentGenerator < Rails::Generators::NamedBase
+      desc "Creates a Motion-enabled component in your application."
+
+      argument :attributes, type: :array, default: [], banner: "attribute"
+
+      def generate_component
+        generate "component", class_name, *attributes.map(&:name)
+      end
+
+      def include_motion
+        inject_into_class component_path, "#{class_name}Component" do
+          "  include Motion::Component\n\n"
+        end
+      end
+
+      private
+
+      def component_path
+        @component_path ||=
+          File.join("app/components", class_path, "#{file_name}_component.rb")
+      end
+
+      def file_name
+        @_file_name ||= super.sub(/_component\z/i, "")
+      end
+    end
+  end
+end

data/lib/generators/motion/install_generator.rb

@@ -16,10 +16,17 @@ module Motion
         )
       end
 
-      def copy_stimlus_controller
+      def copy_client_initializer
         template(
-          "motion_controller.js",
-          "app/javascript/controllers/motion_controller.js"
+          "motion.js",
+          "app/javascript/motion.js"
+        )
+      end
+
+      def add_client_to_application_pack
+        append_to_file(
+          "app/javascript/packs/application.js",
+          'import "motion"'
         )
       end
     end

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

@@ -0,0 +1,37 @@
+import { createClient } from '@unabridged/motion';
+import consumer from './channels/consumer';
+
+export default createClient({
+
+  // To avoid creating a second websocket, make sure to reuse the application's
+  // ActionCable consumer. If you are not otherwise using ActionCable, you can
+  // remove this line and the corresponding import.
+  consumer,
+
+  // Motion can log information about the lifecycle of components to the
+  // browser's console. It is recommended to turn this feature off outside of
+  // development.
+  logging: process.env["RAILS_ENV"] === "development",
+
+  // This function will be called for every motion, and the return value will be
+  // 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:
+  //
+  //    keyAttribute: "data-motion-key",
+  //    stateAttribute: "data-motion-state",
+  //    motionAttribute: "data-motion",
+
+});

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

@@ -1,22 +1,61 @@
 # frozen_string_literal: true
 
-# TODO: Explain all the options.
 Motion.configure do |config|
-  # config.secret = Rails.application.key_generator.generate_key "motion:secret"
+  # Motion needs to be able to uniquely identify the version of the running
+  # 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.
+  #
+  # 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.
+  #
+  # To change or add to your revision paths, uncomment this line:
+  #
+  #     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 }
+  #
+  # Using a value that does not change on every deployment will likely lead to
+  # confusing errors if components are connected during a deployment.
 
-  # config.revision = `git rev-parse HEAD`.chomp
+  # This proc will be invoked by Motion in order to create a renderer for each
+  # websocket connection. By default, your `ApplicationController` will be used
+  # and the session/cookies **as they were when the websocket was first open**
+  # will be available:
+  #
+  #     config.renderer_for_connection_proc = ->(websocket_connection) do
+  #       ApplicationController.renderer.new(
+  #         websocket_connection.env.slice(
+  #           Rack::HTTP_COOKIE,  # Cookies
+  #           Rack::RACK_SESSION, # Session
+  #           'warden'            # Warden (needed for `current_user` in Devise)
+  #         )
+  #       )
+  #     end
 
-  # config.renderer_for_connection_proc = ->(websocket_connection) do
-  #   ApplicationController.renderer.new(
-  #     websocket_connection.env.slice(
-  #       Rack::HTTP_COOKIE,
-  #       Rack::RACK_SESSION,
-  #     )
-  #   )
-  # 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
 
-  # config.stimulus_controller_identifier = "motion"
-  # config.key_attribute = "data-motion-key"
-  # config.state_attribute = "data-motion-state"
-  # config.motion_attribute = "data-motion"
+  # The data attributes used by Motion can be customized, but these values must
+  # also be updated in the JavaScript client configuration:
+  #
+  #     config.key_attribute = "data-motion-key"
+  #     config.state_attribute = "data-motion-state"
+  #     config.motion_attribute = "data-motion"
+  #
 end

data/lib/motion.rb

@@ -14,6 +14,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 +42,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
@@ -70,34 +51,20 @@ module Motion
       def _ensure_declarative_stream_proxy(broadcast)
         return unless @_declarative_stream_proxies.add?(broadcast)
 
-        # TODO: Something about this doesn't deal with the coder correctly.
-        stream_from(broadcast) 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)
+        # 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|
+          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/channel.rb

@@ -6,6 +6,7 @@ require "motion"
 
 module Motion
   class Channel < ActionCable::Channel::Base
+    include ActionCableExtentions::DeclarativeNotifications
     include ActionCableExtentions::DeclarativeStreams
     include ActionCableExtentions::LogSuppression
 
@@ -24,9 +25,7 @@ module Motion
     def subscribed
       state, client_version = params.values_at("state", "version")
 
-      # TODO: This is too restrictive. Introduce a protocol version and support
-      # older versions of the client that have a compatible protocol.
-      unless Motion::VERSION == client_version
+      if Gem::Version.new(Motion::VERSION) < Gem::Version.new(client_version)
         raise IncompatibleClientError.new(Motion::VERSION, client_version)
       end
 
@@ -58,10 +57,19 @@ 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)
+      streaming_from component_connection.broadcasts,
+        to: :process_broadcast
+
+      periodically_notify component_connection.periodic_timers,
+        via: :process_periodic_timer
 
       component_connection.if_render_required do |component|
         transmit(renderer.render(component))