turbo_cable 1.0.0

data/lib/generators/turbo_cable/install/templates/turbo_streams_controller.js

@@ -0,0 +1,184 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Controller that provides custom WebSocket-based Turbo Streams support
+// Automatically subscribes to streams marked with data-turbo-stream
+export default class extends Controller {
+  connect() {
+    console.debug("Turbo Streams WebSocket controller connected")
+
+    // Find all turbo-stream markers in the document
+    const markers = document.querySelectorAll('[data-turbo-stream="true"]')
+
+    if (markers.length === 0) {
+      console.debug("No turbo-stream markers found")
+      return
+    }
+
+    // Collect all stream names
+    this.streams = new Set()
+    markers.forEach(marker => {
+      const streams = marker.dataset.streams
+      if (streams) {
+        streams.split(',').forEach(stream => this.streams.add(stream.trim()))
+      }
+    })
+
+    if (this.streams.size === 0) {
+      console.debug("No streams to subscribe to")
+      return
+    }
+
+    console.debug("Subscribing to streams:", Array.from(this.streams))
+
+    // Create WebSocket connection
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+    this.ws = new WebSocket(`${protocol}//${window.location.host}/cable`)
+    this.subscribed = new Set()
+
+    this.ws.onopen = () => {
+      console.debug('WebSocket connected')
+      // Subscribe to all streams
+      this.streams.forEach(stream => {
+        this.ws.send(JSON.stringify({
+          type: 'subscribe',
+          stream: stream
+        }))
+      })
+    }
+
+    this.ws.onmessage = (event) => {
+      const msg = JSON.parse(event.data)
+
+      switch (msg.type) {
+        case 'subscribed':
+          console.debug('Subscribed to stream:', msg.stream)
+          this.subscribed.add(msg.stream)
+          break
+
+        case 'message':
+          if (this.streams.has(msg.stream)) {
+            console.debug("Received update on stream:", msg.stream)
+            this.processTurboStream(msg.stream, msg.data)
+          }
+          break
+
+        case 'ping':
+          // Respond to ping
+          this.ws.send(JSON.stringify({ type: 'pong' }))
+          break
+      }
+    }
+
+    this.ws.onerror = (error) => {
+      console.error('WebSocket error:', error)
+    }
+
+    this.ws.onclose = () => {
+      console.debug('WebSocket disconnected')
+
+      // Auto-reconnect after 3 seconds if we had subscriptions
+      if (this.subscribed.size > 0) {
+        setTimeout(() => {
+          console.debug('Attempting to reconnect...')
+          this.connect()
+        }, 3000)
+      }
+    }
+  }
+
+  disconnect() {
+    // Clean up subscription when controller is removed
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.streams.forEach(stream => {
+        this.ws.send(JSON.stringify({
+          type: 'unsubscribe',
+          stream: stream
+        }))
+      })
+      this.ws.close()
+    }
+    this.subscribed.clear()
+  }
+
+  processTurboStream(stream, data) {
+    // Check if data is a string (Turbo Stream HTML) or object (custom JSON)
+    if (typeof data === 'string') {
+      // Process as Turbo Stream HTML
+      this.processTurboStreamHTML(data)
+    } else {
+      // Dispatch custom event for JSON data
+      const event = new CustomEvent('turbo:stream-message', {
+        detail: { stream: stream, data: data },
+        bubbles: true
+      })
+      document.dispatchEvent(event)
+      console.debug('Dispatched turbo:stream-message event for stream:', stream)
+    }
+  }
+
+  processTurboStreamHTML(html) {
+    // Parse the Turbo Stream HTML and apply the action
+    const parser = new DOMParser()
+    const doc = parser.parseFromString(html, 'text/html')
+    const turboStream = doc.querySelector('turbo-stream')
+
+    if (!turboStream) {
+      console.warn('No turbo-stream element found in:', html)
+      return
+    }
+
+    const action = turboStream.getAttribute('action')
+    const target = turboStream.getAttribute('target')
+    const template = turboStream.querySelector('template')
+
+    if (!target) {
+      console.warn('No target specified in turbo-stream')
+      return
+    }
+
+    const targetElement = document.getElementById(target)
+    if (!targetElement) {
+      console.warn('Target element not found:', target)
+      return
+    }
+
+    switch (action) {
+      case 'replace':
+        if (template && template.content) {
+          const newElement = template.content.firstElementChild.cloneNode(true)
+          targetElement.replaceWith(newElement)
+          console.debug('Replaced element:', target)
+        }
+        break
+
+      case 'update':
+        if (template && template.content) {
+          targetElement.innerHTML = template.innerHTML
+          console.debug('Updated element:', target)
+        }
+        break
+
+      case 'append':
+        if (template && template.content) {
+          targetElement.appendChild(template.content.cloneNode(true))
+          console.debug('Appended to element:', target)
+        }
+        break
+
+      case 'prepend':
+        if (template && template.content) {
+          targetElement.prepend(template.content.cloneNode(true))
+          console.debug('Prepended to element:', target)
+        }
+        break
+
+      case 'remove':
+        targetElement.remove()
+        console.debug('Removed element:', target)
+        break
+
+      default:
+        console.warn('Unknown turbo-stream action:', action)
+    }
+  }
+}

