inertia_cable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3eef5ebaf526671cbdfa7efd381c2487f9ec19633a4dd6478bd3f399f262c1c
+  data.tar.gz: 064c84423d1c5742e146404d410581d5610223e916082e94c71c214336ab3247
+SHA512:
+  metadata.gz: b16694b36fc8c42c3661a66d6ef94329b306a4b40a183f866993ed43460d3538ae120b68b5ec5115d83523cb252204fc34721c52fd93ba93e376a3246287caeb
+  data.tar.gz: '01828651d1f2f96acbe07e85c5b02cd64153a7f7089a99e77c8d054e6694bd71c8514e6a8a7f864735ca0fac42f7c0358681194c0f7de914206f9ed3577e0799'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cole Robertson
+
+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,454 @@
+# InertiaCable
+
+ActionCable broadcast DSL for [Inertia.js](https://inertiajs.com/) Rails applications. Three lines of code to get real-time updates.
+
+InertiaCable broadcasts lightweight JSON signals over ActionCable. The client receives them and calls `router.reload()` to re-fetch props through Inertia's normal HTTP flow. No data travels over the WebSocket — your controller stays the single source of truth.
+
+```
+Model save → after_commit → ActionCable broadcast (signal)
+                                    ↓
+React hook subscribes → receives signal → router.reload({ only: ['messages'] })
+                                    ↓
+Inertia HTTP request → controller re-evaluates props → React re-renders
+```
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Model DSL](#model-dsl)
+- [Controller Helper](#controller-helper)
+- [React Hook](#react-hook)
+- [Suppressing Broadcasts](#suppressing-broadcasts)
+- [Server-Side Debounce](#server-side-debounce)
+- [Testing](#testing)
+- [Configuration](#configuration)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [Requirements](#requirements)
+- [Development](#development)
+- [License](#license)
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "inertia_cable"
+```
+
+Install the frontend package:
+
+```bash
+npm install @inertia-cable/react @rails/actioncable
+```
+
+Optionally run the install generator:
+
+```bash
+rails generate inertia_cable:install
+```
+
+## Quick Start
+
+### 1. Model — declare what broadcasts
+
+```ruby
+class Message < ApplicationRecord
+  belongs_to :chat
+  broadcasts_to :chat
+end
+```
+
+### 2. Controller — pass a signed stream token as a prop
+
+```ruby
+class ChatsController < ApplicationController
+  def show
+    chat = Chat.find(params[:id])
+    render inertia: 'Chats/Show', props: {
+      chat: chat.as_json,
+      messages: -> { chat.messages.order(:created_at).as_json },
+      cable_stream: inertia_cable_stream(chat)
+    }
+  end
+end
+```
+
+### 3. React — subscribe to the stream
+
+```tsx
+import { useInertiaCable } from '@inertia-cable/react'
+
+export default function ChatShow({ chat, messages, cable_stream }) {
+  useInertiaCable(cable_stream, { only: ['messages'] })
+
+  return (
+    <div>
+      <h1>{chat.name}</h1>
+      {messages.map(msg => <Message key={msg.id} message={msg} />)}
+    </div>
+  )
+}
+```
+
+That's it. When any user creates, updates, or deletes a message, all connected clients automatically reload the `messages` prop.
+
+---
+
+## Model DSL
+
+### `broadcasts_to`
+
+Broadcasts a refresh signal to a named stream whenever the model is committed (via a single `after_commit` callback).
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :board
+
+  broadcasts_to :board                                  # stream to associated record
+  broadcasts_to ->(post) { [post.board, :posts] }       # stream to a lambda
+  broadcasts_to "global_feed"                           # stream to a static string
+end
+```
+
+`broadcasts_refreshes_to` is available as a legacy alias.
+
+#### Stream resolution
+
+| Argument | Resolves to |
+|----------|-------------|
+| `:symbol` | Calls the method on the record (`post.board`) |
+| `Proc` / `lambda` | Calls with the record (`->(post) { ... }`) |
+| `String` | Used as-is |
+| ActiveRecord model | GlobalID (`gid://app/Board/1`) |
+| `Array` | Joins elements with `:` after resolving each |
+
+#### Options
+
+```ruby
+class Post < ApplicationRecord
+  # on: — limit which events trigger broadcasts (default: all)
+  broadcasts_to :board, on: [:create, :destroy]
+
+  # if: / unless: — standard Rails callback conditions
+  broadcasts_to :board, if: :published?
+  broadcasts_to :board, unless: -> { draft? }
+
+  # extra: — attach custom data to the payload (Hash or Proc)
+  broadcasts_to :board, extra: { priority: "high" }
+  broadcasts_to :board, extra: ->(post) { { category: post.category } }
+
+  # debounce: — coalesce rapid broadcasts server-side (requires shared cache store)
+  broadcasts_to :board, debounce: true        # uses global InertiaCable.debounce_delay
+  broadcasts_to :board, debounce: 1.0         # custom delay in seconds
+
+  # Options compose
+  broadcasts_to :board, on: [:create, :destroy], if: :published?
+end
+```
+
+### `broadcasts`
+
+Convention-based version that broadcasts to `model_name.plural` (e.g., `"posts"`):
+
+```ruby
+class Post < ApplicationRecord
+  broadcasts                           # broadcasts to "posts"
+  broadcasts on: [:create, :destroy]   # with options
+end
+```
+
+`broadcasts_refreshes` is available as a legacy alias.
+
+### Instance methods
+
+```ruby
+post = Post.find(1)
+
+# Sync
+post.broadcast_refresh_to(board)
+post.broadcast_refresh_to(board, :posts)       # compound stream
+post.broadcast_refresh                         # to model_name.plural
+
+# Async (via ActiveJob)
+post.broadcast_refresh_later_to(board)
+post.broadcast_refresh_later
+
+# With extra payload or debounce
+post.broadcast_refresh_to(board, extra: { priority: "high" })
+post.broadcast_refresh_later_to(board, debounce: 2.0)
+
+# With inline condition (block — skips broadcast if falsy)
+post.broadcast_refresh_to(board) { published? }
+```
+
+### Broadcast payload
+
+Every broadcast sends this JSON:
+
+```json
+{
+  "type": "refresh",
+  "model": "Message",
+  "id": 42,
+  "action": "create",
+  "timestamp": "2026-02-02T18:15:19+00:00",
+  "extra": {}
+}
+```
+
+The `action` field is `"create"`, `"update"`, or `"destroy"`. The `extra` field contains data from the `extra:` option (empty object if not set).
+
+---
+
+## Controller Helper
+
+`inertia_cable_stream` generates a cryptographically signed stream token. Pass it as an Inertia prop.
+
+```ruby
+inertia_cable_stream(chat)                # signed "gid://app/Chat/1"
+inertia_cable_stream("posts")             # signed "posts"
+inertia_cable_stream(chat, :messages)     # signed "gid://app/Chat/1:messages"
+```
+
+Each element is resolved individually: objects that respond to `to_gid_param` use GlobalID, otherwise `to_param` is called. Nested arrays are flattened and `nil`/blank elements are stripped.
+
+The token is verified server-side when the client subscribes — invalid or tampered tokens are rejected.
+
+---
+
+## React Hook
+
+> Only the React adapter (`@inertia-cable/react`) is available. Vue and Svelte adapters are welcome as community contributions.
+
+### `useInertiaCable(signedStreamName, options?)`
+
+Returns `{ connected }` — a boolean indicating whether the WebSocket subscription is active.
+
+```tsx
+const { connected } = useInertiaCable(cable_stream, {
+  only: ['messages'],           // only reload these props
+  except: ['metadata'],         // reload all except these
+  onRefresh: (data) => {        // callback before each reload
+    console.log(`${data.model} #${data.id} was ${data.action}`)
+    if (data.extra?.priority === 'high') toast.warn('Priority update!')
+  },
+  onConnected: () => {},        // subscription connected
+  onDisconnected: () => {},     // connection dropped
+  debounce: 200,                // client-side debounce in ms (default: 100)
+  enabled: isVisible,           // disable/enable subscription (default: true)
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `only` | `string[]` | — | Only reload these props |
+| `except` | `string[]` | — | Reload all props except these |
+| `onRefresh` | `(data) => void` | — | Callback before each reload |
+| `onConnected` | `() => void` | — | Called when subscription connects |
+| `onDisconnected` | `() => void` | — | Called when connection drops |
+| `debounce` | `number` | `100` | Debounce delay in ms |
+| `enabled` | `boolean` | `true` | Enable/disable subscription |
+
+**Automatic catch-up on reconnection:** When a WebSocket connection drops and reconnects (e.g., network interruption or backgrounded tab), the hook automatically triggers a `router.reload()` to fetch any changes missed while disconnected. This only fires on *re*connection — not the initial connect. ActionCable handles the reconnection itself (with exponential backoff); the hook just ensures your props are fresh when it comes back.
+
+Use `connected` to show connection state in the UI:
+
+```tsx
+const { connected } = useInertiaCable(cable_stream, { only: ['messages'] })
+
+if (!connected) return <Banner>Reconnecting…</Banner>
+```
+
+### Multiple streams on one page
+
+```tsx
+function Dashboard({ stats, notifications, stats_stream, notifications_stream }) {
+  useInertiaCable(stats_stream, { only: ['stats'] })
+  useInertiaCable(notifications_stream, { only: ['notifications'] })
+
+  return (
+    <>
+      <StatsPanel stats={stats} />
+      <NotificationList notifications={notifications} />
+    </>
+  )
+}
+```
+
+### `InertiaCableProvider`
+
+Optional context provider for a custom ActionCable URL. Without it, the hook connects to the default `/cable` endpoint.
+
+```tsx
+import { InertiaCableProvider } from '@inertia-cable/react'
+
+createInertiaApp({
+  setup({ el, App, props }) {
+    createRoot(el).render(
+      <InertiaCableProvider url="wss://cable.example.com/cable">
+        <App {...props} />
+      </InertiaCableProvider>
+    )
+  },
+})
+```
+
+`getConsumer()` and `setConsumer()` are also exported for low-level access to the ActionCable consumer singleton.
+
+TypeScript types (`RefreshPayload`, `UseInertiaCableOptions`, `UseInertiaCableReturn`, `InertiaCableProviderProps`) are exported from `@inertia-cable/react`.
+
+---
+
+## Suppressing Broadcasts
+
+Thread-safe and nestable:
+
+```ruby
+# Global — suppress all models
+InertiaCable.suppressing_broadcasts do
+  1000.times { Post.create!(title: "Imported") }
+end
+
+# Class-level
+Post.suppressing_broadcasts do
+  Post.create!(title: "Silent")
+end
+```
+
+---
+
+## Server-Side Debounce
+
+Optionally coalesce rapid broadcasts using Rails cache. **Not used by default** — the client-side 100ms debounce handles most cases.
+
+Requires a shared cache store (Redis, Memcached, or SolidCache) in multi-process deployments.
+
+```ruby
+InertiaCable.debounce_delay = 0.5  # seconds (default)
+
+InertiaCable::Debounce.broadcast("my_stream", payload)
+InertiaCable::Debounce.broadcast("my_stream", payload, delay: 2.0)
+```
+
+---
+
+## Testing
+
+InertiaCable ships a `TestHelper` module:
+
+```ruby
+class MessageTest < ActiveSupport::TestCase
+  include InertiaCable::TestHelper
+
+  test "broadcasting on create" do
+    chat = chats(:general)
+
+    assert_broadcasts_on(chat) do
+      Message.create!(chat: chat, body: "hello")
+    end
+  end
+
+  test "no broadcasts when suppressed" do
+    chat = chats(:general)
+
+    assert_no_broadcasts_on(chat) do
+      Message.suppressing_broadcasts do
+        Message.create!(chat: chat, body: "silent")
+      end
+    end
+  end
+
+  test "inspect broadcast payloads" do
+    chat = chats(:general)
+
+    payloads = capture_broadcasts_on(chat) do
+      Message.create!(chat: chat, body: "hello")
+    end
+
+    assert_equal "create", payloads.first[:action]
+  end
+end
+```
+
+| Method | Description |
+|--------|-------------|
+| `assert_broadcasts_on(*streamables, count: nil) { }` | Assert broadcasts occurred |
+| `assert_no_broadcasts_on(*streamables) { }` | Assert no broadcasts occurred |
+| `capture_broadcasts_on(*streamables) { }` | Capture and return payload array |
+
+All three accept splat streamables: `assert_broadcasts_on(chat, :messages) { ... }`
+
+---
+
+## Configuration
+
+```ruby
+# config/initializers/inertia_cable.rb
+InertiaCable.signed_stream_verifier_key = "custom_key"  # default: secret_key_base + "inertia_cable"
+InertiaCable.debounce_delay = 0.5                        # server-side debounce (seconds)
+```
+
+---
+
+## Security
+
+Stream tokens are HMAC-SHA256 signed using `secret_key_base` and verified server-side on subscription. Invalid tokens are rejected. No data travels over the WebSocket — actual data is fetched via Inertia's normal HTTP cycle, which runs through your controller and its authorization logic on every reload. Token rotation follows `secret_key_base` rotation.
+
+---
+
+## Troubleshooting
+
+### Stream token mismatch
+
+The stream signed in the controller must match what the model broadcasts to:
+
+```ruby
+# Model
+broadcasts_to :board  # broadcasts to gid://app/Board/1
+
+# Controller — must sign the same object
+inertia_cable_stream(@post.board)  # ✓ signs gid://app/Board/1
+inertia_cable_stream(@post)        # ✗ signs gid://app/Post/1
+```
+
+### `only`/`except` crashes
+
+Always pass arrays, never `undefined`:
+
+```tsx
+// Bad
+useInertiaCable(stream, { only: someCondition ? ['messages'] : undefined })
+
+// Good
+useInertiaCable(stream, { ...(someCondition ? { only: ['messages'] } : {}) })
+```
+
+### Server-side debounce not working across processes
+
+`Rails.cache` defaults to `MemoryStore` (per-process). Use a shared store in production:
+
+```ruby
+config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }
+```
+
+---
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.0 (ActionCable, ActiveJob, ActiveSupport)
+- Inertia.js >= 1.0 with React (`@inertiajs/react`)
+- ActionCable configured with Redis or SolidCable (production) or async (development)
+
+## Development
+
+```bash
+bundle install && bundle exec rspec     # Ruby specs
+cd frontend && npm install && npm test  # Frontend
+```
+
+## License
+
+MIT

data/app/channels/inertia_cable/stream_channel.rb

@@ -0,0 +1,12 @@
+module InertiaCable
+  class StreamChannel < ActionCable::Channel::Base
+    def subscribed
+      verified_stream = InertiaCable.signed_stream_verifier.verified(params[:signed_stream_name])
+      if verified_stream
+        stream_from Array(verified_stream).join(":")
+      else
+        reject
+      end
+    end
+  end
+end

data/lib/generators/inertia_cable/install/install_generator.rb

@@ -0,0 +1,40 @@
+module InertiaCable
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install InertiaCable into your Rails application"
+
+      def copy_cable_setup
+        template "cable_setup.ts", "app/javascript/channels/inertia_cable.ts"
+      end
+
+      def show_instructions
+        say ""
+        say "InertiaCable installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Add the npm package to your frontend:"
+        say "     npm install @inertia-cable/react @rails/actioncable"
+        say ""
+        say "  2. Ensure ActionCable is configured in config/cable.yml"
+        say "     (use redis adapter for production)"
+        say ""
+        say "  3. Add broadcasts_refreshes_to to your models:"
+        say "     class Message < ApplicationRecord"
+        say "       belongs_to :chat"
+        say "       broadcasts_refreshes_to :chat"
+        say "     end"
+        say ""
+        say "  4. Pass cable_stream prop from your controller:"
+        say "     render inertia: 'Chats/Show', props: {"
+        say "       cable_stream: inertia_cable_stream(chat)"
+        say "     }"
+        say ""
+        say "  5. Use the hook in your React component:"
+        say "     useInertiaCable(cable_stream, { only: ['messages'] })"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/inertia_cable/install/templates/cable_setup.ts

@@ -0,0 +1,7 @@
+// InertiaCable - ActionCable setup for Inertia.js
+//
+// This file is auto-generated by `rails g inertia_cable:install`.
+// You can customize the cable URL below if needed.
+
+export { useInertiaCable } from '@inertia-cable/react'
+export { InertiaCableProvider } from '@inertia-cable/react'

data/lib/inertia_cable/broadcast_job.rb

@@ -0,0 +1,10 @@
+module InertiaCable
+  class BroadcastJob < ActiveJob::Base
+    queue_as :default
+    discard_on ActiveJob::DeserializationError
+
+    def perform(stream_name, payload)
+      InertiaCable.broadcast(stream_name, payload)
+    end
+  end
+end

data/lib/inertia_cable/broadcastable.rb

@@ -0,0 +1,172 @@
+module InertiaCable
+  module Broadcastable
+    extend ActiveSupport::Concern
+
+    included do
+      thread_mattr_accessor :suppressed_inertia_cable_broadcasts, instance_accessor: false, default: false
+    end
+
+    class_methods do
+      def suppressed_inertia_cable_broadcasts?
+        suppressed_inertia_cable_broadcasts
+      end
+
+      # Broadcast refresh signal to a named stream on commit.
+      #
+      #   broadcasts_to :board
+      #   broadcasts_to :board, on: [:create, :destroy]
+      #   broadcasts_to :board, if: :published?
+      #   broadcasts_to :board, unless: -> { draft? }
+      #   broadcasts_to ->(post) { [post.board, :posts] }
+      #   broadcasts_to :board, extra: { priority: "high" }
+      #   broadcasts_to :board, extra: ->(post) { { category: post.category } }
+      #   broadcasts_to :board, debounce: true
+      #   broadcasts_to :board, debounce: 1.0
+      #
+      def broadcasts_to(stream, on: %i[create update destroy], if: nil, unless: nil, extra: nil, debounce: nil)
+        callback_condition = binding.local_variable_get(:if)
+        callback_unless    = binding.local_variable_get(:unless)
+        events = Array(on)
+
+        callback_options = {}
+        callback_options[:if]     = callback_condition if callback_condition
+        callback_options[:unless] = callback_unless    if callback_unless
+
+        if events.sort == %i[create destroy update].sort
+          after_commit(**callback_options) do
+            broadcast_refresh_later_to(resolve_stream(stream), extra: resolve_extra(extra), debounce: debounce)
+          end
+        else
+          if events.include?(:create)
+            after_create_commit(**callback_options) do
+              broadcast_refresh_later_to(resolve_stream(stream), extra: resolve_extra(extra), debounce: debounce)
+            end
+          end
+
+          if events.include?(:update)
+            after_update_commit(**callback_options) do
+              broadcast_refresh_later_to(resolve_stream(stream), extra: resolve_extra(extra), debounce: debounce)
+            end
+          end
+
+          if events.include?(:destroy)
+            after_destroy_commit(**callback_options) do
+              broadcast_refresh_later_to(resolve_stream(stream), extra: resolve_extra(extra), debounce: debounce)
+            end
+          end
+        end
+      end
+
+      # Legacy alias — kept for compatibility with Turbo-style naming.
+      alias_method :broadcasts_refreshes_to, :broadcasts_to
+
+      # Convention-based: broadcasts to model_name.plural stream.
+      #
+      #   broadcasts
+      #   broadcasts on: [:create, :destroy]
+      #
+      def broadcasts(**options)
+        broadcasts_to(model_name.plural, **options)
+      end
+
+      # Legacy alias — kept for compatibility with Turbo-style naming.
+      alias_method :broadcasts_refreshes, :broadcasts
+
+      def suppressing_broadcasts(&block)
+        original = suppressed_inertia_cable_broadcasts
+        self.suppressed_inertia_cable_broadcasts = true
+        yield
+      ensure
+        self.suppressed_inertia_cable_broadcasts = original
+      end
+    end
+
+    # Broadcast refresh synchronously to explicit stream(s).
+    #
+    #   post.broadcast_refresh_to(board)
+    #   post.broadcast_refresh_to(board, :posts)
+    #   post.broadcast_refresh_to(board, extra: { priority: "high" })
+    #   post.broadcast_refresh_to(board) { published? }
+    #
+    def broadcast_refresh_to(*streamables, extra: nil, &block)
+      return if self.class.suppressed_inertia_cable_broadcasts?
+      return if block && !instance_exec(&block)
+
+      InertiaCable.broadcast(streamables, refresh_payload(extra: extra))
+    end
+
+    # Broadcast refresh asynchronously to explicit stream(s).
+    #
+    #   post.broadcast_refresh_later_to(board)
+    #   post.broadcast_refresh_later_to(board, :posts)
+    #   post.broadcast_refresh_later_to(board, extra: { priority: "high" })
+    #   post.broadcast_refresh_later_to(board, debounce: true)
+    #   post.broadcast_refresh_later_to(board) { published? }
+    #
+    def broadcast_refresh_later_to(*streamables, extra: nil, debounce: nil, &block)
+      return if self.class.suppressed_inertia_cable_broadcasts?
+      return if block && !instance_exec(&block)
+
+      resolved = InertiaCable::Streams::StreamName.stream_name_from(streamables)
+      payload = refresh_payload(extra: extra)
+
+      if debounce
+        delay = debounce == true ? nil : debounce
+        InertiaCable::Debounce.broadcast(resolved, payload, delay: delay)
+      else
+        InertiaCable::BroadcastJob.perform_later(resolved, payload)
+      end
+    end
+
+    # Broadcast refresh synchronously to model_name.plural.
+    def broadcast_refresh(&block)
+      broadcast_refresh_to(self.class.model_name.plural, &block)
+    end
+
+    # Broadcast refresh asynchronously to model_name.plural.
+    def broadcast_refresh_later(&block)
+      broadcast_refresh_later_to(self.class.model_name.plural, &block)
+    end
+
+    private
+
+    def resolve_stream(stream)
+      case stream
+      when Symbol then send(stream)
+      when Proc   then stream.call(self)
+      when String then stream
+      else stream
+      end
+    end
+
+    def resolve_extra(extra)
+      case extra
+      when Proc then extra.call(self)
+      when Hash then extra
+      else nil
+      end
+    end
+
+    def inferred_action
+      if destroyed?
+        "destroy"
+      elsif previously_new_record?
+        "create"
+      else
+        "update"
+      end
+    end
+
+    def refresh_payload(extra: nil)
+      payload = {
+        type: "refresh",
+        model: self.class.name,
+        id: try(:id),
+        action: inferred_action,
+        timestamp: Time.current.iso8601
+      }
+      payload[:extra] = extra if extra.present?
+      payload
+    end
+  end
+end

data/lib/inertia_cable/channel.rb

@@ -0,0 +1,2 @@
+require "action_cable"
+require_relative "../../app/channels/inertia_cable/stream_channel"

data/lib/inertia_cable/controller_helpers.rb

@@ -0,0 +1,12 @@
+module InertiaCable
+  module ControllerHelpers
+    # Returns a signed stream name to pass as an Inertia prop.
+    #
+    #   inertia_cable_stream(chat)
+    #   inertia_cable_stream(chat, :messages)
+    #
+    def inertia_cable_stream(*streamables)
+      InertiaCable::Streams::StreamName.signed_stream_name(*streamables)
+    end
+  end
+end

data/lib/inertia_cable/debounce.rb

@@ -0,0 +1,12 @@
+module InertiaCable
+  module Debounce
+    def self.broadcast(stream_name, payload, delay: nil)
+      delay = delay || InertiaCable.debounce_delay
+      cache_key = "inertia_cable:debounce:#{stream_name}"
+      return if Rails.cache.exist?(cache_key)
+
+      Rails.cache.write(cache_key, true, expires_in: delay)
+      ActionCable.server.broadcast(stream_name, payload)
+    end
+  end
+end

data/lib/inertia_cable/engine.rb

@@ -0,0 +1,17 @@
+module InertiaCable
+  class Engine < ::Rails::Engine
+    isolate_namespace InertiaCable
+
+    initializer "inertia_cable.broadcastable" do
+      ActiveSupport.on_load(:active_record) do
+        include InertiaCable::Broadcastable
+      end
+    end
+
+    initializer "inertia_cable.controller_helpers" do
+      ActiveSupport.on_load(:action_controller) do
+        include InertiaCable::ControllerHelpers
+      end
+    end
+  end
+end

data/lib/inertia_cable/streams/stream_name.rb

@@ -0,0 +1,27 @@
+module InertiaCable
+  module Streams
+    module StreamName
+      extend self
+
+      def signed_stream_name(*streamables)
+        InertiaCable.signed_stream_verifier.generate(stream_name_from(streamables))
+      end
+
+      def stream_name_from(streamables)
+        streamables = Array(streamables).flatten
+        streamables.compact_blank!
+        streamables.map { |s| single_stream_name(s) }.join(":")
+      end
+
+      private
+
+      def single_stream_name(streamable)
+        if streamable.respond_to?(:to_gid_param)
+          streamable.to_gid_param
+        else
+          streamable.to_param
+        end
+      end
+    end
+  end
+end

data/lib/inertia_cable/suppressor.rb

@@ -0,0 +1,23 @@
+require "active_support/core_ext/module/attribute_accessors_per_thread"
+
+module InertiaCable
+  module Suppressor
+    # Global suppression (across all models).
+    #
+    #   InertiaCable.suppressing_broadcasts { ... }
+    #
+    thread_mattr_accessor :suppressed, default: false
+
+    def self.suppressing(&block)
+      previous = suppressed
+      self.suppressed = true
+      yield
+    ensure
+      self.suppressed = previous
+    end
+
+    def self.suppressed?
+      suppressed
+    end
+  end
+end

data/lib/inertia_cable/test_helper.rb

@@ -0,0 +1,95 @@
+module InertiaCable
+  module TestHelper
+    # Assert that broadcasts were made to the given stream.
+    #
+    #   assert_broadcasts_on(chat) { Message.create!(chat: chat) }
+    #   assert_broadcasts_on(chat, count: 2) { ... }
+    #   assert_broadcasts_on("posts") { post.broadcast_refresh }
+    #
+    def assert_broadcasts_on(*streamables, count: nil, &block)
+      payloads = capture_broadcasts_on(*streamables, &block)
+      stream = InertiaCable::Streams::StreamName.stream_name_from(streamables)
+
+      if count
+        _ic_assert_equal count, payloads.size,
+          "Expected #{count} broadcast(s) on #{stream.inspect}, but got #{payloads.size}"
+      else
+        _ic_assert !payloads.empty?,
+          "Expected at least one broadcast on #{stream.inspect}, but there were none"
+      end
+
+      payloads
+    end
+
+    # Assert that no broadcasts were made to the given stream.
+    #
+    #   assert_no_broadcasts_on(chat) { Message.create!(chat: other_chat) }
+    #
+    def assert_no_broadcasts_on(*streamables, &block)
+      payloads = capture_broadcasts_on(*streamables, &block)
+      stream = InertiaCable::Streams::StreamName.stream_name_from(streamables)
+
+      _ic_assert payloads.empty?,
+        "Expected no broadcasts on #{stream.inspect}, but got #{payloads.size}"
+    end
+
+    # Capture all broadcasts to a stream within a block. Returns an array of payload hashes.
+    #
+    # Automatically performs enqueued BroadcastJobs inline so that both sync
+    # and async broadcasts are captured.
+    #
+    #   payloads = capture_broadcasts_on(chat) { Message.create!(chat: chat) }
+    #   payloads.first[:action] # => "create"
+    #
+    def capture_broadcasts_on(*streamables, &block)
+      stream = InertiaCable::Streams::StreamName.stream_name_from(streamables)
+      collected = []
+
+      callback = ->(name, payload) {
+        collected << payload if name == stream
+      }
+
+      InertiaCable.on_broadcast(&callback)
+
+      if defined?(ActiveJob::Base) && ActiveJob::Base.queue_adapter.respond_to?(:enqueued_jobs)
+        # Perform broadcast jobs inline to capture their broadcasts
+        original_adapter = ActiveJob::Base.queue_adapter
+        ActiveJob::Base.queue_adapter = :inline
+        begin
+          yield
+        ensure
+          ActiveJob::Base.queue_adapter = original_adapter
+        end
+      else
+        yield
+      end
+
+      InertiaCable.off_broadcast(&callback)
+
+      collected
+    end
+
+    private
+
+    # Framework-agnostic assertion — works in both Minitest and RSpec
+    def _ic_assert(condition, message = "Assertion failed")
+      if respond_to?(:assert)
+        assert(condition, message)
+      elsif condition
+        true
+      else
+        raise message
+      end
+    end
+
+    def _ic_assert_equal(expected, actual, message = nil)
+      if respond_to?(:assert_equal)
+        assert_equal(expected, actual, message)
+      elsif expected == actual
+        true
+      else
+        raise message || "Expected #{expected.inspect}, got #{actual.inspect}"
+      end
+    end
+  end
+end

data/lib/inertia_cable/version.rb

@@ -0,0 +1,3 @@
+module InertiaCable
+  VERSION = "0.1.0"
+end

data/lib/inertia_cable.rb

@@ -0,0 +1,57 @@
+require "active_support"
+require "active_support/core_ext/module/attribute_accessors"
+require "active_support/core_ext/module/attribute_accessors_per_thread"
+
+require "inertia_cable/version"
+
+module InertiaCable
+  mattr_accessor :signed_stream_verifier_key
+  mattr_accessor :debounce_delay, default: 0.5
+
+  def self.signed_stream_verifier
+    @signed_stream_verifier ||= ActiveSupport::MessageVerifier.new(
+      signed_stream_verifier_key || Rails.application.secret_key_base + "inertia_cable",
+      digest: "SHA256",
+      serializer: JSON
+    )
+  end
+
+  def self.reset_signed_stream_verifier!
+    @signed_stream_verifier = nil
+  end
+
+  def self.broadcast(streamables, payload)
+    return if Suppressor.suppressed?
+
+    resolved = Streams::StreamName.stream_name_from(streamables)
+    broadcast_callbacks.each { |cb| cb.call(resolved, payload) }
+    ActionCable.server.broadcast(resolved, payload)
+  end
+
+  def self.suppressing_broadcasts(&block)
+    InertiaCable::Suppressor.suppressing(&block)
+  end
+
+  # Test instrumentation — used by InertiaCable::TestHelper
+  def self.on_broadcast(&callback)
+    broadcast_callbacks << callback
+  end
+
+  def self.off_broadcast(&callback)
+    broadcast_callbacks.delete(callback)
+  end
+
+  def self.broadcast_callbacks
+    @broadcast_callbacks ||= []
+  end
+end
+
+require "inertia_cable/streams/stream_name"
+require "inertia_cable/broadcastable"
+require "inertia_cable/channel"
+require "inertia_cable/broadcast_job"
+require "inertia_cable/debounce"
+require "inertia_cable/suppressor"
+require "inertia_cable/controller_helpers"
+require "inertia_cable/test_helper"
+require "inertia_cable/engine" if defined?(Rails::Engine)

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: inertia_cable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cole Robertson
+bindir: bin
+cert_chain: []
+date: 2026-02-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actioncable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Lightweight ActionCable integration for Inertia.js Rails apps. Broadcasts
+  refresh signals over WebSockets, triggering Inertia router.reload() on the client.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/channels/inertia_cable/stream_channel.rb
+- lib/generators/inertia_cable/install/install_generator.rb
+- lib/generators/inertia_cable/install/templates/cable_setup.ts
+- lib/inertia_cable.rb
+- lib/inertia_cable/broadcast_job.rb
+- lib/inertia_cable/broadcastable.rb
+- lib/inertia_cable/channel.rb
+- lib/inertia_cable/controller_helpers.rb
+- lib/inertia_cable/debounce.rb
+- lib/inertia_cable/engine.rb
+- lib/inertia_cable/streams/stream_name.rb
+- lib/inertia_cable/suppressor.rb
+- lib/inertia_cable/test_helper.rb
+- lib/inertia_cable/version.rb
+homepage: https://github.com/cole-robertson/inertia-cable
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: ActionCable broadcast DSL for Inertia Rails
+test_files: []