motion 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2c9776bff100e3017a158810f93d3c374d97e6df42b8d9ffee43bf96da624b5b
+  data.tar.gz: a0764632d832cd96b58b3ffa5c28e9598d09136b0dbe6eadc66ab074bc18d5bd
+SHA512:
+  metadata.gz: b5a0955da6087872bd9ec9940b8b3a674bf6fd2782ccad6b72460255703ff810e06e3d62ea99484a6c95d6fb48883953bbdec1cb3224af2513006ba60d5f3c54
+  data.tar.gz: a0360a0b1a0422b38f5bd4f9a46ba203ed9f1d3a1a6adf6073c89ff77152c0ae5cf212d097e6ad8b864f2bf220772511887db3c1692d7c4b7be3d3f54be01ec5

data/lib/generators/motion/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Motion
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs Motion into your application."
+
+      def copy_initializer
+        template(
+          "motion.rb",
+          "config/initializers/motion.rb"
+        )
+      end
+
+      def copy_stimlus_controller
+        template(
+          "motion_controller.js",
+          "app/javascript/controllers/motion_controller.js"
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# TODO: Explain all the options.
+Motion.configure do |config|
+  # config.secret = Rails.application.key_generator.generate_key "motion:secret"
+
+  # config.revision = `git rev-parse HEAD`.chomp
+
+  # config.renderer_for_connection_proc = ->(websocket_connection) do
+  #   ApplicationController.renderer.new(
+  #     websocket_connection.env.slice(
+  #       Rack::HTTP_COOKIE,
+  #       Rack::RACK_SESSION,
+  #     )
+  #   )
+  # end
+
+  # config.stimulus_controller_identifier = "motion"
+  # config.key_attribute = "data-motion-key"
+  # config.state_attribute = "data-motion-state"
+  # config.motion_attribute = "data-motion"
+end

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

@@ -0,0 +1,28 @@
+import { Controller } from "@unabridged/motion";
+import consumer from "../channels/consumer";
+
+// If you change the name of this controller (determined by the file name),
+// make sure to update `Motion.config.stimulus_controller_identifier`.
+export default class extends Controller {
+  // To avoid creating a second websocket, make sure to reuse the application's
+  // ActionCable consumer.
+  getConsumer() {
+      return consumer;
+  }
+
+  // It is possible to additionally customize the behavior of the client by
+  // overriding these properties and methods:
+
+  // getExtraDataForEvent(event) {}        // `Motion::Event#extra_data`
+
+  // keyAttribute = "data-motion-key";     // `Motion.config.key_attribute`
+  // stateAttribute = "data-motion-state"; // `Motion.config.state_attribute`
+  // motionAttribute = "data-motion";      // `Motion.config.motion_attribute`
+
+  // beforeConnect() { /* by default, dispatches `motion:before-connect`    */ }
+  // connected()     { /* by default, dispatches `motion:connected`         */ }
+  // connectFailed() { /* by default, dispatches `motion:connect-failed`    */ }
+  // disconnected()  { /* by default, dispatches `motion:disconnected`      */ }
+  // beforeRender()  { /* by default, dispatches `motion:before-render`     */ }
+  // rendered()      { /* by default, dispatches `motion:rendered`          */ }
+}

data/lib/motion/action_cable_extentions/declarative_streams.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "motion"
+
+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.
+    module DeclarativeStreams
+      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
+
+        # The method we are currently routing those streams to
+        @_declarative_stream_target = nil
+
+        # Streams that we are setup to listen to. Sadly, there is no public API
+        # to stop streaming so this will only grow.
+        @_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
+
+        @_declarative_streams.clear
+        @_declarative_stream_target = nil
+
+        @_declarative_stream_proxies.clear
+      end
+
+      # Declaratively routes provided broadcasts to the provided method.
+      def streaming_from(broadcasts, to:)
+        @_declarative_streams.replace(broadcasts)
+        @_declarative_stream_target = to
+
+        @_declarative_streams.each(&method(:_ensure_declarative_stream_proxy))
+      end
+
+      def declarative_stream_target
+        @_declarative_stream_target
+      end
+
+      private
+
+      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)
+        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
+
+      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")}"
+        )
+      end
+    end
+  end
+end

data/lib/motion/action_cable_extentions/log_suppression.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  module ActionCableExtentions
+    # By default ActionCable logs a lot. This module suppresses the debugging
+    # information on a _per channel_ basis.
+    module LogSuppression
+      class Suppressor < SimpleDelegator
+        def info(*)
+        end
+
+        def debug(*)
+        end
+      end
+
+      private_constant :Suppressor
+
+      def initialize(*)
+        super
+
+        @_logger = Suppressor.new(logger)
+      end
+
+      def logger
+        return super unless defined?(@_logger)
+
+        @_logger
+      end
+    end
+  end
+end

