asterism-zenoh 0.2.0 → 0.4.0

data/lib/asterism/zenoh/common.rb

@@ -0,0 +1,221 @@
+# The part of Asterism::Zenoh written in Ruby that is the same on every
+# backend: this file is byte for byte the same as mrblib/common.rb of the
+# mruby / PicoRuby binding (picoruby-asterism-zenoh). It runs on CRuby,
+# mruby and PicoRuby, so it keeps to what all three have (no Regexp, no
+# Data, while loops where a block would be called from C).
+#
+# What it adds on top of the C binding:
+# - the deprecation helper (Asterism.deprecated, Asterism.deprecations=),
+#   shared by every Asterism gem, and Asterism.warn_once (lost replies);
+# - the time limit in seconds (timeout:) next to milliseconds (timeout_ms:)
+#   on get and liveliness_get, and keywords for the positional optionals;
+# - connection_count's old name peers, and the one-argument Query#reply
+#   that will change in 1.0, both with a deprecation warning;
+# - Error#code and the readable constant names.
+module Asterism
+  # The root of every Asterism error (the binding's C code defines it first).
+  class Error < StandardError; end
+
+  # Raised instead of a warning when Asterism.deprecations is :raise.
+  class DeprecationError < Error; end
+
+  # How a deprecated call is reported: :warn (once per name, the default),
+  # :raise (DeprecationError; for CI) or :silent. The environment variable
+  # ASTERISM_DEPRECATIONS (warn / raise / silent) sets the default.
+  def self.deprecations
+    if @deprecations.nil?
+      mode = nil
+      begin
+        mode = ENV["ASTERISM_DEPRECATIONS"] if Object.const_defined?(:ENV)
+      rescue StandardError
+        mode = nil
+      end
+      @deprecations = (mode == "raise" || mode == "silent") ? mode.to_sym : :warn
+    end
+    @deprecations
+  end
+
+  def self.deprecations=(mode)
+    m = mode.to_s.to_sym
+    raise ArgumentError, "deprecations must be :warn, :raise or :silent" unless m == :warn || m == :raise || m == :silent
+    @deprecations = m
+  end
+
+  # Reports that `old` is deprecated in favour of `instead`: warns once per
+  # `old` per process (per VM on the boards), raises DeprecationError, or
+  # stays silent (Asterism.deprecations). `why` is an optional sentence.
+  def self.deprecated(old, instead, why = nil)
+    mode = deprecations
+    return nil if mode == :silent
+    msg = "asterism: #{old} is deprecated and goes away in 1.0; use #{instead}"
+    msg = "#{msg} (#{why})" if why
+    raise DeprecationError, msg if mode == :raise
+    @deprecated_seen ||= {}
+    return nil if @deprecated_seen[old]
+    @deprecated_seen[old] = true
+    if respond_to?(:warn, true)
+      warn(msg)
+    else
+      puts(msg)
+    end
+    nil
+  end
+
+  # Warns msg once for obj (a Get, a watch, a wrapper): later calls for
+  # the same object say nothing. For losses the application did not ask
+  # for, such as replies dropped from a full queue. Returns true when it
+  # warned. Ruby's warn stays silent with $VERBOSE = nil.
+  def self.warn_once(obj, msg)
+    # By object_id: not every mruby build has instance_variable_get. The
+    # objects warned about are few; the table is emptied past 256.
+    @warned_once ||= {}
+    id = obj.object_id
+    return false if @warned_once[id]
+    @warned_once = {} if @warned_once.size >= 256
+    @warned_once[id] = true
+    if respond_to?(:warn, true)
+      warn(msg)
+    else
+      puts(msg)
+    end
+    true
+  end
+
+  # The names warned about so far (for tests). @api private
+  def self.deprecated_names
+    (@deprecated_seen || {}).keys
+  end
+
+  # Forget the names warned about (for tests). @api private
+  def self.reset_deprecations
+    @deprecated_seen = {}
+    nil
+  end
+
+  # A time limit in milliseconds from the ways a call may take it: timeout:
+  # (seconds), timeout_ms: or the old positional milliseconds (deprecated).
+  # Giving more than one raises ArgumentError. @api private
+  def self.time_ms(where, timeout, timeout_ms, positional, default_ms)
+    given = 0
+    given += 1 unless timeout.nil?
+    given += 1 unless timeout_ms.nil?
+    given += 1 unless positional.nil?
+    raise ArgumentError, "#{where}: give the time limit once (timeout: in seconds, or timeout_ms:)" if given > 1
+    unless positional.nil?
+      if positional.is_a?(Float)
+        deprecated("#{where} with a Float as the positional time limit", "timeout: (seconds)",
+                   "the positional time limit is milliseconds, so #{positional} waits #{positional.to_i} ms; " \
+                   "a Float there is usually meant as seconds")
+      else
+        deprecated("#{where} with the time limit as a positional argument", "timeout: (seconds) or timeout_ms:")
+      end
+      return positional.to_i
+    end
+    unless timeout_ms.nil?
+      raise TypeError, "#{where}: timeout_ms: must be a number" unless timeout_ms.is_a?(Numeric)
+      return timeout_ms.round
+    end
+    return default_ms if timeout.nil?
+    raise TypeError, "#{where}: timeout: must be a number of seconds" unless timeout.is_a?(Numeric)
+    ms = (timeout * 1000).round
+    raise ArgumentError, "#{where}: timeout: #{timeout} s is less than 1 ms" if ms < 1
+    ms
+  end
+
+  # A queue depth given positionally (kept) or as depth: (not both).
+  # @api private
+  def self.depth_of(where, args, depth, default)
+    raise ArgumentError, "#{where}: too many arguments" if args.size > 1
+    raise ArgumentError, "#{where}: give the depth once (positional or depth:)" if args.size == 1 && !depth.nil?
+    return args[0] if args.size == 1
+    depth.nil? ? default : depth
+  end
+
+  module Zenoh
+    # The readable name of PEER: whether this build has peer mode.
+    PEER_SUPPORTED = PEER
+    # The default time limit of get and liveliness_get, in seconds.
+    DEFAULT_TIMEOUT = 2.0
+
+    class Error
+      # The result code of zenoh-c / zenoh-pico (a negative Integer) when the
+      # failure came with one, else nil.
+      attr_reader :code
+    end
+
+    class Session
+      alias_method :__asterism_get, :get
+      alias_method :__asterism_liveliness_get, :liveliness_get
+      alias_method :__asterism_subscribe, :subscribe
+      alias_method :__asterism_queryable, :queryable
+      alias_method :__asterism_liveliness_watch, :liveliness_watch
+
+      # get(key, timeout: 2.0, params: nil, payload: nil, attachment: nil,
+      #     target: :all, consolidation: :none, depth: DEFAULT_GET_DEPTH,
+      #     ...) -> Get.
+      # timeout: seconds; or timeout_ms:. depth: the replies kept until
+      # taken (past it the oldest go; Get#dropped counts them). The old
+      # positional form get(key, timeout_ms, params, payload) still works
+      # (deprecated).
+      def get(key, *args, timeout: nil, timeout_ms: nil, params: nil, payload: nil, **opts)
+        raise ArgumentError, "get: wrong number of arguments (given #{args.size + 1}, expected 1..4)" if args.size > 3
+        raise ArgumentError, "get: params given twice" if args.size > 1 && !params.nil?
+        raise ArgumentError, "get: payload given twice" if args.size > 2 && !payload.nil?
+        ms = ::Asterism.time_ms("Session#get", timeout, timeout_ms, args[0], 2000)
+        params = args[1] if args.size > 1
+        payload = args[2] if args.size > 2
+        __asterism_get(key, ms, params, payload, **opts)
+      end
+
+      # liveliness_get(key, timeout: 2.0, depth: DEFAULT_GET_DEPTH) -> Get
+      # (or timeout_ms:).
+      def liveliness_get(key, *args, timeout: nil, timeout_ms: nil, depth: nil)
+        raise ArgumentError, "liveliness_get: wrong number of arguments (given #{args.size + 1}, expected 1..2)" if args.size > 1
+        ms = ::Asterism.time_ms("Session#liveliness_get", timeout, timeout_ms, args[0], 2000)
+        __asterism_liveliness_get(key, ms, depth: depth.nil? ? DEFAULT_GET_DEPTH : depth)
+      end
+
+      # subscribe(key, depth = 16) or subscribe(key, depth: 16).
+      def subscribe(key, *args, depth: nil)
+        __asterism_subscribe(key, ::Asterism.depth_of("subscribe", args, depth, DEFAULT_DEPTH))
+      end
+
+      # queryable(key, depth = 16, complete: false) or with depth:.
+      def queryable(key, *args, depth: nil, **opts)
+        __asterism_queryable(key, ::Asterism.depth_of("queryable", args, depth, DEFAULT_DEPTH), **opts)
+      end
+
+      # liveliness_watch(key, depth = DEFAULT_WATCH_DEPTH) or with depth:.
+      # The tokens alive when it is declared come in one burst.
+      def liveliness_watch(key, *args, depth: nil)
+        __asterism_liveliness_watch(key, ::Asterism.depth_of("liveliness_watch", args, depth, DEFAULT_WATCH_DEPTH))
+      end
+
+      # Deprecated: the number of connections is connection_count.
+      def peers
+        ::Asterism.deprecated("Session#peers", "Session#connection_count",
+                              "for a client session it counts routers, not peers")
+        connection_count
+      end
+    end
+
+    class Query
+      alias_method :__asterism_reply, :reply
+
+      # reply(payload) answers on the query's key today. From 1.0 it answers
+      # on the queryable's own key when that key has no wildcard (as the
+      # CRuby block API does); a reply that would change warns now.
+      def reply(*args, **kw)
+        if args.size == 1
+          own = @asterism_queryable_key
+          if own && !own.include?("*") && !own.include?("$") && own != key
+            ::Asterism.deprecated("Query#reply(payload) for a query whose key differs from the queryable's",
+                                  "q.reply(key, payload)",
+                                  "from 1.0 a reply with only a payload answers on the queryable's own key")
+          end
+        end
+        __asterism_reply(*args, **kw)
+      end
+    end
+  end
+end

