cable_ready 4.5.0 → 5.0.0

data/lib/generators/cable_ready/channel_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+class CableReady::ChannelGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  class_option :stream_from, type: :string
+  class_option :stream_for, type: :string
+  class_option :stimulus, type: :boolean
+
+  def destroy_not_supported
+    if behavior == :revoke
+      puts "Sorry, we don't support destroying generated channels.\nDelete the Action Cable channel class, as well as any corresponding JavaScript classes."
+      exit
+    end
+  end
+
+  def check_options
+    if options.key?(:stream_from) && options.key?(:stream_for)
+      puts "Can't specify --stream-from and --stream-for at the same time"
+      exit
+    end
+  end
+
+  def create_channel
+    generate "channel", file_name, "--skip"
+  end
+
+  def enhance_channels
+    @entrypoint = [
+      "app/javascript",
+      "app/frontend"
+    ].find { |path| File.exist?(Rails.root.join(path)) } || "app/javascript"
+    puts "Where do JavaScript files live in your app? Our best guess is: \e[1m#{@entrypoint}\e[22m 🤔"
+    puts "Press enter to accept this, or type a different path."
+    print "> "
+    input = Rails.env.test? ? "tmp/app/javascript" : $stdin.gets.chomp
+    @entrypoint = input unless input.blank?
+    @js_channel = "#{@entrypoint}/channels/#{file_name}_channel.js"
+
+    if using_broadcast_to?
+      if using_stimulus?
+        template("#{@entrypoint}/controllers/%file_name%_controller.js")
+        Rails.root.join(@js_channel).delete
+      else
+        gsub_file "app/channels/#{file_name}_channel.rb", /# stream_from.*\n/, "stream_for #{resource}.find(params[:id])\n", verbose: false
+        gsub_file @js_channel, /"#{resource}Channel"/, verbose: false do
+          <<-JS
+
+  {
+    channel: "#{resource}Channel",
+    id: 1
+  }
+          JS
+        end
+        doctor_javascript_channel_class
+        puts "\nDon't forget to update the id in the channel subscription: #{@js_channel}\nIt's currently set to 1; you'll want to change that to a dynamic value based on something in your DOM."
+      end
+    else
+      gsub_file "app/channels/#{file_name}_channel.rb", /# stream_from.*\n/, "stream_from \"#{identifier}\"\n", verbose: false
+      doctor_javascript_channel_class
+    end
+  end
+
+  private
+
+  def doctor_javascript_channel_class
+    prepend_to_file @js_channel, "import CableReady from 'cable_ready'\n", verbose: false
+    inject_into_file @js_channel, after: "// Called when there's incoming data on the websocket for this channel\n", verbose: false do
+      <<-JS
+    if (data.cableReady) CableReady.perform(data.operations)
+      JS
+    end
+  end
+
+  def option_given?
+    options.key?(:stream_from) || options.key?(:stream_for)
+  end
+
+  def using_broadcast_to?
+    @using_broadcast_to ||= option_given? ? options.key?(:stream_for) : yes?("Are you streaming to a resource using broadcast_to? (y/N)")
+  end
+
+  def using_stimulus?
+    @using_stimulus ||= options.fetch(:stimulus) {
+      yes?("Are you going to use a Stimulus controller to subscribe to this channel? (y/N)")
+    }
+  end
+
+  def resource
+    return @resource if @resource
+
+    stream_for = options.fetch(:stream_for) {
+      ask("Which resource are you streaming for?", default: class_name)
+    }
+
+    stream_for = file_name if stream_for == "stream_for"
+    @resource = stream_for.camelize
+  end
+
+  def identifier
+    return @identifier if @identifier
+
+    stream_from = options.fetch(:stream_from) {
+      ask("What is the stream identifier that goes into stream_from?", default: file_name)
+    }
+
+    stream_from = file_name if stream_from == "stream_from"
+    @identifier = stream_from.underscore
+  end
+end

data/lib/generators/cable_ready/templates/app/javascript/channels/consumer.js.tt

@@ -0,0 +1,6 @@
+// Action Cable provides the framework to deal with WebSockets in Rails.
+// You can generate new channels where WebSocket features live using the `bin/rails generate channel` command.
+
+import { createConsumer } from '@rails/actioncable'
+
+export default createConsumer()

data/lib/generators/cable_ready/templates/app/javascript/channels/index.js.esbuild.tt

@@ -0,0 +1,4 @@
+// Load all the channels within this directory and all subdirectories.
+// Channel files must be named *_channel.js.
+
+import './**/*_channel.js'

