robot_lab-discovery 0.2.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 24e1bc6292612b2ea663e6263851de0dedff0d271e16e8f2d19880c6b434e0e4
+  data.tar.gz: 7980129dba8853c6f5ce97f0792362a5d64aad6685e23a2b650cb98d35334bf6
+SHA512:
+  metadata.gz: d0055e91603ceae005545f8fe8707f33ddfb8f8031631b840b73befa6960d2cfa8bb8975d6733ea3380879f5230d87063ca62f6f4465bd8f93ba03258ad9b35f
+  data.tar.gz: d5a0eadd8e1ae6285654468f6a3be30e5903fce881799295e3fcf199e99670339d1a64430ebd2c4140bfebdd03422465cedc3e425e35aaa0ad847b5d4326fdfb

data/.envrc

@@ -0,0 +1 @@
+export RR=`pwd`

data/.github/workflows/deploy-github-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-github-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs
+          pip install mkdocs-material
+          pip install mkdocs-macros-plugin
+          pip install mike
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

data/.loki

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# robot_lab-discovery — zeroconf/mDNS service discovery.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-discovery".freeze
+
+  header "robot_lab-discovery v#{gem_version} — service discovery"
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1,2 @@
+1	lib/robot_lab/discovery/browser.rb
+1	lib/robot_lab/discovery/txt_record.rb

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-28
+
+### Added
+
+- `RobotLab::Discovery::Advertiser` — registers a robot as a `_robot-lab._tcp.local.`
+  mDNS service in a background thread. Accepts a free-form `capabilities:` array;
+  each capability is encoded in the TXT record and registered as a DNS-SD subtype
+  (`_research._sub._robot-lab._tcp.local.` etc.) for targeted browsing.
+  Supports `start`, `stop`, and `started?`. Sends an mDNS goodbye packet (TTL=0)
+  on `stop` to remove the service from peers' caches immediately.
+- `RobotLab::Discovery::Browser` — browses `_robot-lab._tcp.local.` via
+  `ZeroConf.browse`, parses SRV and TXT records, and returns `Result` objects.
+  Provides:
+  - `browse(timeout:)` — all robots on the LAN
+  - `find(name, timeout:)` — single robot by instance name
+  - `find_by_capability(capability, timeout:)` — robots advertising a given
+    capability, browsed via the corresponding DNS-SD subtype
+  - `list_capabilities(timeout:)` — sorted, deduplicated list of all capability
+    terms currently advertised on the LAN
+- `RobotLab::Discovery::Result` — immutable `Data`-based value object with
+  `name`, `hostname`, `port`, `path`, `capabilities`, and a `url` helper method.
+- `RobotLab::Discovery::TxtRecord` — encodes and decodes DNS TXT record arrays.
+  Fields: `path=`, `rl_version=`, `capabilities=` (comma-separated).
+- `RobotLab::Discovery.dns_label` — normalises a free-form capability string
+  into a valid DNS label (downcased, non-alphanumeric runs collapsed to hyphens).
+- `RobotLab::Discovery` module with `browse`, `find`, `find_by_capability`, and
+  `list_capabilities` convenience class methods. Self-registers as a RobotLab
+  extension when the core gem is present.
+- `examples/01_basic_usage.rb` — end-to-end demo covering all six operations:
+  register with capabilities, browse all, find by name, find by capability,
+  list capability inventory, and unregister.