data/lib/tasks/turbo_cable_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :turbo_cable do
+#   # Task goes here
+# end

data/lib/turbo_cable/broadcastable.rb

@@ -0,0 +1,161 @@
+require "net/http"
+require "json"
+
+module TurboCable
+  # Provides Turbo Streams broadcasting methods for ActiveRecord models
+  # Drop-in replacement for Turbo::Streams::Broadcastable
+  #
+  # Hybrid async/sync approach:
+  # - _later_to methods: Use Active Job if available, otherwise synchronous
+  # - Non-_later_to methods: Always synchronous
+  module Broadcastable
+    extend ActiveSupport::Concern
+
+    # Module-level method for broadcasting custom JSON data
+    # Useful for progress updates, job status, or non-Turbo-Stream messages
+    def self.broadcast_json(stream_name, data)
+      # Get the actual Puma/Rails server port
+      # Priority: TURBO_CABLE_PORT > PORT > 3000
+      # Use TURBO_CABLE_PORT to override PORT when it's set to proxy/Thruster port
+      default_port = ENV["TURBO_CABLE_PORT"] || ENV["PORT"] || "3000"
+      uri = URI(ENV.fetch("TURBO_CABLE_BROADCAST_URL", "http://localhost:#{default_port}/_broadcast"))
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.open_timeout = 1
+      http.read_timeout = 1
+
+      request = Net::HTTP::Post.new(uri.path, "Content-Type" => "application/json")
+      request.body = {
+        stream: stream_name,
+        data: data
+      }.to_json
+
+      http.request(request)
+    rescue => e
+      Rails.logger.error("TurboCable: JSON broadcast failed: #{e.class} - #{e.message}") if defined?(Rails)
+    end
+
+    # Async broadcast methods (truly async if Active Job is configured)
+    def broadcast_replace_later_to(stream_name, **options)
+      if async_broadcast_available?
+        enqueue_broadcast_job(stream_name, action: :replace, **options)
+      else
+        broadcast_action_now(stream_name, action: :replace, **options)
+      end
+    end
+
+    def broadcast_update_later_to(stream_name, **options)
+      if async_broadcast_available?
+        enqueue_broadcast_job(stream_name, action: :update, **options)
+      else
+        broadcast_action_now(stream_name, action: :update, **options)
+      end
+    end
+
+    def broadcast_append_later_to(stream_name, **options)
+      if async_broadcast_available?
+        enqueue_broadcast_job(stream_name, action: :append, **options)
+      else
+        broadcast_action_now(stream_name, action: :append, **options)
+      end
+    end
+
+    def broadcast_prepend_later_to(stream_name, **options)
+      if async_broadcast_available?
+        enqueue_broadcast_job(stream_name, action: :prepend, **options)
+      else
+        broadcast_action_now(stream_name, action: :prepend, **options)
+      end
+    end
+
+    # Synchronous broadcast methods (always immediate)
+    def broadcast_replace_to(stream_name, **options)
+      broadcast_action_now(stream_name, action: :replace, **options)
+    end
+
+    def broadcast_update_to(stream_name, **options)
+      broadcast_action_now(stream_name, action: :update, **options)
+    end
+
+    def broadcast_append_to(stream_name, **options)
+      broadcast_action_now(stream_name, action: :append, **options)
+    end
+
+    def broadcast_prepend_to(stream_name, **options)
+      broadcast_action_now(stream_name, action: :prepend, **options)
+    end
+
+    def broadcast_remove_to(stream_name, target:)
+      turbo_stream_html = <<~HTML
+        <turbo-stream action="remove" target="#{target}">
+        </turbo-stream>
+      HTML
+
+      broadcast_turbo_stream(stream_name, turbo_stream_html)
+    end
+
+    private
+
+    # Check if async broadcasting is available (Active Job with non-inline adapter)
+    def async_broadcast_available?
+      defined?(ActiveJob) &&
+        defined?(TurboCable::BroadcastJob) &&
+        ActiveJob::Base.queue_adapter_name != :inline
+    end
+
+    # Enqueue broadcast job for async processing
+    def enqueue_broadcast_job(stream_name, action:, target: nil, partial: nil, html: nil, locals: {})
+      TurboCable::BroadcastJob.perform_later(
+        stream_name,
+        action: action,
+        model_gid: to_global_id.to_s,
+        target: target,
+        partial: partial,
+        html: html,
+        locals: locals
+      )
+    end
+
+    # Broadcast immediately (synchronous)
+    def broadcast_action_now(stream_name, action:, target: nil, partial: nil, html: nil, locals: {})
+      # Determine target - use explicit target or derive from model
+      target ||= "#{self.class.name.underscore}_#{id}"
+
+      # Generate content HTML
+      content_html = if html
+        html
+      elsif partial
+        # Render partial with locals
+        ApplicationController.render(partial: partial, locals: locals.merge(self.class.name.underscore.to_sym => self))
+      else
+        # Render default partial for this model
+        ApplicationController.render(partial: self, locals: locals)
+      end
+
+      # Generate Turbo Stream HTML
+      turbo_stream_html = <<~HTML
+        <turbo-stream action="#{action}" target="#{target}">
+          <template>
+            #{content_html}
+          </template>
+        </turbo-stream>
+      HTML
+
+      broadcast_turbo_stream(stream_name, turbo_stream_html)
+    end
+
+    def broadcast_turbo_stream(stream_name, html)
+      uri = URI(ENV.fetch("TURBO_CABLE_BROADCAST_URL", "http://localhost:#{ENV.fetch('PORT', 3000)}/_broadcast"))
+      http = Net::HTTP.new(uri.host, uri.port)
+      request = Net::HTTP::Post.new(uri.path, "Content-Type" => "application/json")
+      request.body = {
+        stream: stream_name,
+        data: html
+      }.to_json
+
+      http.request(request)
+    rescue => e
+      Rails.logger.error("Broadcast failed: #{e.message}") if defined?(Rails)
+    end
+  end
+end

