chrono_cable 0.0.1

data/app/javascript/turbo/snakeize.js

@@ -0,0 +1,31 @@
+// Based on https://github.com/nathan7/snakeize
+//
+// This software is released under the MIT license:
+// 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.
+export default function walk (obj) {
+    if (!obj || typeof obj !== 'object') return obj;
+    if (obj instanceof Date || obj instanceof RegExp) return obj;
+    if (Array.isArray(obj)) return obj.map(walk);
+    return Object.keys(obj).reduce(function (acc, key) {
+        var camel = key[0].toLowerCase() + key.slice(1).replace(/([A-Z]+)/g, function (m, x) {
+            return '_' + x.toLowerCase();
+        });
+        acc[camel] = walk(obj[key]);
+        return acc;
+    }, {});
+};

data/app/models/chrono_cable/application_record.rb

@@ -0,0 +1,5 @@
+module ChronoCable
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/solid_cable/channel.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "solid_cable"
+
+module SolidCable
+  class Channel < ::SolidCable::Record
+    def self.lookup(channel)
+      channel_hash = ::SolidCable::Message.channel_hash_for(channel)
+      find_by(channel_hash:) || create_or_find_by!(channel_hash:)
+    end
+  end
+end

data/db/migrate/20260628205427_create_solid_cable_channels.rb

@@ -0,0 +1,12 @@
+class CreateSolidCableChannels < ActiveRecord::Migration[8.1]
+  def change
+    create_table :solid_cable_channels do |t|
+      t.integer :channel_hash, limit: 8, null: false
+      t.bigint :current_id, default: 0, null: false
+      t.index :channel_hash, unique: true
+      t.boolean :deliver_in_order, default: false, null: false
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260629194211_add_channel_id_to_solid_cable_messages.rb

@@ -0,0 +1,7 @@
+class AddChannelIdToSolidCableMessages < ActiveRecord::Migration[8.1]
+  def change
+    add_column :solid_cable_messages, :channel_id, :bigint, if_not_exists: true
+    add_index :solid_cable_messages, [ :channel_hash, :channel_id ], unique: true,
+      if_not_exists: true
+  end
+end

data/lib/action_cable/subscription_adapter/message.rb

@@ -0,0 +1,12 @@
+module ActionCable
+  module SubscriptionAdapter
+    class Message
+      def initialize(id:, payload:)
+        @id = id
+        @payload = payload
+      end
+
+      attr_reader :id, :payload
+    end
+  end
+end

data/lib/chrono_cable/channel_base.rb

@@ -0,0 +1,30 @@
+module ChronoCable::ChannelBase
+  private
+    def transmit(data, via: nil, id: nil, broadcasting: nil) # :doc:
+      logger.debug do
+        status = "#{self.class.name} transmitting #{data.inspect.truncate(300)}"
+        status += " (via #{via})" if via
+        status
+      end
+
+      payload = { channel_class: self.class.name, data: data, via: via }
+      ActiveSupport::Notifications.instrument("transmit.action_cable", payload) do
+        broadcasting = ChronoCable.signed_stream_verifier.generate(broadcasting) if broadcasting
+        connection.transmit **{ identifier: @identifier, message: data, broadcasting:, id: }.compact
+      end
+    end
+
+    def transmit_subscription_confirmation
+      unless subscription_confirmation_sent?
+        logger.debug "#{self.class.name} is transmitting the subscription confirmation"
+
+        ActiveSupport::Notifications.instrument("transmit_subscription_confirmation.action_cable", channel_class: self.class.name, identifier: @identifier) do
+          connection.transmit **{ identifier: @identifier,
+            type: ActionCable::INTERNAL[:message_types][:confirmation],
+            ids: @subscription_confirmation_ids
+          }.compact
+          @subscription_confirmation_sent = true
+        end
+      end
+    end
+end

data/lib/chrono_cable/channel_streams.rb