data/lib/generators/cable_ready/templates/app/javascript/channels/index.js.importmap.tt

@@ -0,0 +1,2 @@
+// app/channels/index.js
+// Importmaps don't require anything here

data/lib/generators/cable_ready/templates/app/javascript/channels/index.js.shakapacker.tt

@@ -0,0 +1,5 @@
+// Load all the channels within this directory and all subdirectories.
+// Channel files must be named *_channel.js.
+
+const channels = require.context('.', true, /_channel\.js$/)
+channels.keys().forEach(channels)

data/lib/generators/cable_ready/templates/app/javascript/channels/index.js.vite.tt

@@ -0,0 +1 @@
+const channels = import.meta.globEager('./**/*_channel.js')

data/lib/generators/cable_ready/templates/app/javascript/channels/index.js.webpacker.tt

@@ -0,0 +1,5 @@
+// Load all the channels within this directory and all subdirectories.
+// Channel files must be named *_channel.js.
+
+const channels = require.context('.', true, /_channel\.js$/)
+channels.keys().forEach(channels)

data/lib/generators/cable_ready/templates/app/javascript/config/cable_ready.js.tt

@@ -0,0 +1,4 @@
+import consumer from '../channels/consumer'
+import CableReady from 'cable_ready'
+
+CableReady.initialize({ consumer })

data/lib/generators/cable_ready/templates/app/javascript/config/index.js.tt

@@ -0,0 +1 @@
+import './cable_ready'

data/lib/generators/cable_ready/templates/app/javascript/config/mrujs.js.tt

@@ -0,0 +1,9 @@
+import CableReady from "cable_ready"
+import mrujs from "mrujs"
+import { CableCar } from "mrujs/plugins"
+
+mrujs.start({
+  plugins: [
+    new CableCar(CableReady)
+  ]
+})

data/lib/generators/cable_ready/templates/app/javascript/controllers/%file_name%_controller.js.tt

@@ -0,0 +1,38 @@
+import { Controller } from '@hotwired/stimulus'
+import CableReady from 'cable_ready'
+
+export default class extends Controller {
+  static values = { id: Number }
+
+  connect () {
+    if (this.preview) return
+    if (this.application.consumer) {
+      this.channel = this.application.consumer.subscriptions.create(
+        {
+          channel: '<%= class_name %>Channel',
+          id: this.idValue
+        },
+        {
+          received (data) {
+            if (data.cableReady) CableReady.perform(data.operations)
+          }
+        }
+      )
+    } else {
+      console.error(
+        `The "<%= class_name.underscore.dasherize %>" Stimulus controller requires an Action Cable consumer.\nPlease set 'application.consumer = consumer' in your application.js.`
+      )
+    }
+  }
+
+  disconnect () {
+    this.channel.unsubscribe()
+  }
+
+  get preview () {
+    return (
+      document.documentElement.hasAttribute('data-turbolinks-preview') ||
+      document.documentElement.hasAttribute('data-turbo-preview')
+    )
+  }
+}

data/lib/generators/cable_ready/templates/app/javascript/controllers/application.js.tt

@@ -0,0 +1,11 @@
+import { Application } from "@hotwired/stimulus"
+import consumer from "../channels/consumer"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false
+application.consumer = consumer
+window.Stimulus = application
+
+export { application }

data/lib/generators/cable_ready/templates/app/javascript/controllers/index.js.esbuild.tt

@@ -0,0 +1,7 @@
+import { application } from "./application"
+
+import controllers from "./**/*_controller.js"
+
+controllers.forEach((controller) => {
+  application.register(controller.name, controller.module.default)
+})

data/lib/generators/cable_ready/templates/app/javascript/controllers/index.js.importmap.tt

@@ -0,0 +1,5 @@
+import { application } from "./application"
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)

data/lib/generators/cable_ready/templates/app/javascript/controllers/index.js.shakapacker.tt

@@ -0,0 +1,5 @@
+import { application } from "./application"
+import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"
+
+const controllers = definitionsFromContext(require.context("controllers", true, /_controller\.js$/))
+application.load(controllers)

data/lib/generators/cable_ready/templates/app/javascript/controllers/index.js.vite.tt

@@ -0,0 +1,5 @@
+import { application } from "./application"
+import { registerControllers } from "stimulus-vite-helpers"
+
+const controllers = import.meta.globEager("./**/*_controller.js");
+registerControllers(application, controllers)

data/lib/generators/cable_ready/templates/app/javascript/controllers/index.js.webpacker.tt