data/lib/motion/action_cable_extentions.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  module ActionCableExtentions
+    autoload :DeclarativeStreams,
+      "motion/action_cable_extentions/declarative_streams"
+
+    autoload :LogSuppression,
+      "motion/action_cable_extentions/log_suppression"
+  end
+end

data/lib/motion/channel.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "action_cable"
+
+require "motion"
+
+module Motion
+  class Channel < ActionCable::Channel::Base
+    include ActionCableExtentions::DeclarativeStreams
+    include ActionCableExtentions::LogSuppression
+
+    ACTION_METHODS = Set.new(["process_motion"]).freeze
+    private_constant :ACTION_METHODS
+
+    # Don't use the ActionCable huertistic for deciding what actions can be
+    # called from JavaScript. Instead, hard-code the list so we can make other
+    # methods public without worrying about them being called from JavaScript.
+    def self.action_methods
+      ACTION_METHODS
+    end
+
+    attr_reader :component_connection
+
+    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
+        raise IncompatibleClientError.new(Motion::VERSION, client_version)
+      end
+
+      @component_connection =
+        ComponentConnection.from_state(state, log_helper: log_helper)
+
+      synchronize
+    rescue => error
+      reject
+
+      handle_error(error, "connecting a component")
+    end
+
+    def unsubscribed
+      component_connection&.close
+
+      @component_connection = nil
+    end
+
+    def process_motion(data)
+      motion, raw_event = data.values_at("name", "event")
+
+      component_connection.process_motion(motion, Event.from_raw(raw_event))
+      synchronize
+    end
+
+    def process_broadcast(broadcast, message)
+      component_connection.process_broadcast(broadcast, message)
+      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
+    end
+
+    def handle_error(error, context)
+      log_helper.error("An error occurred while #{context}", error: error)
+    end
+
+    def log_helper
+      @log_helper ||= LogHelper.for_channel(self)
+    end
+
+    # Memoize the renderer on the connection so that it can be shared accross
+    # all components. `ActionController::Renderer` is already thread-safe and
+    # designed to be reused.
+    def renderer
+      connection.instance_eval do
+        @_motion_renderer ||= Motion.build_renderer_for(self)
+      end
+    end
+  end
+end

data/lib/motion/component/broadcasts.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/object/to_param"
+
+require "motion"
+
+module Motion
+  module Component
+    module Broadcasts
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_broadcast_handlers,
+          instance_reader: false,
+          instance_writer: false,
+          instance_predicate: false,
+          default: {}.freeze
+      end
+
+      class_methods do
+        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
+        def serialize_broadcasting(object)
+          if object.is_a?(Array)
+            object.map { |m| serialize_broadcasting(m) }.join(":")
+          elsif object.respond_to?(:to_gid_param)
+            object.to_gid_param
+          else
+            object.to_param
+          end
+        end
+      end
+
+      def broadcasts
+        _broadcast_handlers.keys
+      end
+
+      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)
+      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(self.class.broadcasting_for(model), handler)
+      end
+
+      private
+
+      attr_writer :_broadcast_handlers
+
+      def _broadcast_handlers
+        return @_broadcast_handlers if defined?(@_broadcast_handlers)
+
+        self.class._broadcast_handlers
+      end
+    end
+  end
+end

data/lib/motion/component/lifecycle.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+require "motion"
+
+module Motion
+  module Component
+    module Lifecycle
+      extend ActiveSupport::Concern
+
+      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
+          )
+        end
+      end
+
+      def connected
+      end
+
+      def disconnected
+      end
+    end
+  end
+end

data/lib/motion/component/motions.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+require "motion"
+
+module Motion
+  module Component
+    module Motions
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_motion_handlers,
+          instance_reader: false,
+          instance_writer: false,
+          instance_predicate: false,
+          default: {}.freeze
+      end
+
+      class_methods do
+        def map_motion(motion, handler = motion)
+          self._motion_handlers =
+            _motion_handlers.merge(motion.to_s => handler.to_sym).freeze
+        end
+      end
+
+      def motions
+        _motion_handlers.keys
+      end
+
+      def process_motion(motion, event = nil)
+        unless (handler = _motion_handlers[motion])
+          raise MotionNotMapped.new(self, motion)
+        end
+
+        if method(handler).arity.zero?
+          send(handler)
+        else
+          send(handler, event)
+        end
+      end
+
+      def map_motion(motion, handler = motion)
+        self._motion_handlers =
+          _motion_handlers.merge(motion.to_s => handler.to_sym).freeze
+      end
+
+      private
+
+      attr_writer :_motion_handlers
+
+      def _motion_handlers
+        return @_motion_handlers if defined?(@_motion_handlers)
+
+        self.class._motion_handlers
+      end
+    end
+  end
+end

