hibiki_rails 0.17.2 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83e9656d09f3910405a4db7167b526c173158eb1035d5cb5129e4f916c88c278
-  data.tar.gz: e22b25605c6522e98cfdc86dcd685e62b3c60ed31ca865eb2daa53f74aaaf946
+  metadata.gz: 915a98a11ca62685f60697d27383e8592978e0c2173b0e984c24eca7736cef55
+  data.tar.gz: 070cd14175c3027b164ec0b52378b59178499f3f3474fe3296722f6432c580ab
 SHA512:
-  metadata.gz: 8c459eb9453de6af88c6e7859849a41dcbf7c0daa5d2e79da12e5ac8f729f4b85093e9d10c176d97cb8cd5141ef47ffeb0bcb2482aa03b223e42b2af4b13d9a6
-  data.tar.gz: 7ccd090ef5fdd72735d7bb45d356a1f7085fb6c323d42692c91b7226a5fd6ac058f0ea477efaa6d7693dfbfe66254d85c358e8ea5ca7d3fcd49f6fde56366040
+  metadata.gz: 5d07fa8e0a897a21cce85e559e42a02dc78090f89986bc37c24202a36fb81322287a1ae86fb4c5166aa615a4ee8924732bb63020643a2e4db8e8ec72a5d870eb
+  data.tar.gz: 993b20b7af2d105e5c067823621eb8050ff426a57a9ac0b0aacccbd2a9fd9136a9a2a6f0f635d7932952f7c4c58bef2645492c67fe1b79acbb28d1c2e86f5a37

data/CHANGELOG.md

@@ -4,6 +4,49 @@ The gem and the npm package are released in lockstep and share these version
 numbers — `app/assets/javascripts/hibiki.js` is a single copy served both ways,
 so importmap and bundler apps always resolve identical client code.
 
+## 0.18.0 — 2026-10-11
+
+### Added
+
+**Instrumentation events.** A channel now publishes
+`ActiveSupport::Notifications` events, so an app can time what a graph does.
+Action Cable's own `perform_action.action_cable` covers only the hand-off to
+the graph's thread; the action, its effects and its renders run after it.
+
+| Event | Duration covers | Payload |
+|---|---|---|
+| `subscribe.hibiki_rails` | building the graph and its first renders | `channel` |
+| `unsubscribe.hibiki_rails` | disposing the graph | `channel` |
+| `action.hibiki_rails` | the action and every effect it flushed | `channel`, `action`, `wait`, `renders` |
+| `render.hibiki_rails` | one `broadcast_replace`, `broadcast_morph` or `broadcast_refresh` | `channel`, `target`, `method` |
+
+- The events are always on and need no configuration. The gem subscribes to
+  none of them. With no subscriber an action costs one to two microseconds
+  more than in 0.17.2.
+- A subscriber runs on the graph's thread, so keep it to cheap work in
+  memory.
+- An action the channel does not have publishes nothing. A raising action
+  publishes, with the exception in the payload.
+- `transmit_value` and `transmit_url` have no event of their own; Action
+  Cable's `transmit.action_cable` covers them.
+
+**`Hibiki::Rails.registry.tally`** returns the live subscriptions by channel
+class name.
+
+**Trips: how long a visitor waited.** With `HibikiController.reportTrips =
+true`, each island times its round trips and sends them with its next action.
+The channel publishes one `trip.hibiki_rails` event for each, with `channel`,
+`action`, `ack` (milliseconds until the server answered) and `paint`
+(milliseconds until the first render arrived, or `nil`).
+
+- Off by default. Set it once, on the class, for every island.
+- A dropped or stalled trip is not reported, and neither is the last trip on
+  a page, since no action follows it.
+- The figures come from the browser. The channel takes at most five per
+  action, only for its own actions, and clamps each to 0 to 60 000 ms.
+- `hbt` joins `hbk` as a reserved payload key. The channel removes it before
+  the action method sees its data.
+
 ## 0.17.2 — 2026-10-11
 
 ### Fixed

