pulse_zero 0.3.0

data/lib/generators/pulse_zero/install/templates/backend/app/jobs/pulse/broadcast_job.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pulse
+  class BroadcastJob < ApplicationJob
+    queue_as { Pulse.config.queue_name }
+
+    discard_on ActiveJob::DeserializationError
+
+    retry_on StandardError, wait: :polynomially_longer, attempts: 5
+
+    def perform(streamables:, event:, payload:, request_id: nil)
+      return if ENV["PULSE_DISABLED"] == "true"
+
+      stream = Pulse::Streams::StreamName.signed_stream_name(streamables)
+      message = {
+        event: event,
+        payload: payload,
+        requestId: request_id,
+        at: Time.current.to_f
+      }
+
+      ActionCable.server.broadcast(stream, message.to_json)
+    rescue => e
+      Rails.logger.error "[Pulse] Broadcast job error: #{e.message}"
+      raise
+    end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/app/models/concerns/pulse/broadcastable.rb.tt

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Pulse::Broadcastable
+  extend ActiveSupport::Concern
+  include Pulse::Streams::Broadcasts
+
+  included do
+    thread_mattr_accessor :suppressed_pulse_broadcasts, instance_accessor: false
+  end
+
+  def suppressed_pulse_broadcasts?
+    self.class.suppressed_pulse_broadcasts
+  end
+
+  class_methods do
+    # Configures the model to broadcast creates, updates, and destroys
+    def broadcasts_to(stream, **rendering)
+      after_create_commit  -> { broadcast_created_later_to(stream.try(:call, self) || send(stream), **rendering) }
+      after_update_commit  -> { broadcast_updated_later_to(stream.try(:call, self) || send(stream), **rendering) }
+      after_destroy_commit -> { broadcast_deleted_to(stream.try(:call, self) || send(stream), **rendering) }
+    end
+
+    def broadcasts(stream = model_name.plural, **rendering)
+      broadcasts_to(stream, **rendering)
+    end
+
+    def broadcasts_refreshes_to(stream, **rendering)
+      after_commit -> { broadcast_refresh_later_to(stream.try(:call, self) || send(stream), **rendering) }
+    end
+
+    # Suppress broadcasts during bulk operations
+    def suppressing_pulse_broadcasts(&block)
+      original, self.suppressed_pulse_broadcasts = self.suppressed_pulse_broadcasts, true
+      yield
+    ensure
+      self.suppressed_pulse_broadcasts = original
+    end
+  end
+
+  # Instance methods with payload extraction
+  def broadcast_created_to(*streamables, **rendering)
+    broadcast_event_to(*streamables, event: :created, **extract_options_and_add_payload(rendering))
+  end
+
+  def broadcast_updated_to(*streamables, **rendering)
+    broadcast_event_to(*streamables, event: :updated, **extract_options_and_add_payload(rendering))
+  end
+
+  def broadcast_deleted_to(*streamables, **rendering)
+    broadcast_event_to(*streamables, event: :deleted, **extract_options_and_add_payload(rendering))
+  end
+
+  def broadcast_refresh_to(*streamables, **rendering)
+    broadcast_event_to(*streamables, event: :refresh, payload: {}, **rendering)
+  end
+
+  # Async variants
+  def broadcast_created_later_to(*streamables, **rendering)
+    broadcast_event_later_to(*streamables, event: :created, **extract_options_and_add_payload(rendering))
+  end
+
+  def broadcast_updated_later_to(*streamables, **rendering)
+    broadcast_event_later_to(*streamables, event: :updated, **extract_options_and_add_payload(rendering))
+  end
+
+  def broadcast_deleted_later_to(*streamables, **rendering)
+    broadcast_event_later_to(*streamables, event: :deleted, **extract_options_and_add_payload(rendering))
+  end
+
+  def broadcast_refresh_later_to(*streamables, **rendering)
+    broadcast_event_later_to(*streamables, event: :refresh, payload: {}, **rendering)
+  end
+
+  private
+
+  def extract_options_and_add_payload(rendering = {})
+    return rendering if suppressed_pulse_broadcasts?
+
+    rendering.tap do |opts|
+      # Use custom payload if provided, otherwise use serialized model
+      opts[:payload] ||= Pulse.serializer.call(self)
+      opts[:request_id] ||= Current.pulse_request_id if defined?(Current.pulse_request_id)
+    end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/app/models/current.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Current < ActiveSupport::CurrentAttributes
+  attribute :pulse_request_id
+
+  # Add other attributes as needed for your application
+  # attribute :account
+  # attribute :request
+end

