turbo_boost-commands 0.1.2 → 0.2.1

data/app/javascript/invoker.js

@@ -0,0 +1,39 @@
+import headers from './headers'
+import lifecycle from './lifecycle'
+import state from './state'
+import urls from './urls'
+import { dispatch } from './events'
+import { render } from './renderer'
+
+const parseError = error => {
+  const errorMessage = `Unexpected error performing a TurboBoost Command! ${error.message}`
+  dispatch(lifecycle.events.clientError, document, { detail: { error: errorMessage } }, true)
+}
+
+const parseAndRenderResponse = response => {
+  const { strategy } = headers.tokenize(response.headers.get(headers.RESPONSE_HEADER))
+
+  // FAIL: Status outside the range of 200-399
+  if (response.status < 200 || response.status > 399) {
+    const error = `Server returned a ${response.status} status code! TurboBoost Commands require 2XX-3XX status codes.`
+    dispatch(lifecycle.events.serverError, document, { detail: { error, response } }, true)
+  }
+
+  response.text().then(content => render(strategy, content))
+}
+
+const invoke = (payload = {}) => {
+  try {
+    fetch(urls.commandInvocationURL.href, {
+      method: 'POST',
+      headers: headers.prepare({}),
+      body: JSON.stringify(payload)
+    })
+      .then(parseAndRenderResponse)
+      .catch(parseError)
+  } catch (error) {
+    parseError(error)
+  }
+}
+
+export { invoke }

data/app/javascript/logger.js

@@ -1,6 +1,8 @@
 import { allEvents as events } from './events'
 
 let currentLevel = 'unknown'