data/README.md

@@ -125,6 +125,52 @@ The generated components are just Rails partials (or Phlex components, if you us
 
 Congratulations! Now you have your first reactive component!
 
+## Instrumentation
+
+A channel publishes `ActiveSupport::Notifications` events. They are always
+on, and the gem subscribes to none of them.
+
+| Event | Duration covers | Payload |
+|---|---|---|
+| `subscribe.hibiki_rails` | building the graph and its first renders | `channel` |
+| `unsubscribe.hibiki_rails` | disposing the graph | `channel` |
+| `action.hibiki_rails` | the action and every effect it flushed | `channel`, `action`, `wait`, `renders` |
+| `render.hibiki_rails` | rendering and handing the stream to Action Cable | `channel`, `target`, `method` |
+| `trip.hibiki_rails` | nothing | `channel`, `action`, `ack`, `paint` |
+
+```ruby
+ActiveSupport::Notifications.subscribe("action.hibiki_rails") do |event|
+  Rails.logger.info "#{event.payload[:channel]}##{event.payload[:action]} #{event.duration.round(1)}ms"
+end
+```
+
+- `channel` is the class name. `wait` is the milliseconds the action queued
+  for the graph's thread. `renders` is how many renders it caused.
+- `method` is `:replace`, `:morph` or `:refresh`. A refresh has no `target`.
+- An action the channel does not have publishes nothing. A raising action
+  publishes, with the exception in the payload.
+- Action Cable's `broadcast.action_cable` fires inside the render event, on
+  the same thread, and carries the message if you want its size.
+- `Hibiki::Rails.registry.tally` returns the live subscriptions by channel
+  class, and `registry.size` the total.
+
+**A subscriber runs on the graph's thread.** Keep it to cheap work in
+memory; anything slow holds up that visitor's actions.
+
+A `trip` is the browser's own timing of one action: `ack` is the
+milliseconds until the server answered and `paint` the milliseconds until
+its first render arrived, or `nil` when nothing rendered. Reporting is off
+until the app turns it on:
+
+```js
+import HibikiController from "hibiki-rails"
+HibikiController.reportTrips = true
+```
+
+Each island then sends its last trips with its next action. The figures come
+from visitors' browsers, so treat them as reported: the gem bounds them (five
+per action, known action names, 0 to 60 000 ms) and cannot verify them.
+
 ## Documentation
 
 Documentation site: <https://planetaska.github.io/hibiki/rails-introduction/>

data/app/assets/javascripts/hibiki.js

