ruby_zmq_framework 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f85c8cb84cb6cfb2fc84e4c03d5fd0e3f00fbf0627a814cab9edbb4a3ca82434
+  data.tar.gz: 02dcec88c184e898f094a292ba3309f3a7a8dc3d477335b7314654681e681d59
+SHA512:
+  metadata.gz: f3e2d7ece26853813dccd26d68d9924ab8028cc65d69610827690b9741c67f4910097c137523d3b3bd47cc31eb0cc5f4ef0b83ddf73ac736e2bfcb11585cb6f6
+  data.tar.gz: 1f4c6eb92e5d93ba39e07e2863f25fd1e1f6843aac60a317836bb517e7b731b8dd219b38e54f7529113dc2712366c67aa9e09d0eaea0e0aa95375ba7eac6d1df

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Changed
+- The repo is now a reference implementation of a flow-based,
+  language-agnostic node runtime ("Node-RED without the UI"): the graph
+  lives in `flow.yml`, `bin/flowctl` computes wiring and runs it, nodes
+  are blackbox processes configured entirely from the environment, and
+  `PROTOCOL.md` is the one-page contract for joining from any language.
+  `examples/` (hand-wired scripts) became `nodes/` (env-wired processes).
+
+### Added (flow runtime)
+- `RubyZmqFramework.boot`: builds a node from `BUS_PORT`, `BUS_PEERS`,
+  `BUS_SUBSCRIBES`, and `NODE_NAME`; standalone-friendly when unset.
+- `RubyZmqFramework::Flow`: parses the manifest and computes each node's
+  peer wiring from topic publishers/subscribers.
+- `bin/flowctl` (with `--plan`): port assignment, spawning, prefixed
+  output streaming, Ctrl-C teardown.
+- `PROTOCOL.md`: transport, wire format, env contract, heartbeat schema,
+  and a minimal Python node.
+
+### Fixed
+- The `ZeroMQBus` listener thread no longer dies silently on malformed
+  JSON, non-two-frame messages, or exceptions raised inside a
+  subscriber's `handle_message` — one bad message previously left the
+  node permanently deaf while its heartbeat kept reporting "ok".
+- Unknown topics arriving off the wire no longer grow the subscriber map
+  without bound, and topic strings from the network are no longer
+  interned into symbols unless someone subscribed to them.
+- The `StrictContract` check now runs before construction, so a class
+  missing a required method can no longer leak a live heartbeat thread
+  from a failed `.new`. The contract also applies to subclasses.
+
+### Added
+- Local dispatch: messages published on a bus now reach subscribers on
+  that same bus, with the same symbolized-key payload representation as
+  wire delivery.
+- Clean shutdown: `ZeroMQBus#close`, `FrameworkModule#stop_heartbeat`,
+  and `CanBridge#close`.
+- Configurable endpoints: `bind_host:` keyword, peers as `"host:port"`
+  or full ZeroMQ endpoints, and `my_port = 0` for an OS-assigned
+  ephemeral port (readable via `ZeroMQBus#port`).
+- `FrameworkModule#node_name`: set `@node_name` to give each node a
+  distinct heartbeat identity.
+- ZeroMQ return codes are checked; failures raise
+  `RubyZmqFramework::Error` instead of passing silently.
+
+## [0.1.0] - 2026-07-21
+
+- Initial version: `ZeroMQBus`, `StrictContract`, `FrameworkModule`
+  auto-heartbeat, `StateRegistry`, `CanBridge`, examples, tests.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Daniel
+
+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.

data/README.md

