broadcast_hub 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 907683a270f04805b2b85e4944654acbe1cb840e5ba71883b0e23fc34d9d293e
+  data.tar.gz: b8752676687f1194caf0e90019041aaa77b2796ab654aac4e009078c7a7c141f
+SHA512:
+  metadata.gz: e3ce1fed49774c3a83009f3f65388de3f6ff7cc4d0ced5747a9b50518afdc2963e5c31019bc802950891b458df77ec49a5ed4887db130c4bb4240ab8dda3992b
+  data.tar.gz: b435a099c2559500fce4c455ea72d5a6571d7cdaf98b9998e7a7f320df02831fbd995e59be544cdcfeee87319db63924702879073ded0bf315206cb3cb0a6c8e

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-24
+
+### Added
+- Initial setup of broadcast_hub Rails engine
+- Stream channel for broadcasting
+- JavaScript controllers (jQuery and subscription)
+- Broadcaster concern for models
+- Services: PayloadBuilder, Renderer, StreamKeyContext, StreamKeyResolver
+- Install generator for broadcast_hub
+- Configuration support
+- Rubocop configuration
+- RSpec test setup with dummy Rails application
+- Devise integration with user authentication
+- Todo model with CRUD operations and broadcasting
+- Multiple UI components (alert, datatable, modal, toast, tooltip)
+- Multiple JavaScript controllers (todos, toggle_theme, render_errors, resource_table)
+- Localization support (English and Portuguese - Brazil)
+- Test factories for users and todos
+
+### Fixed
+- Initial project setup
+
+### Changed
+- Updated Gemfile dependencies
+- Enhanced dummy application with full Rails stack

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alef Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# BroadcastHub
+
+BroadcastHub is a reusable Action Cable broadcasting layer for Rails 5/6 apps that use server-rendered HTML and Sprockets. It replaces model-level Turbo stream helpers with an explicit payload contract sent over `BroadcastHub::StreamChannel`.
+
+## 1) What BroadcastHub is
+
+- Rails engine (`broadcast_hub`) scoped to Rails `>= 5.2`, `< 7.0`
+- Server concern (`BroadcastHub::Broadcaster`) for model callbacks and payload publishing
+- Generic Action Cable channel (`BroadcastHub::StreamChannel`) with authorization and stream key resolution
+- Browser helpers (`BroadcastHub.Subscription` and `BroadcastHub.JQueryController`) for applying append/prepend/update/remove actions
+
+BroadcastHub is designed to work without `turbo-rails`.
+
+## 2) Installation in host app
+
+Add the engine gem to the host app `Gemfile`:
+
+```ruby
+gem 'broadcast_hub', path: 'engines/broadcast_hub'
+```
+
+Install dependencies, then generate the initializer template:
+
+```bash
+bundle install
+bin/rails generate broadcast_hub:install
+```
+
+This creates `config/initializers/broadcast_hub.rb`.
+
+## 3) Initializer configuration
+
+Minimum required settings:
+
+- `allowed_resources`: allowlist of resource keys clients can subscribe to
+- `authorize_scope`: lambda that decides if the Action Cable connection can subscribe
+- `stream_key_resolver`: lambda that maps subscription context to a stream name used by both channel + model broadcaster
+
+Authenticated example:
+
+```ruby
+BroadcastHub.configure do |config|
+  config.allowed_resources = %w[todo]
+
+  config.authorize_scope = lambda do |context|
+    context.current_user.present?
+  end
+
+  config.stream_key_resolver = lambda do |context|
+    "resource:#{context.resource_name}:user:#{context.current_user.id}"
+  end
+end
+```
+
+No-auth/session example:
+
+```ruby
+BroadcastHub.configure do |config|
+  config.allowed_resources = %w[todo]
+
+  config.authorize_scope = lambda do |context|
+    context.session_id.present?
+  end
+
+  config.stream_key_resolver = lambda do |context|
+    "resource:#{context.resource_name}:session:#{context.session_id}"
+  end
+end
+```
+
+If your Action Cable connection does not expose `current_user`, expose a safe identifier (for example `session_id`) in `ApplicationCable::Connection`.
+
+## 4) Model integration
+
+Include the concern and declare broadcast settings in each model:
+
+```ruby
+class Todo < ApplicationRecord
+  include BroadcastHub::Broadcaster
+
+  broadcast_to :todo, partial: 'todos/partials/todo', target: '#todos'
+end
+```
+
+`broadcast_to` wires callbacks:
+
+- `after_create_commit` -> append
+- `after_update_commit` -> update
+- `after_destroy_commit` -> remove
+
+Optional context hook for stream-key alignment (recommended when keys depend on tenant/user/session):
+
+```ruby
+def broadcast_hub_stream_key_context_attributes
+  {
+    tenant_id: nil,
+    current_user: user,
+    session_id: nil,
+    params: {}
+  }
+end
+```
+
+## 5) Client-side integration (Sprockets)
+
+Require BroadcastHub in `app/assets/javascripts/application.js`:
+
+```js
+//= require broadcast_hub/index
+```
+
+Basic subscription wiring (compatible with this repo style):
+
+```js
+(function (global) {
+  function wireTodoChannel(consumer, $) {
+    var controller = new BroadcastHubJQueryController($);
+    var subscription = new BroadcastHubSubscription(consumer, controller);
+
+    return subscription.subscribe('todo');
+  }
+
+  if (global.App && global.App.cable && global.jQuery) {
+    global.App.todo_channel = wireTodoChannel(global.App.cable, global.jQuery);
+  }
+})(this);
+```
+
+`BroadcastHubSubscription` sends `{ channel: 'BroadcastHub::StreamChannel', resource: 'todo' }` and the controller applies incoming payloads to the DOM.
+
+## 6) Payload contract
+
+Payloads emitted by `BroadcastHub::PayloadBuilder` follow this shape:
+
+```json
+{
+  "version": 1,
+  "action": "append",
+  "target": "#todos",
+  "content": "<div id=\"todo_1\">...</div>",
+  "id": "todo_1"
+}
+```
+
+Field meaning:
+
+- `action`: one of `append`, `prepend`, `update`, `remove`
+- `target`: CSS selector used as insertion/update/remove target
+- `content`: rendered HTML for append/prepend/update (typically `null` on remove)
+- `id`: DOM id used by update/remove fast-path replacement
+- `version`: payload contract version from `BroadcastHub.configuration.payload_version`
+

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rdoc/task'
+
+RDoc::Task.new :rdoc do |rdoc|
+  rdoc.main = 'README.md'
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = 'BroadcastHub Documentation'
+  rdoc.options << '--line-numbers' << '--inline-muted'
+  rdoc.rdoc_files.include 'README.md', 'CHANGELOG.md', 'lib/**/*.rb'
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.options = ['--no-output']
+  end
+rescue LoadError
+end