data/lib/turbo_cable/engine.rb

@@ -0,0 +1,24 @@
+module TurboCable
+  class Engine < ::Rails::Engine
+    isolate_namespace TurboCable
+
+    # Add Rack middleware for WebSocket handling
+    initializer "turbo_cable.middleware" do |app|
+      app.middleware.use TurboCable::RackHandler
+    end
+
+    # Prepend Broadcastable in ApplicationRecord (overrides turbo-rails methods)
+    initializer "turbo_cable.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        prepend TurboCable::Broadcastable
+      end
+    end
+
+    # Make helpers available to the host application
+    initializer "turbo_cable.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper TurboCable::StreamsHelper
+      end
+    end
+  end
+end

data/lib/turbo_cable/rack_handler.rb

@@ -0,0 +1,204 @@
+require "digest/sha1"
+require "base64"
+require "json"
+
+module TurboCable
+  # Rack middleware for handling WebSocket connections using Rack hijack
+  # Uses RFC 6455 WebSocket protocol (no dependencies required)
+  class RackHandler
+    GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+    def initialize(app)
+      @app = app
+      @connections = {} # stream => [sockets]
+      @mutex = Mutex.new
+    end
+
+    def call(env)
+      # Handle WebSocket upgrade for /cable
+      if env["PATH_INFO"] == "/cable" && websocket_request?(env)
+        handle_websocket(env)
+        # Return -1 to indicate we've hijacked the connection
+        [ -1, {}, [] ]
+      elsif env["PATH_INFO"] == "/_broadcast" && env["REQUEST_METHOD"] == "POST"
+        handle_broadcast(env)
+      else
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def websocket_request?(env)
+      env["HTTP_UPGRADE"]&.downcase == "websocket" &&
+        env["HTTP_CONNECTION"]&.downcase&.include?("upgrade")
+    end
+
+    def handle_websocket(env)
+      # Hijack the TCP socket from Rack/Puma
+      io = env["rack.hijack"].call
+
+      # Perform WebSocket handshake (RFC 6455)
+      key = env["HTTP_SEC_WEBSOCKET_KEY"]
+      accept = Base64.strict_encode64(Digest::SHA1.digest(key + GUID))
+
+      io.write("HTTP/1.1 101 Switching Protocols\r\n")
+      io.write("Upgrade: websocket\r\n")
+      io.write("Connection: Upgrade\r\n")
+      io.write("Sec-WebSocket-Accept: #{accept}\r\n")
+      io.write("\r\n")
+
+      # Set read timeout to 60 seconds to detect half-dead connections
+      # This matches Navigator's timeout and prevents ghost connections from accumulating
+      io.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [ 60, 0 ].pack("l_2"))
+
+      # Track connection subscriptions
+      subscriptions = Set.new
+
+      # Handle WebSocket frames in a thread
+      Thread.new do
+        begin
+          loop do
+            frame = read_frame(io)
+            break if frame.nil? || frame[:opcode] == 8 # Close frame
+
+            if frame[:opcode] == 1 # Text frame
+              handle_message(io, frame[:payload], subscriptions)
+            elsif frame[:opcode] == 9 # Ping
+              send_frame(io, 10, frame[:payload]) # Pong
+            end
+          end
+        rescue => e
+          Rails.logger.error("WebSocket error: #{e}")
+        ensure
+          # Unsubscribe from all streams
+          @mutex.synchronize do
+            subscriptions.each do |stream|
+              @connections[stream]&.delete(io)
+              @connections.delete(stream) if @connections[stream]&.empty?
+            end
+          end
+          io.close rescue nil
+        end
+      end
+    end
+
+    def handle_message(io, payload, subscriptions)
+      msg = JSON.parse(payload)
+
+      case msg["type"]
+      when "subscribe"
+        stream = msg["stream"]
+
+        # Add connection to stream
+        @mutex.synchronize do
+          @connections[stream] ||= []
+          @connections[stream] << io
+        end
+        subscriptions.add(stream)
+
+        # Send confirmation
+        response = { type: "subscribed", stream: stream }
+        send_frame(io, 1, response.to_json)
+
+      when "unsubscribe"
+        stream = msg["stream"]
+
+        # Remove connection from stream
+        @mutex.synchronize do
+          @connections[stream]&.delete(io)
+          @connections.delete(stream) if @connections[stream]&.empty?
+        end
+        subscriptions.delete(stream)
+
+      when "pong"
+        # Client responding to ping
+      end
+    end
+
+    def handle_broadcast(env)
+      # Security: Only allow broadcasts from localhost
+      unless localhost_request?(env)
+        return [ 403, { "Content-Type" => "text/plain" }, [ "Forbidden: Broadcasts only allowed from localhost" ] ]
+      end
+
+      # Read JSON body
+      input = env["rack.input"].read
+      data = JSON.parse(input)
+
+      stream = data["stream"]
+      message = { type: "message", stream: stream, data: data["data"] }
+      payload = message.to_json
+
+      # Broadcast to all connections on this stream
+      sockets = @mutex.synchronize { @connections[stream]&.dup || [] }
+
+      sockets.each do |io|
+        begin
+          send_frame(io, 1, payload)
+        rescue
+          # Connection died, will be cleaned up by read loop
+        end
+      end
+
+      [ 200, { "Content-Type" => "text/plain" }, [ "OK" ] ]
+    end
+
+    def localhost_request?(env)
+      remote_addr = env["REMOTE_ADDR"]
+      # Allow IPv4 localhost (127.0.0.1, 127.x.x.x) and IPv6 localhost (::1)
+      remote_addr =~ /^127\./ || remote_addr == "::1"
+    end
+
+    # Read WebSocket frame (RFC 6455 format)
+    def read_frame(io)
+      byte1 = io.read(1)&.unpack1("C")
+      return nil if byte1.nil?
+
+      fin = (byte1 & 0x80) != 0
+      opcode = byte1 & 0x0F
+
+      byte2 = io.read(1)&.unpack1("C")
+      return nil if byte2.nil?
+
+      masked = (byte2 & 0x80) != 0
+      length = byte2 & 0x7F
+
+      if length == 126
+        length = io.read(2).unpack1("n")
+      elsif length == 127
+        length = io.read(8).unpack1("Q>")
+      end
+
+      mask_key = masked ? io.read(4).unpack("C*") : nil
+      payload_data = io.read(length)
+
+      if masked && mask_key
+        payload_data = payload_data.bytes.map.with_index do |byte, i|
+          byte ^ mask_key[i % 4]
+        end.pack("C*")
+      end
+
+      { opcode: opcode, payload: payload_data, fin: fin }
+    end
+
+    # Send WebSocket frame (RFC 6455 format)
+    def send_frame(io, opcode, payload)
+      payload = payload.b
+      length = payload.bytesize
+
+      frame = [ 0x80 | opcode ].pack("C") # FIN=1
+
+      if length < 126
+        frame << [ length ].pack("C")
+      elsif length < 65536
+        frame << [ 126, length ].pack("Cn")
+      else
+        frame << [ 127, length ].pack("CQ>")
+      end
+
+      frame << payload
+      io.write(frame)
+    end
+  end
+end

