motion 0.1.1

data/lib/motion/configuration.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  class Configuration
+    class << self
+      attr_reader :options
+
+      def default
+        @default ||= new
+      end
+
+      private
+
+      attr_writer :options
+
+      def option(option, &default)
+        define_option_reader(option, &default)
+        define_option_writer(option)
+
+        self.options = [*options, option].freeze
+      end
+
+      def define_option_reader(option, &default)
+        define_method(option) do
+          if instance_variable_defined?(:"@#{option}")
+            instance_variable_get(:"@#{option}")
+          else
+            instance_variable_set(:"@#{option}", instance_exec(&default))
+          end
+        end
+      end
+
+      def define_option_writer(option)
+        define_method(:"#{option}=") do |value|
+          raise AlreadyConfiguredError if @finalized
+
+          instance_variable_set(:"@#{option}", value)
+        end
+      end
+    end
+
+    def initialize
+      yield self if block_given?
+
+      # Ensure a value is selected for all options
+      self.class.options.each(&method(:public_send))
+
+      # Prevent further changes
+      @finalized = true
+    end
+
+    # //////////////////////////////////////////////////////////////////////////
+
+    option :secret do
+      require "rails"
+
+      Rails.application.key_generator.generate_key("motion:secret")
+    end
+
+    option :revision do
+      warn <<~MSG # TODO: Better message (Focus on "How do I fix this?")
+        Motion is automatically inferring the application's revision from git.
+        Depending on your deployment, this may not work for you in production.
+        If it does, add "config.revision = `git rev-parse HEAD`.chomp" to your
+        Motion initializer. If it does not, do something else (probably read an
+        env var or something).
+      MSG
+
+      `git rev-parse HEAD`.chomp
+    end
+
+    option :renderer_for_connection_proc do
+      ->(websocket_connection) do
+        require "rack"
+        require "action_controller"
+
+        # Make a special effort to use the host application's base controller
+        # in case the CSRF protection has been customized, but don't couple to
+        # a particular constant from the outer application.
+        controller =
+          if defined?(ApplicationController)
+            ApplicationController
+          else
+            ActionController::Base
+          end
+
+        controller.renderer.new(
+          websocket_connection.env.slice(
+            Rack::HTTP_COOKIE,
+            Rack::RACK_SESSION
+          )
+        )
+      end
+    end
+
+    option(:stimulus_controller_identifier) { "motion" }
+    option(:key_attribute) { "data-motion-key" }
+    option(:state_attribute) { "data-motion-state" }
+
+    # This is included for completeness. It is not currently used internally by
+    # Motion, but it might be required for building view helpers in the future.
+    option(:motion_attribute) { "data-motion" }
+  end
+end

data/lib/motion/element.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  class Element
+    def self.from_raw(raw)
+      new(raw) if raw
+    end
+
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw.freeze
+    end
+
+    def tag_name
+      raw["tagName"]
+    end
+
+    def value
+      raw["value"]
+    end
+
+    def attributes
+      raw.fetch("attributes", {})
+    end
+
+    def [](key)
+      key = key.to_s
+
+      attributes[key] || attributes[key.tr("_", "-")]
+    end
+
+    def id
+      self[:id]
+    end
+
+    class DataAttributes
+      attr_reader :element
+
+      def initialize(element)
+        @element = element
+      end
+
+      def [](data)
+        element["data-#{data}"]
+      end
+    end
+
+    private_constant :DataAttributes
+
+    def data
+      return @data if defined?(@data)
+
+      @data = DataAttributes.new(self)
+    end
+
+    def form_data
+      return @form_data if defined?(@form_data)
+
+      @form_data =
+        ActionController::Parameters.new(
+          Rack::Utils.parse_nested_query(
+            raw.fetch("formData", "")
+          )
+        )
+    end
+  end
+end

data/lib/motion/errors.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  class Error < StandardError; end
+
+  class ComponentError < Error
+    attr_reader :component
+
+    def initialize(component, message = nil)
+      super(message)
+      @component = component
+    end
+  end
+
+  class ComponentRenderingError < ComponentError; end
+
+  class MotionNotMapped < ComponentError
+    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
+
+      @motion = motion
+    end
+  end
+
+  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
+    end
+  end
+
+  class MultipleRootsError < ComponentRenderingError
+    def initialize(component)
+      super(component, <<~MSG)
+        The template for #{component.class} can only have one root element.
+
+        Fix: Wrap all elements in a single element, such as <div> or <section>.
+      MSG
+    end
+  end
+
+  class InvalidComponentStateError < ComponentError; end
+
+  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
+    end
+  end
+
+  class SerializedComponentError < Error; end
+
+  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
+    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
+    end
+  end
+
+  class AlreadyConfiguredError < Error
+    def initialize
+      super(<<~MSG)
+        Motion is already configured.
+
+        Fix: Move all Motion config to config/initializers/motion.rb.
+      MSG
+    end
+  end
+
+  class IncompatibleClientError < Error
+    attr_reader :expected_version,
+      :actual_version
+
+    def initialize(expected_version, actual_version)
+      super(<<~MSG)
+        Expected client version #{expected_version}, but got #{actual_version}.
+
+        Fix: Run `bin/yarn add @unabridged/motion@#{expected_version}`
+      MSG
+    end
+  end
+
+  class BadSecretError < Error
+    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
+    end
+  end
+
+  class BadRevisionError < Error
+    def initialize
+      super("The revision cannot contain a NULL byte")
+    end
+  end
+end