data/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Gem Does
+
+`robot_lab-discovery` provides zero-configuration mDNS/DNS-SD robot discovery on local networks. Robots advertise themselves with a name, port, path, and optional capabilities; browsers discover them by name or capability without any central registry.
+
+Uses the `zeroconf` gem. Service type is `_robot-lab._tcp.local.`.
+
+## Commands
+
+```bash
+bundle exec rake test        # Run full test suite (SpecReporter output)
+ruby -Ilib:test test/<file>  # Run a single test file
+```
+
+## Architecture
+
+All source lives under `lib/robot_lab/discovery/`.
+
+**`Discovery`** (`discovery.rb`) — Top-level module with delegation methods:
+- `browse(timeout:)` — returns all visible robots as `Array<Result>`
+- `find(name, timeout:)` — polls until the named robot appears or timeout
+- `find_by_capability(cap, timeout:)` — browses the capability-specific DNS subtype
+- `list_capabilities(timeout:)` — returns sorted unique capability strings across all visible robots
+- `dns_label(capability)` — normalises a capability string to a valid DNS label (`"Web Search"` → `"web-search"`)
+
+**`Advertiser`** (`discovery/advertiser.rb`) — Announces a robot over mDNS. `start` spawns a background thread running the zeroconf service; `stop` tears it down. Each capability is registered as a DNS subtype (`_capability-label._sub._robot-lab._tcp.local.`) enabling capability-filtered browsing.
+
+**`Browser`** (`discovery/browser.rb`) — Wraps `ZeroConf.browse`. Parses raw DNS responses (SRV + TXT records) into `Result` structs, deduplicating by name. `parse_response` is private — do not call directly.
+
+**`TxtRecord`** (`discovery/txt_record.rb`) — Encodes/decodes the DNS TXT payload using short wire keys to conserve UDP packet space:
+- `p` = path, `v` = rl_version, `c` = comma-joined capabilities
+- `encode` validates each string ≤ 255 bytes and total wire size ≤ 1300 bytes
+- `decode` returns `{ path:, rl_version:, capabilities: [] }`
+
+**`Result`** (`discovery/result.rb`) — `Data.define(:name, :hostname, :port, :path, :capabilities)`. Has a `url` convenience method (`"http://hostname:port/path"`).
+
+**`Constants`** (`discovery/constants.rb`) — `SERVICE_TYPE = "_robot-lab._tcp.local."`.
+
+## Usage Example
+
+```ruby
+require 'robot_lab/discovery'
+
+# Advertise
+adv = RobotLab::Discovery::Advertiser.new(
+  name: "analyst", port: 9292, path: "/a2a",
+  capabilities: ["data analysis", "web search"]
+)
+adv.start
+
+# Browse
+robots = RobotLab::Discovery.browse(timeout: 3)
+robots.each { |r| puts "#{r.name} at #{r.url}" }
+
+# Find by capability
+RobotLab::Discovery.find_by_capability("web search", timeout: 3)
+```
+
+## Key Constraints
+
+- mDNS is LAN-only — works within a single subnet, not across routers.
+- `browse` may return stale results if a robot crashes without calling `stop` — mDNS TTLs eventually expire.
+- Capability strings in TXT records are comma-separated in a single field capped at 253 bytes of content. Many short capabilities are fine; very long strings will raise `Discovery::Error`.
+- `find` polls by calling `browse` in a loop — it is blocking and should not be called on the main thread in production.
+
+## Testing
+
+- Minitest with SimpleCov (branch coverage tracked, no minimum threshold enforced yet)
+- Output via `Minitest::Reporters::SpecReporter`
+- Tests mock zeroconf interactions — no actual mDNS traffic is sent
+- Coverage baseline: ~47% line / ~3% branch — test suite is thin relative to implementation

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+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,182 @@
+# robot_lab-discovery
+
+Zero-configuration mDNS/DNS-SD robot discovery for [RobotLab](https://github.com/MadBomber/robot_lab) on local networks.
+
+Robots advertise themselves via multicast DNS (mDNS, RFC 6762) and find each other without any central registry or hardcoded URLs. Augments `robot_lab-a2a` but has no dependency on it — any transport can use the discovered URL.
+
+## How it works
+
+Each robot registers as a `_robot-lab._tcp.local.` mDNS service. Its HTTP path, gem version, and capability taxonomy are stored in the TXT record. Each capability is also registered as a DNS-SD subtype, enabling clients to browse by capability type without enumerating all robots.
+
+```
+Advertiser                              Browser
+──────────────────────────────────────  ────────────────────────────────────────────
+ZeroConf::Service                       ZeroConf.browse("_robot-lab._tcp.local.")
+  instance:     "headline"                → parse SRV + TXT
+  host:         my-server.local           → Result(name, hostname, port, path,
+  port:         9292                                capabilities, url)
+  TXT:          path=/headline
+                capabilities=writing,research
+  subtypes:     _writing._sub._robot-lab._tcp.local.
+                _research._sub._robot-lab._tcp.local.
+
+                                        ZeroConf.browse("_research._sub._robot-lab._tcp.local.")
+                                          → only research robots
+```
+
+## Installation
+
+```bash
+bundle add robot_lab-discovery
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "robot_lab-discovery"
+```
+
+### System prerequisites
+
+None beyond Ruby >= 3.2. The `zeroconf` gem is pure Ruby and implements mDNS itself using standard UDP multicast sockets — it does not wrap Bonjour, Avahi, or any system mDNS daemon. A multicast-capable network interface is all that is required, which is standard on any LAN.
+
+## Usage
+
+### Advertising a robot
+
+```ruby
+require "robot_lab/discovery"
+
+adv = RobotLab::Discovery::Advertiser.new(
+  name:         "headline",           # mDNS instance name — no dots allowed
+  port:         9292,
+  path:         "/headline",          # stored in TXT record
+  hostname:     Socket.gethostname,
+  capabilities: ["writing", "research"]  # free-form taxonomy terms
+)
+
+adv.start   # begins advertising in a background thread
+# ... server runs ...
+adv.stop    # sends mDNS goodbye packet; removes from peers' caches
+```
+
+Capability strings are free-form. They are normalised into valid DNS labels
+(`"Web Search"` → `"web-search"`) and registered as DNS-SD subtypes, so peers
+can browse for them directly.
+
+### Discovering robots
+
+```ruby
+require "robot_lab/discovery"
+
+# All robots on the LAN
+results = RobotLab::Discovery.browse(timeout: 3)
+results.each { |r| puts "#{r.name}: #{r.url}  caps=#{r.capabilities.join(", ")}" }
+
+# Find one robot by name
+result = RobotLab::Discovery.find("headline", timeout: 5)
+result.url           # => "http://my-server.local:9292/headline"
+result.capabilities  # => ["writing", "research"]
+
+# Find all robots offering a specific capability
+researchers = RobotLab::Discovery.find_by_capability("research", timeout: 3)
+
+# List every capability type advertised on the LAN right now
+RobotLab::Discovery.list_capabilities(timeout: 3)
+# => ["analysis", "coding", "research", "writing"]
+```
+
+### Connecting after discovery
+
+`Result#url` returns a plain URL string. Wire it to whatever client you use:
+
+```ruby
+result = RobotLab::Discovery.find("headline")
+
+# With robot_lab-a2a:
+client = A2A.client(url: result.url)
+client.send_task(message: A2A::Models::Message.user("Summarise today's news"))
+
+# With Net::HTTP directly:
+Net::HTTP.get(URI(result.url))
+```
+
+### Result fields
+
+| Field          | Type          | Description |
+|----------------|---------------|-------------|
+| `name`         | String        | mDNS instance name (e.g. `"headline"`) |
+| `hostname`     | String        | Fully-qualified `.local` hostname |
+| `port`         | Integer       | Port the robot server listens on |
+| `path`         | String        | HTTP path to the robot (e.g. `"/headline"`) |
+| `capabilities` | Array<String> | Capability taxonomy terms advertised by this robot |
+| `url`          | String        | `"http://#{hostname}:#{port}#{path}"` |
+
+## Capability taxonomy
+
+Capabilities are free-form strings — there is no enforced registry. Use short,
+lowercase, hyphen-separated terms that describe what the robot does, not how it
+works. Examples:
+
+```
+research      analysis      writing       coding
+vision        memory        tool-use      orchestration
+web-search    summarisation classification
+```
+
+A robot may advertise any number of capabilities. Clients browse by capability
+using `find_by_capability`, which targets the DNS-SD subtype directly and avoids
+scanning all robots on the network.
+
+`dns_label` is available for normalising arbitrary strings:
+
+```ruby
+RobotLab::Discovery.dns_label("Web Search / NLP")  # => "web-search-nlp"
+```
+
+## Examples
+
+```bash
+bundle exec ruby examples/01_basic_usage.rb
+```
+
+Covers all six operations: register with capabilities, browse all, find by name,
+find by capability, list capability inventory, and unregister.
+
+## Architecture
+
+```
+lib/robot_lab/discovery/
+  constants.rb    # SERVICE_TYPE = "_robot-lab._tcp.local."
+  txt_record.rb   # encode/decode TXT record arrays (path, rl_version, capabilities)
+  result.rb       # immutable Data value object (name, hostname, port, path, capabilities)
+  advertiser.rb   # wraps ZeroConf::Service, runs in a thread, registers subtypes
+  browser.rb      # wraps ZeroConf.browse, parses DNS responses
+```
+
+`RobotLab::Discovery` module exposes `browse`, `find`, `find_by_capability`, and
+`list_capabilities` as class methods. If `RobotLab` is loaded, the gem
+self-registers as an extension via `RobotLab.register_extension(:discovery, ...)`.
+
+## Relationship to other robot_lab gems
+
+| Gem | Concern |
+|-----|---------|
+| `robot_lab` | Core robots, networks, memory |
+| `robot_lab-a2a` | A2A HTTP+SSE transport protocol |
+| `robot_lab-discovery` | **Where** are the robots and **what can they do** (mDNS addressing + capability taxonomy) |
+
+Discovery is intentionally transport-agnostic. It finds a URL; you decide what
+protocol to speak to it.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test     # run the test suite
+bin/console               # IRB with the gem loaded
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
+  t.verbose = true
+  t.ruby_opts << '-rtest_helper'
+end
+
+task default: :test
+
+desc 'Run tests with verbose output'
+task :test_verbose do
+  ENV['TESTOPTS'] = '--verbose'
+  Rake::Task[:test].invoke
+end
+
+desc 'Run a single test file'
+task :test_file, [:file] do |_t, args|
+  ruby "test/#{args[:file]}"
+end
+
+desc 'Check code complexity with Flog (warn >=20, fail >=50)'
+task :flog_check do
+  require 'flog'
+
+  method_warn = 20.0
+  method_fail = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob('lib/**/*.rb'))
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?('#none')
+
+    if score > method_fail
+      failures << "#{format('%.1f', score)}: #{method}"
+    elsif score > method_warn
+      warnings << "#{format('%.1f', score)}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
+  else
+    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
+  end
+end
+
+desc 'Check for structural code duplication with Flay (mass >= 50)'
+task :flay_check do
+  require 'flay'
+
+  mass_threshold = 50
+
+  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
+  flay.process(*Dir.glob('lib/**/*.rb'))
+  flay.analyze
+
+  if flay.hashes.empty?
+    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
+  else
+    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
+    flay.report
+    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
+task :quality do
+  gates = [
+    ['Tests + Coverage', 'bundle exec rake test'],
+    ['RuboCop',          'bundle exec rubocop'],
+    ['Flog Complexity',  'bundle exec rake flog_check'],
+    ['Flay Duplication', 'bundle exec rake flay_check']
+  ]
+
+  results = gates.map do |label, command|
+    puts "\n#{'=' * 60}"
+    puts "Quality Gate: #{label}"
+    puts '=' * 60
+    [label, system(command) ? :pass : :fail]
+  end
+
+  green = ->(s) { "\e[32m#{s}\e[0m" }
+  red   = ->(s) { "\e[31m#{s}\e[0m" }
+  width = results.map { |label, _| label.length }.max
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate Summary'
+  puts '=' * 60
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
+  end
+  puts '-' * 60
+
+  passed = results.count { |_, s| s == :pass }
+  failed = results.count { |_, s| s == :fail }
+  tally  = "#{passed} passed, #{failed} failed"
+  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
+  puts '=' * 60
+
+  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
+  puts "\n#{green.call('All quality gates passed.')}"
+end
+
+namespace :docs do
+  desc 'Build MkDocs documentation'
+  task :build do
+    sh 'mkdocs build'
+  end
+
+  desc 'Serve MkDocs documentation locally on http://localhost:8000'
+  task :serve do
+    sh 'mkdocs serve'
+  end
+end