data/app/assets/config/manifest.js

@@ -0,0 +1,2 @@
+//= link_directory ../javascripts/broadcast_hub .js
+

data/app/channels/broadcast_hub/stream_channel.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  # Action Cable channel that subscribes clients to authorized BroadcastHub streams.
+  class StreamChannel < ApplicationCable::Channel
+    # Starts stream subscription for the current channel connection.
+    #
+    # @return [void]
+    def subscribed
+      stream_from(BroadcastHub::StreamKeyResolver.resolve!(stream_key_context))
+    rescue BroadcastHub::StreamKeyResolver::Unauthorized => e
+      logger.info("broadcast_hub.reject reason=#{e.message}") if defined?(Rails) && Rails.env.development?
+      reject
+    end
+
+    private
+
+    # Builds the stream key context from connection data and params.
+    #
+    # @return [BroadcastHub::StreamKeyContext]
+    def stream_key_context
+      BroadcastHub::StreamKeyContext.from_connection(connection: connection, params: params)
+    end
+  end
+end

data/app/javascripts/broadcast_hub/index.js

@@ -0,0 +1,30 @@
+import BroadcastHubJQueryController from './jquery_controller';
+import BroadcastHubSubscription from './subscription';
+
+/**
+ * Global object where browser runtime references are attached.
+ *
+ * @type {Window|typeof globalThis}
+ */
+const root = typeof window !== 'undefined' ? window : globalThis;
+
+if (root) {
+  root.BroadcastHubJQueryController = BroadcastHubJQueryController;
+  root.BroadcastHubSubscription = BroadcastHubSubscription;
+
+  root.BroadcastHub = root.BroadcastHub || {};
+  root.BroadcastHub.JQueryController = root.BroadcastHubJQueryController;
+  root.BroadcastHub.Subscription = root.BroadcastHubSubscription;
+}
+
+export { BroadcastHubJQueryController, BroadcastHubSubscription };
+
+/**
+ * Public API exported by the BroadcastHub package entrypoint.
+ *
+ * @type {{BroadcastHubJQueryController: typeof BroadcastHubJQueryController, BroadcastHubSubscription: typeof BroadcastHubSubscription}}
+ */
+export default {
+  BroadcastHubJQueryController,
+  BroadcastHubSubscription
+};

