asterism-zenoh 0.2.0 → 0.3.0

data/lib/asterism/zenoh/values.rb

@@ -0,0 +1,105 @@
+# The values the C extension hands out (samples, replies, events), and the
+# Ruby half of scouting. Plain immutable Data objects: they work with
+# pattern matching (case sample in {kind: :delete, key:}).
+module Asterism
+  module Zenoh
+    # A received sample, from Subscriber#each_sample and
+    # AdvancedSubscriber#each_sample. payload and attachment are binary
+    # Strings (attachment nil when there was none). kind is :put or
+    # :delete; encoding a String such as "application/json"; timestamp an
+    # Asterism::Zenoh::Timestamp or nil (zenoh only stamps samples when the
+    # sender or a router does); priority, congestion_control and
+    # reliability Symbols; source_zid the sender's Zenoh ID when it said.
+    # Sample.new(key, payload, attachment) still works (the other fields
+    # have defaults).
+    Sample = Data.define(:key, :payload, :attachment, :kind, :encoding, :timestamp, :priority,
+                         :congestion_control, :express, :reliability, :source_zid) do
+      def initialize(key:, payload:, attachment: nil, kind: :put, encoding: nil, timestamp: nil, priority: nil,
+                     congestion_control: nil, express: false, reliability: nil, source_zid: nil)
+        super
+      end
+
+      # The payload as UTF-8.
+      def text
+        payload.dup.force_encoding(Encoding::UTF_8)
+      end
+
+      def put? = kind == :put
+      def delete? = kind == :delete
+
+      def to_s
+        "#{key}: #{payload}"
+      end
+    end
+
+    # A reply to a get, from Get#each_result: an answer (error false) with
+    # the fields of a sample, or an error reply (error true: payload and
+    # encoding of the error, key nil). replier_zid: who answered, when known.
+    # Reply.new(key, payload, attachment) still works.
+    Reply = Data.define(:key, :payload, :attachment, :kind, :encoding, :timestamp, :error, :replier_zid) do
+      def initialize(key:, payload:, attachment: nil, kind: :put, encoding: nil, timestamp: nil, error: false,
+                     replier_zid: nil)
+        super
+      end
+
+      def text
+        payload.dup.force_encoding(Encoding::UTF_8)
+      end
+
+      def ok? = !error
+      def error? = error
+
+      def to_s
+        error ? "error: #{payload}" : "#{key}: #{payload}"
+      end
+    end
+
+    # An answer to scouting: a router or peer (whatami :router / :peer /
+    # :client), its Zenoh ID and the locators it can be reached at.
+    Hello = Data.define(:zid, :whatami, :locators)
+
+    # A connection to another peer or router (Session#transports).
+    Transport = Data.define(:zid, :whatami, :qos, :multicast)
+
+    # A transport that appeared (kind :added) or went (:removed), from
+    # Session#transport_events.
+    TransportEvent = Data.define(:kind, :zid, :whatami, :qos, :multicast) do
+      def added? = kind == :added
+      def removed? = kind == :removed
+    end
+
+    # A link (one connection of a transport; Session#links).
+    Link = Data.define(:zid, :src, :dst, :mtu, :streamed, :reliability, :interfaces, :group, :auth_identifier)
+
+    # A link that opened (kind :added) or closed (:removed), from
+    # Session#link_events.
+    LinkEvent = Data.define(:kind, :zid, :src, :dst, :mtu, :streamed, :reliability, :interfaces, :group,
+                            :auth_identifier) do
+      def added? = kind == :added
+      def removed? = kind == :removed
+    end
+
+    # Samples that a publisher sent and that never arrived
+    # (AdvancedSubscriber#miss_listener): count of them, from the publisher
+    # source_zid / source_eid.
+    Miss = Data.define(:source_zid, :source_eid, :count)
+
+    SCOUT_WHAT = { router: 1, peer: 2, client: 4 }.freeze
+
+    # Looks for routers and / or peers by multicast scouting for timeout
+    # seconds (or timeout_ms milliseconds) and returns what answered, as an
+    # Array of Hello. what: :router, :peer, :client, an Array of them, or
+    # :all. config: a Hash of zenoh configuration keys, as for
+    # Session.open (e.g. {"scouting/multicast/interface" => "eth0"}).
+    # Multicast must be allowed on the network (it often is not in
+    # containers and VPNs).
+    def self.scout(what: %i[router peer], timeout: 1.0, timeout_ms: nil, config: nil)
+      kinds = what == :all ? SCOUT_WHAT.keys : Array(what)
+      mask = kinds.sum do |k|
+        SCOUT_WHAT.fetch(k.to_sym) { raise ArgumentError, "what must be :router, :peer, :client or :all" }
+      end
+      ms = timeout_ms || (timeout * 1000).round
+      _scout(mask, ms, config)
+    end
+  end
+end

data/lib/asterism/zenoh/version.rb

@@ -1,6 +1,6 @@
 module Asterism
   module Zenoh
     # The gem's version.
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/asterism/zenoh.rb

@@ -1,6 +1,10 @@
 # Asterism::Zenoh for CRuby: the Zenoh binding of Asterism, over zenoh-c.
 # The same Ruby API as the mruby / PicoRuby gem (picoruby-asterism-zenoh):
 # see README.md. Receiving is polled (each_pending / each_reply) from the
-# application's own thread; nothing calls into Ruby behind its back.
+# application's own thread; nothing calls into Ruby behind its back. The
+# calls added in 0.3.0 (configuration, publishers, queriers, the advanced
+# publisher / subscriber, events, key expressions, timestamps) are CRuby
+# only: see docs/feature_coverage.md.
 require_relative "zenoh/version"
 require_relative "asterism_zenoh"
+require_relative "zenoh/values"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asterism-zenoh
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Katsuhiko Kageyama
@@ -11,9 +11,11 @@ cert_chain: []
 date: 2026-10-08 00:00:00.000000000 Z
 dependencies: []
 description: Sessions, put / subscribe, get / queryable, liveliness and attachments,
-  received by polling. The same Ruby API as Asterism's mruby / PicoRuby binding. The
-  C extension is compiled at install time against the official prebuilt zenoh-c release
-  for the machine, downloaded and checked against a pinned sha256.
+  received by polling. The same Ruby API as Asterism's mruby / PicoRuby binding, plus
+  (CRuby only) configuration and TLS, scouting, publishers, queriers, the advanced
+  publisher / subscriber, events, key expressions and timestamps. The C extension
+  is compiled at install time against the official prebuilt zenoh-c release for the
+  machine, downloaded and checked against a pinned sha256.
 email: 
 executables: []
 extensions:
@@ -23,11 +25,13 @@ files:
 - LICENSE
 - README.md
 - ZENOH_C_PIN
+- docs/feature_coverage.md
 - ext/asterism_zenoh/extconf.rb
 - ext/asterism_zenoh/zenoh.c
 - ext/asterism_zenoh/zenoh_c.rb
 - lib/asterism/zenoh.rb
 - lib/asterism/zenoh/global.rb
+- lib/asterism/zenoh/values.rb
 - lib/asterism/zenoh/version.rb
 - licenses/zenoh-c/LICENSE-APACHE
 - licenses/zenoh-c/NOTICE.md