data/lib/motion/event.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  class Event
+    def self.from_raw(raw)
+      new(raw) if raw
+    end
+
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw.freeze
+    end
+
+    def type
+      raw["type"]
+    end
+
+    alias name type
+
+    def details
+      raw.fetch("details", {})
+    end
+
+    def extra_data
+      raw["extraData"]
+    end
+
+    def target
+      return @target if defined?(@target)
+
+      @target = Motion::Element.from_raw(raw["target"])
+    end
+
+    def form_data
+      target&.form_data
+    end
+  end
+end

data/lib/motion/log_helper.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_support/core_ext/string/indent"
+
+require "motion"
+
+module Motion
+  class LogHelper
+    BACKTRACE_FRAMES = 5
+    DEFAULT_TAG = "Motion"
+
+    def self.for_channel(channel, logger: channel.connection.logger)
+      new(logger: logger, tag: DEFAULT_TAG)
+    end
+
+    def self.for_component(component, logger: nil)
+      new(logger: logger, tag: "#{component.class}:#{component.object_id}")
+    end
+
+    attr_reader :logger, :tag
+
+    def initialize(logger: nil, tag: nil)
+      @logger = logger || Rails.logger
+      @tag = tag || DEFAULT_TAG
+    end
+
+    def error(message, error: nil)
+      error_info = error ? ":\n#{indent(format_exception(error))}" : ""
+
+      logger.error("[#{tag}] #{message}#{error_info}")
+    end
+
+    def info(message)
+      logger.info("[#{tag}] #{message}")
+    end
+
+    def timing(message)
+      start_time = Time.now
+      result = yield
+      end_time = Time.now
+
+      info("#{message} (in #{format_duration(end_time - start_time)})")
+
+      result
+    end
+
+    def for_component(component)
+      self.class.for_component(component, logger: logger)
+    end
+
+    private
+
+    def format_exception(exception)
+      frames = exception.backtrace.first(BACKTRACE_FRAMES).join("\n")
+
+      "#{exception.class}: #{exception}\n#{indent(frames)}"
+    end
+
+    def format_duration(duration)
+      duration_ms = duration * 1000
+
+      if duration_ms < 0.1
+        "less than 0.1ms"
+      else
+        "#{duration_ms.round(1)}ms"
+      end
+    end
+
+    def indent(string)
+      string.indent(1, "\t")
+    end
+  end
+end

data/lib/motion/markup_transformer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+require "motion"
+
+module Motion
+  class MarkupTransformer
+    STIMULUS_CONTROLLER_ATTRIBUTE = "data-controller"
+
+    attr_reader :serializer,
+      :stimulus_controller_identifier,
+      :key_attribute,
+      :state_attribute
+
+    def initialize(
+      serializer: Motion.serializer,
+      stimulus_controller_identifier:
+        Motion.config.stimulus_controller_identifier,
+      key_attribute: Motion.config.key_attribute,
+      state_attribute: Motion.config.state_attribute
+    )
+      @serializer = serializer
+      @stimulus_controller_identifier = stimulus_controller_identifier
+      @key_attribute = key_attribute
+      @state_attribute = state_attribute
+    end
+
+    def add_state_to_html(component, html)
+      key, state = serializer.serialize(component)
+
+      transform_root(component, html) do |root|
+        root[STIMULUS_CONTROLLER_ATTRIBUTE] =
+          values(
+            stimulus_controller_identifier,
+            root[STIMULUS_CONTROLLER_ATTRIBUTE]
+          )
+
+        root[key_attribute] = key
+        root[state_attribute] = state
+      end
+    end
+
+    private
+
+    def transform_root(component, html)
+      fragment = Nokogiri::HTML::DocumentFragment.parse(html)
+      root, *unexpected_others = fragment.children
+
+      raise MultipleRootsError, component if unexpected_others.any?(&:present?)
+
+      yield root
+
+      fragment.to_html.html_safe
+    end
+
+    def values(*values, delimiter: " ")
+      values
+        .compact
+        .flat_map { |value| value.split(delimiter) }
+        .uniq
+        .join(delimiter)
+    end
+  end
+end

data/lib/motion/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  class MyRailtie < Rails::Railtie
+    generators do
+      require "generators/motion/install_generator"
+    end
+  end
+end