+let initialized = false
+let history = []
 
 const logLevels = {
   debug: Object.values(events),
@@ -10,14 +12,33 @@ const logLevels = {
   unknown: []
 }
 
-Object.values(events).forEach(name => {
-  addEventListener(name, event => {
-    if (logLevels[currentLevel].includes(event.type)) {
-      const { target, detail } = event
-      console[currentLevel](event.type, { target, detail })
-    }
-  })
-})
+const shouldLogEvent = event => {
+  if (!logLevels[currentLevel].includes(event.type)) return false
+  if (typeof console[currentLevel] !== 'function') return false
+
+  const { detail } = event
+  if (!detail.id) return true
+
+  const key = `${event.type}-${detail.id}`
+  if (history.includes(key)) return false
+
+  if (history.length > 16) history.shift()
+  history.push(key)
+
+  return true
+}
+
+const logEvent = event => {
+  if (shouldLogEvent(event)) {
+    const { target, type, detail } = event
+    console[currentLevel](type, detail.id || '', { target, detail })
+  }
+}
+
+if (!initialized) {
+  initialized = true
+  Object.values(events).forEach(name => addEventListener(name, event => logEvent(event)))
+}
 
 export default {
   get level() {

data/app/javascript/renderer.js

@@ -1,16 +1,18 @@
-function replaceDocument(content) {
-  const head = '<html'
-  const tail = '</html'
-  const headIndex = content.indexOf(head)
-  const tailIndex = content.lastIndexOf(tail)
-  if (headIndex >= 0 && tailIndex >= 0) {
-    const html = content.slice(content.indexOf('>', headIndex) + 1, tailIndex)
-    document.documentElement.innerHTML = html
-  }
-}
+import uuids from './uuids'
 
-function append(content) {
+const append = content => {
   document.body.insertAdjacentHTML('beforeend', content)
 }
 
-export default { append, replaceDocument }
+const replace = content => {
+  const parser = new DOMParser()
+  const doc = parser.parseFromString(content, 'text/html')
+  TurboBoost.Streams.morph.method(document.documentElement, doc.documentElement)
+}
+
+export const render = (strategy, content) => {
+  if (strategy.match(/^Append$/i)) return append(content)
+  if (strategy.match(/^Replace$/i)) return replace(content)
+}
+
+export default { render }

data/app/javascript/turbo.js

@@ -1,46 +1,37 @@
-import state from './state'
-import renderer from './renderer'
-import { dispatch } from './events'
+import headers from './headers'
 import lifecycle from './lifecycle'
+import { dispatch } from './events'
+import { render } from './renderer'
 
 const frameSources = {}
 
-// fires before making a turbo HTTP request
-addEventListener('turbo:before-fetch-request', event => {
-  const frame = event.target.closest('turbo-frame')
-  const { fetchOptions } = event.detail
-
-  // command invoked and busy
-  if (self.TurboBoost?.Commands?.busy) {
-    let acceptHeaders = ['text/vnd.turbo-boost.html', fetchOptions.headers['Accept']]
-    acceptHeaders = acceptHeaders.filter(entry => entry && entry.trim().length > 0).join(', ')
-    fetchOptions.headers['Accept'] = acceptHeaders
-  }
-})
-
 // fires after receiving a turbo HTTP response
 addEventListener('turbo:before-fetch-response', event => {
   const frame = event.target.closest('turbo-frame')
+  if (frame?.id && frame?.src) frameSources[frame.id] = frame.src
+
   const { fetchResponse: response } = event.detail
+  const header = response.header(headers.RESPONSE_HEADER)
 
-  if (frame) frameSources[frame.id] = frame.src
+  if (!header) return
 
-  if (response.header('TurboBoost')) {
-    if (response.statusCode < 200 || response.statusCode > 399) {
-      const error = `Server returned a ${response.statusCode} status code! TurboBoost Commands require 2XX-3XX status codes.`
-      dispatch(lifecycle.events.clientError, document, { detail: { ...event.detail, error } }, true)
-    }
+  // We'll take it from here Hotwire...
+  event.preventDefault()
+  const { statusCode } = response
+  const { strategy } = headers.tokenize(header)
 
-    if (response.header('TurboBoost') === 'Append') {
-      event.preventDefault()
-      response.responseText.then(content => renderer.append(content))
-    }
+  // FAIL: Status outside the range of 200-399
+  if (statusCode < 200 || statusCode > 399) {
+    const error = `Server returned a ${status} status code! TurboBoost Commands require 2XX-3XX status codes.`
+    dispatch(lifecycle.events.clientError, document, { detail: { error, response } }, true)
   }
+
+  response.responseHTML.then(content => render(strategy, content))
 })
 
 // fires when a frame element is navigated and finishes loading
 addEventListener('turbo:frame-load', event => {
   const frame = event.target.closest('turbo-frame')
-  frame.dataset.turboBoostSrc = frameSources[frame.id] || frame.src || frame.dataset.turboBoostSrc
+  frame.dataset.src = frameSources[frame.id] || frame.src || frame.dataset.src
   delete frameSources[frame.id]
 })

data/app/javascript/urls.js

@@ -1,9 +1,11 @@
-function build(urlString, payload = {}) {
+const buildURL = path => {
   const a = document.createElement('a')
-  a.href = urlString
-  const url = new URL(a)
-  url.searchParams.set('tbc', JSON.stringify(payload))
-  return url
+  a.href = path
+  return new URL(a)
 }
 
-export default { build }
+export default {
+  get commandInvocationURL() {
+    return buildURL('/turbo-boost-command-invocation')
+  }
+}

data/app/javascript/version.js

@@ -1 +1 @@
-export default '0.1.2'
+export default '0.2.1'

data/lib/turbo_boost/commands/command.rb

@@ -90,7 +90,11 @@ class TurboBoost::Commands::Command
     @turbo_streams = Set.new
   end
 
-  # Abstract `perform` method, overridde in subclassed commands
+  # Abstract method to resolve state (default noop), override in subclassed commands
+  def resolve_state(client_state)
+  end
+
+  # Abstract `perform` method, override in subclassed commands
   def perform
     raise NotImplementedError, "#{self.class.name} must implement the `perform` method!"
   end
@@ -113,6 +117,7 @@ class TurboBoost::Commands::Command
   end
 
   # Same method signature as ActionView::Rendering#render (i.e. controller.view_context.render)
+  # Great for rendering partials with short-hand syntax sugar → `render "/path/to/partial"`
   def render(options = {}, locals = {}, &block)
     return controller.view_context.render(options, locals, &block) unless options.is_a?(Hash)
 

data/lib/turbo_boost/commands/controller_pack.rb

@@ -8,6 +8,7 @@ class TurboBoost::Commands::ControllerPack
   attr_reader :runner, :command
 
   delegate(
+    :command_state,
     :command_aborted?,
     :command_errored?,
     :command_performed?,
@@ -15,7 +16,6 @@ class TurboBoost::Commands::ControllerPack
     :command_requested?,
     :command_succeeded?,
     :controller,
-    :state,
     to: :runner
   )
 
@@ -23,4 +23,9 @@ class TurboBoost::Commands::ControllerPack
     @runner = TurboBoost::Commands::Runner.new(controller)
     @command = runner.command_instance
   end
+
+  def state
+    ActiveSupport::Deprecation.warn "The `state` method has been deprecated. Please update to `command_state`."
+    command_state
+  end
 end

data/lib/turbo_boost/commands/engine.rb

@@ -7,6 +7,7 @@ require_relative "version"
 require_relative "http_status_codes"
 require_relative "errors"
 require_relative "patches"
+require_relative "middleware"
 require_relative "command"
 require_relative "controller_pack"
 require_relative "../../../app/controllers/concerns/turbo_boost/commands/controller"
@@ -19,16 +20,16 @@ module TurboBoost::Commands
 
   class Engine < ::Rails::Engine
     config.turbo_boost_commands = ActiveSupport::OrderedOptions.new
-    config.turbo_boost_commands[:validate_client_token] = false
+    config.turbo_boost_commands[:protect_from_forgery] = true
+    config.turbo_boost_commands[:precompile_assets] = true
 
     # must opt-in to state overrides
     config.turbo_boost_commands[:apply_client_state_overrides] = false
     config.turbo_boost_commands[:apply_server_state_overrides] = false
 
-    config.turbo_boost_commands.precompile_assets = true
-
-    initializer "turbo_boost_commands.configuration" do
+    initializer "turbo_boost_commands.configuration" do |app|
       Mime::Type.register "text/vnd.turbo-boost.html", :turbo_boost
+      app.middleware.insert 0, TurboBoost::Commands::Middleware
 
       ActiveSupport.on_load :action_controller_base do
         # `self` is ActionController::Base

data/lib/turbo_boost/commands/middleware.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+class TurboBoost::Commands::Middleware
+  PATH = "/turbo-boost-command-invocation"
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    request = Rack::Request.new(env)
+    modify! request if modify?(request)
+    @app.call env
+  end
+
+  private
+
+  # Returns the MIME type for TurboBoost Command invocations.
+  def mime_type
+    Mime::Type.lookup_by_extension(:turbo_boost)
+  end
+
+  # Indicates whether or not the request is a TurboBoost Command invocation that requires modifications
+  # before we hand things over to Rails.
+  #
+  # @param request [Rack::Request] the request to check
+  # @return [Boolean] true if the request is a TurboBoost Command invocation, false otherwise
+  def modify?(request)
+    return false unless request.post?
+    return false unless request.path.start_with?(PATH)
+    return false unless mime_type && request.env["HTTP_ACCEPT"]&.include?(mime_type)
+    true
+  rescue => error
+    puts "#{self.class.name} failed to determine if the request should be modified! #{error.message}"
+    false
+  end
+
+  # Modifies the given POST request so Rails sees it as GET.
+  #
+  # The posted JSON body content holds the TurboBoost Command meta data.
+  # The parsed JSON body is stored in the environment under the `turbo_boost_command` key.
+  #
+  # @example POST payload for: /turbo-boost-command-invocation
+  #   {
+  #     "id"                => "turbo-command-f824ded1-a86e-4a36-9442-ea2165a64569",                 # unique command invocation id
+  #     "name"              => "IncrementCountCommand",                                              # the command being invoked
+  #     "elementId"         => nil,                                                                  # the triggering element's dom id
+  #     "elementAttributes" => {"tag"=>"BUTTON", "checked"=>false, "disabled"=>false, "value"=>nil}, # the triggering element's attributes
+  #     "startedAt"         => 1708213193567,                                                        # the time the command was invoked
+  #     "changedState"      => {},                                                                   # the delta of optimistic state changes made on the client
+  #     "clientState"       => {                                                                     # the state as it was on the client
+  #       "command_token" => "IlU0dVVhNElFdkVCZVUi--a878d33d85ed9b9611c155ed1d7bb8785fb..."}         # the command token used for forgery protection
+  #     },
+  #     "signedState"       => "eyJfcmFpbHMiOnsiZGF0YSI6ImdpZDovL2R1VuaXZlcnNhbElEOjpFeH...",        # the state as it was on the server at the time of the last command invocation
+  #     "driver"            => "frame",                                                              # the driver used to invoke the command
+  #     "frameId"           => "basic_command-turbo-frame",                                          # the turbo-frame id (if applicable)
+  #     "src"               => "/basic_command.turbo_stream"                                         # the URL to present to Rails (turbo-frame src, window location, etc.)
+  #   }
+  #
+  # @param request [Rack::Request] the request to modify
+  def modify!(request)
+    params = JSON.parse(request.body.string)
+    uri = URI.parse(params["src"])
+
+    request.env.tap do |env|
+      # Store the command params in the environment
+      env["turbo_boost_command"] = params
+
+      # Change the method from POST to GET
+      env["REQUEST_METHOD"] = "GET"
+
+      # Update the URI, PATH_INFO, and QUERY_STRING
+      env["REQUEST_URI"] = uri.to_s if env.key?("REQUEST_URI")
+      env["PATH_INFO"] = uri.path
+      env["QUERY_STRING"] = uri.query.to_s
+
+      # Clear the body and related headers so the appears and behaves like a GET
+      env["rack.input"] = StringIO.new
+      env["CONTENT_LENGTH"] = "0"
+      env.delete("CONTENT_TYPE")
+    end
+  rescue => error
+    puts "#{self.class.name} failed to modify the request! #{error.message}"
+  end
+end

data/lib/turbo_boost/commands/runner.rb

@@ -4,6 +4,8 @@ require_relative "sanitizer"
 require_relative "state"
 
 class TurboBoost::Commands::Runner
+  RESPONSE_HEADER = "TurboBoost-Command"
+
   SUPPORTED_MEDIA_TYPES = {
     "text/html" => true,
     "text/vnd.turbo-boost.html" => true,
@@ -16,8 +18,8 @@ class TurboBoost::Commands::Runner
     @controller = controller
   end
 
-  def state
-    @state ||= begin
+  def command_state
+    @command_state ||= begin
       sgid = command_params[:signed_state]
       value = TurboBoost::Commands::State.from_sgid_param(sgid) if sgid
       value || TurboBoost::Commands::State.new
@@ -25,7 +27,7 @@ class TurboBoost::Commands::Runner
   end
 
   def command_requested?
-    command_params.present?
+    controller.request.env.key?("turbo_boost_command") || controller.params.key?("turbo_boost_command")
   end
 
   def command_valid?
@@ -44,18 +46,19 @@ class TurboBoost::Commands::Runner
     end
 
     # validate csrf token
-    unless valid_client_token?
+    unless valid_command_token?
       raise TurboBoost::Commands::InvalidTokenError,
-        "Token mismatch! The token: #{client_token}` does not match the expected value of `#{server_token}`."
+        "Token mismatch! The token: #{client_command_token}` does not match the expected value of `#{server_command_token}`."
     end
 
     true
   end
 
   def command_params
-    return ActionController::Parameters.new if controller.params.keys.none?(/\A(tbc|turbo_boost_command)\z/o)
+    return ActionController::Parameters.new unless command_requested?
     @command_params ||= begin
-      payload = parsed_command_params.deep_transform_keys(&:underscore)
+      payload = parsed_command_params.transform_keys(&:underscore)
+      payload["element_attributes"]&.deep_transform_keys!(&:underscore)
       ActionController::Parameters.new(payload).permit!
     end
   end
@@ -83,7 +86,7 @@ class TurboBoost::Commands::Runner
   end
 
   def command_instance
-    @command_instance ||= command_class&.new(controller, state, command_params).tap do |instance|
+    @command_instance ||= command_class&.new(controller, command_state, command_params).tap do |instance|
       instance&.add_observer self, :handle_command_event
     end
   end
@@ -108,6 +111,10 @@ class TurboBoost::Commands::Runner
     !!command_instance&.succeeded?
   end
 
+  def controller_action_allowed?
+    !controller_action_prevented?
+  end
+
   def controller_action_prevented?
     !!@controller_action_prevented
   end
@@ -123,7 +130,8 @@ class TurboBoost::Commands::Runner
     return if command_errored?
     return if command_performing?
     return if command_performed?
-    state.resolve command_params[:client_state]
+
+    command_instance.resolve_state command_params[:changed_state]
     command_instance.perform_with_callbacks command_method_name
   end
 
@@ -136,17 +144,16 @@ class TurboBoost::Commands::Runner
       render_response status: response_status
       append_success_to_response
     when TurboBoost::Commands::AbortError
-      render_response status: error.http_status_code, headers: {"TurboBoost-Command-Status": error.message}
+      render_response status: error.http_status_code, status_header: error.message
       append_streams_to_response_body
     when TurboBoost::Commands::PerformError
-      render_response status: error.http_status_code, headers: {"TurboBoost-Command-Status": error.message}
+      render_response status: error.http_status_code, status_header: error.message
       append_error_to_response error
     else
-      render_response status: :internal_server_error, headers: {"TurboBoost-Command-Status": error.message}
+      render_response status: :internal_server_error, status_header: error.message
       append_error_to_response error
     end
 
-    append_command_token_to_response_body
     append_command_state_to_response_body
   end
 
@@ -156,17 +163,16 @@ class TurboBoost::Commands::Runner
 
     return if controller_action_prevented?
 
-    append_to_response_headers
-    append_command_token_to_response_body
     append_command_state_to_response_body
+    append_to_response_headers if command_performed?
     append_success_to_response if command_succeeded?
   rescue => error
     Rails.logger.error "TurboBoost::Commands::Runner failed to update the response! #{error.message}"
   end
 
-  def render_response(html: "", status: nil, headers: {})
-    controller.render html: html, layout: false, status: status || response_status
-    append_to_response_headers headers.merge(TurboBoost: :Append)
+  def render_response(html: "", status: nil, status_header: nil)
+    controller.render html: html, layout: false, status: status || response_status # unless controller.performed?
+    append_to_response_headers status_header
   end
 
   def turbo_stream
@@ -191,40 +197,40 @@ class TurboBoost::Commands::Runner
   private
 
   def parsed_command_params
-    @parsed_command_params ||= JSON.parse(controller.params[:tbc] || controller.params[:turbo_boost_command])
+    @parsed_command_params ||= begin
+      params = controller.request.env["turbo_boost_command"]
+      params ||= JSON.parse(controller.params["turbo_boost_command"])
+      params || {}
+    end
   end
 
   def content_sanitizer
     TurboBoost::Commands::Sanitizer.instance
   end
 
-  # TODO: revisit command token validation
-  def new_token
-    @new_token ||= SecureRandom.alphanumeric(13)
+  def new_command_token
+    @new_command_token ||= SecureRandom.alphanumeric(13)
   end
 
-  # TODO: revisit command token validation
-  def server_token
-    nil
+  def client_command_token
+    command_params.dig(:client_state, :command_token)
   end
 
-  # TODO: revisit command token validation
-  def client_token
-    command_params[:token].to_s
+  def server_command_token
+    command_state[:command_token]
   end
 
-  # TODO: revisit command token validation
-  def valid_client_token?
-    # return true unless Rails.configuration.turbo_boost_commands.validate_client_token
-    # return false unless client_token.present?
-    # return false unless message_verifier.valid_message?(client_token)
-    # unmasked_client_token = message_verifier.verify(client_token)
-    # unmasked_client_token == server_token
-    true
+  def valid_command_token?
+    return true unless Rails.configuration.turbo_boost_commands.protect_from_forgery
+    return false unless client_command_token.present?
+    return false unless server_command_token.present?
+    server_command_token == message_verifier.verify(client_command_token, purpose: controller.request.session&.id)
+  rescue ActiveSupport::MessageVerifier::InvalidSignature
+    false
   end
 
   def should_redirect?
-    return false if controller.request.method.match?(/GET/i)
+    return false if controller.request.get?
     controller.request.accepts.include? Mime::Type.lookup_by_extension(:turbo_stream)
   end
 
@@ -235,12 +241,34 @@ class TurboBoost::Commands::Runner
 
   def response_type
     body = (controller.response_body.try(:join) || controller.response_body.to_s).strip
-    return :body if body.match?(/<\/\s*body/i)
-    return :frame if body.match?(/<\/\s*turbo-frame/i)
-    return :stream if body.match?(/<\/\s*turbo-stream/i)
+    return :body if body.match?(/<\/\s*body/io)
+    return :frame if body.match?(/<\/\s*turbo-frame/io)
+    return :stream if body.match?(/<\/\s*turbo-stream/io)
     :unknown
   end
 
+  # Indicates if a TurboStream template exists for the current action.
+  # Any template with the format of :turbo_boost or :turbo_stream format is considered a match.
+  # @return [Boolean] true if a TurboStream template exists, false otherwise
+  def turbo_stream_template_exists?
+    controller.lookup_context.exists? controller.action_name, controller.lookup_context.prefixes, formats: [:turbo_boost, :turbo_stream]
+  end
+
+  def rendering_strategy
+    # Use the replace strategy if the follow things are true:
+    #
+    # 1. The command was triggered by the WINDOW driver
+    # 2. After the command finishes, normal Rails mechanics resume (i.e. prevent_controller_action was not called)
+    # 3. There is NO TurboStream template for the current action (i.e. example.turbo_boost.erb, example.turbo_frame.erb)
+    #
+    # TODO: Revisit the "Replace" strategy after morph ships with Turbo 8
+    if command_params[:driver] == "window" && controller_action_allowed?
+      return "Replace" unless turbo_stream_template_exists?
+    end
+
+    "Append"
+  end
+
   def append_success_to_response
     append_success_event_to_response_body
     append_streams_to_response_body
@@ -256,14 +284,16 @@ class TurboBoost::Commands::Runner
     command_instance.turbo_streams.each { |stream| append_to_response_body stream }
   end
 
-  def append_command_token_to_response_body
-    append_to_response_body turbo_stream.invoke("TurboBoost.Commands.token=", args: [new_token], camelize: false)
-  rescue => error
-    Rails.logger.error "TurboBoost::Commands::Runner failed to append the Command token to the response! #{error.message}"
-  end
-
   def append_command_state_to_response_body
-    append_to_response_body turbo_stream.invoke("TurboBoost.State.initialize", args: [state.to_json, state.to_sgid_param], camelize: false)
+    # use the masked token for the client state
+    command_state[:command_token] = message_verifier.generate(new_command_token, purpose: controller.request.session&.id)
+    client_state = command_state.to_json
+
+    # use the unmasked token for the signed (server) state
+    command_state[:command_token] = new_command_token
+    signed_state = command_state.to_sgid_param
+
+    append_to_response_body turbo_stream.invoke("TurboBoost.State.initialize", args: [client_state, signed_state], camelize: false)
   rescue => error
     Rails.logger.error "TurboBoost::Commands::Runner failed to append the Command state to the response! #{error.message}"
   end
@@ -316,10 +346,10 @@ class TurboBoost::Commands::Runner
 
     html = case response_type
     when :body
-      match = controller.response.body.match(/<\/\s*body/i).to_s
+      match = controller.response.body.match(/<\/\s*body/io).to_s
       controller.response.body.sub match, [sanitized_content, match].join
     when :frame
-      match = controller.response.body.match(/<\/\s*turbo-frame/i).to_s
+      match = controller.response.body.match(/<\/\s*turbo-frame/io).to_s
       controller.response.body.sub match, [sanitized_content, match].join
     else
       [controller.response.body, sanitized_content].join
@@ -336,10 +366,15 @@ class TurboBoost::Commands::Runner
     controller.response.set_header key.to_s, value.to_s
   end
 
-  def append_to_response_headers(headers = {})
+  def append_to_response_headers(status = nil)
     return unless command_performed?
-    headers.each { |key, val| append_response_header key, val }
-    append_response_header "TurboBoost-Command", command_name
-    append_response_header "TurboBoost-Command-Status", "HTTP #{controller.response.status} #{TurboBoost::Commands::HTTP_STATUS_CODES[controller.response.status]}"
+
+    values = [
+      status || "#{controller.response.status} #{TurboBoost::Commands::HTTP_STATUS_CODES[controller.response.status]}".delete(","),
+      rendering_strategy,
+      command_name
+    ]
+
+    append_response_header RESPONSE_HEADER, values.join(", ")
   end
 end