motion 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1b1922ab9d0ef3ead51f333bf255e48f1f470a475ccc2463726e7d805d26344
-  data.tar.gz: 57204e95779dfffb7413bb5080da1fb97f8d0bd519a6ae5f07cce80e4bad58f7
+  metadata.gz: 7645381b6b2749a4a9ba90a15c93916636e1b9edfd7b3a6a1bf7d47429fedb3f
+  data.tar.gz: 46c929b8aa2d1de8c714eb8b8db1db8524aec892576a13ad1582b7fa858565f7
 SHA512:
-  metadata.gz: 3240417ce4c5928aa52c17fb1eb89aa641983d1c119d0ad38b7ec05e60c29172ac95fac9b1ab5cba6ef35ea94b7df819b2b917213cfb193dbb749484b485a33a
-  data.tar.gz: b7c973c8a93f0c9fac94fffa21a6b597635e064c4363b55d6718704bfdc5936125956e9116ebafb2936d5c555c95c34dff7e474a873605d49b36b7e0bebefeac
+  metadata.gz: b8c99a480f51e9d818f5d22de3efbf8923155943d1815188e19332c54b8f24b909bc371abc7282d3a9caac754cf1b0aee4bb3193dad75b7f1d86a9112ed13983
+  data.tar.gz: a12e9213ba0ae38cbc5d839ae1408a5aab064be055896300f19a2296ebcd74b49922b96636bc52bd7b7aef62be9868ea47437544938f20facaad45534744bc4e

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

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

@@ -42,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/component/broadcasts.rb

@@ -75,10 +75,12 @@ module Motion
       def process_broadcast(broadcast, message)
         return unless (handler = _broadcast_handlers[broadcast])
 
-        if method(handler).arity.zero?
-          send(handler)
-        else
-          send(handler, message)
+        _run_action_callbacks(context: handler) do
+          if method(handler).arity.zero?
+            send(handler)
+          else
+            send(handler, message)
+          end
         end
       end
 

data/lib/motion/component/lifecycle.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require "active_support/callbacks"
 require "active_support/concern"
+require "active_support/deprecation"
 
 require "motion"
 
@@ -9,22 +11,102 @@ module Motion
     module Lifecycle
       extend ActiveSupport::Concern
 
+      include ActiveSupport::Callbacks
+
+      included do
+        define_callbacks :action, :connect, :disconnect
+
+        # The built-in triggers defined on the target class will override ours.
+        remove_method(:_run_action_callbacks)
+      end
+
       class_methods do