@@ -0,0 +1,121 @@
+module ChronoCable::ChannelStreams
+  def stream_from(broadcasting, callback = nil, coder: nil, deliver_in_order: false, &block)
+    return if unsubscribed?
+
+    broadcasting = String(broadcasting)
+    ordered = deliver_in_order && pubsub.supports_history?
+
+    ordered_streams.delete broadcasting
+    pubsub.enable_ordered_delivery(broadcasting) if ordered
+
+    # Don't send the confirmation until pubsub#subscribe is successful
+    defer_subscription_confirmation!
+
+    # Build a stream handler by wrapping the user-provided callback with a decoder
+    # or defaulting to a JSON-decoding retransmitter.
+    user_handler = callback || block
+    handler = worker_pool_stream_handler(broadcasting, user_handler, coder: coder)
+    streams[broadcasting] = handler
+
+    if ordered
+      ordered_streams[broadcasting] = user_handler && stream_handler(broadcasting, user_handler, coder:)
+    end
+
+    pubsub.subscribe(broadcasting, handler, lambda do |last_id = nil|
+      confirmation_was_sent = subscription_confirmation_sent?
+
+      record_subscription_confirmation_id broadcasting, last_id if ordered_stream?(broadcasting)
+      ensure_confirmation_sent
+      transmit_subscription_id broadcasting, last_id if confirmation_was_sent
+
+      logger.info "#{self.class.name} is streaming from #{broadcasting}"
+    end)
+  end
+
+  def stop_all_streams
+    super
+    ordered_streams.clear
+  end
+
+  def stop_stream_from(broadcasting)
+    broadcasting = String(broadcasting)
+    super
+    ordered_streams.delete broadcasting
+  end
+
+  private
+    def stream_decoder(handler = nil, coder:)
+      ->(message) do
+        payload = message.try(:payload) || message
+        payload = coder.decode(payload) if coder
+
+        handler ? handler.(payload) : payload
+      end
+    end
+
+    def stream_transmitter(handler = nil, broadcasting:)
+      via = "streamed from #{broadcasting}"
+
+      ->(message) do
+        data =
+          if handler
+            handler.(message)
+          else
+            message
+          end
+
+        params = { via: via }
+        params.merge!(id: message.try(:id), broadcasting:) if ordered_stream?(broadcasting)
+        transmit data, **params
+      end
+    end
+
+    def ordered_streams
+      @ordered_streams ||= {}
+    end
+
+    def ordered_stream?(broadcasting)
+      ordered_streams.key? broadcasting
+    end
+
+    def record_subscription_confirmation_id(broadcasting, id)
+      return if id.nil?
+
+      @subscription_confirmation_ids ||= {}
+      @subscription_confirmation_ids[ChronoCable.signed_stream_verifier.generate(broadcasting)] = id
+    end
+
+    def __history(data = nil)
+      signed_broadcasting = data.to_h["broadcasting"]
+      return unless signed_broadcasting.is_a?(String)
+
+      broadcasting = ChronoCable.signed_stream_verifier.verified(signed_broadcasting)
+      return unless ordered_stream?(broadcasting)
+
+      messages = pubsub.history(broadcasting, after_id: data["id"])
+      if handler = ordered_streams[broadcasting]
+        messages.each do |message|
+          handler.call ActionCable::SubscriptionAdapter::Message.new(
+            id: message[:id], payload: message[:payload]
+          )
+        end
+        transmit_history [], broadcasting:
+      else
+        transmit_history messages, broadcasting:
+      end
+    end
+
+    def transmit_subscription_id(broadcasting, id)
+      return unless ordered_stream?(broadcasting) && id
+
+      transmit_history [], broadcasting:, id:
+    end
+
+    def transmit_history(messages, broadcasting:, id: nil)
+      message = { messages:, id: }.compact
+      broadcasting = ChronoCable.signed_stream_verifier.generate(broadcasting)
+
+      connection.transmit identifier: @identifier, broadcasting:,
+        type: ActionCable::INTERNAL[:message_types][:history], message: message
+    end
+end

data/lib/chrono_cable/connection_subscriptions.rb

