motion 0.1.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f50ecf7f319478fcd72dca2dd6e55c36a67d803e6235d24c39ac36537528bb88
-  data.tar.gz: 10c88dabd3104c7351a5d2eeb6623564214171c1b26fdf9b25aca3d8297c2a46
+  metadata.gz: 54eb6afb0f21c0333d46c1a21602739146fa1e2a021d3ffda048c9763dc85e66
+  data.tar.gz: c3d9476c0e34869f5d4e46121316dee4f2c78d91b0a9b51d05c14a0b4d4e63ac
 SHA512:
-  metadata.gz: 31a107b75a0e553febfec1f0b93cc878c4c727f5f61ba1d0e39b89c9c7c1a7b45d5ecf188a49b9e1293c2f4056974afb755c1cb2cd4594895e95c3166e38563f
-  data.tar.gz: 7ad03d82e4a4ca05338368db8cda1b12813662f3f3fe2937f576baeb47b8b7c99b41b5bfc4ec9b11eb42facbce155990b7f278c6171603b0bf972b9adb641c52
+  metadata.gz: b17d8159ba7eae3b144a6380385e68eb9a2b49b0733926d9e285bf60c8f0767646d30841ee90d62d4b3a359f5c5f9beb62d4793c6d48dff6f1887c9fd7367a70
+  data.tar.gz: 0c47ed993c63378f0d562e341a44539bda1578c34d42ae8449c1dfd9dedabf7481e9e5f272c0869416893533fe31b5901368ebcc2e53c0752db120afb0e84c50

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

@@ -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