data/lib/generators/pulse_zero/install/templates/backend/config/initializers/pulse.rb.tt

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+Rails.application.configure do
+  # Configure Pulse real-time broadcasting
+  # Note: Pulse module must be loaded from lib/pulse.rb
+
+  if defined?(Pulse)
+    # Debounce window in milliseconds
+    # This prevents rapid-fire broadcasts from overwhelming clients
+    Pulse.config.debounce_ms = 300
+
+    # Background job queue name
+    # Use a lower priority queue if broadcasts are not time-critical
+    Pulse.config.queue_name = :default
+
+    # Custom serializer for broadcast payloads
+    # Return a hash that will be sent to the frontend
+    # Default: ->(rec) { rec.as_json }
+    #
+    # Pulse.config.serializer = lambda do |record|
+    #   case record
+    #   when Post
+    #     {
+    #       id: record.id,
+    #       title: record.title,
+    #       content: record.content,
+    #       state: record.state,
+    #       author_name: record.user.name,
+    #       updated_at: record.updated_at.iso8601
+    #     }
+    #   else
+    #     record.as_json
+    #   end
+    # end
+
+    # Disable broadcasts in test environment
+    if Rails.env.test?
+      ENV["PULSE_DISABLED"] = "true"
+    end
+  else
+    Rails.logger.warn "[Pulse] Module not loaded. Ensure lib is in autoload paths and pulse.rb exists."
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/lib/pulse/engine.rb.tt

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Pulse
+  class Engine < Rails::Engine
+    isolate_namespace Pulse
+
+    config.pulse = ActiveSupport::OrderedOptions.new
+    config.pulse.queue_name = :default
+    config.pulse.debounce_ms = 300
+    config.pulse.serializer = ->(rec) { rec.as_json }
+
+    # Autoload paths for Pulse components
+    config.autoload_once_paths = %W[
+      #{root}/app/channels
+      #{root}/app/controllers/concerns
+      #{root}/app/models/concerns
+      #{root}/app/jobs
+    ]
+
+    # Don't eager load jobs if ActiveJob is not available
+    initializer "pulse.no_active_job", before: :set_eager_load_paths do
+      unless defined?(ActiveJob)
+        config.eager_load_paths.delete("#{root}/app/jobs")
+      end
+    end
+
+    # Don't eager load channels if ActionCable is not available
+    initializer "pulse.no_action_cable", before: :set_eager_load_paths do
+      unless defined?(ActionCable)
+        config.eager_load_paths.delete("#{root}/app/channels")
+      end
+    end
+
+    # Set up configuration after Rails loads
+    initializer "pulse.configure" do
+      if defined?(Rails) && Rails.application
+        Pulse.config = config.pulse
+      end
+    end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/lib/pulse/streams/broadcasts.rb.tt

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pulse::Streams::Broadcasts
+  include Pulse::Streams::StreamName
+
+  def broadcast_created_to(*streamables, **opts)
+    broadcast_event_to(*streamables, event: :created, **opts)
+  end
+
+  def broadcast_updated_to(*streamables, **opts)
+    broadcast_event_to(*streamables, event: :updated, **opts)
+  end
+
+  def broadcast_deleted_to(*streamables, **opts)
+    broadcast_event_to(*streamables, event: :deleted, **opts)
+  end
+
+  def broadcast_refresh_to(*streamables, **opts)
+    broadcast_event_to(*streamables, event: :refresh, payload: {}, **opts)
+  end
+
+  # Async variants
+  def broadcast_created_later_to(*streamables, **opts)
+    broadcast_event_later_to(*streamables, event: :created, **opts)
+  end
+
+  def broadcast_updated_later_to(*streamables, **opts)
+    broadcast_event_later_to(*streamables, event: :updated, **opts)
+  end
+
+  def broadcast_deleted_later_to(*streamables, **opts)
+    broadcast_event_later_to(*streamables, event: :deleted, **opts)
+  end
+
+  def broadcast_refresh_later_to(*streamables, **opts)
+    broadcast_event_later_to(*streamables, event: :refresh, payload: {}, **opts)
+  end
+
+  def broadcast_event_to(*streamables, event:, payload: nil, request_id: nil)
+    broadcast_stream_to(*streamables,
+      event: event,
+      payload: payload,
+      request_id: request_id
+    )
+  end
+
+  def broadcast_event_later_to(*streamables, **opts)
+    if defined?(Pulse::BroadcastJob)
+      streamables.flatten!
+      streamables.compact!
+      Pulse::BroadcastJob.perform_later(streamables: streamables, **opts)
+    else
+      broadcast_event_to(*streamables, **opts)
+    end
+  end
+
+  def broadcast_stream_to(*streamables, event:, payload:, request_id: nil)
+    streamables.flatten!
+    streamables.compact!
+
+    return if streamables.empty?
+    return if ENV["PULSE_DISABLED"] == "true"
+
+    stream = signed_stream_name(streamables)
+    message = {
+      event: event,
+      payload: payload,
+      requestId: request_id,
+      at: Time.current.to_f
+    }
+
+    if defined?(Pulse::ThreadDebouncer)
+      Pulse::ThreadDebouncer.for(stream).debounce do
+        ActionCable.server.broadcast(stream, message.to_json)
+      end
+    else
+      ActionCable.server.broadcast(stream, message.to_json)
+    end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/lib/pulse/streams/stream_name.rb.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pulse::Streams::StreamName
+  extend self
+
+  # Used by Pulse::Channel to verify a signed stream name
+  def verified_stream_name(signed_stream_name)
+    Pulse.signed_stream_verifier.verified signed_stream_name
+  rescue ActiveSupport::MessageVerifier::InvalidSignature
+    nil
+  end
+
+  # Used to generate a signed stream name from streamables
+  def signed_stream_name(streamables)
+    Pulse.signed_stream_verifier.generate stream_name_from(streamables)
+  end
+
+  module ClassMethods
+    # Can be used by custom channels to obtain signed stream name from params
+    def verified_stream_name_from_params
+      Pulse::Streams::StreamName.verified_stream_name(params[:'signed-stream-name'])
+    end
+  end
+
+  private
+
+  def stream_name_from(streamables)
+    if streamables.is_a?(Array)
+      streamables.map { |streamable| stream_name_from(streamable) }.join(":")
+    else
+      streamables.then { |streamable| streamable.try(:to_gid_param) || streamable.to_param }
+    end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/lib/pulse/thread_debouncer.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pulse
+  class ThreadDebouncer
+    def self.for(key, **opt)
+      Thread.current[key] ||= new(key, Thread.current, **opt)
+    end
+    private_class_method :new
+
+    def initialize(key, thread, delay: 0.3)
+      @key, @thread = key, thread
+      @delay = delay
+      @timer = nil
+      @mutex = Mutex.new
+    end
+
+    def debounce(&blk)
+      @mutex.synchronize do
+        @timer&.kill
+        @timer = Thread.new do
+          sleep @delay
+          blk.call
+        end.tap { Thread.current[@key] = nil }
+      end
+    end
+
+    def wait
+      @timer&.join
+    end
+  end
+end

data/lib/generators/pulse_zero/install/templates/backend/lib/pulse.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pulse
+  extend ActiveSupport::Autoload
+
+  autoload :Engine, "pulse/engine"
+  autoload :ThreadDebouncer, "pulse/thread_debouncer"
+
+  module Streams
+    extend ActiveSupport::Autoload
+
+    autoload :Broadcasts, "pulse/streams/broadcasts"
+    autoload :StreamName, "pulse/streams/stream_name"
+  end
+
+  # Configuration
+  mattr_accessor :config
+  self.config = ActiveSupport::OrderedOptions.new
+  config.queue_name = :default
+  config.debounce_ms = 300
+  config.serializer = ->(rec) { rec.as_json }
+
+  # Thread-safe stream verifier
+  class << self
+    attr_writer :signed_stream_verifier
+
+    def signed_stream_verifier
+      @signed_stream_verifier ||= begin
+        key = Rails.application.secret_key_base
+        ActiveSupport::MessageVerifier.new(key, serializer: JSON)
+      end
+    end
+
+    def serializer
+      config.serializer
+    end
+  end
+end