asterism-zenoh 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2855bdb36755d80af0a3e56ff6b270d9b641063b80acd59807579d06fbd17636
+  data.tar.gz: ffe16a1e240950235c16d339bd18688aed345bffb72d54ccd5a271315deaa0f7
+SHA512:
+  metadata.gz: 99b027cbc1b7af3e4ce63edd8acfcae3ba305c9d0320d9f6ba219b4b740cfa072957bc074045f255104d22bc7ac94f4f285f9371cc94f0dd69d64daa036994d1
+  data.tar.gz: 75c62b48351b64c4feb546113de28632602c23fdea6ad07b42ce8507db2a3a2468884c8b7afee4c86e25dbdc54ef2d578784d5ec0da687b832c7965ccdc9b853

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Katsuhiko Kageyama
+
+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,180 @@
+# asterism-zenoh
+
+An unofficial Zenoh binding for CRuby, `Asterism::Zenoh`, over the prebuilt
+[zenoh-c](https://github.com/eclipse-zenoh/zenoh-c) 1.10.1. Its Ruby API is
+the one of Asterism's mruby / PicoRuby binding (over zenoh-pico), so the
+same Ruby code runs on a PC and on the boards.
+
+```ruby
+require "asterism/zenoh"
+
+s = Asterism::Zenoh::Session.open("tcp/192.0.2.2:7447")   # client of a router
+sub = s.subscribe("demo/in")
+loop do
+  break unless s.poll                       # false once the connection is lost
+  s.put("demo/out", "hello")
+  sub.each_pending { |key, payload, attachment| puts "#{key}: #{payload}" }
+  sleep 0.05
+end
+```
+
+## API
+
+The same calls, arguments and results as the mruby / PicoRuby gem
+([picoruby-asterism-zenoh](https://github.com/ruby-asterism/picoruby-asterism-zenoh)):
+
+| Call | Notes |
+|---|---|
+| `Session.open(locator = nil, mode: :client, listen: nil)` | client of a router, or `mode: :peer` connecting to `locator` and/or listening on `listen:`. `Error` when nobody answers within `CONNECT_TIMEOUT_MS`. Releases the GVL while connecting |
+| `session.put(key, payload, attachment: nil)` | `payload` / `attachment` are Strings (bytes). Releases the GVL |
+| `session.subscribe(key, depth = 16)` -> `Subscriber` | `each_pending { \|key, payload, attachment\| }` (or an Array), `pending` / `received` / `dropped`, `close` / `closed?` |
+| `session.get(key, timeout_ms = 2000, params = nil, payload = nil, attachment: nil, target: :all, consolidation: :none)` -> `Get` | returns at once; `each_reply { \|key, payload, attachment\| }`, `done?`, `pending` / `received` / `dropped` / `errors` |
+| `session.queryable(key, depth = 16, complete: false)` -> `Queryable` | `each_pending { \|q\| }` (each query finished after the block) or an Array of `Query` |
+| `q.key` / `params` / `payload` / `attachment`, `q.reply([key,] payload, attachment: nil)`, `q.finish` / `finished?` | |
+| `session.liveliness(key)` -> `LivelinessToken` | `close` / `closed?` |
+| `session.liveliness_watch(key, depth = 16)` -> `LivelinessWatch` | `each_pending { \|key, alive\| }`; the tokens alive now come first |
+| `session.liveliness_get(key, timeout_ms = 2000)` -> `Get` | |
+| `session.poll(steps = 8)` / `closed?` / `close` / `zid` / `peers` | |
+| `Asterism::Zenoh::Error` | |
+| `CONNECT_TIMEOUT_MS`, `SEND_TIMEOUT_MS` (3000), `PEER` (true), `MAX_PEERS`, `C_VERSION` | `MAX_PEERS` is zenoh-c's `transport/unicast/max_sessions` (1000); `C_VERSION` stands for the mruby gem's `PICO_VERSION` |
+
+Keys come back as UTF-8 Strings, payloads and attachments as binary
+(ASCII-8BIT) Strings.
+
+`require "asterism/zenoh/global"` defines `Zenoh = Asterism::Zenoh` for
+those who want the short name; nothing defines it by default.
+
+## How receiving works
+
+zenoh-c runs the protocol on its own threads. Every subscriber, liveliness
+watch, queryable and get has a zenoh-c FIFO channel; the gem's callback in
+front of it (plain C: no Ruby, no GVL) counts what arrives and, when the
+channel is full, drops the oldest entry, like the mruby gem's ring. The
+application takes the entries out with `each_pending` / `each_reply` from
+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.
+
+## Behaviour kept from the mruby gem
+
+- **No scouting**: 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?`
+  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).
+
+Differences: `C_VERSION` instead of `PICO_VERSION`; `MAX_PEERS` is zenoh-c's
+limit, not 3; the time limits of gets are kept by zenoh-c (exact, not
+checked once a second); liveliness watches may also report the session's
+own tokens.
+
+## Installing
+
+```
+gem install asterism-zenoh       # or `gem install asterism`, which depends on it
+```
+
+Needs CRuby 3.2+ and a C compiler; nothing else (no Rust, no git, curl or
+unzip). `gem install` compiles the C extension against the official
+prebuilt zenoh-c release pinned in `ZENOH_C_PIN`:
+
+1. With `ZENOH_C_DIR` set (or `gem install asterism-zenoh --
+   --with-zenoh-c-dir=DIR`), that zenoh-c (its `include/` and `lib/`) is
+   used and nothing is downloaded.
+2. Otherwise extconf.rb downloads the release archive for the machine from
+   `https://github.com/eclipse-zenoh/zenoh-c/releases/download/<tag>/`
+   (Ruby's net/http; proxies from the usual environment variables), checks
+   it against the sha256 pinned for that machine, and unpacks `include/`
+   and the shared library with Ruby's zlib. An archive whose sha256 differs
+   is not used.
+3. Machines without a pinned release, and machines that cannot download
+   it, stop with what to do instead (`ZENOH_C_DIR`, or a mirror).
+
+Pinned machines: x86_64 and aarch64 Linux (glibc and musl), x86_64 and
+arm64 macOS. The glibc builds of zenoh-c need glibc 2.34 or newer (Ubuntu
+22.04, Debian 12 and later). macOS is handled by extconf (the dylib's install
+name is rewritten to `@rpath`) but has not been tested yet. `ASTERISM_ZENOH_C_MIRROR=<base>` downloads
+`<base>/<tag>/<asset>` instead (an http(s) or `file://` URL, or a local
+directory), for a mirror or a machine without access to GitHub.
+
+The installed gem has, in `lib/asterism/`, the extension, zenoh-c's shared
+library next to it (found through the rpath: `$ORIGIN` on Linux,
+`@loader_path` on macOS), and `zenoh-c/` with the text of the Apache
+License 2.0, zenoh-c's NOTICE.md and `SOURCE` (which archive was used, and
+its sha256). The downloaded archive is not kept. `gem uninstall` removes
+all of it.
+
+## Building and testing
+
+In the repository (needs CRuby 3.2+ and a C compiler):
+
+```
+rake                  # zenoh_c:fetch, compile, test
+rake zenoh_c:fetch    # download the release pinned in ZENOH_C_PIN to vendor/zenoh-c (sha256 checked)
+rake compile          # build lib/asterism/asterism_zenoh.so (+ libzenohc.so)
+rake test             # two sessions over a local peer link; no router needed
+ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 rake test   # the same through a zenohd router
+ZENOH_C_DIR=/path/to/zenoh-c rake compile           # use another zenoh-c (include/ and lib/)
+rake gem              # build pkg/asterism-zenoh-<version>.gem
+```
+
+`rake zenoh_c:fetch` uses the same code as the installation
+(`ext/asterism_zenoh/zenoh_c.rb`). The extension links zenoh-c's shared
+library, which `rake compile` copies next to it, so `ruby -I lib` works
+without installing anything.
+
+The object layer, the ROS 2 node and the message types on top of this
+binding are the `asterism` gem
+([ruby-asterism/asterism](https://github.com/ruby-asterism/asterism)).
+
+## License
+
+MIT (see LICENSE) for everything in this repository except
+`licenses/zenoh-c/` (zenoh-c's notices and the Apache License text, below).
+The C extension
+(`ext/asterism_zenoh/zenoh.c`) is this gem's own code: it calls zenoh-c's
+API and copies no code from zenoh-c's examples or headers.
+
+### zenoh-c is not in this repository or in the gem file
+
+[zenoh-c](https://github.com/eclipse-zenoh/zenoh-c) (Eclipse Zenoh's C
+binding, Copyright ZettaScale Technology) is offered under the Eclipse
+Public License 2.0 or the Apache License, Version 2.0 (EPL-2.0 OR
+Apache-2.0). This gem uses it under the **Apache License, Version 2.0**.
+Neither this repository nor the gem file contains it: `gem install` (and
+`rake zenoh_c:fetch`) downloads the official prebuilt release pinned in
+`ZENOH_C_PIN` (sha256 checked) on the user's machine, from zenoh-c's own
+GitHub releases (or a mirror the user names).
+
+The prebuilt release archives contain only `include/` and `lib/`, not
+zenoh-c's LICENSE or NOTICE.md. So the gem carries, in `licenses/zenoh-c/`,
+the text of the Apache License, Version 2.0 (`LICENSE-APACHE`) and zenoh-c's
+NOTICE.md at the pinned tag, unchanged, and installs both next to the
+shared library (`lib/asterism/zenoh-c/`). The gemspec lists `MIT` and
+`Apache-2.0`: MIT for this gem's own code, Apache-2.0 for zenoh-c, which
+the installed gem holds.
+
+### Distribution notes
+
+A package that **carries** zenoh-c itself (a prebuilt, platform-specific
+gem with the shared library inside, a container image, an archive of an
+installed gem or a built `lib/`) is a redistribution of zenoh-c under the
+Apache License, Version 2.0, and must carry:
+
+- the text of the Apache License, Version 2.0, and zenoh-c's NOTICE.md
+  (its notices, including the Eclipse trademark notice), unchanged: the
+  installed `lib/asterism/zenoh-c/` has both;
+- the licenses and notices of the Rust crates compiled into the shared
+  library (zenoh and its dependencies, listed in zenoh-c's Cargo.lock;
+  zenoh-c's NOTICE.md does not list them). Collect them from that
+  Cargo.lock for the pinned release with a tool such as cargo-about
+  before publishing such a package.

data/ZENOH_C_PIN

@@ -0,0 +1,31 @@
+# Pinned zenoh-c (Eclipse Zenoh's C binding of the Rust implementation), used
+# by the asterism-zenoh gem (the CRuby Asterism::Zenoh).
+# Same scheme as ZENOH_PICO_PIN of picoruby-asterism-zenoh:
+# - At `gem install`, extconf.rb downloads the official prebuilt release for
+#   the machine (asset.<platform> below) from <repo>/releases/download/<tag>/,
+#   checks its sha256 and builds the extension against it
+#   (ext/asterism_zenoh/zenoh_c.rb). `rake zenoh_c:fetch` does the same into
+#   vendor/zenoh-c (gitignored) for working in the repository. Nothing is
+#   built with Rust.
+# - Upstream tag 1.10.1: the same number as zenoh-pico (the boards, pinned
+#   in picoruby-asterism-zenoh) and the zenohd router used in the tests of
+#   the Family mruby project. Zenoh keeps the wire compatible within 1.x;
+#   keep them together anyway.
+# - <platform> is <cpu>-<os> as ZenohCFetch.platform_key names this machine.
+#   The sha256 values were computed from the downloaded archives and agree
+#   with the digests GitHub lists for the release assets.
+# - To update: bump the tag, the asset names and their sha256 here.
+repo: https://github.com/eclipse-zenoh/zenoh-c
+tag: 1.10.1
+asset.x86_64-linux: zenoh-c-1.10.1-x86_64-unknown-linux-gnu-standalone.zip
+sha256.x86_64-linux: 9ee0f2d732b0f3042a7e1cd3076042a2bc3ac0415587c40bc3ed7b8b62fbde11
+asset.aarch64-linux: zenoh-c-1.10.1-aarch64-unknown-linux-gnu-standalone.zip
+sha256.aarch64-linux: 65970bbed6dc10fec4fa39d05f3876e85fcb9b0f87d5be0a54bd7517240db501
+asset.x86_64-linux-musl: zenoh-c-1.10.1-x86_64-unknown-linux-musl-standalone.zip
+sha256.x86_64-linux-musl: 293866bb632fd579fb0603bbfdb8d383e7c2d4eadc8ec3ae199fafa1dbc99c55
+asset.aarch64-linux-musl: zenoh-c-1.10.1-aarch64-unknown-linux-musl-standalone.zip
+sha256.aarch64-linux-musl: de99cc82c7ae93eaa2aa5a0c8bcfcefed7624b0e0f85c679f7dba9c54ccdff9c
+asset.x86_64-darwin: zenoh-c-1.10.1-x86_64-apple-darwin-standalone.zip
+sha256.x86_64-darwin: 6578ef42b0460a0522e7af4b1baa965ec75ce39f4c652cdd938252fdf6695219
+asset.aarch64-darwin: zenoh-c-1.10.1-aarch64-apple-darwin-standalone.zip
+sha256.aarch64-darwin: 82da6e95eb895413369f55d1a53eb5b621b22ab8afc446b041b7760eec240ff4

data/ext/asterism_zenoh/extconf.rb

@@ -0,0 +1,98 @@
+# Builds the C extension of asterism-zenoh against a prebuilt zenoh-c.
+#
+# Where zenoh-c comes from:
+# 1. ZENOH_C_DIR (or `gem install asterism-zenoh -- --with-zenoh-c-dir=DIR`):
+#    a zenoh-c of your own, its include/ and lib/. The Rakefile passes its
+#    vendor/zenoh-c this way.
+# 2. Otherwise the official prebuilt release pinned in ZENOH_C_PIN for this
+#    machine is downloaded and checked against the pinned sha256
+#    (zenoh_c.rb). Machines without a pinned release, and machines that
+#    cannot download it, stop here with what to do instead.
+#
+# zenoh-c is linked as a shared library. `make install` puts it next to the
+# extension (lib/asterism/ of the installed gem), with the text of the
+# Apache License 2.0 and zenoh-c's NOTICE.md in lib/asterism/zenoh-c/; the
+# extension finds it through its rpath ($ORIGIN on Linux, @loader_path on
+# macOS). Uninstalling the gem removes all of it.
+require "mkmf"
+require_relative "zenoh_c"
+
+LIB = ZenohCFetch.lib_name
+DARWIN = RbConfig::CONFIG["host_os"].match?(/darwin/)
+LICENSES = File.expand_path("../../licenses/zenoh-c", __dir__)
+STAMP = ".zenoh-c-installed"
+
+zdir = with_config("zenoh-c-dir") || ENV["ZENOH_C_DIR"]
+if zdir && !zdir.empty?
+  zdir = File.expand_path(zdir)
+  source = "zenoh-c from ZENOH_C_DIR (not fetched by this gem)\n"
+  fetched = false
+  message "using zenoh-c in #{zdir}\n"
+else
+  zdir = File.expand_path("zenoh-c")
+  begin
+    got = ZenohCFetch.fetch(zdir)
+  rescue ZenohCFetch::Error => e
+    abort "asterism-zenoh: #{e.message}"
+  end
+  source = got.map { |k, v| "#{k}: #{v}\n" }.join
+  fetched = true
+  message "fetched zenoh-c #{got['tag']} (#{got['platform']}), sha256 #{got['sha256']} OK\n"
+end
+inc = File.join(zdir, "include")
+lib = File.join(zdir, "lib")
+unless File.exist?(File.join(inc, "zenoh.h")) && File.exist?(File.join(lib, LIB))
+  abort "asterism-zenoh: zenoh-c not found in #{zdir} (needs include/zenoh.h and lib/#{LIB}).\n" +
+        ZenohCFetch.help
+end
+File.write("zenoh-c-SOURCE", source)
+
+$INCFLAGS << " -I#{inc}"
+$CFLAGS << " -std=gnu11 -Wall -Wno-unused-parameter"
+$LDFLAGS << " -L#{lib}"
+$LDFLAGS << (DARWIN ? " -Wl,-rpath,@loader_path" : " -Wl,-rpath,'$$ORIGIN'")
+have_library("pthread") || abort("asterism-zenoh: pthread is needed")
+have_library("zenohc", "z_open", "zenoh.h") || abort("asterism-zenoh: cannot link #{lib}/#{LIB}")
+
+create_makefile("asterism/asterism_zenoh")
+
+# The prebuilt dylib names itself by the path it was built at; refer to it
+# through the rpath instead (and sign the changed bundle again).
+postlink = []
+if DARWIN
+  id = `otool -D #{lib}/#{LIB}`.lines.last.to_s.strip
+  abort "asterism-zenoh: cannot read the install name of #{lib}/#{LIB} (otool)" if id.empty?
+  unless id.start_with?("@rpath/")
+    postlink << "\t$(Q) install_name_tool -change '#{id}' '@rpath/#{LIB}' $@"
+    postlink << "\t-$(Q) codesign --force --sign - $@"
+  end
+end
+
+mk = File.read("Makefile")
+unless postlink.empty?
+  mk.sub!(/^(\$\(TARGET_SO\):.*\n(?:\t.*\n)*?\t.*\$\(LDSHARED\).*\n)/) { $1 + postlink.join("\n") + "\n" } or
+    abort "asterism-zenoh: no link rule in the Makefile"
+end
+mk << <<~MAKE
+
+  # zenoh-c next to the extension, with its license text and notices.
+  ZENOHC_LIB = #{lib}/#{LIB}
+  ZENOHC_DOCS = #{LICENSES}/LICENSE-APACHE #{LICENSES}/NOTICE.md
+  install-so: install-zenoh-c
+  install-zenoh-c: $(TARGET_SO)
+  \t$(Q) $(MAKEDIRS) $(RUBYARCHDIR)/zenoh-c
+  \t$(INSTALL_PROG) $(ZENOHC_LIB) $(RUBYARCHDIR)
+  \t$(INSTALL_DATA) $(ZENOHC_DOCS) $(RUBYARCHDIR)/zenoh-c
+  \t$(INSTALL_DATA) zenoh-c-SOURCE $(RUBYARCHDIR)/zenoh-c/SOURCE
+MAKE
+if fetched
+  # RubyGems runs `make clean` before building and again after installing;
+  # the downloaded zenoh-c goes with the second one only.
+  mk << <<~MAKE
+    \t$(Q) touch #{STAMP}
+    clean: clean-zenoh-c
+    clean-zenoh-c:
+    \t-$(Q) if test -f #{STAMP}; then $(RM_RF) zenoh-c zenoh-c-SOURCE #{STAMP}; fi
+  MAKE
+end
+File.write("Makefile", mk)