data/lib/asterism/zenoh/cruby.rb

@@ -0,0 +1,128 @@
+# What only the CRuby binding (zenoh-c) adds in Ruby: the backend
+# constants, Session.open with a block and connect_timeout:, seconds and
+# keywords on the CRuby-only calls (querier, advanced subscriber,
+# listeners), the long reply names, and scout's argument check.
+module Asterism
+  module Zenoh
+    # Which Zenoh implementation is underneath (:zenoh_pico on the boards).
+    BACKEND = :zenoh_c
+    # Its version (C_VERSION here, PICO_VERSION on the boards).
+    BACKEND_VERSION = C_VERSION
+
+    class Session
+      class << self
+        alias_method :__asterism_open, :open
+
+        # Session.open(locator = nil, mode:, listen:, scouting:,
+        # timestamping:, config:, config_file:, connect_timeout:) -> Session.
+        # connect_timeout: seconds to wait for a router or peer
+        # (CONNECT_TIMEOUT_MS by default; zenoh's connect/timeout_ms). With a
+        # block: yields the session, closes it when the block ends (also on
+        # an exception) and returns the block's value.
+        def open(locator = nil, connect_timeout: nil, **opts)
+          unless connect_timeout.nil?
+            ms = ::Asterism.time_ms("Session.open connect_timeout:", connect_timeout, nil, nil, CONNECT_TIMEOUT_MS)
+            cfg = opts[:config]
+            if cfg.nil?
+              opts[:config] = { "connect/timeout_ms" => ms }
+            elsif cfg.is_a?(Hash)
+              if cfg.key?("connect/timeout_ms") || cfg.key?(:"connect/timeout_ms")
+                raise ArgumentError, "connect_timeout: and config: {\"connect/timeout_ms\" => ...} given together"
+              end
+              opts[:config] = cfg.merge("connect/timeout_ms" => ms)
+            else
+              raise ArgumentError, "connect_timeout: cannot be added to a config String; set connect/timeout_ms in it"
+            end
+          end
+          s = __asterism_open(locator, **opts)
+          return s unless block_given?
+          begin
+            yield s
+          ensure
+            s.close
+          end
+        end
+      end
+
+      alias_method :__asterism_querier, :querier
+      alias_method :__asterism_advanced_subscriber, :advanced_subscriber
+      alias_method :__asterism_transport_events, :transport_events
+      alias_method :__asterism_link_events, :link_events
+
+      # querier(key, timeout: 2.0, ...) -> Querier (or timeout_ms:).
+      def querier(key, timeout: nil, timeout_ms: nil, **opts)
+        ms = ::Asterism.time_ms("Session#querier", timeout, timeout_ms, nil, nil)
+        opts[:timeout_ms] = ms unless ms.nil?
+        __asterism_querier(key, **opts)
+      end
+
+      # advanced_subscriber(key, depth = 16, query_timeout: seconds, ...)
+      # (or depth:, query_timeout_ms:).
+      def advanced_subscriber(key, *args, depth: nil, query_timeout: nil, query_timeout_ms: nil, **opts)
+        d = ::Asterism.depth_of("advanced_subscriber", args, depth, 16)
+        ms = ::Asterism.time_ms("Session#advanced_subscriber query_timeout", query_timeout, query_timeout_ms, nil, nil)
+        opts[:query_timeout_ms] = ms unless ms.nil?
+        __asterism_advanced_subscriber(key, d, **opts)
+      end
+
+      # transport_events(depth = 16, history: false) or with depth:.
+      def transport_events(*args, depth: nil, **opts)
+        __asterism_transport_events(::Asterism.depth_of("transport_events", args, depth, 16), **opts)
+      end
+
+      # link_events(depth = 16, history: false) or with depth:.
+      def link_events(*args, depth: nil, **opts)
+        __asterism_link_events(::Asterism.depth_of("link_events", args, depth, 16), **opts)
+      end
+    end
+
+    # matching_listener(depth = 16) or matching_listener(depth: 16).
+    module MatchingDepth
+      def matching_listener(*args, depth: nil)
+        super(::Asterism.depth_of("matching_listener", args, depth, 16))
+      end
+    end
+    Publisher.prepend(MatchingDepth)
+    AdvancedPublisher.prepend(MatchingDepth)
+
+    class Querier
+      prepend MatchingDepth
+      alias_method :__asterism_get, :get
+
+      # get(params: nil, payload: nil, attachment:, encoding:, depth:) -> Get; the
+      # positional get(params, payload) still works.
+      def get(*args, params: nil, payload: nil, **opts)
+        raise ArgumentError, "get: wrong number of arguments (given #{args.size}, expected 0..2)" if args.size > 2
+        raise ArgumentError, "get: params given twice" if args.size > 0 && !params.nil?
+        raise ArgumentError, "get: payload given twice" if args.size > 1 && !payload.nil?
+        params = args[0] if args.size > 0
+        payload = args[1] if args.size > 1
+        __asterism_get(params, payload, **opts)
+      end
+    end
+
+    class AdvancedSubscriber
+      alias_method :__asterism_miss_listener, :miss_listener
+      alias_method :__asterism_detect_publishers, :detect_publishers
+
+      def miss_listener(*args, depth: nil)
+        __asterism_miss_listener(::Asterism.depth_of("miss_listener", args, depth, 16))
+      end
+
+      def detect_publishers(*args, depth: nil, **opts)
+        __asterism_detect_publishers(::Asterism.depth_of("detect_publishers", args, depth, 16), **opts)
+      end
+    end
+
+    class Query
+      # The spelled-out names of reply_err and reply_del (those stay).
+      def reply_error(payload, **opts)
+        reply_err(payload, **opts)
+      end
+
+      def reply_delete(key = nil, **opts)
+        reply_del(key, **opts)
+      end
+    end
+  end
+end

data/lib/asterism/zenoh/values.rb

@@ -0,0 +1,112 @@
+# 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 express? = express
+
+      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) do
+      def multicast? = multicast
+    end
+
+    # A transport that appeared (kind :added) or went (:removed), from
+    # Session#transport_events.
+    TransportEvent = Data.define(:kind, :zid, :whatami, :qos, :multicast) do
+      def multicast? = multicast
+      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) do
+      def streamed? = streamed
+    end
+
+    # 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 streamed? = streamed
+      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; not both) 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: nil, 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 = ::Asterism.time_ms("Asterism::Zenoh.scout", timeout, timeout_ms, nil, 1000)
+      _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.4.0"
   end
 end

data/lib/asterism/zenoh.rb

@@ -1,6 +1,12 @@
 # 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"
+require_relative "zenoh/common"
+require_relative "zenoh/cruby"

metadata

@@ -1,33 +1,40 @@
 --- !ruby/object:Gem::Specification
 name: asterism-zenoh
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Katsuhiko Kageyama
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-08 00:00:00.000000000 Z
+date: 2026-10-09 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:
 - ext/asterism_zenoh/extconf.rb
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - 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/common.rb
+- lib/asterism/zenoh/cruby.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