@@ -284,6 +284,10 @@ export class ChannelController extends Controller {
   static busyCeiling = 10000
   static focusGrace = 500
 
+  // Whether to tell the server how long each trip took (see "Trips"
+  // below). Off unless an app sets it, once, for every island.
+  static reportTrips = false
+
   async connect() {
     this.prepareTransport()
     await this.openSubscription()
@@ -302,6 +306,7 @@ export class ChannelController extends Controller {
     this.seq = 0
     this.renders = 0
     this.busy = new Map()
+    this.trips = []
     this.settledAt = -Infinity
     this.lastControl = null
     this.queued = []
@@ -345,7 +350,8 @@ export class ChannelController extends Controller {
   // a sequence number under the reserved `hbk` key and opens a busy record
   // that the matching ack closes; the seq is stamped LAST so a form field
   // can never overwrite it. (`hbk` is the second reserved payload key —
-  // ActionCable's own Subscription#perform already writes `action`.)
+  // ActionCable's own Subscription#perform already writes `action`. `hbt`
+  // is the third: the trips timed since the last perform.)
   //
   // Public API on the island controller (the header's "App JS reaching
   // the graph"). Returns the seq when the action was accepted, so a
@@ -356,8 +362,10 @@ export class ChannelController extends Controller {
   perform(action, payload = {}) {
     const seq = ++this.seq
     payload.hbk = seq
+    delete payload.hbt
     if (this.subscribed) {
-      this.beginBusy(seq)
+      this.sendTrips(payload)
+      this.beginBusy(seq, action)
       // Subscription#perform returns false when the socket is not open —
       // the gap between the socket dying and the connection monitor
       // noticing, during which `subscribed` still says live. The frame
@@ -383,7 +391,8 @@ export class ChannelController extends Controller {
     // whole gap — the signal the connect window cannot give, where the
     // page is painted and looks live.
     if (!this.connectedOnce) {
-      this.beginBusy(seq)
+      this.sendTrips(payload)
+      this.beginBusy(seq, action)
       this.queued.push([action, payload])
       return seq
     }
@@ -430,9 +439,11 @@ export class ChannelController extends Controller {
   // means the server has not answered, and a hold is motion after the
   // answer.
 
-  beginBusy(seq) {
+  beginBusy(seq, action) {
     const record = {
       control: null,
+      action,
+      at: performance.now(),
       // Which render the island was on when this started, so the ack can
       // ask "has anything painted since?" without consulting a clock.
       renders: this.renders,
@@ -486,6 +497,7 @@ export class ChannelController extends Controller {
     if (this.state === "stalled") this.setState("ready")
     const record = this.busy.get(ack)
     if (!record) return
+    if (!dropped) record.ack = Math.round(performance.now() - record.at)
     if (dropped || this.renders > record.renders) return this.settle(ack)
     record.grace = setTimeout(() => this.settle(ack), this.constructor.busyGrace)
   }
@@ -499,6 +511,7 @@ export class ChannelController extends Controller {
     this.settledAt = performance.now()
     record.control?.removeAttribute("data-hibiki-busy")
     if (this.busy.size === 0) this.hideBusy()
+    if (record.ack !== undefined && this.constructor.reportTrips) this.keepTrip(record)
   }
 
   settleAll() {
@@ -528,13 +541,49 @@ export class ChannelController extends Controller {
     this.setState("stalled")
   }
 
+  // ── Trips ─────────────────────────────────────────────────────────────
+  //
+  // Only the browser sees both halves of a trip land: the ack on the
+  // island's socket and the render after its pubsub hop. With reportTrips
+  // on, each acked trip is kept as its action, the ms to the ack and the ms
+  // to the first render of its own (null when nothing rendered), and the
+  // next perform carries the last five under `hbt`. A dropped or stalled
+  // trip is not reported, and the last trip on a page never is.
+
+  keepTrip({ action, at, ack, paint }) {
+    this.trips.push({ action, at, ack, paint, settled: this.settledAt })
+    if (this.trips.length > 5) this.trips.shift()
+  }
+
+  sendTrips(payload) {
+    if (!this.trips.length) return
+    payload.hbt = this.trips.map(({ action, ack, paint }) => [action, ack, paint ?? null])
+    this.trips = []
+  }
+
+  // A render of this island's own has arrived. Timed now, not when it is
+  // applied: the order and motion holds come after the answer. A trip that
+  // settled a moment ago still takes it, by the rule own() uses.
+  arrived() {
+    const now = performance.now()
+    for (const record of this.busy.values()) record.paint ??= Math.round(now - record.at)
+    for (const trip of this.trips) {
+      if (trip.paint === undefined && now - trip.settled <= this.constructor.focusGrace) {
+        trip.paint = Math.round(now - trip.at)
+      }
+    }
+  }
+
   // Every inbound frame lands here first. Acks are transport bookkeeping,
   // handled by the base and deliberately NOT routed through received() — so
   // a subclass that overrides received without calling super still clears
   // its pending state.
   handleMessage(data) {
     if (data && "ack" in data) return this.acknowledge(data)
-    if (data && data.html) this.renders++
+    if (data && data.html) {
+      this.renders++
+      this.arrived()
+    }
     this.received(data)
   }
 
@@ -855,6 +904,9 @@ export default class HibikiController extends ChannelController {
     this.streamRender = (event) => {
       const render = event.detail.render
       const stream = event.detail.newStream
+      if (stream?.getAttribute?.("data-hibiki-from") === `${this.channelValue}/${this.cidValue}`) {
+        this.arrived()
+      }
       // Taken now, not when the render's turn comes: see arrival().
       const arrival = this.arrival()
       event.detail.render = (streamElement) =>

data/lib/hibiki/rails/broadcasts.rb

@@ -13,14 +13,19 @@ module Hibiki
     # All private — a public helper would become a client-invocable action
     # (see the NOTE on Hibiki::Rails::Channel).
     module Broadcasts
+      include Instrumentation
+
       private
 
       # Replace the element with DOM id `target` (accepts partial:/locals:,
       # html:, or anything Turbo's renderer takes).
       def broadcast_replace(target:, attributes: {}, **rendering)
-        Turbo::StreamsChannel.broadcast_replace_to(
-          *stream_name, target:, attributes: attributes.merge(render_stamp), **rendering
-        )
+        method = attributes[:method].to_s == "morph" ? :morph : :replace
+        instrument_render(target:, method:) do
+          Turbo::StreamsChannel.broadcast_replace_to(
+            *stream_name, target:, attributes: attributes.merge(render_stamp), **rendering
+          )
+        end
       end
 
       # Replace via Turbo 8 morphing (<turbo-stream action="replace"
@@ -32,7 +37,7 @@ module Hibiki
       # Tell the page to refresh itself (Turbo 8 morph-everything style).
       # Pair with Debounce when many writes should mean one refresh.
       def broadcast_refresh
-        Turbo::StreamsChannel.broadcast_refresh_to(*stream_name)
+        instrument_render(method: :refresh) { Turbo::StreamsChannel.broadcast_refresh_to(*stream_name) }
       end
 
       # The Morph-everything style as one call: an effect that tracks

data/lib/hibiki/rails/channel.rb

@@ -77,13 +77,20 @@ module Hibiki
       # produces zero bytes, and "clear on the next render" would hang
       # forever. `delete`, not `[]`: the key must not reach the action
       # method's data. No `hbk`, no ack, so a 0.3.0 page keeps working.
+      #
+      # `hbt` is the third reserved key: the trips the browser timed since
+      # its last action (see Instrumentation#trips_from). Deleted whether or
+      # not anyone listens, for the same reason as `hbk`.
       def perform_action(data)
         seq = data.delete("hbk")
+        trips = trips_from(data.delete("hbt"))
+        asked = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
         # A nil actor means the subscription was rejected or already torn
         # down; drop the action rather than blow up the cable thread.
         posted = @__hibiki_actor&.post do
-          Hibiki.batch { super(data) }
+          trips.each { instrument("trip", it) }
+          instrument_action(data, asked) { Hibiki.batch { super(data) } }
         ensure
           # Hibiki.batch flushes in its own ensure, so effects queued
           # before a raise have run by the time this does — the ack is
@@ -111,7 +118,9 @@ module Hibiki
         # The block runs owned + untracked (Hibiki.root); the effects it
         # creates do their dependency-collecting first run right here, on
         # the graph thread.
-        @__hibiki_actor.post { @__hibiki_root = Hibiki.root { build_graph } }
+        @__hibiki_actor.post do
+          instrument("subscribe") { @__hibiki_root = Hibiki.root { build_graph } }
+        end
         Hibiki::Rails.registry.register(self)
       end
 
@@ -123,7 +132,7 @@ module Hibiki
         return unless @__hibiki_actor
 
         Hibiki::Rails.registry.unregister(self)
-        @__hibiki_actor.post { @__hibiki_root.dispose }
+        @__hibiki_actor.post { instrument("unsubscribe") { @__hibiki_root.dispose } }
         @__hibiki_actor.stop
       end
 

data/lib/hibiki/rails/instrumentation.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    # The channel's ActiveSupport::Notifications events (`*.hibiki_rails`).
+    # Always on: with no subscriber `instrument` only yields. The gem
+    # subscribes to none of them. A subscriber runs on the graph thread, so
+    # it holds up that graph for as long as it takes.
+    #
+    # All private — a public helper would become a client-invocable action
+    # (see the NOTE on Hibiki::Rails::Channel).
+    module Instrumentation
+      # The most trips one action may report, and the longest time one may
+      # claim, in ms. The figures come from a browser, so they are bounded
+      # rather than believed.
+      TRIP_LIMIT = 5
+      TRIP_RANGE = (0..60_000)
+
+      EVENTS = %w[subscribe unsubscribe action render trip].to_h { [it, "#{it}.hibiki_rails"] }.freeze
+
+      private
+
+      # With nobody listening this is one lookup and a yield; no payload is
+      # built.
+      def instrument(event, payload = nil, &)
+        return (yield({}) if block_given?) unless listening?(event)
+
+        ActiveSupport::Notifications.instrument(EVENTS.fetch(event), { channel: self.class.name, **payload }, &)
+      end
+
+      # `asked` is the clock as the cable thread posted the action; `wait` is
+      # how long the graph thread took to reach it, in ms. An action the
+      # channel does not have gets no event: the name is the client's, and a
+      # subscriber that stores it must not be handed arbitrary strings.
+      def instrument_action(data, asked)
+        action = data["action"].to_s
+        return yield unless listening?("action") && self.class.action_methods.include?(action)
+
+        before = @__hibiki_render_count.to_i
+        instrument("action", { action:, wait: ms_since(asked) }) do |payload|
+          yield
+        ensure
+          payload[:renders] = @__hibiki_render_count.to_i - before
+        end
+      end
+
+      def listening?(event) = ActiveSupport::Notifications.notifier.listening?(EVENTS.fetch(event))
+
+      def ms_since(clock) = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - clock) * 1000
+
+      def instrument_render(method:, target: nil, &)
+        @__hibiki_render_count = @__hibiki_render_count.to_i + 1
+        instrument("render", { target:, method: }.compact, &)
+      end
+
+      # The trips a browser reported under `hbt`, as event payloads. Each is
+      # `[action, ack, paint]`: ms to the ack, and ms to the first render, or
+      # nil when nothing rendered.
+      def trips_from(reported)
+        reported.is_a?(Array) ? reported.first(TRIP_LIMIT).filter_map { trip(*it) } : []
+      end
+
+      def trip(action = nil, ack = nil, paint = nil, *)
+        return unless action.is_a?(String) && self.class.action_methods.include?(action)
+        return unless ack.is_a?(Numeric) && (paint.nil? || paint.is_a?(Numeric))
+
+        { action:, ack: ack.clamp(TRIP_RANGE), paint: paint&.clamp(TRIP_RANGE) }
+      end
+    end
+  end
+end

data/lib/hibiki/rails/registry.rb

@@ -28,6 +28,13 @@ module Hibiki
         @lock.synchronize { @channels.size }
       end
 
+      # The live subscriptions by channel class name. Count from this rather
+      # than from subscribe and unsubscribe events: a development reload
+      # drops sockets without running `unsubscribed`.
+      def tally
+        @lock.synchronize { @channels.map { it.class.name }.tally }
+      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

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.17.2"
+    VERSION = "0.18.0"
   end
 end

data/lib/hibiki/rails.rb

@@ -68,6 +68,7 @@ require_relative "rails/version"
 require_relative "rails/registry"
 require_relative "rails/graph_actor"
 require_relative "rails/debounce"
+require_relative "rails/instrumentation"
 require_relative "rails/broadcasts"
 require_relative "rails/channel"
 require_relative "rails/nested_actions"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.17.2
+  version: 0.18.0
 platform: ruby
 authors:
 - planetaska
@@ -187,6 +187,7 @@ files:
 - lib/hibiki/rails/engine.rb
 - lib/hibiki/rails/graph_actor.rb
 - lib/hibiki/rails/helpers.rb
+- lib/hibiki/rails/instrumentation.rb
 - lib/hibiki/rails/keys.rb
 - lib/hibiki/rails/nested_actions.rb
 - lib/hibiki/rails/reactive_form.rb