hibiki_rails 0.1.0

data/lib/hibiki/rails/graph_actor.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    # Funnels all access to one connection's signal graph through a single
+    # worker thread. ActionCable dispatches incoming commands on a thread
+    # pool with no per-channel ordering guarantee, while hibiki's threading
+    # model is confinement without locks — so the graph is built, mutated,
+    # and disposed on exactly one thread, and cable threads only ever
+    # enqueue closures.
+    #
+    # Thread-per-graph is deliberate while the gem incubates; a pooled
+    # executor with per-graph ordering can replace it behind
+    # Channel#build_graph_actor once real numbers ask for one.
+    class GraphActor
+      def initialize(name: "hibiki-graph", on_error: Hibiki::Rails.default_error_reporter)
+        @on_error = on_error
+        @queue = Queue.new
+        @thread = Thread.new { work }
+        @thread.name = name # keep <= 15 chars: Linux truncates pthread names
+      end
+
+      # Enqueue a closure for the worker. Returns false (rather than
+      # raising) once stopped: an action can race teardown, and a cable
+      # thread must never blow up because the user just navigated away.
+      def post(&job)
+        @queue << job
+        true
+      rescue ClosedQueueError
+        false
+      end
+
+      # Queue#close, not clear: already-posted jobs — in particular the
+      # root dispose posted from unsubscribed — drain before the worker
+      # exits. Idempotent. `wait: true` joins the worker; specs use it as
+      # a deterministic drain barrier.
+      def stop(wait: false)
+        @queue.close
+        @thread.join if wait
+        nil
+      end
+
+      def stopped? = @queue.closed?
+
+      private
+
+      # Per-job rescue keeps the worker alive: one bad action must not take
+      # the whole graph down. StandardError only — an Interrupt should.
+      def work
+        while (job = @queue.pop)
+          begin
+            job.call
+          rescue StandardError => e
+            @on_error.call(e)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hibiki/rails/helpers.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hibiki
+  module Rails
+    # Opt-in helpers that stamp the packaged client's attribute protocol
+    # (interpreted by the vendored hibiki.js Stimulus controller). Strictly
+    # opt-in, mirroring Hibiki::DSL: include it where you want the bare
+    # names — ApplicationHelper for ERB views, individual Phlex components —
+    # the gem never includes it for you.
+    #
+    #   div(**hibiki_island(CounterChannel, cid:)) do
+    #     button(**on(:increment)) { "+" }
+    #     button(**on(:toggle, with: { index: 3 })) { "toggle" }
+    #     input(name: "step", **on(:set_step, event: :change))
+    #     form(**on(:add, event: :submit)) { ... }
+    #   end
+    #
+    # Both helpers return a `{ data: { ... } }` hash: splat it into Phlex
+    # element methods or Rails tag helpers (`tag.div(**hibiki_island(...))`).
+    # When the element needs other attributes on the same `data:` key, merge
+    # the hashes yourself (Phlex's `mix` does this).
+    #
+    # The emitted attribute names are a private contract between these
+    # helpers and the gem's JS — they version together; don't hand-write
+    # them in app code.
+    module Helpers
+      # The island root: one channel subscription per island, identified by
+      # a per-page-load cid (each tab is its own graph). `channel` is the
+      # channel class or its name as a string.
+      def hibiki_island(channel, cid:)
+        channel_name = channel.is_a?(Class) ? channel.name : channel.to_s
+        { data: { controller: "hibiki", hibiki_channel_value: channel_name,
+                  hibiki_cid_value: cid } }
+      end
+
+      # Forward a DOM event on this element as a channel action. `event:`
+      # picks the DOM event (:click, :change, :submit); `with:` is a hash
+      # sent as the action's payload. The client adds event-derived data on
+      # top: a changed control contributes `{ name => value }`, a submitted
+      # form contributes its FormData (and is reset after the perform).
+      def on(action, event: :click, with: nil)
+        data = { hibiki_on: "#{event}->#{action}" }
+        data[:hibiki_with] = JSON.generate(with) unless with.nil?
+        { data: }
+      end
+    end
+  end
+end

