ruby_zmq_framework 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f85c8cb84cb6cfb2fc84e4c03d5fd0e3f00fbf0627a814cab9edbb4a3ca82434
-  data.tar.gz: 02dcec88c184e898f094a292ba3309f3a7a8dc3d477335b7314654681e681d59
+  metadata.gz: 5463eeb0f6933758bd516406c8fc45dd1d366089337244760247a87376639174
+  data.tar.gz: 90ebc27c4e1635883fc246a3d188ba5cf7c67233a9dc5e219b964cc1e240ff1d
 SHA512:
-  metadata.gz: f3e2d7ece26853813dccd26d68d9924ab8028cc65d69610827690b9741c67f4910097c137523d3b3bd47cc31eb0cc5f4ef0b83ddf73ac736e2bfcb11585cb6f6
-  data.tar.gz: 1f4c6eb92e5d93ba39e07e2863f25fd1e1f6843aac60a317836bb517e7b731b8dd219b38e54f7529113dc2712366c67aa9e09d0eaea0e0aa95375ba7eac6d1df
+  metadata.gz: a927b2df81d865d478db868c47dccb12674cf775d7211f02d4d2068b0c52fc979a4cb170b87906a2b988091df27bdc8ca7201a203b737346e2ceb529eab748bb
+  data.tar.gz: 4a030f0e3bb7715ec8d42de84e14e8a6fe1be1a2148dd3ec0831d6bde0bcdede4a0530306a133b44f9ab4de7138bc39d24d9b00bc616ba7daec00153abbb84d8

data/CHANGELOG.md

@@ -49,6 +49,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - ZeroMQ return codes are checked; failures raise
   `RubyZmqFramework::Error` instead of passing silently.
 
+## [0.1.1] - 2026-07-24
+
+### Fixed
+- `bin/flowctl` is now actually packaged with the gem (registered as the
+  `flowctl` executable) instead of only existing in the git checkout —
+  previously a project that merely depended on the gem had no way to run
+  the Quick Start despite the README instructing `bundle exec bin/flowctl`.
+  `PROTOCOL.md` is shipped alongside it for the same reason.
+- `bin/flowctl` resolved its nodes' working directory from its own
+  install location (`__dir__`) rather than the manifest it was given, so
+  a `flow.yml` outside this repo would spawn nodes that couldn't find
+  their own relative `cmd` paths. It now `chdir`s to the manifest's
+  directory.
+
 ## [0.1.0] - 2026-07-21
 
 - Initial version: `ZeroMQBus`, `StrictContract`, `FrameworkModule`

data/PROTOCOL.md

