turbo_reflex 0.0.9 → 0.0.11

data/app/javascript/state/index.js

@@ -0,0 +1,52 @@
+import meta from '../meta'
+import observable from './observable'
+import { stateEvents as events } from '../events'
+
+let oldState, state, changedState
+let observer
+
+function loadState () {
+  const json = atob(meta.element.dataset.state)
+  changedState = {}
+  oldState = state = observable(JSON.parse(json))
+}
+
+function initObserver () {
+  if (observer) observer.disconnect()
+  observer = new MutationObserver(loadState)
+  observer.observe(meta.element, {
+    attributes: true,
+    attributeFilter: ['data-state']
+  })
+}
+
+addEventListener('DOMContentLoaded', loadState)
+addEventListener('DOMContentLoaded', initObserver)
+addEventListener('turbo:load', initObserver)
+addEventListener('turbo:frame-load', initObserver)
+
+addEventListener(
+  events.beforeStateChange,
+  event => (oldState = JSON.parse(JSON.stringify(state)))
+)
+
+addEventListener(events.stateChange, event => {
+  changedState = {}
+  for (const [key, value] of Object.entries(state))
+    if (oldState[key] !== value) changedState[key] = value
+  meta.element.dataset.state = btoa(JSON.stringify(state))
+})
+
+export { state }
+export default {
+  events,
+
+  // The UI state changes are split into chunks and sent to the server in an HTTP request header.
+  // Max size for an HTTP header is around 4k or 4,000 bytes.
+  // A Base64 character is an 8-bit-padded ASCII character... or 1 byte
+  //
+  // SEE: lib/state.rb - for info on how `state` is serialized/deserialized
+  get payloadChunks () {
+    return btoa(JSON.stringify(changedState)).match(/.{1,2000}/g)
+  }
+}

data/app/javascript/state/observable.js

@@ -0,0 +1,36 @@
+import meta from '../meta'
+import { dispatch, stateEvents as events } from '../events'
+
+let head
+
+function observable (object, parent = null) {
+  if (!object || typeof object !== 'object') return object
+
+  const proxy = new Proxy(object, {
+    deleteProperty (target, key) {
+      dispatch(events.beforeStateChange, meta.element, { state: head })
+      delete target[key]
+      dispatch(events.stateChange, meta.element, { state: head })
+      return true
+    },
+
+    set (target, key, value, receiver) {
+      dispatch(events.beforeStateChange, meta.element, { state: head })
+      target[key] = observable(value, this)
+      dispatch(events.stateChange, meta.element, { state: head })
+      return true
+    }
+  })
+
+  if (Array.isArray(object)) {
+    object.forEach((value, index) => (object[index] = observable(value, proxy)))
+  } else if (typeof object === 'object') {
+    for (const [key, value] of Object.entries(object))
+      object[key] = observable(value, proxy)
+  }
+
+  if (!parent) head = proxy
+  return proxy
+}
+
+export default observable

data/app/javascript/turbo.js

@@ -1,5 +1,7 @@
 import meta from './meta'
+import state from './state'
 import renderer from './renderer'
+import { dispatch } from './events'
 import lifecycle from './lifecycle'
 
 const frameSources = {}