data/lib/motion/component/rendering.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  module Component
+    module Rendering
+      # Use the presence/absence of the ivar instead of true/false to avoid
+      # extra serialized state (Note that in this scheme, the presence of
+      # the ivar will never be serialized).
+      RERENDER_MARKER_IVAR = :@__awaiting_forced_rerender__
+      private_constant :RERENDER_MARKER_IVAR
+
+      def rerender!
+        instance_variable_set(RERENDER_MARKER_IVAR, true)
+      end
+
+      def awaiting_forced_rerender?
+        instance_variable_defined?(RERENDER_MARKER_IVAR)
+      end
+
+      # * This can be overwritten.
+      # * It will _not_ be sent to the client.
+      # * If it doesn't change every time the component's state changes,
+      #   things may fall out of sync unless you also call `#rerender!`
+      def render_hash
+        # TODO: This implementation is trivially correct, but very wasteful.
+        #
+        # Is something with Ruby's built-in `hash` Good Enough(TM)?
+        #
+        #  instance_variables
+        #    .map { |ivar| instance_variable_get(ivar).hash }
+        #    .reduce(0, &:^)
+
+        key, _state = Motion.serializer.serialize(self)
+        key
+      end
+
+      def render_in(view_context)
+        raise BlockNotAllowedError, self if block_given?
+        clear_awaiting_forced_rerender!
+
+        html = view_context.capture { without_new_instance_variables { super } }
+
+        Motion.markup_transformer.add_state_to_html(self, html)
+      end
+
+      private
+
+      def clear_awaiting_forced_rerender!
+        return unless awaiting_forced_rerender?
+
+        remove_instance_variable(RERENDER_MARKER_IVAR)
+      end
+
+      def without_new_instance_variables
+        existing_instance_variables = instance_variables
+
+        yield
+      ensure
+        (instance_variables - existing_instance_variables)
+          .each(&method(:remove_instance_variable))
+      end
+    end
+  end
+end

data/lib/motion/component.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+require "motion"
+
+require "motion/component/broadcasts"
+require "motion/component/lifecycle"
+require "motion/component/motions"
+require "motion/component/rendering"
+
+module Motion
+  module Component
+    extend ActiveSupport::Concern
+
+    include Broadcasts
+    include Lifecycle
+    include Motions
+    include Rendering
+  end
+end

data/lib/motion/component_connection.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  class ComponentConnection
+    def self.from_state(
+      state,
+      serializer: Motion.serializer,
+      log_helper: LogHelper.new,
+      **kargs
+    )
+      component = serializer.deserialize(state)
+
+      new(component, log_helper: log_helper.for_component(component), **kargs)
+    end
+
+    attr_reader :component
+
+    def initialize(component, log_helper: LogHelper.for_component(component))
+      @component = component
+      @log_helper = log_helper
+
+      timing("Connected") do
+        @render_hash = component.render_hash
+
+        component.connected
+      end
+    end
+
+    def close
+      timing("Disconnected") do
+        component.disconnected
+      end
+
+      true
+    rescue => error
+      handle_error(error, "disconnecting the component")
+
+      false
+    end
+
+    def process_motion(motion, event = nil)
+      timing("Proccessed #{motion}") do
+        component.process_motion(motion, event)
+      end
+
+      true
+    rescue => error
+      handle_error(error, "processing #{motion}")
+
+      false
+    end
+
+    def process_broadcast(broadcast, message)
+      timing("Proccessed broadcast to #{broadcast}") do
+        component.process_broadcast broadcast, message
+      end
+
+      true
+    rescue => error
+      handle_error(error, "processing a broadcast to #{broadcast}")
+
+      false
+    end
+
+    def if_render_required(&block)
+      timing("Rendered") do
+        next_render_hash = component.render_hash
+
+        return if @render_hash == next_render_hash &&
+          !component.awaiting_forced_rerender?
+
+        yield(component)
+
+        @render_hash = next_render_hash
+      end
+    rescue => error
+      handle_error(error, "rendering the component")
+    end
+
+    def broadcasts
+      component.broadcasts
+    end
+
+    private
+
+    attr_reader :log_helper
+
+    def timing(context, &block)
+      log_helper.timing(context, &block)
+    end
+
+    def handle_error(error, context)
+      log_helper.error("An error occurred while #{context}", error: error)
+    end
+  end
+end