robot_lab-discovery 0.2.6

data/lib/robot_lab/discovery/advertiser.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "socket"
+require "zeroconf"
+
+module RobotLab
+  module Discovery
+    class Advertiser
+      attr_reader :name, :port, :path, :hostname, :capabilities
+
+      def initialize(name:, port:, path:, hostname: Socket.gethostname, capabilities: [])
+        @name         = name
+        @port         = port
+        @path         = path
+        @hostname     = hostname
+        @capabilities = Array(capabilities).map(&:to_s)
+        @service      = nil
+        @thread       = nil
+      end
+
+      def start
+        @service = ZeroConf::Service.new(
+          SERVICE_TYPE,
+          @port,
+          @hostname,
+          instance_name: @name,
+          text:     TxtRecord.encode(path: @path, capabilities: @capabilities),
+          subtypes: @capabilities.map { |c| "_#{RobotLab::Discovery.dns_label(c)}" }
+        )
+        @thread = Thread.new { @service.start }
+        self
+      end
+
+      def stop
+        @service&.stop
+        @thread&.join
+        @service = nil
+        @thread  = nil
+        self
+      end
+
+      def started? = @thread&.alive? || false
+    end
+  end
+end

data/lib/robot_lab/discovery/browser.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "resolv"
+require "zeroconf"
+
+module RobotLab
+  module Discovery
+    module Browser
+      def self.browse(timeout: 3)
+        ZeroConf.browse(SERVICE_TYPE, timeout:)
+                .filter_map { |r| parse_response(r) }
+                .uniq(&:name)
+      end
+
+      def self.find(name, timeout: 5)
+        deadline = Time.now + timeout
+        loop do
+          remaining = deadline - Time.now
+          return nil if remaining <= 0
+          result = browse(timeout: [remaining, 1].min).find { |r| r.name == name }
+          return result if result
+        end
+      end
+
+      def self.find_by_capability(capability, timeout: 3)
+        label   = RobotLab::Discovery.dns_label(capability)
+        subtype = "_#{label}._sub.#{SERVICE_TYPE}"
+        ZeroConf.browse(subtype, timeout:)
+                .filter_map { |r| parse_response(r) }
+                .uniq(&:name)
+      end
+
+      def self.list_capabilities(timeout: 3)
+        browse(timeout:)
+          .flat_map(&:capabilities)
+          .uniq
+          .sort
+      end
+
+      def self.parse_response(response)
+        instance_name = nil
+        hostname      = nil
+        port          = nil
+        txt           = {}
+
+        (response.answer + response.additional).each do |rname, _ttl, data|
+          case data
+          when Resolv::DNS::Resource::IN::SRV
+            port          = data.port
+            hostname      = data.target.to_s.delete_suffix(".")
+            instance_name = rname.to_s.split(".").first
+          when Resolv::DNS::Resource::IN::TXT
+            txt = TxtRecord.decode(data.strings)
+          end
+        end
+
+        return nil unless instance_name && hostname && port && txt[:path]
+        Result.new(
+          name:         instance_name,
+          hostname:,
+          port:,
+          path:         txt[:path],
+          capabilities: txt.fetch(:capabilities, [])
+        )
+      end
+      private_class_method :parse_response
+    end
+  end
+end

data/lib/robot_lab/discovery/constants.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Discovery
+    SERVICE_TYPE = "_robot-lab._tcp.local."
+  end
+end

data/lib/robot_lab/discovery/result.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Discovery
+    Result = Data.define(:name, :hostname, :port, :path, :capabilities) do
+      def url = "http://#{hostname}:#{port}#{path}"
+    end
+  end
+end

data/lib/robot_lab/discovery/txt_record.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Discovery
+    module TxtRecord
+      # Short wire keys — every byte saved is more room for capability names.
+      #   p  = path          (vs "path="         — saves 3 bytes)
+      #   v  = rl_version    (vs "rl_version="   — saves 9 bytes)
+      #   c  = capabilities  (vs "capabilities=" — saves 11 bytes)
+      PATH_KEY         = "p"
+      VERSION_KEY      = "v"
+      CAPABILITIES_KEY = "c"
+
+      # RFC 1035 §3.3.14: each string in a TXT record is length-prefixed with
+      # one byte, so the content of any single string is capped at 255 bytes.
+      MAX_STRING_BYTES = 255
+
+      # mDNS runs over UDP. Ethernet MTU (1500) minus IP/UDP/DNS headers leaves
+      # ~1472 bytes for the DNS payload. After accounting for the SRV, A/AAAA,
+      # and PTR records that accompany a service announcement, the TXT record
+      # wire size (1 length-prefix byte per string + content bytes) should stay
+      # under 1300 bytes to fit in a single unfragmented packet.
+      MAX_TOTAL_BYTES = 1300
+
+      # Bytes available for capability names + commas after key + "=" overhead.
+      MAX_CAPABILITIES_CONTENT = MAX_STRING_BYTES - CAPABILITIES_KEY.bytesize - 1  # 253
+
+      def self.encode(path:, capabilities: [])
+        record = [
+          "#{PATH_KEY}=#{path}",
+          "#{VERSION_KEY}=#{VERSION}"
+        ]
+        record << "#{CAPABILITIES_KEY}=#{Array(capabilities).join(",")}" unless Array(capabilities).empty?
+        validate!(record)
+        record
+      end
+
+      def self.decode(strings)
+        strings.each_with_object({}) do |entry, hash|
+          k, v = entry.split("=", 2)
+          next unless k && v
+          case k
+          when PATH_KEY         then hash[:path]         = v
+          when VERSION_KEY      then hash[:rl_version]   = v
+          when CAPABILITIES_KEY then hash[:capabilities] = v.split(",")
+          end
+        end
+      end
+
+      def self.validate!(strings)
+        strings.each do |s|
+          next unless s.bytesize > MAX_STRING_BYTES
+          raise Error,
+                "TXT record string exceeds #{MAX_STRING_BYTES} bytes " \
+                "(#{s.bytesize} bytes): #{s[0, 40].inspect}#{"..." if s.length > 40}"
+        end
+
+        # Wire size: each string occupies 1 length-prefix byte + its content.
+        wire_size = strings.sum { |s| 1 + s.bytesize }
+        if wire_size > MAX_TOTAL_BYTES
+          raise Error,
+                "TXT record wire size exceeds #{MAX_TOTAL_BYTES} bytes (#{wire_size} bytes). " \
+                "Shorten path or reduce the number/length of capabilities."
+        end
+
+        strings
+      end
+    end
+  end
+end