data/lib/motion/serializer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "digest"
+require "active_support/message_encryptor"
+
+require "motion"
+
+module Motion
+  class Serializer
+    HASH_PEPPER = "Motion"
+    private_constant :HASH_PEPPER
+
+    NULL_BYTE = "\0"
+
+    attr_reader :secret, :revision
+
+    def self.minimum_secret_byte_length
+      ActiveSupport::MessageEncryptor.key_len
+    end
+
+    def initialize(
+      secret: Motion.config.secret,
+      revision: Motion.config.revision
+    )
+      unless secret.each_byte.count >= self.class.minimum_secret_byte_length
+        raise BadSecretError.new(self.class.minimum_secret_byte_length)
+      end
+
+      raise BadRevisionError if revision.include?(NULL_BYTE)
+
+      @secret = secret
+      @revision = revision
+    end
+
+    def serialize(component)
+      state = dump(component)
+      state_with_revision = "#{revision}#{NULL_BYTE}#{state}"
+
+      [
+        salted_digest(state_with_revision),
+        encrypt_and_sign(state_with_revision)
+      ]
+    end
+
+    def deserialize(serialized_component)
+      state_with_revision = decrypt_and_verify(serialized_component)
+      serialized_revision, state = state_with_revision.split(NULL_BYTE, 2)
+      component = load(state)
+
+      if revision == serialized_revision
+        component
+      else
+        component.class.upgrade_from(serialized_revision, component)
+      end
+    end
+
+    private
+
+    def dump(component)
+      Marshal.dump(component)
+    rescue TypeError => e
+      raise UnrepresentableStateError.new(component, e.message)
+    end
+
+    def load(state)
+      Marshal.load(state)
+    end
+
+    def encrypt_and_sign(cleartext)
+      encryptor.encrypt_and_sign(cleartext)
+    end
+
+    def decrypt_and_verify(cypertext)
+      encryptor.decrypt_and_verify(cypertext)
+    rescue ActiveSupport::MessageEncryptor::InvalidMessage,
+      ActiveSupport::MessageVerifier::InvalidSignature
+      raise InvalidSerializedStateError
+    end
+
+    def salted_digest(input)
+      Digest::SHA256.base64digest(hash_salt + input)
+    end
+
+    def encryptor
+      @encryptor ||= ActiveSupport::MessageEncryptor.new(derive_encryptor_key)
+    end
+
+    def hash_salt
+      @hash_salt ||= derive_hash_salt
+    end
+
+    def derive_encryptor_key
+      secret.byteslice(0, self.class.minimum_secret_byte_length)
+    end
+
+    def derive_hash_salt
+      Digest::SHA256.digest(HASH_PEPPER + secret)
+    end
+  end
+end

data/lib/motion/test_helpers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "motion"
+
+module Motion
+  module TestHelpers
+    def assert_motion(component, motion_name)
+      assert motion?(component, motion_name)
+    end
+
+    def refute_motion(component, motion_name)
+      refute motion?(component, motion_name)
+    end
+
+    def motion?(component, motion_name)
+      component.motions.include?(motion_name.to_s)
+    end
+
+    def run_motion(component, motion_name)
+      if block_given?
+        c = component.dup
+        c.process_motion(motion_name.to_s)
+        yield c
+      else
+        component.process_motion(motion_name.to_s)
+      end
+    end
+  end
+end

data/lib/motion/version.rb

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

data/lib/motion.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "motion/version"
+require "motion/errors"
+
+module Motion
+  autoload :ActionCableExtentions, "motion/action_cable_extentions"
+  autoload :Channel, "motion/channel"
+  autoload :Component, "motion/component"
+  autoload :ComponentConnection, "motion/component_connection"
+  autoload :Configuration, "motion/configuration"
+  autoload :Element, "motion/element"
+  autoload :Event, "motion/event"
+  autoload :LogHelper, "motion/log_helper"
+  autoload :MarkupTransformer, "motion/markup_transformer"
+  autoload :Railtie, "motion/railtie"
+  autoload :Serializer, "motion/serializer"
+  autoload :TestHelpers, "motion/test_helpers"
+
+  def self.configure(&block)
+    raise AlreadyConfiguredError if @config
+
+    @config = Configuration.new(&block)
+  end
+
+  def self.config
+    @config ||= Configuration.default
+  end
+
+  singleton_class.alias_method :configuration, :config
+
+  def self.serializer
+    @serializer ||= Serializer.new
+  end
+
+  def self.markup_transformer
+    @markup_transformer ||= MarkupTransformer.new
+  end
+
+  def self.build_renderer_for(websocket_connection)
+    config.renderer_for_connection_proc.call(websocket_connection)
+  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.
+  def self.reset_internal_state_for_testing!(new_configuration = nil)
+    @config = new_configuration
+    @serializer = nil
+    @markup_transformer = nil
+  end
+end
+
+require "motion/railtie" if defined?(Rails)