@@ -0,0 +1,5 @@
+import { application } from "./application"
+import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"
+
+const controllers = definitionsFromContext(require.context("controllers", true, /_controller\.js$/))
+application.load(controllers)

data/lib/generators/cable_ready/templates/config/initializers/cable_ready.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+CableReady.configure do |config|
+  # Enable/disable exiting / warning when the sanity checks fail options:
+  # `:exit` or `:warn` or `:ignore`
+  #
+  # config.on_failed_sanity_checks = :exit
+
+  # Enable/disable assets compilation
+  # `true` or `false`
+  #
+  # config.precompile_assets = true
+
+  # Define your own custom operations
+  # https://cableready.stimulusreflex.com/customization#custom-operations
+  #
+  # config.add_operation_name :jazz_hands
+
+  # Change the default Active Job queue used for broadcast_later and broadcast_later_to
+  #
+  # config.broadcast_job_queue = :default
+
+  # Specify a default debounce time for CableReady::Updatable callbacks
+  # Doing so is a best practice to avoid heavy ActionCable traffic
+  #
+  # config.updatable_debounce_time = 0.1.seconds
+end

data/lib/generators/cable_ready/templates/esbuild.config.mjs.tt

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+// Esbuild is configured with 3 modes:
+//
+// `yarn build` - Build JavaScript and exit
+// `yarn build --watch` - Rebuild JavaScript on change
+// `yarn build --reload` - Reloads page when views, JavaScript, or stylesheets change
+//
+// Minify is enabled when "RAILS_ENV=production"
+// Sourcemaps are enabled in non-production environments
+
+import * as esbuild from "esbuild"
+import path from "path"
+import rails from "esbuild-rails"
+import chokidar from "chokidar"
+import http from "http"
+import { setTimeout } from "timers/promises"
+
+const clients = []
+
+const entryPoints = [
+  "application.js"
+]
+
+const watchDirectories = [
+  "./app/javascript/**/*.js",
+  "./app/views/**/*.html.erb",
+  "./app/assets/builds/**/*.css", // Wait for cssbundling changes
+]
+
+const config = {
+  absWorkingDir: path.join(process.cwd(), "app/javascript"),
+  bundle: true,
+  entryPoints: entryPoints,
+  minify: process.env.RAILS_ENV == "production",
+  outdir: path.join(process.cwd(), "app/assets/builds"),
+  plugins: [rails()],
+  sourcemap: process.env.RAILS_ENV != "production"
+}
+
+async function buildAndReload() {
+  // Foreman & Overmind assign a separate PORT for each process
+  const port = parseInt(process.env.PORT)
+  const context = await esbuild.context({
+    ...config,
+    banner: {
+      js: ` (() => new EventSource("http://localhost:${port}").onmessage = () => location.reload())();`,
+    }
+  })
+
+  // Reload uses an HTTP server as an even stream to reload the browser
+  http.createServer((req, res) => {
+    return clients.push(
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Access-Control-Allow-Origin": "*",
+        Connection: "keep-alive",
+      })
+    )
+  }).listen(port)
+
+  await context.rebuild()
+  console.log("[reload] initial build succeeded")
+
+  let ready = false
+  chokidar.watch(watchDirectories).on("ready", () => {
+    console.log("[reload] ready")
+    ready = true
+  }).on("all", async (event, path) => {
+    if (ready === false)  return
+
+    if (path.includes("javascript")) {
+      try {
+        await setTimeout(20)
+        await context.rebuild()
+        console.log("[reload] build succeeded")
+      } catch (error) {
+        console.error("[reload] build failed", error)
+      }
+    }
+    clients.forEach((res) => res.write("data: update\n\n"))
+    clients.length = 0
+  })
+}
+
+if (process.argv.includes("--reload")) {
+  buildAndReload()
+} else if (process.argv.includes("--watch")) {
+  let context = await esbuild.context({...config, logLevel: 'info'})
+  context.watch()
+} else {
+  esbuild.build(config)
+}