data/lib/robot_lab/discovery/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Discovery
+    VERSION = "0.2.6"
+  end
+end

data/lib/robot_lab/discovery.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "discovery/version"
+require_relative "discovery/constants"
+require_relative "discovery/txt_record"
+require_relative "discovery/result"
+require_relative "discovery/advertiser"
+require_relative "discovery/browser"
+
+module RobotLab
+  module Discovery
+    class Error < StandardError; end
+
+    def self.browse(timeout: 3)                      = Browser.browse(timeout:)
+    def self.find(name, timeout: 5)                  = Browser.find(name, timeout:)
+    def self.find_by_capability(cap, timeout: 3)     = Browser.find_by_capability(cap, timeout:)
+    def self.list_capabilities(timeout: 3)           = Browser.list_capabilities(timeout:)
+
+    # Converts a free-form capability string into a valid DNS label:
+    # downcased, non-alphanumeric runs replaced with hyphens, no leading/trailing hyphens.
+    # "Web Search" → "web-search",  "NLP/Analysis" → "nlp-analysis"
+    def self.dns_label(capability)
+      capability.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+  end
+end
+
+if defined?(RobotLab) && RobotLab.respond_to?(:register_extension)
+  RobotLab.register_extension(:discovery, RobotLab::Discovery)
+end

data/mkdocs.yml

@@ -0,0 +1,117 @@
+site_name: robot_lab-discovery
+site_description: Zero-configuration mDNS/DNS-SD robot discovery for the RobotLab LLM agent framework
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/robot_lab-discovery
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+repo_name: MadBomber/robot_lab-discovery
+repo_url: https://github.com/MadBomber/robot_lab-discovery
+edit_uri: edit/main/docs/
+docs_dir: docs
+
+theme:
+  name: material
+
+  palette:
+    - scheme: default
+      primary: cyan
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: cyan
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/radar
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: MadBomber
+      repo: robot_lab-discovery
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/robot_lab-discovery
+      name: robot_lab-discovery on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/robot_lab-discovery
+      name: robot_lab-discovery on RubyGems
+
+nav:
+  - Home: index.md
+  - Getting Started: getting_started.md
+  - How It Works: how_it_works.md
+  - API Reference: api_reference.md

data/sig/robot_lab/discovery.rbs

@@ -0,0 +1,6 @@
+module RobotLab
+  module Discovery
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: robot_lab-discovery
+version: !ruby/object:Gem::Version
+  version: 0.2.6
+platform: ruby
+authors:
+- Dewayne VanHoozer
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeroconf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Allows RobotLab robots to advertise themselves and discover each other
+  on a local network using multicast DNS (mDNS/Bonjour/Avahi) via the zeroconf gem.
+email:
+- dvanhoozer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".github/workflows/deploy-github-pages.yml"
+- ".loki"
+- ".quality/reek_baseline.txt"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/api_reference.md
+- docs/getting_started.md
+- docs/how_it_works.md
+- docs/index.md
+- examples/01_basic_usage.rb
+- examples/common.rb
+- lib/robot_lab/discovery.rb
+- lib/robot_lab/discovery/advertiser.rb
+- lib/robot_lab/discovery/browser.rb
+- lib/robot_lab/discovery/constants.rb
+- lib/robot_lab/discovery/result.rb
+- lib/robot_lab/discovery/txt_record.rb
+- lib/robot_lab/discovery/version.rb
+- mkdocs.yml
+- sig/robot_lab/discovery.rbs
+homepage: https://github.com/MadBomber/robot_lab-discovery
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MadBomber/robot_lab-discovery
+  source_code_uri: https://github.com/MadBomber/robot_lab-discovery
+  changelog_uri: https://github.com/MadBomber/robot_lab-discovery/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.17
+specification_version: 4
+summary: Zero-configuration mDNS/DNS-SD robot discovery for RobotLab on local networks.
+test_files: []