@@ -8,6 +10,8 @@ const frameSources = {}
 addEventListener('turbo:before-fetch-request', event => {
   const frame = event.target.closest('turbo-frame')
   const { fetchOptions } = event.detail
+
+  // reflex invoked and busy
   if (meta.busy) {
     let acceptHeaders = [
       'text/vnd.turbo-reflex.html',
@@ -17,12 +21,14 @@ addEventListener('turbo:before-fetch-request', event => {
       .filter(entry => entry && entry.trim().length > 0)
       .join(', ')
     fetchOptions.headers['Accept'] = acceptHeaders
+    fetchOptions.headers['TurboReflex-Token'] = meta.token
   }
-  fetchOptions.headers['TurboReflex-Token'] = meta.token
-  meta.uiStateBase64Chunks.forEach(
+
+  // always send state
+  state.payloadChunks.forEach(
     (chunk, i) =>
       (fetchOptions.headers[
-        `TurboReflex-UiState-${i.toString().padStart(6, '0')}`
+        `TurboReflex-State-${i.toString().padStart(4, '0')}`
       ] = chunk)
   )
 })
@@ -37,7 +43,12 @@ addEventListener('turbo:before-fetch-response', event => {
   if (response.header('TurboReflex')) {
     if (response.statusCode < 200 || response.statusCode > 399) {
       const error = `Server returned a ${response.statusCode} status code! TurboReflex requires 2XX-3XX status codes.`
-      lifecycle.dispatchClientError({ ...event.detail, error })
+      dispatch(
+        lifecycle.events.clientError,
+        document,
+        { ...event.detail, error },
+        true
+      )
     }
 
     if (response.header('TurboReflex') === 'Append') {

data/lib/turbo_reflex/base.rb

@@ -6,18 +6,19 @@
 # Reflexes are executed via a before_action in the Rails controller lifecycle.
 # They have access to the following methods and properties.
 #
-# * dom_id ....................... The Rails dom_id helper
-# * dom_id_selector .............. Returns a CSS selector for a dom_id
-# * controller ................... The Rails controller processing the HTTP request
-# * element ...................... A struct that represents the DOM element that triggered the reflex
-# * params ....................... Reflex specific params (frame_id, element, etc.)
-# * render ....................... Renders Rails templates, partials, etc. (doesn't halt controller request handling)
-# * render_response .............. Renders a full controller response
-# * renderer ..................... An ActionController::Renderer
-# * prevent_controller_action .... Prevents the rails controller/action from running (i.e. the reflex handles the response entirely)
-# * turbo_stream ................. A Turbo Stream TagBuilder
-# * turbo_streams ................ A list of Turbo Streams to append to the response (also aliased as streams)
-# * ui_state ..................... An object that stores ephemeral UI state
+# * dom_id ...................... The Rails dom_id helper
+# * dom_id_selector ............. Returns a CSS selector for a dom_id
+# * controller .................. The Rails controller processing the HTTP request
+# * element ..................... A struct that represents the DOM element that triggered the reflex
+# * morph ....................... Appends a Turbo Stream to morph a DOM element
+# * params ...................... Reflex specific params (frame_id, element, etc.)
+# * render ...................... Renders Rails templates, partials, etc. (doesn't halt controller request handling)
+# * render_response ............. Renders a full controller response
+# * renderer .................... An ActionController::Renderer
+# * prevent_controller_action ... Prevents the rails controller/action from running (i.e. the reflex handles the response entirely)
+# * turbo_stream ................ A Turbo Stream TagBuilder
+# * turbo_streams ............... A list of Turbo Streams to append to the response (also aliased as streams)
+# * state ....................... An object that stores ephemeral `state`
 #
 class TurboReflex::Base
   class << self
@@ -64,13 +65,12 @@ class TurboReflex::Base
   attr_reader :controller, :turbo_streams
   alias_method :streams, :turbo_streams
 
-  delegate :dom_id, to: :"controller.view_context"
-  delegate :render, to: :renderer
+  delegate :dom_id, :render, to: :"controller.view_context"
   delegate(
     :controller_action_prevented?,
     :render_response,
     :turbo_stream,
-    :ui_state,
+    :state,
     to: :@runner
   )
 
@@ -84,6 +84,10 @@ class TurboReflex::Base
     "##{dom_id(...)}"
   end
 
+  def morph(selector, html)
+    turbo_streams << turbo_stream.invoke("morph", args: [html], selector: selector)
+  end
+
   # default reflex invoked when method not specified
   def noop
   end
@@ -96,22 +100,22 @@ class TurboReflex::Base
     @element ||= begin
       attributes = params[:element_attributes]
       attrs = attributes.keys.each_with_object({}) do |key, memo|
+        memo[:aria] ||= {}
         memo[:dataset] ||= {}
         if key.start_with?("data_")
           memo[:dataset][key[5..].parameterize.underscore.to_sym] = attributes[key]
+        elsif key.start_with?("aria_")
+          memo[:aria][key[5..].parameterize.underscore.to_sym] = attributes[key]
         else
           memo[key.parameterize.underscore.to_sym] = attributes[key]
         end
       end
-      attrs[:dataset] = Struct.new(*attrs[:dataset].keys).new(*attrs[:dataset].values)
-      Struct.new(*attrs.keys).new(*attrs.values)
+      attrs[:aria] = OpenStruct.new(attrs[:aria])
+      attrs[:dataset] = OpenStruct.new(attrs[:dataset])
+      OpenStruct.new attrs
     end
   end
 
-  def renderer
-    ActionController::Renderer.for controller.class, controller.request.env
-  end
-
   def should_prevent_controller_action?(method_name)
     self.class.should_prevent_controller_action? self, method_name
   end

data/lib/turbo_reflex/controller_pack.rb

@@ -15,7 +15,7 @@ class TurboReflex::ControllerPack
     :controller_action_prevented?,
     :meta_tag,
     :run,
-    :ui_state,
+    :state,
     :update_response,
     to: :runner
   )

data/lib/turbo_reflex/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module TurboReflex
+  class InvalidClassError < StandardError
+  end
+
+  class InvalidMethodError < StandardError
+  end
+
+  class InvalidTokenError < StandardError
+  end
+end

data/lib/turbo_reflex/runner.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
+require_relative "errors"
 require_relative "sanitizer"
-require_relative "ui_state"
+require_relative "state_manager"
 
 class TurboReflex::Runner
-  attr_reader :controller, :ui_state
+  attr_reader :controller, :state_manager
+  alias_method :state, :state_manager
 
   delegate_missing_to :controller
 
   def initialize(controller)
     @controller = controller
-    @ui_state = TurboReflex::UiState.new(controller)
+    @state_manager = TurboReflex::StateManager.new(self)
   end
 
   def meta_tag
@@ -19,7 +21,7 @@ class TurboReflex::Runner
       id: "turbo-reflex",
       name: "turbo-reflex",
       content: masked_token,
-      data: {busy: false, ui_state: ui_state.serialize}
+      data: {busy: false, state: state_manager.payload}
     }
     view_context.tag("meta", options).html_safe
   end
@@ -30,9 +32,26 @@ class TurboReflex::Runner
 
   def reflex_valid?
     return false unless reflex_requested?
-    return false unless valid_client_token?
-    return false unless reflex_instance.is_a?(TurboReflex::Base)
-    reflex_instance.respond_to? reflex_method_name
+
+    # validate class
+    unless reflex_instance.is_a?(TurboReflex::Base)
+      raise TurboReflex::InvalidClassError,
+        "`#{reflex_class_name}` is not a subclass of `TurboReflex::Base`!"
+    end
+
+    # validate method
+    unless reflex_instance.respond_to?(reflex_method_name)
+      raise TurboReflex::InvalidMethodError,
+        "`#{reflex_class_name}` does not define the public method `#{reflex_method_name}`!"
+    end
+
+    # validate csrf token
+    unless valid_client_token?
+      raise TurboReflex::InvalidTokenError,
+        "CSRF token mismatch! The request header `TurboReflex-Token: #{client_token}` does not match the expected value of `#{server_token}`."
+    end
+
+    true
   end
 
   def reflex_params
@@ -103,10 +122,12 @@ class TurboReflex::Runner
     prevent_controller_action if should_prevent_controller_action?
   rescue => error
     @reflex_errored = true
+    raise error if controller_action_prevented?
     prevent_controller_action error: error
   end
 
   def prevent_controller_action(error: nil)
+    return if controller_action_prevented?
     @controller_action_prevented = true
 
     if error
@@ -117,17 +138,18 @@ class TurboReflex::Runner
       append_success_to_response
     end
 
-    ui_state.set_cookie
+    append_meta_tag_to_response_body # called before `set_cookie` so all state is emitted to the DOM
+    state_manager.set_cookie # truncates state to stay within cookie size limits (4k)
   end
 
   def update_response
+    return if controller_action_prevented?
     return if @update_response_performed
     @update_response_performed = true
 
-    append_meta_tag_to_response_body
-    return if controller_action_prevented?
+    append_meta_tag_to_response_body # called before `set_cookie` so all state is emitted to the DOM
+    state_manager.set_cookie # truncates state to stay within cookie size limits (4k)
     append_success_to_response if reflex_succeeded?
-    ui_state.set_cookie
   end
 
   def render_response(html: "", status: nil, headers: {TurboReflex: :Append})
@@ -139,16 +161,16 @@ class TurboReflex::Runner
     @turbo_stream ||= Turbo::Streams::TagBuilder.new(controller.view_context)
   end
 
+  def message_verifier
+    ActiveSupport::MessageVerifier.new session.id.to_s, digest: "SHA256"
+  end
+
   private
 
   def parsed_reflex_params
     @parsed_reflex_params ||= JSON.parse(params[:turbo_reflex])
   end
 
-  def message_verifier
-    ActiveSupport::MessageVerifier.new Rails.application.secret_key_base, digest: "SHA256"
-  end
-
   def content_sanitizer
     TurboReflex::Sanitizer.instance
   end
@@ -178,7 +200,7 @@ class TurboReflex::Runner
   end
 
   def response_status
-    return :multiple_choices if :should_redirect?
+    return :multiple_choices if should_redirect?
     :ok
   end
 
@@ -208,7 +230,7 @@ class TurboReflex::Runner
 
   def append_meta_tag_to_response_body
     session[:turbo_reflex_token] = new_token
-    append_to_response_body turbo_stream.replace("turbo-reflex", meta_tag)
+    append_to_response_body turbo_stream.invoke("morph", args: [meta_tag], selector: "#turbo-reflex")
   end
 
   def append_success_event_to_response_body

data/lib/turbo_reflex/state.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+class TurboReflex::State
+  class << self
+    def serialize_base64(data)
+      Base64.urlsafe_encode64 data.to_json, padding: false
+    end
+
+    def deserialize_base64(string)
+      return {} if string.blank?
+      JSON.parse Base64.urlsafe_decode64(string)
+    end
+
+    def serialize(data)
+      dump = Marshal.dump(data)
+      deflated = Zlib::Deflate.deflate(dump, Zlib::BEST_COMPRESSION)
+      Base64.urlsafe_encode64 deflated
+    end
+
+    def deserialize(string)
+      return {} if string.blank?
+      decoded = Base64.urlsafe_decode64(string)
+      inflated = Zlib::Inflate.inflate(decoded)
+      Marshal.load inflated
+    end
+  end
+
+  def initialize(ordinal_payload = nil)
+    @internal_keys = []
+    @internal_data = {}.with_indifferent_access
+
+    self.class.deserialize(ordinal_payload).each do |(key, value)|
+      write key, value
+    end
+  end
+
+  delegate :size, to: :internal_data
+  delegate :include?, :has_key?, :key?, :member?, to: :internal_data
+
+  def cache_key
+    "turbo-reflex/ui-state/#{Base64.urlsafe_encode64 Digest::MD5.hexdigest(payload), padding: false}"
+  end
+
+  def read(*keys, default: nil)
+    value = internal_data[key_for(*keys)]
+    value = write(*keys, default) if value.nil? && default
+    value
+  end
+
+  def write(*keys, value)
+    key = key_for(*keys)
+    internal_keys.delete key if internal_keys.include?(key)
+    internal_keys << key
+    internal_data[key] = value
+    value
+  end
+
+  def payload
+    self.class.serialize_base64 internal_data
+  end
+
+  def ordinal_payload
+    self.class.serialize internal_list
+  end
+
+  def shrink!
+    @internal_data = shrink(internal_data).with_indifferent_access
+    @internal_keys = internal_keys & internal_data.keys
+  end
+
+  def prune!(max_bytesize: 2.kilobytes)
+    return if internal_keys.blank?
+    return if internal_data.blank?
+
+    percentage = max_bytesize > 0 ? ordinal_payload.bytesize / max_bytesize.to_f : 0
+    while percentage > 1
+      keys_to_keep = internal_keys.slice((internal_keys.length - (internal_keys.length / percentage).floor)..-1)
+      keys_to_remove = internal_keys - keys_to_keep
+      @internal_keys = keys_to_keep
+      keys_to_remove.each { |key| internal_data.delete key }
+      percentage = max_bytesize > 0 ? ordinal_payload.bytesize / max_bytesize.to_f : 0
+    end
+  end
+
+  private
+
+  attr_reader :internal_keys
+  attr_reader :internal_data
+
+  def internal_list
+    internal_keys.map { |key| [key, internal_data[key]] }
+  end
+
+  def key_for(*keys)
+    keys.map { |key| key.try(:cache_key) || key.to_s }.join("/")
+  end
+
+  def shrink(obj)
+    case obj
+    when Array
+      obj.each_with_object([]) do |value, memo|
+        value = shrink(value)
+        memo << value if value.present?
+      end
+    when Hash
+      obj.each_with_object({}.with_indifferent_access) do |(key, value), memo|
+        value = shrink(value)
+        memo[key] = value if value.present?
+      end
+    else
+      obj
+    end
+  end
+end

data/lib/turbo_reflex/state_manager.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "state"
+
+# Class used to hold ephemeral state related to the rendered UI.
+#
+# Examples:
+#
+# - Sidebar open/closed state
+# - Tree view open/closed state
+# - Accordion collapsed/expanded state
+# - Customized layout / presentation
+# - Applied data filters
+# - Number of data rows to display etc.
+#
+class TurboReflex::StateManager
+  include ActiveModel::Dirty
+
+  class << self
+    attr_writer :cookie_max_bytesize
+
+    def cookie_max_bytesize
+      @cookie_max_bytesize ||= 2.kilobytes
+    end
+
+    def state_override_blocks
+      @state_overrides ||= {}
+    end
+
+    def add_state_override_block(controller_name, block)
+      state_override_blocks[controller_name] = block
+    end
+
+    def state_override_block(controller)
+      return nil if state_override_blocks.blank?
+      ancestor = controller.class.ancestors.find { |a| state_override_blocks[a.name] }
+      state_override_blocks[ancestor.name]
+    end
+  end
+
+  # For ActiveModel::Dirty tracking
+  define_attribute_methods :state
+
+  delegate :request, :response, to: :"runner.controller"
+
+  def initialize(runner)
+    @runner = runner
+    @state = TurboReflex::State.new(cookie) # server state as stored in the cookie
+
+    # Apply server state overrides (i.e. state stored in databases like Redis, Postgres, etc...)
+    state_override_block = self.class.state_override_block(runner.controller)
+    if state_override_block
+      server_data = runner.controller.instance_eval(&state_override_block).with_indifferent_access
+      server_data.each { |key, val| self[key] = val }
+    end
+
+    # Merge client state into server state (i.e. optimistic state)
+    # NOTE: Client state HTTP headers are only sent if/when state has changed on the client (only the changes are sent).
+    #       This prevents race conditions (state mismatch) caused when frame and XHR requests emit immediately
+    #       before the <meta id="turbo-reflex"> has been updated with the latest state from the server.
+    client_data = TurboReflex::State.deserialize_base64(header).with_indifferent_access
+    client_data.each { |key, val| self[key] = val }
+  end
+
+  delegate :cache_key, :payload, to: :state
+
+  def [](*keys, default: nil)
+    state.read(*keys, default: default)
+  end
+
+  def []=(*keys, value)
+    state_will_change! if value != self[*keys]
+    state.write(*keys, value)
+  end
+
+  def set_cookie
+    return unless changed?
+    state.shrink!
+    state.prune! max_bytesize: TurboReflex::StateManager.cookie_max_bytesize
+    response.set_cookie "_turbo_reflex_state", value: state.ordinal_payload, path: "/", expires: 1.day.from_now
+    changes_applied
+  end
+
+  private
+
+  attr_reader :runner
+  attr_reader :state
+
+  def headers
+    request.headers.select { |(key, _)| key.match?(/TURBOREFLEX_STATE/i) }.sort
+  end
+
+  # State that exists on the client.
+  def header
+    headers.map(&:last).join
+  end
+
+  # State that the server last rendered with.
+  def cookie
+    request.cookies["_turbo_reflex_state"]
+  end
+end

data/lib/turbo_reflex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurboReflex
-  VERSION = "0.0.9"
+  VERSION = "0.0.11"
 end

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbo_reflex",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Reflexes for Turbo Frames that help you build robust reactive applications",
   "main": "app/javascript/index.js",
   "repository": "https://github.com/hopsoft/turbo_reflex",