data/app/javascripts/broadcast_hub/jquery_controller.js

@@ -0,0 +1,69 @@
+function isBlank(value) {
+  return value == null || String(value).trim() === '';
+}
+
+export default class BroadcastHubJQueryController {
+  constructor($, options) {
+    this.$ = $;
+    this.env = (options && options.env) || 'production';
+  }
+
+  apply(payload) {
+    const action = payload && payload.action;
+    const targetSelector = payload && payload.target;
+    const content = payload && payload.content;
+    const id = payload && payload.id;
+
+    if (!this._isValidPayload(action, targetSelector, content)) {
+      this._warnInvalidPayload();
+      return;
+    }
+
+    const $target = this.$(targetSelector);
+    const $byId = id ? this.$(`#${id}`) : this.$();
+
+    switch (action) {
+      case 'append':
+        $target.append(content);
+        return;
+      case 'prepend':
+        $target.prepend(content);
+        return;
+      case 'update':
+        if ($byId.length > 0) {
+          $byId.replaceWith(content);
+        } else {
+          $target.html(content);
+        }
+        return;
+      case 'remove':
+        if (id) {
+          const $withinTarget = $target.filter(`#${id}`).add($target.find(`#${id}`)).first();
+          if ($withinTarget.length > 0) {
+            $withinTarget.remove();
+          }
+        }
+        return;
+      default:
+        this._warnInvalidPayload();
+    }
+  }
+
+  _isValidPayload(action, targetSelector, content) {
+    if (isBlank(action) || isBlank(targetSelector)) {
+      return false;
+    }
+
+    if ((action === 'append' || action === 'prepend' || action === 'update') && isBlank(content)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  _warnInvalidPayload() {
+    if (this.env === 'development' && typeof console !== 'undefined' && typeof console.warn === 'function') {
+      console.warn('[BroadcastHub] Invalid payload ignored.');
+    }
+  }
+}

data/app/javascripts/broadcast_hub/subscription.js

@@ -0,0 +1,33 @@
+function isBlank(value) {
+  return value == null || String(value).trim() === '';
+}
+
+export default class BroadcastHubSubscription {
+  constructor(consumer, controller) {
+    this.consumer = consumer;
+    this.controller = controller;
+  }
+
+  subscribe(resource, tenant) {
+    if (isBlank(resource)) {
+      throw new Error('resource is required');
+    }
+
+    const params = {
+      channel: 'BroadcastHub::StreamChannel',
+      resource: String(resource)
+    };
+
+    if (!isBlank(tenant)) {
+      params.tenant = String(tenant);
+    }
+
+    return this.consumer.subscriptions.create(params, {
+      received: this._handleReceived.bind(this)
+    });
+  }
+
+  _handleReceived(payload) {
+    this.controller.apply(payload);
+  }
+}

data/app/models/concerns/broadcast_hub/broadcaster.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  # Adds lifecycle-driven Action Cable broadcasting helpers to models.
+  module Broadcaster
+    extend ActiveSupport::Concern
+
+    # Broadcasts an append action for the model instance.
+    #
+    # @param target [String] DOM target for insertion
+    # @return [void]
+    def broadcast_append(target)
+      broadcast_action("append", target)
+    end
+
+    # Broadcasts a prepend action for the model instance.
+    #
+    # @param target [String] DOM target for insertion
+    # @return [void]
+    def broadcast_prepend(target)
+      broadcast_action("prepend", target)
+    end
+
+    # Broadcasts an update action for the model instance.
+    #
+    # @param target [String] DOM target to replace
+    # @return [void]
+    def broadcast_update(target)
+      broadcast_action("update", target)
+    end
+
+    # Broadcasts a remove action for the model instance.
+    #
+    # @param target [String] DOM target to remove
+    # @return [void]
+    def broadcast_remove(target)
+      broadcast_action("remove", target)
+    end
+
+    class_methods do
+      # Configures callbacks and rendering metadata for model broadcasts.
+      #
+      # @param resource_name [String, Symbol] stream resource identifier
+      # @param partial [String] partial used to render broadcast content
+      # @param target [String] default DOM target used by lifecycle callbacks
+      # @return [void]
+      def broadcast_to(resource_name, partial:, target:)
+        define_method(:broadcast_hub_resource_name) { resource_name.to_s }
+        define_method(:broadcast_hub_partial) { partial }
+        define_method(:broadcast_hub_target) { target }
+
+        after_create_commit { broadcast_append(broadcast_hub_target) }
+        after_update_commit { broadcast_update(broadcast_hub_target) }
+        after_destroy_commit { broadcast_remove(broadcast_hub_target) }
+      end
+    end
+
+    private
+
+    # Broadcasts a payload to the configured stream key.
+    #
+    # @param action [String] payload action
+    # @param target [String] DOM target
+    # @return [void]
+    def broadcast_action(action, target)
+      content = action == "remove" ? nil : render_broadcast_content
+      payload = BroadcastHub::PayloadBuilder.build(
+        action: action,
+        target: target,
+        content: content,
+        id: broadcast_hub_dom_id,
+        meta: {}
+      )
+
+      ActionCable.server.broadcast(broadcast_hub_stream_key, payload)
+    end
+
+    # Renders model content used in append/prepend/update actions.
+    #
+    # @return [String]
+    def render_broadcast_content
+      BroadcastHub::Renderer.new.render(
+        partial: broadcast_hub_partial,
+        locals: { self.class.model_name.singular.to_sym => self }
+      )
+    end
+
+    # Resolves the stream key for the current model event.
+    #
+    # @return [String]
+    # @raise [RuntimeError] when stream key resolver is not configured
+    def broadcast_hub_stream_key
+      resolver = BroadcastHub.configuration.stream_key_resolver
+      raise "stream_key_resolver not configured" unless resolver
+
+      context_attributes = {
+        tenant_id: nil,
+        current_user: nil,
+        session_id: nil,
+        params: {}
+      }.merge((broadcast_hub_stream_key_context_attributes || {}).to_h)
+
+      resolver.call(
+        BroadcastHub::StreamKeyContext.new(
+          resource_name: broadcast_hub_resource_name,
+          tenant_id: context_attributes[:tenant_id],
+          current_user: context_attributes[:current_user],
+          session_id: context_attributes[:session_id],
+          params: context_attributes[:params]
+        )
+      )
+    end
+
+    # Default context attributes used for stream key resolution.
+    #
+    # @return [Hash]
+    def broadcast_hub_stream_key_context_attributes
+      {
+        tenant_id: nil,
+        current_user: nil,
+        session_id: nil,
+        params: {}
+      }
+    end
+
+    # Generates a stable payload identifier for this instance.
+    #
+    # @return [String]
+    def broadcast_hub_dom_id
+      "#{self.class.model_name.singular}_#{id}"
+    end
+  end
+end

data/app/services/broadcast_hub/payload_builder.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  # Builds and validates normalized payloads sent through Action Cable.
+  class PayloadBuilder
+    # Raised when payload data is invalid.
+    class ValidationError < StandardError; end
+
+    VALID_ACTIONS = %w[append prepend update remove].freeze
+    ACTIONS_REQUIRING_CONTENT = %w[append prepend update].freeze
+    ALLOWED_KEYS = %i[version action target content id meta].freeze
+
+    class << self
+      # Builds the broadcast payload hash.
+      #
+      # @param action [String] one of {VALID_ACTIONS}
+      # @param target [String] DOM target identifier
+      # @param content [String, nil] rendered HTML for non-remove actions
+      # @param id [String] unique entry identifier
+      # @param meta [Hash, nil] optional metadata included in the payload
+      # @return [Hash] payload constrained to {ALLOWED_KEYS}
+      # @raise [ValidationError] when any input fails validation
+      def build(action:, target:, content:, id:, meta: {})
+        validate_action!(action)
+        validate_target!(target)
+        validate_content!(action, content)
+
+        payload = {
+          version: BroadcastHub.configuration.payload_version,
+          action: action,
+          target: target,
+          content: content,
+          id: id,
+          meta: normalize_meta(meta)
+        }
+
+        payload.slice(*ALLOWED_KEYS)
+      end
+
+      private
+
+      # @param action [String]
+      # @raise [ValidationError]
+      def validate_action!(action)
+        raise ValidationError, "invalid action" unless VALID_ACTIONS.include?(action)
+      end
+
+      # @param target [String]
+      # @raise [ValidationError]
+      def validate_target!(target)
+        raise ValidationError, "target required" if target.to_s.strip.empty?
+      end
+
+      # @param action [String]
+      # @param content [String, nil]
+      # @raise [ValidationError]
+      def validate_content!(action, content)
+        return unless ACTIONS_REQUIRING_CONTENT.include?(action)
+        raise ValidationError, "content required" if content.to_s.strip.empty?
+      end
+
+      # @param meta [Hash, nil]
+      # @return [Hash]
+      # @raise [ValidationError]
+      def normalize_meta(meta)
+        return {} if meta.nil?
+        raise ValidationError, "meta must be a hash" unless meta.is_a?(Hash)
+
+        meta
+      end
+    end
+  end
+end

data/app/services/broadcast_hub/renderer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  # Renders partials used in broadcast payloads.
+  class Renderer
+    # @param renderer [#render] rendering backend, defaults to Rails renderer
+    def initialize(renderer: ApplicationController.renderer)
+      @renderer = renderer
+    end
+
+    # Renders a partial with locals.
+    #
+    # @param partial [String] partial path
+    # @param locals [Hash] locals passed to the partial
+    # @return [String] rendered HTML fragment
+    def render(partial:, locals: {})
+      @renderer.render(partial: partial, locals: locals)
+    end
+  end
+end

data/app/services/broadcast_hub/stream_key_context.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  # Immutable context object shared by stream key authorization and resolution.
+  class StreamKeyContext
+    attr_reader :resource_name, :tenant_id, :current_user, :session_id, :params
+
+    # Builds a context from an Action Cable connection and channel params.
+    #
+    # @param connection [Object] Action Cable connection
+    # @param params [#to_h, #to_unsafe_h] channel subscription params
+    # @return [BroadcastHub::StreamKeyContext]
+    def self.from_connection(connection:, params: {})
+      normalized_params = normalize_params(params)
+
+      new(
+        resource_name: normalized_params[:resource],
+        tenant_id: normalized_params[:tenant],
+        current_user: connection_value(connection, :current_user),
+        session_id: connection_value(connection, :session_id) || normalized_params[:session_id],
+        params: normalized_params
+      )
+    end
+
+    # @param resource_name [String, Symbol, nil] resource requested by the client
+    # @param tenant_id [Object] tenant identity for scoped streams
+    # @param current_user [Object] authenticated user on the connection
+    # @param session_id [String, nil] optional session identifier
+    # @param params [Hash] normalized channel params
+    def initialize(resource_name:, tenant_id:, current_user:, session_id:, params: {})
+      @resource_name = resource_name
+      @tenant_id = tenant_id
+      @current_user = current_user
+      @session_id = session_id
+      @params = (params || {}).dup.freeze
+      freeze
+    end
+
+    class << self
+      private
+
+      # @param params [#to_h, #to_unsafe_h]
+      # @return [Hash] params normalized to symbol keys
+      def normalize_params(params)
+        hash = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+        hash.symbolize_keys
+      rescue StandardError
+        {}
+      end
+
+      # @param connection [Object]
+      # @param key [Symbol]
+      # @return [Object, nil]
+      def connection_value(connection, key)
+        return nil unless connection.respond_to?(key)
+
+        connection.public_send(key)
+      end
+    end
+  end
+end

data/app/services/broadcast_hub/stream_key_resolver.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  # Validates subscription context and resolves an Action Cable stream key.
+  class StreamKeyResolver
+    # Raised when the context cannot subscribe to the requested resource.
+    class Unauthorized < StandardError; end
+
+    class << self
+      # Resolves the stream key for a subscription context.
+      #
+      # @param context [BroadcastHub::StreamKeyContext] normalized subscription context
+      # @return [String] stream identifier used by Action Cable
+      # @raise [Unauthorized] when the context is invalid or not authorized
+      def resolve!(context)
+        reject!("missing_resource") if context.resource_name.to_s.strip.empty?
+
+        allowed_resources = Array(configuration.allowed_resources).map(&:to_s)
+        reject!("invalid_resource") unless allowed_resources.include?(context.resource_name.to_s)
+
+        authorize_scope = configuration.authorize_scope
+        reject!("missing_authorize_scope") unless authorize_scope.respond_to?(:call)
+        reject!("unauthorized_scope") unless authorize_scope.call(context)
+
+        stream_key_resolver = configuration.stream_key_resolver
+        reject!("missing_stream_key_resolver") unless stream_key_resolver.respond_to?(:call)
+
+        stream_key = stream_key_resolver.call(context)
+        reject!("missing_identity") if stream_key.to_s.strip.empty?
+
+        stream_key
+      end
+
+      private
+
+      # @return [BroadcastHub::Configuration]
+      def configuration
+        BroadcastHub.configuration
+      end
+
+      # @param reason [String] symbolic rejection reason
+      # @raise [Unauthorized]
+      def reject!(reason)
+        raise Unauthorized, reason
+      end
+    end
+  end
+end

data/lib/broadcast_hub/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  class Configuration
+    attr_accessor :payload_version,
+                  :update_strategy,
+                  :strict_client_validation,
+                  :allowed_resources,
+                  :authorize_scope,
+                  :stream_key_resolver
+
+    def initialize
+      @payload_version = 1
+      @update_strategy = :replace_with
+      @strict_client_validation = false
+      @allowed_resources = []
+      @authorize_scope = nil
+      @stream_key_resolver = nil
+    end
+  end
+end

data/lib/broadcast_hub/engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  class Engine < ::Rails::Engine
+    isolate_namespace BroadcastHub
+  end
+end

data/lib/broadcast_hub/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module BroadcastHub
+  VERSION = "0.1.0"
+
+  class Version
+    def self.to_s
+      VERSION
+    end
+  end
+end

data/lib/broadcast_hub.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "logger"
+require "broadcast_hub/version"
+require "broadcast_hub/configuration"
+require "broadcast_hub/engine"
+
+module BroadcastHub
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/generators/broadcast_hub/install_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "logger"
+require "rails/generators"
+
+module BroadcastHub
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "broadcast_hub.rb.tt", "config/initializers/broadcast_hub.rb"
+      end
+
+      def add_javascript_requires
+        manifest_path = "app/assets/javascripts/application.js"
+        absolute_manifest_path = File.expand_path(manifest_path, destination_root)
+
+        unless File.exist?(absolute_manifest_path)
+          say_status :skip, "#{manifest_path} not found", :yellow
+          return
+        end
+
+        directives = [
+          "//= require jquery3",
+          "//= require broadcast_hub/index"
+        ]
+
+        manifest_content = File.read(absolute_manifest_path)
+        missing_directives = directives.reject { |directive| manifest_content.include?(directive) }
+        return if missing_directives.empty?
+
+        append_to_file manifest_path, "\n#{missing_directives.join("\n")}\n"
+      end
+
+      def show_javascript_install_hint
+        say "Add BroadcastHub assets in app/assets/javascripts/application.js:"
+        say "//= require jquery3"
+        say "//= require broadcast_hub/index"
+      end
+    end
+  end
+end

data/lib/generators/broadcast_hub/templates/broadcast_hub.rb.tt

@@ -0,0 +1,35 @@
+BroadcastHub.configure do |config|
+  # Allowlist channel resources that clients are permitted to subscribe to.
+  # Add your resource keys here.
+  config.allowed_resources = %w[todo]
+
+  # Required: return true when the connection context can subscribe to
+  # the requested scope. Keep this check strict.
+  config.authorize_scope = lambda do |context|
+    context.current_user.present? || context.session_id.present?
+  end
+
+  # Default stream key keeps publisher and subscriber contexts aligned even when
+  # models do not provide current_user/session_id/tenant_id attributes.
+  #
+  # If your app needs tenant/user/session isolation, customize this resolver.
+  # See examples below.
+  config.stream_key_resolver = lambda do |context|
+    "resource:#{context.resource_name}"
+  end
+
+  # Auth mode example (customize authorize_scope to match your policy):
+  #
+  # config.stream_key_resolver = lambda do |context|
+  #   "tenant:#{context.tenant_id}:#{context.resource_name}:user:#{context.current_user.id}"
+  # end
+
+  # No-auth mode example (for public/session-based channels):
+  #
+  # config.stream_key_resolver = lambda do |context|
+  #   "tenant:#{context.tenant_id}:#{context.resource_name}:session:#{context.session_id}"
+  # end
+end
+
+# For apps without `current_user` in Action Cable, expose a safe `session_id`
+# identifier in ApplicationCable::Connection.

data/vendor/assets/javascripts/broadcast_hub/index.js

@@ -0,0 +1,8 @@
+//= require broadcast_hub/jquery_controller
+//= require broadcast_hub/subscription
+
+(function (global) {
+  global.BroadcastHub = global.BroadcastHub || {};
+  global.BroadcastHub.JQueryController = global.BroadcastHubJQueryController;
+  global.BroadcastHub.Subscription = global.BroadcastHubSubscription;
+})(this);

data/vendor/assets/javascripts/broadcast_hub/jquery_controller.js

@@ -0,0 +1,71 @@
+(function (global) {
+  function isBlank(value) {
+    return value == null || String(value).trim() === '';
+  }
+
+  function BroadcastHubJQueryController($, options) {
+    this.$ = $;
+    this.env = (options && options.env) || 'production';
+  }
+
+  BroadcastHubJQueryController.prototype.apply = function (payload) {
+    var action = payload && payload.action;
+    var targetSelector = payload && payload.target;
+    var content = payload && payload.content;
+    var id = payload && payload.id;
+
+    if (!this._isValidPayload(action, targetSelector, content)) {
+      this._warnInvalidPayload();
+      return;
+    }
+
+    var $target = this.$(targetSelector);
+    var $byId = id ? this.$('#' + id) : this.$();
+
+    switch (action) {
+      case 'append':
+        $target.append(content);
+        return;
+      case 'prepend':
+        $target.prepend(content);
+        return;
+      case 'update':
+        if ($byId.length > 0) {
+          $byId.replaceWith(content);
+        } else {
+          $target.html(content);
+        }
+        return;
+      case 'remove':
+        if (id) {
+          var $withinTarget = $target.filter('#' + id).add($target.find('#' + id)).first();
+          if ($withinTarget.length > 0) {
+            $withinTarget.remove();
+          }
+        }
+        return;
+      default:
+        this._warnInvalidPayload();
+    }
+  };
+
+  BroadcastHubJQueryController.prototype._isValidPayload = function (action, targetSelector, content) {
+    if (isBlank(action) || isBlank(targetSelector)) {
+      return false;
+    }
+
+    if ((action === 'append' || action === 'prepend' || action === 'update') && isBlank(content)) {
+      return false;
+    }
+
+    return true;
+  };
+
+  BroadcastHubJQueryController.prototype._warnInvalidPayload = function () {
+    if (this.env === 'development' && global.console && typeof global.console.warn === 'function') {
+      global.console.warn('[BroadcastHub] Invalid payload ignored.');
+    }
+  };
+
+  global.BroadcastHubJQueryController = BroadcastHubJQueryController;
+})(this);

data/vendor/assets/javascripts/broadcast_hub/subscription.js

@@ -0,0 +1,35 @@
+(function (global) {
+  function isBlank(value) {
+    return value == null || String(value).trim() === '';
+  }
+
+  function BroadcastHubSubscription(consumer, controller) {
+    this.consumer = consumer;
+    this.controller = controller;
+  }
+
+  BroadcastHubSubscription.prototype.subscribe = function (resource, tenant) {
+    if (isBlank(resource)) {
+      throw new Error('resource is required');
+    }
+
+    var params = {
+      channel: 'BroadcastHub::StreamChannel',
+      resource: String(resource)
+    };
+
+    if (!isBlank(tenant)) {
+      params.tenant = String(tenant);
+    }
+
+    return this.consumer.subscriptions.create(params, {
+      received: this._handleReceived.bind(this)
+    });
+  };
+
+  BroadcastHubSubscription.prototype._handleReceived = function (payload) {
+    this.controller.apply(payload);
+  };
+
+  global.BroadcastHubSubscription = BroadcastHubSubscription;
+})(this);

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: broadcast_hub
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alef Oliveira
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jquery-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/manifest.js
+- app/channels/broadcast_hub/stream_channel.rb
+- app/javascripts/broadcast_hub/index.js
+- app/javascripts/broadcast_hub/jquery_controller.js
+- app/javascripts/broadcast_hub/subscription.js
+- app/models/concerns/broadcast_hub/broadcaster.rb
+- app/services/broadcast_hub/payload_builder.rb
+- app/services/broadcast_hub/renderer.rb
+- app/services/broadcast_hub/stream_key_context.rb
+- app/services/broadcast_hub/stream_key_resolver.rb
+- lib/broadcast_hub.rb
+- lib/broadcast_hub/configuration.rb
+- lib/broadcast_hub/engine.rb
+- lib/broadcast_hub/version.rb
+- lib/generators/broadcast_hub/install_generator.rb
+- lib/generators/broadcast_hub/templates/broadcast_hub.rb.tt
+- vendor/assets/javascripts/broadcast_hub/index.js
+- vendor/assets/javascripts/broadcast_hub/jquery_controller.js
+- vendor/assets/javascripts/broadcast_hub/subscription.js
+homepage: https://github.com/nemuba/broadcast_hub
+licenses: []
+metadata:
+  homepage_uri: https://github.com/nemuba/broadcast_hub
+  source_code_uri: https://github.com/nemuba/broadcast_hub
+  changelog_uri: https://github.com/nemuba/broadcast_hub/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/nemuba/broadcast_hub/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options:
+- "--title"
+- BroadcastHub
+- "--main"
+- README.md
+- "--line-numbers"
+- "--inline-muted"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key: 
+specification_version: 4
+summary: Reusable Action Cable broadcasting engine for Rails 5/6
+test_files: []