data/lib/turbo_cable/version.rb

@@ -0,0 +1,3 @@
+module TurboCable
+  VERSION = "1.0.0"
+end

data/lib/turbo_cable.rb

@@ -0,0 +1,9 @@
+require "turbo_cable/version"
+require "turbo_cable/engine"
+require "turbo_cable/rack_handler"
+require "turbo_cable/broadcastable"
+
+module TurboCable
+  # Custom WebSocket-based Turbo Streams implementation
+  # Drop-in replacement for Action Cable with reduced memory footprint
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: turbo_cable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sam Ruby
+bindir: bin
+cert_chain: []
+date: 2025-11-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  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: TurboCable replaces Action Cable with a custom WebSocket implementation
+  for Turbo Streams, providing 79-85% memory savings (134-144MB per process) while
+  maintaining full API compatibility. Designed for single-server deployments with
+  zero external dependencies beyond Ruby's standard library.
+email:
+- rubys@intertwingly.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- EXAMPLES.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/turbo_cable/application.css
+- app/controllers/turbo_cable/application_controller.rb
+- app/helpers/turbo_cable/application_helper.rb
+- app/helpers/turbo_cable/streams_helper.rb
+- app/jobs/turbo_cable/application_job.rb
+- app/jobs/turbo_cable/broadcast_job.rb
+- app/mailers/turbo_cable/application_mailer.rb
+- app/models/turbo_cable/application_record.rb
+- app/views/layouts/turbo_cable/application.html.erb
+- config/routes.rb
+- lib/generators/turbo_cable/install/install_generator.rb
+- lib/generators/turbo_cable/install/templates/turbo_streams_controller.js
+- lib/tasks/turbo_cable_tasks.rake
+- lib/turbo_cable.rb
+- lib/turbo_cable/broadcastable.rb
+- lib/turbo_cable/engine.rb
+- lib/turbo_cable/rack_handler.rb
+- lib/turbo_cable/version.rb
+homepage: https://github.com/rubys/turbo_cable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rubys/turbo_cable
+  source_code_uri: https://github.com/rubys/turbo_cable
+  changelog_uri: https://github.com/rubys/turbo_cable/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Lightweight WebSocket-based Turbo Streams for single-server Rails deployments
+test_files: []