@@ -0,0 +1,16 @@
+module ChronoCable::ConnectionSubscriptions
+  def execute_command(data)
+    if data["command"] == "history"
+      fetch_history data
+    else
+      super
+    end
+  end
+
+  def fetch_history(data)
+    subscription = find(data)
+    raise ActionCable::Connection::Subscriptions::UnknownSubscription.new(data["identifier"]) unless subscription
+
+    subscription.__send__(:__history, data)
+  end
+end

data/lib/chrono_cable/engine.rb

@@ -0,0 +1,11 @@
+module ChronoCable
+  class Engine < ::Rails::Engine
+    isolate_namespace ChronoCable
+
+    initializer "chrono_cable" do
+      ActiveSupport.on_load(:action_cable) do
+        ::ChronoCable.install!
+      end
+    end
+  end
+end

data/lib/chrono_cable/solid_cable_adapter.rb

@@ -0,0 +1,26 @@
+module ChronoCable::SolidCableAdapter
+  def supports_history?
+    true
+  end
+
+  def history(channel, after_id: nil)
+    messages = ::SolidCable::Message.
+      where(channel_hash: channel_hash_for(channel)).
+      where.not(channel_id: nil)
+    messages = messages.where(channel_id: (after_id.to_i + 1)..) if after_id
+    messages.order(:channel_id).pluck(:channel_id, :payload).map do |id, payload|
+      { id:, payload: }
+    end
+  end
+
+  def enable_ordered_delivery(channel)
+    channel = ::SolidCable::Channel.lookup(channel_with_prefix(channel))
+
+    channel.update_columns(deliver_in_order: true) unless channel.deliver_in_order?
+  end
+
+  private
+    def channel_hash_for(channel)
+      ::SolidCable::Message.channel_hash_for channel_with_prefix(channel)
+    end
+end

data/lib/chrono_cable/solid_cable_adapter_listener.rb

@@ -0,0 +1,28 @@
+module ChronoCable::SolidCableAdapterListener
+  Broadcast = Data.define(:channel, :payload)
+
+  def add_subscriber(channel, subscriber, on_success)
+    if on_success
+      callback = on_success
+      on_success = -> { callback.call current_channel_id(channel) }
+    end
+
+    super
+  end
+
+  private
+    def current_channel_id(channel)
+      SolidCable::Message.
+        where(channel_hash: SolidCable::Message.channel_hash_for(channel)).
+        maximum(:channel_id).to_i
+    end
+
+    def broadcast(message)
+      payload = ::ActionCable::SubscriptionAdapter::Message.new(
+        payload: message.payload,
+        id: message.channel_id
+      )
+
+      super Broadcast.new(message.channel, payload)
+    end
+end

data/lib/chrono_cable/solid_cable_broadcasting.rb

@@ -0,0 +1,19 @@
+module ChronoCable::SolidCableBroadcasting
+  Message = Struct.new(:channel, :payload, :channel_id, keyword_init: true)
+
+  def broadcast(channel, payload)
+    message = Message.new(channel:, payload:)
+    channel_record = SolidCable::Channel.lookup(channel)
+
+    if channel_record.deliver_in_order?
+      channel_record.with_lock do
+        channel_record.increment!(:current_id)
+        message.channel_id = channel_record.current_id
+      end
+    end
+
+    queue.enq message
+  rescue ClosedQueueError
+    raise SolidCable::BatchedBroadcaster::Stopped, "Solid Cable writer has stopped"
+  end
+end

data/lib/chrono_cable/solid_cable_message_class_methods.rb

@@ -0,0 +1,9 @@
+module ChronoCable::SolidCableMessageClassMethods
+  def broadcast_batch(broadcasts)
+    created_at = Time.current
+    insert_all broadcasts.map { |message|
+      { created_at:, channel: message.channel, channel_id: message.channel_id,
+        payload: message.payload, channel_hash: channel_hash_for(message.channel) }
+    }
+  end
+end

data/lib/chrono_cable/subscription_adapter_base_extensions.rb

@@ -0,0 +1,5 @@
+module ChronoCable::SubscriptionAdapterBaseExtensions
+  def supports_history?
+    false
+  end
+end

data/lib/chrono_cable/turbo_streams_channel.rb

