asterism-zenoh 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2855bdb36755d80af0a3e56ff6b270d9b641063b80acd59807579d06fbd17636
-  data.tar.gz: ffe16a1e240950235c16d339bd18688aed345bffb72d54ccd5a271315deaa0f7
+  metadata.gz: 67d782b46dad2501a9bb2ae1eed359b376c337ba0395f00dcf80d4d410df16a7
+  data.tar.gz: 394689733273761f4cd8e52be3c7e4339f55ae72501a4cdb247ce2c2cd48e4c0
 SHA512:
-  metadata.gz: 99b027cbc1b7af3e4ce63edd8acfcae3ba305c9d0320d9f6ba219b4b740cfa072957bc074045f255104d22bc7ac94f4f285f9371cc94f0dd69d64daa036994d1
-  data.tar.gz: 75c62b48351b64c4feb546113de28632602c23fdea6ad07b42ce8507db2a3a2468884c8b7afee4c86e25dbdc54ef2d578784d5ec0da687b832c7965ccdc9b853
+  metadata.gz: 33b506497a568ba6851979bf141d53954ec221417f866c7e8438cb3e8e12bcf6d5530206b3854a18522d3bc46626037860aeb7f35065eb2338b8a24156c4afcc
+  data.tar.gz: 6db7c0db2a026ab7e6517d24fa996c0b31b5d90cd49f2e47fe335e3424703b62222788eeae631cef621d11a69d6f97bb3231baa52ccb06d654fe0a1ac107cf09

data/README.md