@@ -0,0 +1,130 @@
+# ruby_zmq_framework
+
+**Think Node-RED without the UI: a flow-based, language-agnostic runtime for
+blackbox nodes wired together by topics.**
+
+- **Nodes** are independent OS processes. Each one does one job, lives in one
+  file, and knows nothing about any other node — not their ports, not their
+  names, not their language.
+- **Wires** are pub/sub topics carrying JSON, over ZeroMQ.
+- **The graph is data**: [`flow.yml`](flow.yml) is the only artifact that
+  knows the topology. `bin/flowctl` reads it, computes the wiring, and runs
+  everything.
+- **The contract is one page**: [`PROTOCOL.md`](PROTOCOL.md) is everything a
+  node in any language needs to join.
+
+The design goal is LLM-friendliness: each node is a task you can hand to an
+agent with the protocol page and a one-line description ("write a Go node
+that decodes DBC frames") — it never needs the rest of the repo in context.
+
+## Quick start
+
+You need the ZeroMQ library (`libzmq3-dev` on Debian/Ubuntu, `brew install
+zeromq` on macOS), then:
+
+```bash
+bundle install
+bundle exec bin/flowctl
+```
+
+That runs the demo graph from `flow.yml`: a simulated ECU blasting RPM data,
+a telemetry node that commands a throttle cut on over-rev, a web dashboard
+on <http://localhost:4567>, a state registry caching heartbeats and
+telemetry, and a dashboard consumer syncing the registry's snapshot. Output
+is streamed with a `[node_name]` prefix; Ctrl-C stops everything.
+
+`bundle exec bin/flowctl --plan` prints the computed wiring without running
+anything.
+
+## Writing a node
+
+A Ruby node is a class with one method, booted from the environment:
+
+```ruby
+require_relative '../lib/ruby_zmq_framework'
+$stdout.sync = true
+
+class RpmSmoother
+  include RubyZmqFramework::FrameworkModule
+
+  def initialize(bus)
+    @bus = bus
+    @window = []
+  end
+
+  def handle_message(topic, payload)
+    @window = (@window << payload[:rpm]).last(5)
+    broadcast(:engine_data_smooth, { rpm: @window.sum / @window.size })
+  end
+end
+
+RubyZmqFramework.boot(RpmSmoother)
+sleep
+```
+
+Note what's absent: no ports, no peers, no subscribe calls. Wiring comes
+from environment variables (`BUS_PORT`, `BUS_PEERS`, `BUS_SUBSCRIBES`,
+`NODE_NAME` — see `PROTOCOL.md`), which `flowctl` computes from the node's
+entry in the manifest:
+
+```yaml
+  rpm_smoother:
+    cmd: ruby nodes/rpm_smoother.rb
+    subscribes: [engine_data]
+    publishes: [engine_data_smooth]
+```
+
+Run standalone (no environment needed — it binds an ephemeral port) to poke
+at a node in isolation: `bundle exec ruby nodes/rpm_smoother.rb`.
+
+Every node automatically heartbeats every 5 seconds. `StrictContract`
+raises at `.new` if a node forgets `handle_message` — loudly and
+immediately, which is exactly the feedback an iterating agent needs.
+
+## Nodes in other languages
+
+The bus is just two-frame ZeroMQ pub/sub — `[topic, json]` — and the whole
+contract fits on one page: [`PROTOCOL.md`](PROTOCOL.md), including a
+complete minimal Python node. Follow it, add a `cmd` entry to `flow.yml`,
+and the language never matters again. A Python companion library exists at
+[python_zmq_framework](https://github.com/pgdaniel/python_zmq_framework),
+with the same `boot()`-from-environment contract, `node_name`, and clean
+shutdown as this gem — a Python node under its `nodes/` and a Ruby node
+under this repo's `nodes/` are interchangeable entries in one `flow.yml`.
+
+## What's in the box
+
+| piece | file | job |
+|-------|------|-----|
+| `ZeroMQBus` | `lib/ruby_zmq_framework/zeromq_bus.rb` | hardened transport: poison-message-proof listener, per-handler error isolation, local dispatch, clean `close` |
+| `FrameworkModule` | `lib/ruby_zmq_framework/framework.rb` | node mixin: contract enforcement, auto-heartbeat, `broadcast`, `node_name`, `stop_heartbeat` |
+| `Flow` | `lib/ruby_zmq_framework/flow.rb` | parses `flow.yml`, computes each node's env wiring |
+| `flowctl` | `bin/flowctl` | assigns ports, spawns nodes, prefixes output, tears down |
+| `StateRegistry` | `lib/ruby_zmq_framework/state_registry.rb` | passive cluster-state cache; replays snapshots on request |
+| `CanBridge` | `lib/ruby_zmq_framework/can_bridge.rb` | real SocketCAN frames → `can_frame` topic (classic CAN, via raw ioctls, no extra gem) |
+| demo nodes | `nodes/*.rb` | one blackbox process per file |
+
+Delivery is fire-and-forget (latest-value-wins; slow consumers drop old
+messages), handlers on one bus never run concurrently, and a bad message or
+a raising handler can never kill a node's listener. See `CHANGELOG.md` for
+the full hardening history.
+
+> **Note:** ZeroMQ is reached through
+> [`ffi-rzmq`](https://github.com/chuckremes/ffi-rzmq), which is stable but
+> hasn't seen a release in years. The wire format is deliberately plain
+> two-frame PUB/SUB, so swapping bindings — or the transport itself — stays
+> a contained change behind the three-method bus interface
+> (`publish`/`subscribe`/`close`).
+
+## CAN hardware
+
+Uncomment the `can_bridge` node in `flow.yml` (set `CAN_IFACE`, e.g.
+`vcan0`) to relay real SocketCAN frames onto the bus as `can_frame`
+messages. Needs an actual or virtual CAN interface; fails fast with the
+underlying `Errno` if it doesn't exist.
+
+## Tests
+
+```bash
+bundle exec rake test
+```

data/lib/ruby_zmq_framework/can_bridge.rb

@@ -0,0 +1,92 @@
+require 'socket'
+
+module RubyZmqFramework
+  # Reads raw frames off a real SocketCAN interface (can0, vcan0, ...) and
+  # rebroadcasts each one onto the ZeroMQ bus. Pure producer: it has no
+  # interest in bus traffic, so handle_message is a no-op that only exists
+  # to satisfy FrameworkModule's contract.
+  #
+  # Talks to the kernel directly via Ruby's built-in Socket + a couple of
+  # raw ioctl/struct calls (see linux/can.h, linux/sockios.h) rather than
+  # a third-party gem, since no maintained "socketcan" gem is published on
+  # RubyGems.
+  #
+  # Classic CAN only: reads assume the 16-byte struct can_frame. That is
+  # safe even on an FD-enabled interface — the kernel only delivers
+  # 72-byte canfd_frames to sockets that opt in via CAN_RAW_FD_FRAMES,
+  # which this one never does — but it means FD traffic is invisible here.
+  class CanBridge
+    include FrameworkModule
+
+    CAN_RAW       = 1
+    SIOCGIFINDEX  = 0x8933
+    FRAME_SIZE    = 16 # sizeof(struct can_frame): 4(id) + 1(len) + 3(pad) + 8(data)
+    CAN_EFF_FLAG  = 0x80000000
+    CAN_EFF_MASK  = 0x1FFFFFFF
+    CAN_SFF_MASK  = 0x7FF
+
+    def self.parse_frame(raw)
+      id_raw, len = raw.unpack('L< C')
+      extended = (id_raw & CAN_EFF_FLAG) != 0
+      can_id = id_raw & (extended ? CAN_EFF_MASK : CAN_SFF_MASK)
+
+      { id: can_id, extended: extended, dlc: len, data: raw[8, len].bytes }
+    end
+
+    def initialize(bus, interface:, topic: :can_frame)
+      @bus = bus
+      @topic = topic
+      @socket = open_can_socket(interface)
+      @running = true
+      start_reader
+    end
+
+    def handle_message(topic, payload); end
+
+    # Stops the whole node: heartbeat, reader thread, CAN socket. Closing
+    # the socket from here is what interrupts the reader's blocking read.
+    def close
+      return unless @running
+
+      @running = false
+      stop_heartbeat
+      @socket.close unless @socket.closed?
+      @reader.join(2)
+      nil
+    end
+
+    private
+
+    def open_can_socket(interface)
+      socket = Socket.new(Socket::PF_CAN, Socket::SOCK_RAW, CAN_RAW)
+      socket.bind(sockaddr_can(interface_index(socket, interface)))
+      socket
+    end
+
+    def interface_index(socket, interface)
+      ifreq = [interface].pack('a16') + ("\0" * 24)
+      socket.ioctl(SIOCGIFINDEX, ifreq)
+      ifreq[16, 4].unpack1('l')
+    end
+
+    def sockaddr_can(ifindex)
+      [Socket::AF_CAN, 0, ifindex].pack('S S l') + ("\0" * 8)
+    end
+
+    def start_reader
+      @reader = Thread.new do
+        while @running
+          begin
+            raw = @socket.read(FRAME_SIZE)
+            broadcast(@topic, self.class.parse_frame(raw)) if raw&.bytesize == FRAME_SIZE
+          rescue StandardError => e
+            break unless @running # close interrupted the blocking read
+
+            warn "[Framework Error] CanBridge read failed: #{e.message}"
+            sleep 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_zmq_framework/flow.rb

@@ -0,0 +1,85 @@
+require 'yaml'
+
+module RubyZmqFramework
+  # Parses a flow manifest (flow.yml) — the graph as data, Node-RED style.
+  # The manifest is the ONLY place that knows the topology; node processes
+  # learn their wiring from the environment variables computed here, and a
+  # node's code never mentions another node.
+  #
+  #   nodes:
+  #     ecu:
+  #       cmd: ruby nodes/ecu.rb
+  #       publishes: [engine_data]
+  #       subscribes: [throttle_request]
+  #       env: { SOME_KNOB: "42" }   # optional, merged into the process env
+  class Flow
+    Node = Struct.new(:name, :cmd, :publishes, :subscribes, :env, keyword_init: true)
+
+    attr_reader :nodes
+
+    def self.load(path)
+      new(YAML.safe_load(File.read(path)))
+    end
+
+    def initialize(spec)
+      unless spec.is_a?(Hash) && spec['nodes'].is_a?(Hash)
+        raise Error, '[Framework Error] Flow manifest needs a top-level "nodes" map'
+      end
+
+      @nodes = spec['nodes'].map do |name, cfg|
+        cfg ||= {}
+        raise Error, "[Framework Error] Flow node #{name} needs a cmd" unless cfg['cmd']
+
+        Node.new(
+          name: name.to_s,
+          cmd: cfg['cmd'],
+          publishes: Array(cfg['publishes']).map(&:to_s),
+          subscribes: Array(cfg['subscribes']).map(&:to_s),
+          env: (cfg['env'] || {}).transform_values(&:to_s)
+        )
+      end
+      warn_about_deaf_subscriptions
+    end
+
+    # The environment for every node process, given a {name => port} map.
+    # This is the whole trick that keeps nodes blackboxes: each node's peer
+    # list is computed from who publishes the topics it subscribes to.
+    def wiring(ports)
+      @nodes.to_h do |node|
+        peers = peer_names(node).map { |name| "127.0.0.1:#{ports.fetch(name)}" }
+        [node.name, {
+          'BUS_PORT' => ports.fetch(node.name).to_s,
+          'BUS_PEERS' => peers.join(','),
+          'BUS_SUBSCRIBES' => node.subscribes.join(','),
+          'NODE_NAME' => node.name
+        }.merge(node.env)]
+      end
+    end
+
+    private
+
+    # Every FrameworkModule node broadcasts :heartbeat implicitly, so for
+    # that topic everyone counts as a publisher. A node never peers with
+    # itself — the bus already delivers its own publishes locally.
+    def peer_names(node)
+      node.subscribes
+          .flat_map { |topic| publisher_names(topic) }
+          .uniq - [node.name]
+    end
+
+    def publisher_names(topic)
+      return @nodes.map(&:name) if topic == 'heartbeat'
+
+      @nodes.select { |n| n.publishes.include?(topic) }.map(&:name)
+    end
+
+    def warn_about_deaf_subscriptions
+      published = @nodes.flat_map(&:publishes).uniq + ['heartbeat']
+      @nodes.each do |node|
+        (node.subscribes - published).each do |topic|
+          warn "[Framework Warning] #{node.name} subscribes to #{topic.inspect} but no node in the flow publishes it"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_zmq_framework/framework.rb

@@ -0,0 +1,109 @@
+module RubyZmqFramework
+  module StrictContract
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def requires_methods(*methods)
+        @required_methods = methods
+      end
+
+      def required_methods
+        inherited = superclass.respond_to?(:required_methods) ? superclass.required_methods : []
+        inherited | (@required_methods || [])
+      end
+
+      # The check runs BEFORE super (i.e. before allocate/initialize), so a
+      # violating class never gets partially constructed. This matters for
+      # FrameworkModule: its prepended Heartbeat starts a broadcasting thread
+      # inside initialize, and checking afterwards would leak that thread
+      # from a zombie instance whose .new appeared to fail.
+      def new(...)
+        missing = required_methods.reject do |m|
+          method_defined?(m) || private_method_defined?(m)
+        end
+        if missing.any?
+          raise NotImplementedError,
+                "[Framework Error] Contract Violation: #{self} missing #{missing.join(', ')}"
+        end
+        super
+      end
+    end
+  end
+
+  module FrameworkModule
+    HEARTBEAT_INTERVAL = 5 # seconds
+
+    def self.included(base)
+      base.include(StrictContract)
+      base.requires_methods(:handle_message)
+      base.prepend(Heartbeat)
+    end
+
+    # Prepended so it wraps whatever initialize the concrete module defines,
+    # starting the heartbeat only once @bus has actually been assigned.
+    module Heartbeat
+      def initialize(...)
+        super
+        start_heartbeat
+      end
+    end
+
+    def broadcast(topic, payload = {})
+      @bus.publish(topic, payload)
+    end
+
+    # Identity used in heartbeats. Precedence: @node_name set by the node
+    # itself, then NODE_NAME from the environment (how bin/flowctl names
+    # the processes it spawns), then the class name. Distinct names matter
+    # when several instances of one class run — otherwise they overwrite
+    # each other in any StateRegistry's active_nodes.
+    def node_name
+      @node_name || ENV['NODE_NAME'] || self.class.name || 'AnonymousNode'
+    end
+
+    # Gracefully stops the heartbeat thread. Call this before closing the
+    # bus the node broadcasts on. Wakes the thread out of its interval wait
+    # rather than killing it, so an in-flight broadcast always completes.
+    def stop_heartbeat
+      thread = @heartbeat_thread
+      return unless thread
+
+      @heartbeat_mutex.synchronize do
+        @heartbeat_running = false
+        @heartbeat_wakeup.signal
+      end
+      thread.join(HEARTBEAT_INTERVAL + 1)
+      @heartbeat_thread = nil
+    end
+
+    private
+
+    def start_heartbeat
+      @heartbeat_mutex = Mutex.new
+      @heartbeat_wakeup = ConditionVariable.new
+      @heartbeat_running = true
+
+      @heartbeat_thread = Thread.new do
+        loop do
+          begin
+            broadcast(:heartbeat, {
+              node_name: node_name,
+              status: "ok",
+              timestamp: Time.now.to_i
+            })
+          rescue StandardError => e
+            warn "[Framework Error] Heartbeat failed for #{node_name}: #{e.message}"
+          end
+
+          keep_going = @heartbeat_mutex.synchronize do
+            @heartbeat_wakeup.wait(@heartbeat_mutex, HEARTBEAT_INTERVAL) if @heartbeat_running
+            @heartbeat_running
+          end
+          break unless keep_going
+        end
+      end
+    end
+  end
+end

data/lib/ruby_zmq_framework/state_registry.rb

@@ -0,0 +1,31 @@
+module RubyZmqFramework
+  # A passive, in-memory cache of cluster-wide state. It listens to
+  # heartbeats and telemetry broadcast by other FrameworkModule nodes and,
+  # on request, replays its current snapshot back onto the bus. It never
+  # makes a blocking call and never crashes when a peer goes quiet — a
+  # silent node simply stops getting its active_nodes timestamp updated.
+  class StateRegistry
+    include FrameworkModule
+
+    attr_reader :store
+
+    def initialize(bus)
+      @bus = bus
+      @store = { active_nodes: {}, telemetry: {} }
+    end
+
+    def handle_message(topic, payload)
+      case topic
+      when :heartbeat
+        @store[:active_nodes][payload[:node_name]] = {
+          status: payload[:status],
+          timestamp: payload[:timestamp]
+        }
+      when :request_global_state
+        broadcast(:global_state_snapshot, @store)
+      else
+        @store[:telemetry][topic] = payload
+      end
+    end
+  end
+end

data/lib/ruby_zmq_framework/version.rb

@@ -0,0 +1,3 @@
+module RubyZmqFramework
+  VERSION = "0.1.0"
+end

data/lib/ruby_zmq_framework/zeromq_bus.rb

@@ -0,0 +1,167 @@
+require 'ffi-rzmq'
+require 'json'
+require 'monitor'
+
+module RubyZmqFramework
+  class ZeroMQBus
+    # How long the listener blocks in poll before looping, in milliseconds.
+    POLL_TIMEOUT_MS = 100
+
+    # The port actually bound — differs from my_port when my_port is 0.
+    attr_reader :port
+
+    # my_port may be 0 to bind an OS-assigned ephemeral port (read it back
+    # via #port). peer_ports entries may be Integers (loopback ports),
+    # "host:port" strings, or full ZeroMQ endpoints ("tcp://10.0.0.5:5555").
+    # Pass bind_host: "0.0.0.0" to accept peers from other machines.
+    def initialize(my_port, peer_ports = [], bind_host: '127.0.0.1')
+      @context = ZMQ::Context.new
+
+      # Publisher Socket
+      @pub = @context.socket(ZMQ::PUB)
+      bind_endpoint = "tcp://#{bind_host}:#{my_port.to_i.zero? ? '*' : my_port}"
+      check! @pub.bind(bind_endpoint), "bind to #{bind_endpoint}"
+      @port = bound_port
+
+      # Subscriber Socket
+      @sub = @context.socket(ZMQ::SUB)
+      peer_ports.each do |peer|
+        endpoint = peer_endpoint(peer)
+        check! @sub.connect(endpoint), "connect to #{endpoint}"
+      end
+      check! @sub.setsockopt(ZMQ::SUBSCRIBE, ''), 'subscribe'
+
+      # Keyed by topic *string*, with no default proc: the listener looks up
+      # every topic that arrives off the wire, and a defaulting hash would
+      # insert a permanent empty entry per unknown topic — an unbounded,
+      # network-driven leak. A Monitor guards it because subscribe runs on
+      # the caller's thread while dispatch runs on the listener thread.
+      @local_subscribers = {}
+      @subscribers_lock = Monitor.new
+      @running = true
+      start_listener
+    end
+
+    # Stops the listener thread and releases both sockets and the context.
+    # Stop anything still publishing on this bus first (heartbeats, reader
+    # threads): publishing on a closed bus raises RubyZmqFramework::Error.
+    # Idempotent.
+    def close
+      return if @closed
+
+      @closed = true
+      @running = false
+      @listener.join(POLL_TIMEOUT_MS / 1000.0 + 1) unless Thread.current == @listener
+
+      [@sub, @pub].each do |sock|
+        sock.setsockopt(ZMQ::LINGER, 0)
+        sock.close
+      end
+      @context.terminate
+      nil
+    end
+
+    def subscribe(topic, module_instance)
+      @subscribers_lock.synchronize do
+        (@local_subscribers[topic.to_s] ||= []) << module_instance
+      end
+    end
+
+    def publish(topic, payload = {})
+      json = payload.to_json
+      check! @pub.send_strings([topic.to_s, json]), "publish #{topic}"
+
+      # A SUB socket never connects back to its own PUB, so without this,
+      # two modules sharing one bus in the same process could not hear each
+      # other. Delivering the serialized form keeps the payload
+      # representation identical whether a message arrived locally or over
+      # the wire (string keys become symbols either way).
+      dispatch(topic.to_s, json)
+    end
+
+    private
+
+    def check!(rc, action)
+      return if ZMQ::Util.resultcode_ok?(rc)
+
+      raise Error, "[Framework Error] ZeroMQ #{action} failed: #{ZMQ::Util.error_string}"
+    end
+
+    def bound_port
+      endpoint = []
+      check! @pub.getsockopt(ZMQ::LAST_ENDPOINT, endpoint), 'read bound endpoint'
+      # ffi-rzmq returns the endpoint with a trailing NUL, e.g. "tcp://127.0.0.1:5555\0"
+      endpoint.first.delete("\0").rpartition(':').last.to_i
+    end
+
+    def peer_endpoint(peer)
+      case peer
+      when Integer then "tcp://127.0.0.1:#{peer}"
+      when %r{\A[a-z]+://} then peer # already a full ZeroMQ endpoint
+      else "tcp://#{peer}"           # "host:port"
+      end
+    end
+
+    def start_listener
+      @listener = Thread.new do
+        poller = ZMQ::Poller.new
+        poller.register_readable(@sub)
+
+        while @running
+          ready = poller.poll(POLL_TIMEOUT_MS)
+          if ready == -1
+            break unless @running
+
+            warn "[Framework Error] Listener poll failed: #{ZMQ::Util.error_string}"
+            sleep 0.1
+            next
+          end
+          next if ready.zero?
+
+          messages = []
+          unless ZMQ::Util.resultcode_ok?(@sub.recv_strings(messages))
+            warn "[Framework Error] Listener receive failed: #{ZMQ::Util.error_string}"
+            next
+          end
+
+          topic, json = messages
+          # Drop anything that doesn't match the two-frame [topic, json] wire format.
+          next if topic.nil? || json.nil?
+
+          dispatch(topic, json)
+        end
+      end
+    end
+
+    # A bad payload or a raising subscriber must never kill the listener
+    # thread: one poisoned message would otherwise leave the node deaf for
+    # good while its heartbeat keeps reporting "ok".
+    # Runs entirely inside the Monitor, which is reentrant: dispatch happens
+    # on the listener thread AND on whichever thread called publish, and
+    # serializing them guarantees a subscriber's handle_message is never
+    # executed concurrently — while a handler that publishes from within
+    # handle_message simply re-enters the lock it already holds.
+    def dispatch(topic_str, json)
+      @subscribers_lock.synchronize do
+        subscribers = @local_subscribers[topic_str]
+        return if subscribers.nil? || subscribers.empty?
+
+        begin
+          payload = JSON.parse(json, symbolize_names: true)
+        rescue JSON::ParserError => e
+          warn "[Framework Error] Dropping malformed payload on #{topic_str}: #{e.message}"
+          return
+        end
+
+        topic = topic_str.to_sym
+        # Dup so a handler that subscribes mid-dispatch can't mutate the
+        # list we're iterating.
+        subscribers.dup.each do |mod|
+          mod.handle_message(topic, payload)
+        rescue StandardError => e
+          warn "[Framework Error] #{mod.class} failed handling #{topic}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_zmq_framework.rb

@@ -0,0 +1,41 @@
+require_relative "ruby_zmq_framework/version"
+require_relative "ruby_zmq_framework/framework"
+require_relative "ruby_zmq_framework/zeromq_bus"
+require_relative "ruby_zmq_framework/state_registry"
+require_relative "ruby_zmq_framework/can_bridge"
+require_relative "ruby_zmq_framework/flow"
+
+module RubyZmqFramework
+  class Error < StandardError; end
+
+  # Boots a node the flow-runtime way: all bus wiring comes from
+  # environment variables (set by bin/flowctl, or by hand), so node code
+  # never contains ports, peer lists, or subscription calls — a node is
+  # just a class with handle_message plus whatever it broadcasts.
+  #
+  #   BUS_PORT        port to bind (default 0 = OS-assigned ephemeral)
+  #   BUS_PEERS       comma-separated peer endpoints ("127.0.0.1:5555,...")
+  #   BUS_SUBSCRIBES  comma-separated topics routed to node#handle_message
+  #   NODE_NAME       heartbeat identity (defaults to the class name)
+  #
+  # node_class must take the bus as its first constructor argument. With
+  # no environment set, the node still boots standalone on an ephemeral
+  # port — handy for poking at a single node in isolation.
+  def self.boot(node_class, *args, **kwargs)
+    bus = ZeroMQBus.new(ENV.fetch('BUS_PORT', '0').to_i, env_list('BUS_PEERS'))
+    node = node_class.new(bus, *args, **kwargs)
+    env_list('BUS_SUBSCRIBES').each { |topic| bus.subscribe(topic, node) }
+
+    # Booted nodes are processes managed by a supervisor (bin/flowctl) or a
+    # terminal: exit quietly on TERM/INT instead of dumping a backtrace
+    # from an interrupted sleep. Frameworks that install their own traps
+    # afterwards (e.g. Sinatra) simply override these.
+    %w[TERM INT].each { |sig| trap(sig) { exit } }
+    node
+  end
+
+  def self.env_list(key)
+    ENV.fetch(key, '').split(',').map(&:strip).reject(&:empty?)
+  end
+  private_class_method :env_list
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: ruby_zmq_framework
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paul Daniel
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi-rzmq
+  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'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'Blackbox node processes wired together by pub/sub topics: the graph
+  lives in a flow.yml manifest, nodes are configured entirely from the environment,
+  and a one-page protocol lets any language join the bus. Includes a hardened ZeroMQ
+  transport with strict runtime module contracts.'
+email:
+- paulgdan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ruby_zmq_framework.rb
+- lib/ruby_zmq_framework/can_bridge.rb
+- lib/ruby_zmq_framework/flow.rb
+- lib/ruby_zmq_framework/framework.rb
+- lib/ruby_zmq_framework/state_registry.rb
+- lib/ruby_zmq_framework/version.rb
+- lib/ruby_zmq_framework/zeromq_bus.rb
+homepage: https://github.com/pgdaniel/ruby_zmq_framework
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/pgdaniel/ruby_zmq_framework
+  changelog_uri: https://github.com/pgdaniel/ruby_zmq_framework/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Flow-based, language-agnostic node runtime over ZeroMQ — Node-RED without
+  the UI
+test_files: []