@@ -0,0 +1,5 @@
+module ChronoCable::TurboStreamsChannel
+  def stream_from(*args, **options, &block)
+    super(*args, deliver_in_order: params[:deliver_in_order].to_s == "true", **options, &block)
+  end
+end

data/lib/chrono_cable/version.rb

@@ -0,0 +1,3 @@
+module ChronoCable
+  VERSION = "0.0.1"
+end

data/lib/chrono_cable.rb

@@ -0,0 +1,38 @@
+require "chrono_cable/version"
+require "chrono_cable/engine"
+
+require "action_cable/subscription_adapter/message"
+
+require "chrono_cable/subscription_adapter_base_extensions"
+require "chrono_cable/connection_subscriptions"
+require "chrono_cable/channel_base"
+require "chrono_cable/channel_streams"
+require "chrono_cable/turbo_streams_channel"
+
+require "chrono_cable/solid_cable_message_class_methods"
+require "chrono_cable/solid_cable_adapter_listener"
+require "chrono_cable/solid_cable_adapter"
+require "chrono_cable/solid_cable_broadcasting"
+
+module ChronoCable
+  def self.signed_stream_verifier
+    Rails.application.message_verifier("chrono_cable/stream_name")
+  end
+
+  def self.install!
+    ::ActionCable::INTERNAL[:message_types][:history] = "history"
+
+    ::ActionCable::SubscriptionAdapter::Base.include ::ChronoCable::SubscriptionAdapterBaseExtensions
+
+    ::ActionCable::Connection::Subscriptions.prepend ChronoCable::ConnectionSubscriptions
+    ::ActionCable::Channel::Base.prepend ChronoCable::ChannelBase
+    ::ActionCable::Channel::Streams.prepend ChronoCable::ChannelStreams
+    ::Turbo::StreamsChannel.prepend ChronoCable::TurboStreamsChannel if defined?(::Turbo::StreamsChannel)
+
+    ::ActionCable::SubscriptionAdapter::SolidCable::Listener.prepend ::ChronoCable::SolidCableAdapterListener
+    ::ActionCable::SubscriptionAdapter::SolidCable.include ChronoCable::SolidCableAdapter
+
+    SolidCable::BatchedBroadcaster.prepend ::ChronoCable::SolidCableBroadcasting
+    SolidCable::Message.singleton_class.prepend ::ChronoCable::SolidCableMessageClassMethods
+  end
+end