data/lib/hibiki/rails/registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    # Tracks every live hibiki channel in the process so the Rails
+    # reloader can tear them down: a long-lived graph holds blocks bound
+    # to the class versions it was built from, so surviving a code reload
+    # would mean effects running stale code forever.
+    #
+    # NOTE: the core's no-mutex rule is about the GRAPH (confinement, see
+    # hibiki's docs-md/threading-model.md). This is glue infrastructure
+    # touched from many cable threads; a lock is the right tool here.
+    class Registry
+      def initialize
+        @lock = Mutex.new
+        @channels = Set.new
+      end
+
+      def register(channel)
+        @lock.synchronize { @channels << channel }
+      end
+
+      def unregister(channel)
+        @lock.synchronize { @channels.delete(channel) }
+      end
+
+      def size
+        @lock.synchronize { @channels.size }
+      end
+
+      # Close each distinct cable connection, which routes every one of
+      # its channels through the normal unsubscribed path — dispose root,
+      # stop actor, unregister — so teardown has exactly ONE code path and
+      # idempotency comes free. Clients auto-reconnect, resubscribe, and
+      # #build_graph reruns on fresh class versions; graph state resets,
+      # which is inherent to a remount (LiveView does the same).
+      def dispose_all
+        channels = @lock.synchronize { @channels.to_a }
+        channels.map(&:connection).uniq.each(&:close)
+      end
+    end
+
+    @registry = Registry.new
+
+    class << self
+      # Process-wide registry of live hibiki channels.
+      attr_reader :registry
+    end
+  end
+end

data/lib/hibiki/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/hibiki/rails.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# NOTE: for everything under lib/hibiki/rails/ — inside this namespace a bare
+# `Rails` constant resolves to Hibiki::Rails, not the framework. Always
+# write `::Rails.` when you mean the framework.
+module Hibiki
+  # Rails glue for hibiki: connection-scoped signal graphs over ActionCable,
+  # pushing re-rendered HTML through Turbo Streams.
+  module Rails
+    # Default per-job error sink for GraphActor: the Rails error reporter,
+    # so a raising action shows up wherever the app already sends errors.
+    # This is the outer layer of the funnel — a flush error first goes to
+    # an app-set Hibiki.error_handler if there is one, and only re-raises
+    # into the actor's per-job rescue when there isn't.
+    def self.default_error_reporter
+      ->(error) { ::Rails.error.report(error, handled: true, source: "hibiki_rails") }
+    end
+  end
+end
+
+require_relative "rails/version"
+require_relative "rails/registry"
+require_relative "rails/graph_actor"
+require_relative "rails/debounce"
+require_relative "rails/broadcasts"
+require_relative "rails/channel"
+require_relative "rails/helpers"
+require_relative "rails/engine"

data/lib/hibiki_rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "hibiki"
+require "hibiki/rails"

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: hibiki_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- planetaska
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actioncable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: hibiki
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'Run a hibiki signal graph per ActionCable connection: build it in subscribed,
+  mutate it from channel actions (batched, confined to one worker thread), and let
+  effects push re-rendered partials to the page through Turbo Streams.'
+email:
+- planetaska@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- app/assets/javascripts/hibiki.js
+- config/importmap.rb
+- lib/generators/hibiki/rails/generator_helpers.rb
+- lib/generators/hibiki/rails/install/install_generator.rb
+- lib/generators/hibiki/rails/install/templates/channel.rb.tt
+- lib/generators/hibiki/rails/install/templates/connection.rb.tt
+- lib/generators/hibiki/rails/install/templates/hibiki_controller.js.tt
+- lib/generators/hibiki/rails/island/island_generator.rb
+- lib/generators/hibiki/rails/island/templates/channel.rb.tt
+- lib/generators/hibiki/rails/island/templates/display.html.erb.tt
+- lib/generators/hibiki/rails/island/templates/island.html.erb.tt
+- lib/generators/hibiki/rails/phlex/phlex_generator.rb
+- lib/generators/hibiki/rails/phlex/templates/channel.rb.tt
+- lib/generators/hibiki/rails/phlex/templates/component.rb.tt
+- lib/generators/hibiki/rails/phlex/templates/island_component.rb.tt
+- lib/generators/hibiki/rails/stimulus/stimulus_generator.rb
+- lib/generators/hibiki/rails/stimulus/templates/channel.rb.tt
+- lib/generators/hibiki/rails/stimulus/templates/controller.js.tt
+- lib/generators/hibiki/rails/stimulus/templates/display.html.erb.tt
+- lib/generators/hibiki/rails/stimulus/templates/island.html.erb.tt
+- lib/hibiki/rails.rb
+- lib/hibiki/rails/broadcasts.rb
+- lib/hibiki/rails/channel.rb
+- lib/hibiki/rails/debounce.rb
+- lib/hibiki/rails/engine.rb
+- lib/hibiki/rails/graph_actor.rb
+- lib/hibiki/rails/helpers.rb
+- lib/hibiki/rails/registry.rb
+- lib/hibiki/rails/version.rb
+- lib/hibiki_rails.rb
+homepage: https://github.com/planetaska/hibiki-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/planetaska/hibiki-rails
+  source_code_uri: https://github.com/planetaska/hibiki-rails
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Rails glue for hibiki: connection-scoped signal graphs over ActionCable
+  + Turbo Streams.'
+test_files: []