@@ -18,6 +18,28 @@ loop do
 end
 ```
 
+## Feature coverage
+
+Supported: sessions (client, peer, listening, multicast scouting), any
+zenoh configuration (a Hash of keys, a JSON5 String or file: TLS, QUIC,
+WebSocket, authentication, timeouts), put / delete with encoding, priority,
+congestion control, express, reliability and timestamps, declared
+publishers and queriers with matching status, subscribers with the full
+sample (kind, encoding, timestamp, ...), get / queryable with error and
+delete replies, liveliness, the advanced publisher / subscriber (history
+for late subscribers, recovery, publisher detection; ROS 2 transient
+local), transport and link events, key expression operations and declared
+key expressions, HLC timestamps, zenoh-c's log.
+
+Not exposed: shared memory, background declarations, zenoh's own
+serializer (MessagePack and CDR are used instead), the publication cache /
+querying subscriber (the older form of the advanced ones), cancelling a
+get.
+
+The table, with the reasons and what the boards' zenoh-pico could offer:
+[docs/feature_coverage.md](docs/feature_coverage.md). The calls added in
+0.3.0 are CRuby only.
+
 ## API
 
 The same calls, arguments and results as the mruby / PicoRuby gem
@@ -41,6 +63,65 @@ The same calls, arguments and results as the mruby / PicoRuby gem
 Keys come back as UTF-8 Strings, payloads and attachments as binary
 (ASCII-8BIT) Strings.
 
+### Added in 0.3.0 (CRuby only)
+
+Every 0.2.0 call works as before; these are new keywords and methods.
+
+| Call | Notes |
+|---|---|
+| `Session.open(locator = nil, mode:, listen:, scouting:, timestamping:, config:, config_file:)` | `config:` a Hash (`{"transport/link/tls/root_ca_certificate" => "ca.pem"}`, Ruby values sent as JSON) or a JSON5 String; `config_file:` a JSON5 file. Lowest first: zenoh's defaults, the gem's own settings (no scouting, the time limits), the file / String, the arguments, the Hash. `scouting: true` needs no locator |
+| `Asterism::Zenoh.scout(what: [:router, :peer], timeout: 1.0, config: nil)` | Array of `Hello` (`zid`, `whatami`, `locators`) |
+| `session.put(key, payload, attachment:, encoding:, priority:, congestion_control:, express:, reliability:, timestamp:, allowed_destination:)` | `priority:` `:real_time` .. `:background` (or 1..7), `congestion_control:` `:drop` / `:block` / `:block_first`, `reliability:` `:reliable` / `:best_effort`, `timestamp:` `true` or a `Timestamp`, `allowed_destination:` `:any` / `:remote` / `:session_local` |
+| `session.delete(key, ...)` | the same options without payload, attachment and encoding |
+| `session.publisher(key, encoding:, priority:, ...)` -> `Publisher` | `put(payload, attachment:, encoding:, timestamp:)`, `delete(timestamp:)`, `matching?`, `matching_listener(depth = 16)`, `close` / `closed?` |
+| `session.querier(key, target:, consolidation:, timeout_ms:, ...)` -> `Querier` | `get(params = nil, payload = nil, attachment:, encoding:)` -> `Get`, `matching?`, `matching_listener`, `close` |
+| `sub.each_sample { \|sample\| }` | `Sample` (`key`, `payload`, `attachment`, `kind`, `encoding`, `timestamp`, `priority`, `congestion_control`, `express`, `reliability`, `source_zid`); same queue as `each_pending` |
+| `get.each_result { \|reply\| }` | `Reply` (`ok?` / `error?`, `key`, `payload`, `encoding`, `kind`, `timestamp`, `replier_zid`); error replies included. `each_reply` still leaves them out |
+| `session.get(..., encoding:, priority:, congestion_control:, express:, accept_replies:)` | |
+| `q.reply(..., encoding:, timestamp:, priority:, congestion_control:, express:)`, `q.reply_err(payload, encoding:)`, `q.reply_del(key = nil)`, `q.encoding` | |
+| `session.advanced_publisher(key, cache:, sample_miss_detection:, publisher_detection:, ...)` -> `AdvancedPublisher` | as `Publisher`. `cache: N` keeps the last N samples for late subscribers |
+| `session.advanced_subscriber(key, depth = 16, history:, recovery:, subscriber_detection:, query_timeout_ms:)` -> `AdvancedSubscriber` | as `Subscriber`, plus `detect_publishers` (a `LivelinessWatch`) and `miss_listener` (`Miss`: `source_zid`, `source_eid`, `count`) |
+| `session.transport_events(depth = 16, history: false)`, `session.link_events(...)` -> `EventListener` | `each_pending` gives `TransportEvent` / `LinkEvent` (`kind` `:added` / `:removed`, `zid`, ...) |
+| `session.peer_zids`, `router_zids`, `transports`, `links` | the IDs, `Transport` and `Link` values connected now |
+| `session.new_timestamp` -> `Timestamp` | `ntp64`, `id`, `to_time`, Comparable. From the session's HLC with `timestamping: true` (strictly increasing); otherwise from the system clock, so two in a row may be equal |
+| `Asterism::Zenoh::KeyExpr.new(str, autocanonize: false)` | `intersects?`, `includes?`, `relation_to` (`:disjoint` / `:intersects` / `:includes` / `:equals`), `join`, `concat`, `==`; `KeyExpr.canonize(str)`, `KeyExpr.valid?(str)`. Accepted wherever a key String is |
+| `session.declare_keyexpr(key)` -> `KeyExpr` | declared on the session (sent as a number afterwards); `undeclare` |
+| `Asterism::Zenoh.init_log(level = nil)` | zenoh-c's log on standard output (`"info"`, `"debug"`, or a filter); `RUST_LOG` wins |
+
+Listeners (`MatchingListener`, `EventListener`) are polled like the
+subscribers: `each_pending` (yields or returns an Array), `pending`,
+`received`, `dropped`, `close` / `closed?`. The values are `Data` objects
+(`lib/asterism/zenoh/values.rb`), so they work with pattern matching.
+
+```ruby
+Z = Asterism::Zenoh
+s = Z::Session.open("tls/192.0.2.2:7447",
+                    config: { "transport/link/tls/root_ca_certificate" => "ca.pem" })
+pub = s.publisher("demo/temp", encoding: "text/plain", priority: :data_high)
+watch = pub.matching_listener
+sub = s.subscribe("demo/**")
+loop do
+  watch.each_pending { |listening| puts "listened to: #{listening}" }
+  pub.put("21.5", timestamp: true)
+  sub.each_sample do |sm|
+    case sm
+    in {kind: :delete, key:} then puts "#{key} deleted"
+    in {encoding: "application/json", payload:} then p payload
+    else puts "#{sm.key} at #{sm.timestamp&.to_time}"
+    end
+  end
+  sleep 0.1
+end
+
+# A late subscriber gets the last values (ROS 2's transient local works this way)
+latched = s.advanced_publisher("demo/mode", cache: 1, sample_miss_detection: true)
+latched.put("eco")
+late = s.advanced_subscriber("demo/mode", history: true)
+
+Z.scout(what: :peer, timeout: 1.0).each { |h| puts "#{h.zid} #{h.locators}" }
+Z::KeyExpr.new("demo/*").includes?("demo/temp")   # => true
+```
+
 `require "asterism/zenoh/global"` defines `Zenoh = Asterism::Zenoh` for
 those who want the short name; nothing defines it by default.
 
@@ -55,19 +136,26 @@ its own thread. Nothing calls into Ruby behind its back, and `poll` does not
 need to run for data to arrive: it only checks the connection.
 
 Waiting calls (`Session.open`, `put`, `get`, `liveliness_get`, `close`)
-release the GVL. One `Session` and its objects are meant to be used from
-one Ruby thread at a time, as on the boards.
+release the GVL. A `Session` and its objects may be used from several Ruby
+threads: the calls that keep the GVL are serialized by it, the ones that
+release it by a lock of the session, and a session that closes (by `close`
+or because the connection was lost) is closed for every thread before
+zenoh-c lets it go; calls made after that raise `Asterism::Zenoh::Error`.
+Each entry of a queue is taken by exactly one `each_pending` /
+`each_reply`. The gem itself starts no Ruby thread: blocks, a receiving
+thread and Enumerators on top of this API are in the CRuby layer of the
+`asterism` gem.
 
 ## Behaviour kept from the mruby gem
 
-- **No scouting**: the locator is given. A peer that only connects does not
-  listen.
+- **No scouting** unless asked for (`scouting: true`): the locator is
+  given. A peer that only connects does not listen.
 - **Remote only**: a session's own puts do not reach its own subscribers,
   and its gets do not reach its own queryables (zenoh-pico's behaviour;
   Asterism calls its own objects in place).
 - **Losing the connection**: a client session is closed when it has no
   router left, a peer session that only connects when it has no peer left;
-  a listening session stays open. From then on `poll` is false, `closed?`
+  a listening (or scouting) session stays open. From then on `poll` is false, `closed?`
   true, and `put` raises `Asterism::Zenoh::Error`. No reconnection.
 - **Full queues drop the oldest** entry and count it in `dropped` (a dropped
   query is finished, so its requester gets no answer from it).

data/docs/feature_coverage.md

@@ -0,0 +1,54 @@
+# zenoh-c feature coverage of asterism-zenoh
+
+Which zenoh-c 1.10.1 features the Ruby binding exposes (asterism-zenoh 0.3.0).
+"Yes" = usable from Ruby, "Partial" = usable with fixed settings or a subset,
+"No" = not exposed, with the reason. The Ruby-like layer of the `asterism`
+gem builds on the same methods. The mruby gem (picoruby-asterism-zenoh) has
+the 0.2.0 part of the API; its column says whether zenoh-pico could offer
+the feature. Everything added in 0.3.0 is CRuby only for now.
+
+| Area | zenoh-c | asterism-zenoh (CRuby) | Ruby | Possible on the boards (zenoh-pico) |
+|---|---|---|---|---|
+| Session: client / peer / listen | `z_open` | Yes | `Session.open(loc, mode:, listen:)` | Yes (done) |
+| Session configuration | `zc_config_insert_json5`, `zc_config_from_str`, `zc_config_from_file` | Yes (0.3.0) | `config: {"key/path" => value}` (Ruby values sent as JSON), `config: "<JSON5>"`, `config_file:`. TLS, QUIC, WebSocket, authentication and timeouts are reachable this way; TLS is tested between two sessions | Partial (zenoh-pico has its own, smaller set of keys; no TLS on ESP32) |
+| Scouting (finding peers / routers) | `z_scout`, multicast scouting, gossip | Yes (0.3.0) | `Asterism::Zenoh.scout(what:, timeout:)` -> `Hello` (zid, whatami, locators); `Session.open(scouting: true)` | Yes (off on purpose: the locator is given) |
+| Session information | `z_info_zid`, `z_info_peers_zid`, `z_info_routers_zid`, `z_info_transports`, `z_info_links` | Yes (0.3.0) | `zid`, `peers` (count, as before), `peer_zids`, `router_zids`, `transports`, `links` | Yes (zid lists); transports / links: No |
+| put | `z_put` | Yes (0.3.0) | `put(key, payload, attachment:, encoding:, priority:, congestion_control:, express:, reliability:, timestamp:, allowed_destination:)` | Partial (encoding, priority, congestion control, express: yes) |
+| delete | `z_delete` | Yes (0.3.0) | `session.delete(key, ...)` | Yes |
+| Declared publisher | `z_declare_publisher`, `z_publisher_put`, `z_publisher_delete` | Yes (0.3.0) | `session.publisher(key, ...)` -> `put`, `delete`, `close` | Yes |
+| Matching status (is anyone listening?) | `z_*_get_matching_status`, `z_*_declare_matching_listener` | Yes (0.3.0) | `matching?`, `matching_listener` -> `MatchingListener#each_pending` (polled) | Partial (zenoh-pico has it behind a build option) |
+| Subscriber | `z_declare_subscriber` + FIFO channel | Yes | `each_pending { \|k, v, a\| }` as before; `each_sample` -> `Sample` (kind, encoding, timestamp, priority, congestion_control, express, reliability, source_zid) | Yes (done; the fields: Partial) |
+| get | `z_get` | Yes | timeout, parameters, payload, attachment, target, consolidation; 0.3.0: encoding, priority, congestion control, express, accept_replies; `each_result` -> `Reply` with error replies | Yes (done) |
+| Declared querier | `z_declare_querier`, `z_querier_get` | Yes (0.3.0) | `session.querier(key, target:, consolidation:, timeout_ms:, ...)` -> `get(params, payload, attachment:, encoding:)`, `matching?`, `matching_listener` | Yes |
+| Queryable | `z_declare_queryable`, `z_query_reply`, `z_query_reply_err`, `z_query_reply_del` | Yes (0.3.0) | `reply(..., encoding:, timestamp:, priority:, congestion_control:, express:)`, `reply_err(payload, encoding:)`, `reply_del(key)`, `query.encoding` | Yes |
+| Liveliness | tokens, subscriber, get | Yes | `liveliness`, `liveliness_watch`, `liveliness_get` | Yes (done) |
+| Encoding (content types) | `z_encoding_from_str`, `z_encoding_to_string` | Yes (0.3.0) | Strings ("application/json", "text/plain;charset=utf-8"); default "zenoh/bytes" | Yes |
+| Timestamps (HLC) | `z_timestamp_new`, `z_sample_timestamp`, timestamping | Yes (0.3.0) | `session.new_timestamp`, `Timestamp` (`ntp64`, `id`, `to_time`, Comparable), `put(timestamp: true)`, `Session.open(timestamping: true)` | Partial |
+| Key expression operations | `z_keyexpr_intersects`, `includes`, `relation_to`, `join`, `concat`, `canonize`, `z_declare_keyexpr` | Yes (0.3.0) | `KeyExpr.new(str, autocanonize:)`, `intersects?`, `includes?`, `relation_to`, `join`, `concat`, `KeyExpr.canonize`, `KeyExpr.valid?`; `session.declare_keyexpr(key)`. A KeyExpr goes wherever a key String does | Yes |
+| Advanced publisher / subscriber | `ze_declare_advanced_publisher`, `ze_declare_advanced_subscriber`, publisher detection, sample miss listener | Yes (0.3.0) | `advanced_publisher(key, cache:, sample_miss_detection:, publisher_detection:)`, `advanced_subscriber(key, history:, recovery:, subscriber_detection:)`, `detect_publishers`, `miss_listener`. A late rmw_zenoh subscriber with transient-local durability got the cached values | Partial (RAM to be measured) |
+| Transport / link events | `z_declare_transport_events_listener`, `z_declare_link_events_listener` | Yes (0.3.0) | `session.transport_events(history:)`, `link_events` -> `EventListener#each_pending` (polled) of `TransportEvent` / `LinkEvent` | No |
+| Logging | `zc_init_log_from_env_or`, `zc_try_init_log_from_env` | Yes (0.3.0) | `Asterism::Zenoh.init_log(level)`; written to standard output by zenoh-c; `RUST_LOG` wins | No |
+| Error text | `zc_get_last_error` | Yes (0.3.0) | appended to the `Asterism::Zenoh::Error` messages of failed opens and declarations | No |
+| Serialization helpers | `ze_serialize_*`, `ze_deserialize_*` | No | Not needed: MessagePack (objects) and CDR (ROS 2) are used; payloads stay Strings | Partial |
+| Publication cache / querying subscriber | `ze_declare_publication_cache`, `ze_declare_querying_subscriber` | No | The older form of the advanced publisher / subscriber, which covers it | Partial |
+| Shared memory | `z_shm_*` | No | Same-host only, and a Ruby String is copied anyway, so it would gain nothing | No |
+| Background declarations | `z_declare_background_*` | No | Not needed: every object is closed by `close`, by its session or when it is freed | Partial |
+| Cancellation of gets, source info on puts | `cancellation_token`, `source_info` | No | Rarely needed; a get ends by its time limit | No |
+
+How receiving works, for all of the above: zenoh-c's callbacks copy what
+arrives into a queue of plain C memory (no Ruby, no GVL), dropping the
+oldest entry when it is full; Ruby takes the entries out by polling
+(`each_pending`, `each_sample`, `each_result`). This holds for the matching
+listeners, the transport / link events and the missed samples too.
+
+Notes:
+
+- The prebuilt zenoh-c that `gem install` downloads contains all of the above
+  (the "unstable" API included).
+- An advanced publisher with a cache and without `sample_miss_detection`
+  needs a session with timestamping (`Session.open(..., timestamping: true)`).
+- For ROS 2 transient-local, publish on the rmw_zenoh topic key with an
+  advanced publisher (`cache:`, `publisher_detection: true`,
+  `sample_miss_detection: true`) and declare the liveliness token with
+  durability transient local in its QoS (`":1:,10:,:,:,,"`).
+  `Asterism::ROS` does not do this by itself yet.