data/lib/generators/chrono_cable/install/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Copies the Chrono Cable database migrations into the application.
+
+Example:
+    bin/rails generate chrono_cable:install
+
+    This will create:
+        db/cable_migrate/*_create_solid_cable_channels.rb
+        db/cable_migrate/*_add_channel_id_to_solid_cable_messages.rb

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

@@ -0,0 +1,32 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+class ChronoCable::InstallGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  source_root File.expand_path("templates", __dir__)
+
+  def self.next_migration_number(dirname)
+    ActiveRecord::Generators::Base.next_migration_number(dirname)
+  end
+
+  def copy_migrations
+    migration_template "create_solid_cable_channels.rb",
+      "db/cable_migrate/create_solid_cable_channels.rb"
+
+    migration_template "add_channel_id_to_solid_cable_messages.rb",
+      "db/cable_migrate/add_channel_id_to_solid_cable_messages.rb"
+  end
+
+  def update_importmap
+    return unless File.exist?(File.join(destination_root, "config/importmap.rb"))
+
+    gsub_file "config/importmap.rb",
+      /pin\s+["']@rails\/actioncable["'],\s+to:\s+["']actioncable\.esm\.js["']/,
+      'pin "@rails/actioncable", to: "chronocable.js"'
+
+    gsub_file "config/importmap.rb",
+      /pin\s+["']@hotwired\/turbo-rails["'],\s+to:\s+["']turbo\.min\.js["']/,
+      'pin "@hotwired/turbo-rails", to: "chronocable_turbo.min.js"'
+  end
+end

data/lib/generators/chrono_cable/install/templates/add_channel_id_to_solid_cable_messages.rb

@@ -0,0 +1,7 @@
+class AddChannelIdToSolidCableMessages < ActiveRecord::Migration[8.1]
+  def change
+    add_column :solid_cable_messages, :channel_id, :bigint, if_not_exists: true
+    add_index :solid_cable_messages, [ :channel_hash, :channel_id ], unique: true,
+      if_not_exists: true
+  end
+end

data/lib/generators/chrono_cable/install/templates/create_solid_cable_channels.rb

@@ -0,0 +1,12 @@
+class CreateSolidCableChannels < ActiveRecord::Migration[8.1]
+  def change
+    create_table :solid_cable_channels, if_not_exists: true do |t|
+      t.integer :channel_hash, limit: 8, null: false
+      t.bigint :current_id, default: 0, null: false
+      t.index :channel_hash, unique: true
+      t.boolean :deliver_in_order, default: false, null: false
+
+      t.timestamps
+    end
+  end
+end

data/lib/tasks/chrono_cable_tasks.rake

@@ -0,0 +1,6 @@
+desc "Copy over the migrations and set the js for Chrono Cable"
+namespace :chrono_cable do
+  task :install do
+    Rails::Command.invoke :generate, [ "chrono_cable:install" ]
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: chrono_cable
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nick Pezza
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: solid_cable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Adds per-stream sequence numbers and history replay to Action Cable broadcasts
+  stored by Solid Cable.
+email:
+- pezza@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/javascripts/chronocable.js
+- app/assets/javascripts/chronocable_turbo.js
+- app/assets/javascripts/chronocable_turbo.min.js
+- app/javascript/action_cable/adapters.js
+- app/javascript/action_cable/connection.js
+- app/javascript/action_cable/connection_monitor.js
+- app/javascript/action_cable/consumer.js
+- app/javascript/action_cable/index.js
+- app/javascript/action_cable/internal.js
+- app/javascript/action_cable/logger.js
+- app/javascript/action_cable/stream.js
+- app/javascript/action_cable/subscription.js
+- app/javascript/action_cable/subscription_guarantor.js
+- app/javascript/action_cable/subscriptions.js
+- app/javascript/turbo/cable.js
+- app/javascript/turbo/cable_stream_source_element.js
+- app/javascript/turbo/fetch_requests.js
+- app/javascript/turbo/index.js
+- app/javascript/turbo/snakeize.js
+- app/models/chrono_cable/application_record.rb
+- app/models/solid_cable/channel.rb
+- db/migrate/20260628205427_create_solid_cable_channels.rb
+- db/migrate/20260629194211_add_channel_id_to_solid_cable_messages.rb
+- lib/action_cable/subscription_adapter/message.rb
+- lib/chrono_cable.rb
+- lib/chrono_cable/channel_base.rb
+- lib/chrono_cable/channel_streams.rb
+- lib/chrono_cable/connection_subscriptions.rb
+- lib/chrono_cable/engine.rb
+- lib/chrono_cable/solid_cable_adapter.rb
+- lib/chrono_cable/solid_cable_adapter_listener.rb
+- lib/chrono_cable/solid_cable_broadcasting.rb
+- lib/chrono_cable/solid_cable_message_class_methods.rb
+- lib/chrono_cable/subscription_adapter_base_extensions.rb
+- lib/chrono_cable/turbo_streams_channel.rb
+- lib/chrono_cable/version.rb
+- lib/generators/chrono_cable/install/USAGE
+- lib/generators/chrono_cable/install/install_generator.rb
+- lib/generators/chrono_cable/install/templates/add_channel_id_to_solid_cable_messages.rb
+- lib/generators/chrono_cable/install/templates/create_solid_cable_channels.rb
+- lib/tasks/chrono_cable_tasks.rake
+homepage: https://github.com/npezza93/chrono_cable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/npezza93/chrono_cable
+  source_code_uri: https://github.com/npezza93/chrono_cable
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+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: 4.0.20
+specification_version: 4
+summary: Ordered, recoverable Action Cable streams backed by Solid Cable.
+test_files: []