hotsock-turbo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: acb980991920b0cf9f918c2eb1415f7236cd68a1b7d32ef32fb23e61ef123ec1
+  data.tar.gz: 501175af602730032c80b888b419050d3dd9f95258e9c6d3b96c850c91b583e9
+SHA512:
+  metadata.gz: d4f52b687ea9e85db973edad805dac02761ec3f0c1ec602c36473c13a7c38dafd51f6b864004cad85f9db5dd6230d11d0236bf3445e97f6b5ba7b20a74405017
+  data.tar.gz: 509e133c9a296026acaf7ed40ed161075c688c08da13a9a6379208dbe5317c18cb9932fcf4a561d6feff8285e5f2958f15a55c6f0895dda5f2895236890b3dca

data/.standard.yml

@@ -0,0 +1 @@
+ruby_version: 3.2

data/Gemfile

@@ -0,0 +1,16 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rails", "~> 8.1"
+gem "turbo-rails", "~> 2.0"
+
+group :development, :test do
+  gem "rake"
+  gem "standard", require: false
+end
+
+group :test do
+  gem "maxitest"
+  gem "ostruct"
+end

data/README.md

@@ -0,0 +1,323 @@
+# Hotsock Turbo
+
+Turbo Streams integration for [Hotsock](https://www.hotsock.io), enabling real-time updates in Rails applications using Hotsock's WebSocket infrastructure.
+
+## Overview
+
+Hotsock Turbo provides a seamless way to broadcast Turbo Stream updates to your Rails application using Hotsock instead of Action Cable. It offers:
+
+- Real-time page updates via WebSockets
+- Model callbacks for automatic broadcasting on create, update, and destroy
+- Support for Turbo Stream refresh (morphing) broadcasts
+- Drop-in replacement mode for existing `Turbo::Broadcastable` usage
+- Both synchronous and asynchronous (ActiveJob) broadcasting
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails with [Turbo](https://github.com/hotwired/turbo-rails)
+- [Hotsock](https://rubygems.org/gems/hotsock) gem (>= 1.0)
+- [@hotsock/hotsock-js](https://www.npmjs.com/package/@hotsock/hotsock-js) npm package
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "turbo-rails"
+gem "hotsock-turbo"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### JavaScript Setup
+
+#### Using Importmap
+
+```bash
+bin/importmap pin @hotsock/hotsock-js
+```
+
+Then in your `application.js`:
+
+```javascript
+import "@hotsock/hotsock-js"
+import "hotsock-turbo"
+```
+
+#### Using npm/yarn
+
+```bash
+npm install @hotsock/hotsock-js
+# or
+yarn add @hotsock/hotsock-js
+```
+
+Then in your JavaScript entry point:
+
+```javascript
+import "@hotsock/hotsock-js"
+import "hotsock-turbo"
+```
+
+## Configuration
+
+Create an initializer at `config/initializers/hotsock_turbo.rb`:
+
+```ruby
+Hotsock::Turbo.configure do |config|
+  # Required: Path to an endpoint that returns Hotsock connection tokens
+  config.connect_token_path = "/hotsock/connect_token"
+
+  # Required: Your Hotsock WebSocket URL
+  config.wss_url = "wss://your-hotsock-instance.example.com"
+
+  # Optional: Log level for the JavaScript client (default: "warn")
+  config.log_level = "warn"
+
+  # Optional: Parent controller for any generated routes (default: "ApplicationController")
+  config.parent_controller = "ApplicationController"
+
+  # Optional: Enable drop-in replacement for Turbo::Broadcastable (default: false)
+  config.override_turbo_broadcastable = false
+end
+```
+
+### Configuration Options
+
+| Option                         | Default                   | Description                                                            |
+| ------------------------------ | ------------------------- | ---------------------------------------------------------------------- |
+| `connect_token_path`           | `nil`                     | Path to your endpoint that issues Hotsock connection tokens            |
+| `wss_url`                      | `nil`                     | Your Hotsock WebSocket server URL                                      |
+| `log_level`                    | `"warn"`                  | JavaScript client log level (`"debug"`, `"info"`, `"warn"`, `"error"`) |
+| `parent_controller`            | `"ApplicationController"` | Base controller for generated routes                                   |
+| `override_turbo_broadcastable` | `false`                   | When `true`, overrides standard Turbo broadcast methods to use Hotsock |
+
+## Usage
+
+### View Helpers
+
+#### Meta Tags
+
+Add the required meta tags to your layout (typically in `<head>`):
+
+```erb
+<%= hotsock_turbo_meta_tags %>
+```
+
+This renders the configuration needed by the JavaScript client:
+
+```html
+<meta name="hotsock:connect-token-path" content="/hotsock/connect_token" />
+<meta name="hotsock:log-level" content="warn" />
+<meta
+  name="hotsock:wss-url"
+  content="wss://your-hotsock-instance.example.com"
+/>
+```
+
+You can override configuration per-page:
+
+```erb
+<%= hotsock_turbo_meta_tags wss_url: "wss://other.example.com", log_level: "debug" %>
+```
+
+#### Stream Subscriptions
+
+Subscribe to streams in your views:
+
+```erb
+<%= hotsock_turbo_stream_from @board %>
+<%= hotsock_turbo_stream_from @board, :messages %>
+<%= hotsock_turbo_stream_from "custom_stream_name" %>
+```
+
+This renders a custom element that manages the WebSocket subscription:
+
+```html
+<hotsock-turbo-stream-source
+  data-channel="..."
+  data-token="..."
+  data-user-id="..."
+>
+</hotsock-turbo-stream-source>
+```
+
+### Model Broadcasting
+
+Hotsock Turbo automatically includes broadcasting methods in all ActiveRecord models.
+
+#### Broadcasting Refreshes
+
+For models that should trigger page refreshes (works great with Turbo's morphing):
+
+```ruby
+class Board < ApplicationRecord
+  # Broadcasts refresh to "boards" stream on create/update/destroy
+  hotsock_broadcasts_refreshes
+end
+
+class Column < ApplicationRecord
+  belongs_to :board
+
+  # Broadcasts refresh to the board's stream on create/update/destroy
+  hotsock_broadcasts_refreshes_to :board
+end
+```
+
+#### Broadcasting DOM Updates
+
+For fine-grained DOM updates (append, replace, remove):
+
+```ruby
+class Message < ApplicationRecord
+  belongs_to :board
+
+  # Broadcasts append on create, replace on update, remove on destroy
+  hotsock_broadcasts_to :board
+end
+
+class Comment < ApplicationRecord
+  # Broadcasts to "comments" stream by default
+  hotsock_broadcasts
+end
+```
+
+#### Options
+
+```ruby
+class Message < ApplicationRecord
+  belongs_to :board
+
+  # Customize the insert action and target
+  hotsock_broadcasts_to :board,
+    inserts_by: :prepend,          # :append (default), :prepend
+    target: "board_messages",       # DOM ID to target
+    partial: "messages/card"        # Custom partial
+end
+```
+
+### Instance Methods
+
+Broadcast from anywhere in your application:
+
+```ruby
+message = Message.find(1)
+
+# Sync broadcasts (immediate)
+message.hotsock_broadcast_refresh
+message.hotsock_broadcast_refresh_to(board)
+message.hotsock_broadcast_replace
+message.hotsock_broadcast_replace_to(board)
+message.hotsock_broadcast_append_to(board, target: "messages")
+message.hotsock_broadcast_prepend_to(board, target: "messages")
+message.hotsock_broadcast_remove
+message.hotsock_broadcast_remove_to(board)
+
+# Async broadcasts (via ActiveJob)
+message.hotsock_broadcast_refresh_later
+message.hotsock_broadcast_refresh_later_to(board)
+message.hotsock_broadcast_replace_later
+message.hotsock_broadcast_replace_later_to(board)
+message.hotsock_broadcast_append_later_to(board, target: "messages")
+message.hotsock_broadcast_prepend_later_to(board, target: "messages")
+```
+
+### Direct Channel Broadcasting
+
+Broadcast without a model instance:
+
+```ruby
+Hotsock::Turbo::StreamsChannel.broadcast_refresh_to(board)
+Hotsock::Turbo::StreamsChannel.broadcast_append_to(
+  board,
+  target: "messages",
+  partial: "messages/message",
+  locals: { message: message }
+)
+Hotsock::Turbo::StreamsChannel.broadcast_remove_to(board, target: "message_123")
+```
+
+### Drop-in Turbo Replacement
+
+If you have existing code using `Turbo::Broadcastable` methods, you can enable drop-in replacement mode:
+
+```ruby
+# config/initializers/hotsock_turbo.rb
+Hotsock::Turbo.configure do |config|
+  config.override_turbo_broadcastable = true
+end
+```
+
+Now standard Turbo method names work with Hotsock:
+
+```ruby
+class Message < ApplicationRecord
+  belongs_to :board
+
+  # These now use Hotsock instead of Action Cable
+  broadcasts_refreshes_to :board
+  broadcasts_to :board
+  broadcasts
+  broadcasts_refreshes
+end
+
+# Instance methods also work
+message.broadcast_refresh
+message.broadcast_replace_later_to(board)
+```
+
+### Suppressing Broadcasts
+
+Temporarily disable broadcasts within a block:
+
+```ruby
+Message.suppressing_turbo_broadcasts do
+  # No broadcasts will be sent
+  Message.create!(content: "Silent message", board: board)
+  message.update!(content: "Silent update")
+end
+```
+
+Check suppression status:
+
+```ruby
+Message.suppressed_turbo_broadcasts?  # => false
+
+Message.suppressing_turbo_broadcasts do
+  Message.suppressed_turbo_broadcasts?  # => true
+end
+```
+
+## Customization
+
+### Custom User Identification
+
+By default, subscriptions use `session.id` as the user identifier. Override this by defining `hotsock_uid` in your helper or controller:
+
+```ruby
+# app/helpers/application_helper.rb
+module ApplicationHelper
+  private
+
+  def hotsock_uid
+    current_user&.id&.to_s || session.id.to_s
+  end
+end
+```
+
+## How It Works
+
+1. **Meta tags** provide configuration to the JavaScript client
+2. **`<hotsock-turbo-stream-source>`** elements connect to Hotsock via WebSocket
+3. **Model callbacks** or direct calls trigger broadcasts via `Hotsock::Turbo::StreamsChannel`
+4. **Hotsock** delivers messages to subscribed clients
+5. **JavaScript client** receives messages and calls `Turbo.renderStreamMessage()` to update the DOM
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new(:test) do |test|
+  test.warning = true
+  test.pattern = "test/**/*.rb"
+end
+
+task default: ["standard:fix", :test]

data/app/assets/javascripts/hotsock-turbo.js

@@ -0,0 +1,142 @@
+import { HotsockClient } from "@hotsock/hotsock-js"
+
+function createHotsockClient() {
+  return new HotsockClient(
+    document
+      .querySelector('meta[name="hotsock:wss-url"]')
+      ?.getAttribute("content"),
+    {
+      connectTokenFn: async () => {
+        const connectTokenPath = document.querySelector(
+          'meta[name="hotsock:connect-token-path"]'
+        ).content
+        const csrfToken = document.querySelector(
+          'meta[name="csrf-token"]'
+        ).content
+        const response = await fetch(connectTokenPath, {
+          method: "POST",
+          headers: {
+            "x-csrf-token": csrfToken,
+          },
+        })
+        const data = await response.json()
+        return data.token
+      },
+      lazyConnection: true,
+      logLevel: document.querySelector('meta[name="hotsock:log-level"]')
+        ?.content,
+    }
+  )
+}
+
+const hotsockClient = window.Hotsock || createHotsockClient()
+window.Hotsock = hotsockClient
+
+// Track active subscriptions by channel
+const subscriptions = new Map() // channel -> { binding, elements: Set, unsubscribeTimer }
+const UNSUBSCRIBE_DELAY_MS = 250
+
+class HotsockTurboStreamSourceElement extends HTMLElement {
+  #channel = null
+
+  connectedCallback() {
+    this.#subscribe()
+  }
+
+  disconnectedCallback() {
+    this.#unsubscribe()
+  }
+
+  #subscribe() {
+    const { channel, token } = this.dataset
+
+    if (!channel || !token) {
+      return
+    }
+
+    this.#channel = channel
+
+    if (typeof window === "undefined" || !window.Turbo) {
+      console.warn("hotsock-turbo-stream-source: Turbo is not available")
+      return
+    }
+
+    let sub = subscriptions.get(channel)
+
+    if (sub) {
+      // Cancel unsubscribe if pending
+      if (sub.unsubscribeTimer) {
+        clearTimeout(sub.unsubscribeTimer)
+        sub.unsubscribeTimer = null
+      }
+      // Add this element to the subscription's element set
+      sub.elements.add(this)
+    } else {
+      const { Turbo } = window
+      const binding = hotsockClient.bind(
+        "turbo_stream",
+        ({ data }) => {
+          if (!data?.html) return
+          try {
+            Turbo.renderStreamMessage(data.html)
+          } catch (error) {
+            console.error("Failed to render Turbo Stream message:", error)
+          }
+        },
+        { channel, subscribeTokenFn: () => token }
+      )
+
+      sub = { binding, elements: new Set([this]), unsubscribeTimer: null }
+      subscriptions.set(channel, sub)
+    }
+
+    this.subscriptionConnected()
+  }
+
+  #unsubscribe() {
+    const channel = this.#channel
+    if (!channel) {
+      return
+    }
+
+    const sub = subscriptions.get(channel)
+    if (!sub) {
+      this.subscriptionDisconnected()
+      return
+    }
+
+    // Remove this element from the subscription
+    sub.elements.delete(this)
+
+    // If no elements remain, schedule delayed unsubscribe
+    if (sub.elements.size === 0 && !sub.unsubscribeTimer) {
+      sub.unsubscribeTimer = setTimeout(() => {
+        // Double-check no elements have reconnected
+        if (sub.elements.size === 0) {
+          sub.binding.unbind()
+          subscriptions.delete(channel)
+        }
+      }, UNSUBSCRIBE_DELAY_MS)
+    }
+
+    this.subscriptionDisconnected()
+    this.#channel = null
+  }
+
+  subscriptionConnected() {
+    this.setAttribute("connected", "")
+  }
+
+  subscriptionDisconnected() {
+    this.removeAttribute("connected")
+  }
+}
+
+if (customElements.get("hotsock-turbo-stream-source") === undefined) {
+  customElements.define(
+    "hotsock-turbo-stream-source",
+    HotsockTurboStreamSourceElement
+  )
+}
+
+export { hotsockClient }

data/app/controllers/hotsock/turbo/tokens_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hotsock
+  module Turbo
+    class TokensController < Hotsock::Turbo.config.parent_controller.constantize
+      def connect
+        render json: {token: connect_token}
+      end
+
+      private
+
+      def connect_token
+        uid = respond_to?(:hotsock_uid, true) ? hotsock_uid : session.id.to_s
+        umd = respond_to?(:hotsock_umd, true) ? hotsock_umd : nil
+
+        claims = {scope: "connect", keepAlive: true, uid:, umd:}
+        Hotsock.issue_token(claims)
+      end
+    end
+  end
+end

data/app/jobs/hotsock/turbo/action_broadcast_job.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Hotsock
+  module Turbo
+    # The job that powers all the broadcast_$action_later broadcasts.
+    class ActionBroadcastJob < ActiveJob::Base
+      discard_on ActiveJob::DeserializationError
+
+      def perform(stream, action:, target:, targets: nil, attributes: {}, **rendering)
+        Hotsock::Turbo::StreamsChannel.broadcast_action_to(
+          stream,
+          action:,
+          target:,
+          targets:,
+          attributes:,
+          **rendering
+        )
+      end
+    end
+  end
+end

data/app/jobs/hotsock/turbo/broadcast_job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Hotsock
+  module Turbo
+    # The job that powers broadcast_render_later_to for rendering turbo stream templates.
+    class BroadcastJob < ActiveJob::Base
+      discard_on ActiveJob::DeserializationError
+
+      def perform(stream, **rendering)
+        Hotsock::Turbo::StreamsChannel.broadcast_render_to(stream, **rendering)
+      end
+    end
+  end
+end

data/app/jobs/hotsock/turbo/broadcast_refresh_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Hotsock
+  module Turbo
+    class BroadcastRefreshJob < ActiveJob::Base
+      discard_on ActiveJob::DeserializationError
+
+      def perform(stream, request_id: nil)
+        Hotsock::Turbo::StreamsChannel.broadcast_refresh_to(stream, request_id:)
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Hotsock::Turbo::Engine.routes.draw do
+  post "connect", to: "tokens#connect"
+end

data/hotsock-turbo.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(::File.join(::File.dirname(__FILE__), "lib"))
+
+require "hotsock/turbo/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "hotsock-turbo"
+  spec.version = Hotsock::Turbo::VERSION
+  spec.authors = ["James Miller"]
+  spec.email = ["support@hotsock.io"]
+  spec.homepage = "https://www.hotsock.io"
+  spec.summary = "Turbo Streams integration for Hotsock"
+  spec.description = "Provides Turbo Streams integration for Hotsock, enabling real-time updates in Rails applications using Hotsock's WebSocket infrastructure."
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata = {
+    "homepage_uri" => "https://www.hotsock.io",
+    "bug_tracker_uri" => "https://github.com/hotsock/hotsock-turbo/issues",
+    "documentation_uri" => "https://github.com/hotsock/hotsock-turbo/blob/main/README.md",
+    "changelog_uri" => "https://github.com/hotsock/hotsock-turbo/releases",
+    "source_code_uri" => "https://github.com/hotsock/hotsock-turbo"
+  }
+
+  ignored = Regexp.union(
+    /\A\.git/,
+    /\Atest/
+  )
+  spec.files = `git ls-files`.split("\n").reject { |f| ignored.match(f) }
+
+  spec.add_dependency "hotsock", "~> 1.0"
+end