data/lib/install/action_cable.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "cable_ready/installer"
+
+# verify that Action Cable is installed
+if defined?(ActionCable::Engine)
+  say "✅ ActionCable::Engine is loaded and in scope"
+else
+  halt "ActionCable::Engine is not loaded, please add or uncomment `require \"action_cable/engine\"` to your `config/application.rb`"
+  return
+end
+
+return if pack_path_missing?
+
+# verify that the Action Cable pubsub config is created
+cable_config = Rails.root.join("config/cable.yml")
+
+if cable_config.exist?
+  say "✅ config/cable.yml is present"
+else
+  inside "config" do
+    template "cable.yml"
+  end
+end
+
+# verify that the Action Cable pubsub is set to use redis in development
+yaml = YAML.safe_load(cable_config.read)
+app_name = Rails.application.class.module_parent.name.underscore
+
+if yaml["development"]["adapter"] == "redis"
+  say "✅ config/cable.yml is configured to use the redis adapter in development"
+elsif yaml["development"]["adapter"] == "async"
+  yaml["development"] = {
+    "adapter" => "redis",
+    "url" => "<%= ENV.fetch(\"REDIS_URL\") { \"redis://localhost:6379/1\" } %>",
+    "channel_prefix" => "#{app_name}_development"
+  }
+  backup(cable_config) do
+    cable_config.write(yaml.to_yaml)
+  end
+  say "✅ config/cable.yml was updated to use the redis adapter in development"
+else
+  say "🤷 config/cable.yml should use the redis adapter - or something like it - in development. You have something else specified, and we trust that you know what you're doing."
+end
+
+if Rails::VERSION::MAJOR >= 7
+  add_gem "redis@~> 5"
+else
+  add_gem "redis@~> 4"
+end
+
+# install action-cable-redis-backport gem if using Action Cable < 7.1
+unless ActionCable::VERSION::MAJOR >= 7 && ActionCable::VERSION::MINOR >= 1
+  if !gemfile.match?(/gem ['"]action-cable-redis-backport['"]/)
+    add_gem "action-cable-redis-backport@~> 1"
+  end
+end
+
+# verify that the Action Cable channels folder and consumer class is available
+step_path = "/app/javascript/channels/"
+channels_path = Rails.root.join(entrypoint, "channels")
+consumer_src = fetch(step_path, "consumer.js.tt")
+consumer_path = channels_path / "consumer.js"
+index_src = fetch(step_path, "index.js.#{bundler}.tt")
+index_path = channels_path / "index.js"
+friendly_index_path = index_path.relative_path_from(Rails.root).to_s
+
+empty_directory channels_path unless channels_path.exist?
+
+copy_file(consumer_src, consumer_path) unless consumer_path.exist?
+
+if index_path.exist?
+  if index_path.read == index_src.read
+    say "✅ #{friendly_index_path} is present"
+  else
+    backup(index_path) do
+      copy_file(index_src, index_path, verbose: false)
+    end
+    say "✅ #{friendly_index_path} has been created"
+  end
+else
+  copy_file(index_src, index_path)
+end
+
+# import Action Cable channels into application pack
+channels_pattern = /import ['"](\.\.\/|\.\/)?channels['"]/
+channels_commented_pattern = /\s*\/\/\s*#{channels_pattern}/
+channel_import = "import \"#{prefix}channels\"\n"
+
+if pack.match?(channels_pattern)
+  if pack.match?(channels_commented_pattern)
+    proceed = if options.key? "uncomment"
+      options["uncomment"]
+    else
+      !no?("✨ Action Cable seems to be commented out in your application.js. Do you want to uncomment it? (Y/n)")
+    end
+
+    if proceed
+      # uncomment_lines only works with Ruby comments 🙄
+      lines = pack_path.readlines
+      matches = lines.select { |line| line =~ channels_commented_pattern }
+      lines[lines.index(matches.last).to_i] = channel_import
+      pack_path.write lines.join
+      say "✅ channels imported in #{friendly_pack_path}"
+    else
+      say "🤷 your Action Cable channels are not being imported in your application.js. We trust that you have a reason for this."
+    end
+  else
+    say "✅ channels imported in #{friendly_pack_path}"
+  end
+else
+  lines = pack_path.readlines
+  matches = lines.select { |line| line =~ /^import / }
+  lines.insert lines.index(matches.last).to_i + 1, channel_import
+  pack_path.write lines.join
+  say "✅ channels imported in #{friendly_pack_path}"
+end
+
+# create working copy of Action Cable initializer in tmp
+if action_cable_initializer_path.exist?
+  FileUtils.cp(action_cable_initializer_path, action_cable_initializer_working_path)
+else
+  # create Action Cable initializer if it doesn't already exist
+  create_file(action_cable_initializer_working_path, verbose: false) do
+    <<~RUBY
+      # frozen_string_literal: true
+
+    RUBY
+  end
+  say "✅ Action Cable initializer created"
+end
+
+# silence notoriously chatty Action Cable logs
+if !action_cable_initializer_working_path.read.match?(/^[^#]*ActionCable.server.config.logger/)
+  append_file(action_cable_initializer_working_path, verbose: false) do
+    <<~RUBY
+      ActionCable.server.config.logger = Logger.new(nil)
+
+    RUBY
+  end
+  say "✅ Action Cable logger silenced for performance and legibility"
+end
+
+complete_step :action_cable

data/lib/install/broadcaster.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "cable_ready/installer"
+
+proceed = if options.key? "broadcaster"
+  options["broadcaster"]
+else
+  !no?("✨ Make CableReady::Broadcaster available to channels, controllers, jobs and models? (Y/n)")
+end
+
+unless proceed
+  complete_step :broadcaster
+
+  puts "⏩ Skipping."
+  return
+end
+
+# include CableReady::Broadcaster in Action Cable Channel classes
+channel_path = Rails.root.join("app/channels/application_cable/channel.rb")
+if channel_path.exist?
+  lines = channel_path.readlines
+  if !lines.index { |line| line =~ /^\s*include CableReady::Broadcaster/ }
+    backup(channel_path) do
+      index = lines.index { |line| line.include?("class Channel < ActionCable::Channel::Base") }
+      lines.insert index + 1, "    include CableReady::Broadcaster\n"
+      channel_path.write lines.join
+    end
+
+    puts "✅ include CableReady::Broadcaster in Action Cable channels"
+  else
+    puts "⏩  already included CableReady::Broadcaster in Action Cable channels. Skipping"
+  end
+end
+
+# include CableReady::Broadcaster in Action Controller classes
+controller_path = Rails.root.join("app/controllers/application_controller.rb")
+if controller_path.exist?
+  lines = controller_path.readlines
+  if !lines.index { |line| line =~ /^\s*include CableReady::Broadcaster/ }
+    backup(controller_path) do
+      index = lines.index { |line| line.include?("class ApplicationController < ActionController::Base") }
+      lines.insert index + 1, "  include CableReady::Broadcaster\n"
+      controller_path.write lines.join
+    end
+
+    puts "✅ include CableReady::Broadcaster in Action Controller classes"
+  else
+    puts "⏩  already included CableReady::Broadcaster in Action Controller classes. Skipping"
+  end
+end
+
+# include CableReady::Broadcaster in Active Job classes, if present
+if defined?(ActiveJob)
+  job_path = Rails.root.join("app/jobs/application_job.rb")
+  if job_path.exist?
+    lines = job_path.readlines
+    if !lines.index { |line| line =~ /^\s*include CableReady::Broadcaster/ }
+      backup(job_path) do
+        index = lines.index { |line| line.include?("class ApplicationJob < ActiveJob::Base") }
+        lines.insert index + 1, "  include CableReady::Broadcaster\n"
+        job_path.write lines.join
+      end
+
+      puts "✅ include CableReady::Broadcaster in Active Job classes"
+    else
+      puts "⏩  already included CableReady::Broadcaster in Active Job classes. Skipping"
+    end
+  end
+else
+  puts "⏩ Active Job not available. Skipping."
+end
+
+# include CableReady::Broadcaster in StateMachines, if present
+if defined?(StateMachines)
+  lines = action_cable_initializer_working_path.read
+  if !lines.include?("StateMachines::Machine.prepend(CableReady::Broadcaster)")
+    inject_into_file action_cable_initializer_working_path, after: "CableReady.configure do |config|\n", verbose: false do
+      <<-RUBY
+
+  StateMachines::Machine.prepend(CableReady::Broadcaster)
+
+      RUBY
+    end
+
+    puts "✅ prepend CableReady::Broadcaster into StateMachines::Machine"
+  else
+    puts "⏩  already prepended CableReady::Broadcaster into StateMachines::Machine. Skipping"
+  end
+else
+  puts "⏩ StateMachines not available. Skipping."
+end
+
+# include CableReady::Broadcaster in Active Record model classes
+if Rails.root.join(application_record_path).exist?
+  lines = application_record_path.readlines
+  if !lines.index { |line| line =~ /^\s*include CableReady::Broadcaster/ }
+    backup(application_record_path) do
+      index = lines.index { |line| line.include?("class ApplicationRecord < ActiveRecord::Base") }
+      lines.insert index + 1, "  include CableReady::Broadcaster\n"
+      application_record_path.write lines.join
+    end
+
+    puts "✅ include CableReady::Broadcaster in Active Record model classes"
+  else
+    puts "⏩  already included CableReady::Broadcaster in Active Record model classes. Skipping"
+  end
+end
+
+complete_step :broadcaster