@@ -0,0 +1,93 @@
+# Bus Protocol
+
+This one page is the entire contract. A node written in any language that
+follows it is a full citizen of the flow — no framework code required.
+It is deliberately small enough to paste into an LLM prompt as the
+complete context for writing a new node.
+
+## Transport
+
+ZeroMQ PUB/SUB over TCP. Every node owns exactly one PUB socket (bound to
+its own port, where it publishes everything) and one SUB socket
+(connected to each peer's PUB port, subscribed to `""` — all topics —
+with filtering done after receipt).
+
+## Wire format
+
+Every message is a two-frame ZeroMQ multipart message:
+
+| frame | content                                    |
+|-------|--------------------------------------------|
+| 0     | topic — UTF-8 string, `lower_snake_case`   |
+| 1     | payload — a JSON **object** (`{...}`), UTF-8 |
+
+Anything else (single frames, non-JSON payloads) is dropped by
+well-behaved receivers with a warning. Never crash on a bad message.
+
+## Process environment (set by the launcher)
+
+A node learns its wiring from four environment variables and must not
+hardcode any topology:
+
+| variable         | meaning                                            | example                         |
+|------------------|----------------------------------------------------|---------------------------------|
+| `BUS_PORT`       | port to bind the PUB socket on (`0`/unset = any)   | `5555`                          |
+| `BUS_PEERS`      | comma-separated `host:port` list to connect SUB to | `127.0.0.1:5556,127.0.0.1:5557` |
+| `BUS_SUBSCRIBES` | comma-separated topics this node should act on     | `engine_data,heartbeat`         |
+| `NODE_NAME`      | this node's identity, used in heartbeats           | `ecu`                           |
+
+Unset variables mean: bind any free port, no peers, no subscriptions —
+the node must still start (standalone mode).
+
+## Heartbeat
+
+Every node publishes on topic `heartbeat` every **5 seconds**:
+
+```json
+{ "node_name": "<NODE_NAME>", "status": "ok", "timestamp": 1784796766 }
+```
+
+`timestamp` is Unix seconds. A node that stops heartbeating is presumed
+dead; there is no other liveness mechanism.
+
+## Conventions
+
+- Payloads are always JSON objects, never bare arrays/scalars.
+- Delivery is fire-and-forget: no acks, no replay. A slow consumer loses
+  old messages (ZeroMQ drops at the high-water mark). Design for
+  latest-value-wins.
+- PUB/SUB connections take ~a few hundred ms to establish ("slow
+  joiner"): wait ~1s after startup before your first meaningful publish,
+  or design so early messages are harmless to lose.
+- Request/response is done with a topic pair by convention, e.g. publish
+  `request_global_state` → someone publishes `global_state_snapshot`.
+
+## Minimal node, any language (Python shown)
+
+```python
+import json, os, time, threading, zmq
+
+ctx = zmq.Context()
+pub = ctx.socket(zmq.PUB); pub.bind(f"tcp://127.0.0.1:{os.environ.get('BUS_PORT', '*')}")
+sub = ctx.socket(zmq.SUB); sub.setsockopt_string(zmq.SUBSCRIBE, "")
+for peer in filter(None, os.environ.get("BUS_PEERS", "").split(",")):
+    sub.connect(f"tcp://{peer}")
+
+name = os.environ.get("NODE_NAME", "python-node")
+topics = set(filter(None, os.environ.get("BUS_SUBSCRIBES", "").split(",")))
+
+def heartbeat():
+    while True:
+        pub.send_multipart([b"heartbeat", json.dumps(
+            {"node_name": name, "status": "ok", "timestamp": int(time.time())}).encode()])
+        time.sleep(5)
+threading.Thread(target=heartbeat, daemon=True).start()
+
+while True:
+    topic, payload = sub.recv_multipart()
+    if topic.decode() in topics:
+        handle(topic.decode(), json.loads(payload))  # your logic here
+```
+
+Add the node to `flow.yml` with its `cmd`, `publishes`, and `subscribes`,
+and `bin/flowctl` wires it in.

data/bin/flowctl

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# Runs a flow manifest: assigns each node a free port, computes the peer
+# wiring, spawns every node with that wiring in its environment, and
+# streams their output with a [name] prefix. Ctrl-C stops everything.
+#
+#   bundle exec bin/flowctl              # runs ./flow.yml
+#   bundle exec bin/flowctl other.yml
+#   bundle exec bin/flowctl --plan       # print computed wiring, run nothing
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'ruby_zmq_framework'
+require 'socket'
+require 'optparse'
+
+plan_only = false
+OptionParser.new do |opts|
+  opts.banner = 'Usage: bin/flowctl [--plan] [flow.yml]'
+  opts.on('--plan', 'Print the computed wiring and exit') { plan_only = true }
+end.parse!
+
+manifest = ARGV.first || 'flow.yml'
+manifest_path = File.expand_path(manifest, Dir.pwd)
+root = File.dirname(manifest_path)
+flow = RubyZmqFramework::Flow.load(manifest_path)
+
+def free_port
+  server = TCPServer.new('127.0.0.1', 0)
+  port = server.addr[1]
+  server.close
+  port
+end
+
+ports = flow.nodes.to_h { |node| [node.name, free_port] }
+wiring = flow.wiring(ports)
+
+if plan_only
+  wiring.each do |name, env|
+    puts name
+    env.each { |k, v| puts "  #{k}=#{v}" }
+  end
+  exit
+end
+
+children = {}
+flow.nodes.each do |node|
+  reader, writer = IO.pipe
+  pid = spawn(wiring[node.name], node.cmd, out: writer, err: writer, chdir: root)
+  writer.close
+  children[pid] = node.name
+
+  Thread.new do
+    reader.each_line { |line| puts "[#{node.name}] #{line}" }
+  end
+end
+
+puts "[flowctl] started #{children.size} nodes: #{children.values.join(', ')}"
+
+begin
+  until children.empty?
+    pid = Process.wait
+    puts "[flowctl] #{children.delete(pid)} exited with status #{$?.exitstatus.inspect}"
+  end
+  puts '[flowctl] all nodes exited'
+rescue Interrupt
+  puts "\n[flowctl] shutting down #{children.size} nodes"
+  children.each_key do |pid|
+    Process.kill('TERM', pid)
+  rescue Errno::ESRCH
+    nil
+  end
+  children.each_key do |pid|
+    Process.wait(pid)
+  rescue Errno::ECHILD
+    nil
+  end
+end

data/lib/ruby_zmq_framework/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_zmq_framework
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Paul Daniel
@@ -58,13 +58,16 @@ description: 'Blackbox node processes wired together by pub/sub topics: the grap
   transport with strict runtime module contracts.'
 email:
 - paulgdan@gmail.com
-executables: []
+executables:
+- flowctl
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.txt
+- PROTOCOL.md
 - README.md
+- bin/flowctl
 - lib/ruby_zmq_framework.rb
 - lib/ruby_zmq_framework/can_bridge.rb
 - lib/ruby_zmq_framework/flow.rb