-        # TODO: "IncorrectRevisionError" doesn't make sense for this anymore.
-        # It should probably be something like "CannotUpgrade" and the error
-        # message should focus on how to handle deployments gracefully.
-        def upgrade_from(previous_revision, _instance)
-          raise IncorrectRevisionError.new(
-            Motion.config.revision,
-            previous_revision
+        def upgrade_from(previous_revision, instance)
+          raise UpgradeNotImplementedError.new(
+            instance,
+            previous_revision,
+            Motion.config.revision
           )
         end
+
+        def before_action(*methods, **options, &block)
+          set_action_callback(:before, *methods, **options, &block)
+        end
+
+        def around_action(*methods, **options, &block)
+          set_action_callback(:around, *methods, **options, &block)
+        end
+
+        def after_action(*methods, **options, &block)
+          set_action_callback(:after, *methods, **options, &block)
+        end
+
+        def after_connect(*methods, **options, &block)
+          set_callback(:connect, :after, *methods, **options, &block)
+        end
+
+        def after_disconnect(*methods, **options, &block)
+          set_callback(:disconnect, :after, *methods, **options, &block)
+        end
+
+        private
+
+        def set_action_callback(kind, *methods, **options, &block)
+          filters = Array(options.delete(:if))
+
+          if (only = Array(options.delete(:only))).any?
+            filters << action_callback_context_filter(only)
+          end
+
+          if (except = Array(options.delete(:except))).any?
+            filters << action_callback_context_filter(except, invert: true)
+          end
+
+          set_callback(:action, kind, *methods, if: filters, **options, &block)
+        end
+
+        def action_callback_context_filter(contexts, invert: false)
+          proc { contexts.include?(@_action_callback_context) ^ invert }
+        end
+      end
+
+      def process_connect
+        _run_connect_callbacks
+
+        # TODO: Remove at next minor release
+        if respond_to?(:connected)
+          ActiveSupport::Deprecation.warn(
+            "The `connected` lifecycle method is being replaced by the " \
+            "`after_connect` callback and will no longer be automatically " \
+            "invoked in the next **minor release** of Motion."
+          )
+
+          send(:connected)
+        end
       end
 
-      def connected
+      def process_disconnect
+        _run_disconnect_callbacks
+
+        # TODO: Remove at next minor release
+        if respond_to?(:disconnected)
+          ActiveSupport::Deprecation.warn(
+            "The `disconnected` lifecycle method is being replaced by the " \
+            "`after_disconnect` callback and will no longer be automatically " \
+            "invoked in the next **minor release** of Motion."
+          )
+
+          send(:disconnected)
+        end
       end
 
-      def disconnected
+      def _run_action_callbacks(context:, &block)
+        @_action_callback_context = context
+
+        run_callbacks(:action, &block)
+      ensure
+        # `@_action_callback_context = nil` would still appear in the state
+        remove_instance_variable(:@_action_callback_context)
       end
     end
   end

data/lib/motion/component/motions.rb

@@ -47,10 +47,12 @@ module Motion
           raise MotionNotMapped.new(self, motion)
         end
 
-        if method(handler).arity.zero?
-          send(handler)
-        else
-          send(handler, event)
+        _run_action_callbacks(context: handler) do
+          if method(handler).arity.zero?
+            send(handler)
+          else
+            send(handler, event)
+          end
         end
       end
 

data/lib/motion/component/periodic_timers.rb

@@ -49,7 +49,9 @@ module Motion
       def process_periodic_timer(name)
         return unless (handler, _interval = _periodic_timers[name])
 
-        send(handler)
+        _run_action_callbacks(context: handler) do
+          send(handler)
+        end
       end
 
       private

data/lib/motion/component/rendering.rb

@@ -29,22 +29,28 @@ module Motion
 
       def render_in(view_context)
         raise BlockNotAllowedError, self if block_given?
-        clear_awaiting_forced_rerender!
 
-        html = view_context.capture { without_new_instance_variables { super } }
+        html =
+          _run_action_callbacks(context: :render) {
+            _clear_awaiting_forced_rerender!
+
+            view_context.capture { _without_new_instance_variables { super } }
+          }
+
+        raise RenderAborted, self if html == false
 
         Motion.markup_transformer.add_state_to_html(self, html)
       end
 
       private
 
-      def clear_awaiting_forced_rerender!
+      def _clear_awaiting_forced_rerender!
         return unless awaiting_forced_rerender?
 
         remove_instance_variable(RERENDER_MARKER_IVAR)
       end
 
-      def without_new_instance_variables
+      def _without_new_instance_variables
         existing_instance_variables = instance_variables
 
         yield

data/lib/motion/component_connection.rb

@@ -24,13 +24,13 @@ module Motion
       timing("Connected") do
         @render_hash = component.render_hash
 
-        component.connected
+        component.process_connect
       end
     end
 
     def close
       timing("Disconnected") do
-        component.disconnected
+        component.process_disconnect
       end
 
       true

data/lib/motion/configuration.rb

@@ -72,6 +72,10 @@ module Motion
       RevisionCalculator.new(revision_paths: revision_paths).perform
     end
 
+    # TODO: Is this always the correct key?
+    WARDEN_ENV = "warden"
+    private_constant :WARDEN_ENV
+
     option :renderer_for_connection_proc do
       ->(websocket_connection) do
         require "rack"
@@ -90,12 +94,15 @@ module Motion
         controller.renderer.new(
           websocket_connection.env.slice(
             Rack::HTTP_COOKIE,
-            Rack::RACK_SESSION
+            Rack::RACK_SESSION,
+            WARDEN_ENV
           )
         )
       end
     end
 
+    option(:error_notification_proc) { nil }
+
     option(:key_attribute) { "data-motion-key" }
     option(:state_attribute) { "data-motion-state" }
 

data/lib/motion/errors.rb

@@ -10,6 +10,7 @@ module Motion
 
     def initialize(component, message = nil)
       super(message)
+
       @component = component
     end
   end
@@ -20,13 +21,13 @@ module Motion
     attr_reader :motion
 
     def initialize(component, motion)
-      super(component, <<~MSG)
-        No component motion handler mapped for motion '#{motion}' in component #{component.class}.
-
-        Fix: Add the following to #{component.class}:
-
-        map_motion :#{motion}
-      MSG
+      super(
+        component,
+        "No component motion handler mapped for motion `#{motion}` in " \
+        "component `#{component.class}`.\n" \
+        "\n" \
+        "Hint: Consider adding `map_motion :#{motion}` to `#{component.class}`."
+      )
 
       @motion = motion
     end
@@ -34,20 +35,32 @@ module Motion
 
   class BlockNotAllowedError < ComponentRenderingError
     def initialize(component)
-      super(component, <<~MSG)
-        Motion does not support rendering with a block.
-
-        Fix: Use a plain component and wrap with a motion component.
-      MSG
+      super(
+        component,
+        "Motion does not support rendering with a block.\n" \
+        "\n" \
+        "Hint: Try wrapping a plain component with a motion component."
+      )
     end
   end
 
   class MultipleRootsError < ComponentRenderingError
     def initialize(component)
-      super(component, <<~MSG)
-        The template for #{component.class} can only have one root element.
+      super(
+        component,
+        "The template for #{component.class} can only have one root " \
+        "element.\n" \
+        "\n" \
+        "Hint: Wrap all elements in a single element, such as `<div>` or " \
+        "`<section>`."
+      )
+    end
+  end
 
-        Fix: Wrap all elements in a single element, such as <div> or <section>.
+  class RenderAborted < ComponentRenderingError
+    def initialize(component)
+      super(component, <<~MSG)
+        Rendering #{component.class} was aborted by a callback.
       MSG
     end
   end
@@ -56,18 +69,19 @@ module Motion
 
   class UnrepresentableStateError < InvalidComponentStateError
     def initialize(component, cause)
-      super(component, <<~MSG)
-        Some state prevented #{component.class} from being serialized into a
-        string. Motion components must be serializable using Marshal.dump. Many
-        types of objects are not serializable including procs, references to
-        anonymous classes, and more. See the documentation for Marshal.dump for
-        more information.
-
-        Fix: Ensure that any exotic state variables in #{component.class} are
-        removed or replaced.
-
-        The specific (but probably useless) error from Marshal was: #{cause}
-      MSG
+      super(
+        component,
+        "Some state prevented `#{component.class}` from being serialized " \
+        "into a string. Motion components must be serializable using " \
+        "`Marshal.dump`. Many types of objects are not serializable " \
+        "including procs, references to anonymous classes, and more. See the " \
+        "documentation for `Marshal.dump` for more information.\n" \
+        "\n" \
+        "The specific error from `Marshal.dump` was: #{cause}\n" \
+        "\n" \
+        "Hint: Ensure that any exotic state variables in " \
+        "`#{component.class}` are removed or replaced."
+      )
     end
   end
 
@@ -75,44 +89,48 @@ module Motion
 
   class InvalidSerializedStateError < SerializedComponentError
     def initialize
-      super(<<~MSG)
-        The serialized state of your component is not valid.
-
-        Fix: Ensure that you have not tampered with the DOM.
-      MSG
+      super(
+        "The serialized state of your component is not valid.\n" \
+        "\n" \
+        "Hint: Ensure that you have not tampered with the contents of data " \
+        "attributes added by Motion in the DOM or changed the value of " \
+        "`Motion.config.secret`."
+      )
     end
   end
 
-  class IncorrectRevisionError < SerializedComponentError
-    attr_reader :expected_revision,
-      :actual_revision
-
-    def initialize(expected_revision, actual_revision)
-      super(<<~MSG)
-        Cannot mount a component from another version of the application.
-
-        Expected revision `#{expected_revision}`;
-        Got `#{actual_revision}`
-
-        Read more: https://github.com/unabridged/motion/wiki/IncorrectRevisionError
-
-        Fix:
-          * Avoid tampering with Motion DOM elements and data attributes (e.g. data-motion-state).
-          * In production, enforce a page refresh for pages with Motion components on deploy.
-      MSG
-
-      @expected_revision = expected_revision
-      @actual_revision = actual_revision
+  class UpgradeNotImplementedError < ComponentError
+    attr_reader :previous_revision,
+      :current_revision
+
+    def initialize(component, previous_revision, current_revision)
+      super(
+        component,
+        "Cannot upgrade `#{component.class}` from a previous revision of the " \
+        "application (#{previous_revision}) to the current revision of the " \
+        "application (#{current_revision})\n" \
+        "\n" \
+        "By default, Motion does not allow components from other revisions " \
+        "of the application to be mounted because new code with old state " \
+        "can lead to unpredictable and unsafe behavior.\n" \
+        "\n" \
+        "Hint: If you would like to allow this component to surive " \
+        "deployments, consider providing an alternative implimentation for " \
+        "`#{component.class}.upgrade_from`."
+      )
+
+      @previous_revision = previous_revision
+      @current_revision = current_revision
     end
   end
 
   class AlreadyConfiguredError < Error
     def initialize
-      super(<<~MSG)
-        Motion is already configured.
-
-        Fix: Move all Motion config to config/initializers/motion.rb.
-      MSG
+      super(
+        "Motion is already configured.\n" \
+        "\n" \
+        "Hint: Move all Motion config to `config/initializers/motion.rb`."
+      )
     end
   end
 
@@ -120,12 +138,12 @@ module Motion
     attr_reader :server_version, :client_version
 
     def initialize(server_version, client_version)
-      super(<<~MSG)
-        The client version (#{client_version}) is newer than the server version
-        (#{server_version}). Please upgrade the Motion gem.
-
-        Fix: Run `bundle update motion`
-      MSG
+      super(
+        "The client version (#{client_version}) is newer than the server " \
+        "version (#{server_version}). Please upgrade the Motion gem.\n" \
+        "\n" \
+        "Hint: Run `bundle add motion --version \">= #{client_version}\"`."
+      )
 
       @server_version = server_version
       @client_version = client_version
@@ -136,26 +154,26 @@ module Motion
     attr_reader :minimum_bytes
 
     def initialize(minimum_bytes)
-      super(<<~MSG)
-        The secret that you provided is not long enough. It must have at least
-        #{minimum_bytes} bytes.
-      MSG
+      super(
+        "The secret that you provided is not long enough. It must be at " \
+        "least #{minimum_bytes} bytes long."
+      )
     end
   end
 
   class BadRevisionError < Error
     def initialize
-      super("The revision cannot contain a NULL byte")
+      super("The revision cannot contain a NULL byte.")
     end
   end
 
   class BadRevisionPathsError < Error
     def initialize
-      super(<<~MSG)
-        Revision paths must be a Rails::Paths::Root object or an object
-        that responds to `all_paths.flat_map(&:existent)` and returns an
-        Array of strings representing full paths.
-      MSG
+      super(
+        "Revision paths must be a `Rails::Paths::Root` object or an object " \
+        "that responds to `all_paths.flat_map(&:existent)` and returns an " \
+        "Array of strings representing full paths."
+      )
     end
   end
 end

data/lib/motion/log_helper.rb

@@ -29,6 +29,8 @@ module Motion
       error_info = error ? ":\n#{indent(format_exception(error))}" : ""
 
       logger.error("[#{tag}] #{message}#{error_info}")
+
+      Motion.notify_error(error, message)
     end
 
     def info(message)

data/lib/motion/markup_transformer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "nokogiri"
+require "active_support/core_ext/object/blank"
 
 require "motion"
 
@@ -21,7 +22,7 @@ module Motion
     end
 
     def add_state_to_html(component, html)
-      return html if html.blank?
+      return if html.blank?
 
       key, state = serializer.serialize(component)
 

data/lib/motion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Motion
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: motion
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Alec Larsen
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-08 00:00:00.000000000 Z
+date: 2020-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -86,7 +86,7 @@ metadata:
   source_code_uri: https://github.com/unabridged/motion
 post_install_message: |
   Friendly reminder: When updating the motion gem, don't forget to update the
-  NPM package as well (`bin/yarn add '@unabridged/motion@0.2.2'`).
+  NPM package as well (`bin/yarn add '@unabridged/motion@0.3.0'`).
 rdoc_options: []
 require_paths:
 - lib