asterism 0.7.1 → 0.9.0

data/mrblib/credentials.rb

@@ -0,0 +1,197 @@
+# The credentials of one node or router as one file: the .tar an Asterism
+# console hands out when it issues a certificate ("Save all (.tar)" on the
+# certificate page; the archive is made in the browser that made the key).
+# It holds, at its top or in one directory:
+#
+#   <name>.key      the private key (PKCS#8 PEM)
+#   <name>.pem      the certificate (its common name is <name>)
+#   ca.pem          the CA that signed it (and the router's certificate)
+#   zenoh.json5     an example configuration (for zenohd or another client)
+#   asterism.json   {"name": ..., "router": "tls/host:port", "not_after": ..., ...}
+#
+#   Asterism.connect(credentials: "/home/asterism/alice.tar", app: "game")
+#
+# The certificates go to zenoh as base64 (transport/link/tls/*_base64) with
+# enable_mtls, and the router's locator and the node ID come from
+# asterism.json unless given. This is the portable part, in plain Ruby for
+# the boards (mruby / PicoRuby: no Regexp, no pack, no File.binread): the
+# file is read whole and the tar taken apart with byteslice / getbyte.
+# CRuby replaces the reading and adds checks (lib/asterism/cruby/credentials.rb:
+# the standard library's tar reader, file modes, the key pair).
+module Asterism
+  class Credentials
+    # What a credentials file is missing or holds wrong.
+    class Error < ::Asterism::Error; end
+
+    TLS = "transport/link/tls"
+    # The largest file read (the real ones are a few KB).
+    MAX_SIZE = 1024 * 1024
+    BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+    attr_reader :path, :name, :kind, :router, :not_after, :key_pem, :cert_pem, :ca_pem, :info
+
+    # Reads path (a String of a .tar). warn: false skips the check of who
+    # may read the file (CRuby; the boards have no file modes).
+    def self.load(path, warn: true)
+      new(path, warn: warn)
+    end
+
+    # A credentials file (a path or a Credentials) and the arguments of a
+    # connection -> [locator, config Hash, credentials]. The locator given
+    # wins over asterism.json's router; config given (a Hash) is laid over
+    # the TLS keys. @api private
+    def self.merge(credentials, locator, config)
+      creds = credentials.is_a?(Credentials) ? credentials : load(credentials)
+      if config.is_a?(String)
+        raise ArgumentError, "credentials: and a config String cannot be combined; pass config: as a Hash"
+      end
+      merged = creds.zenoh_config
+      (config || {}).each { |k, v| merged[k] = v }
+      [locator || creds.router, merged, creds]
+    end
+
+    # {basename => content} of the regular files of a ustar archive (data,
+    # a String of its bytes), at its top or in one directory. @api private
+    def self.untar(data, path = "the file")
+      files = {}
+      pos = 0
+      total = data.bytesize
+      while pos + 512 <= total
+        break if data.getbyte(pos) == 0 # the end: blocks of zeros
+        name = field(data, pos, 100)
+        prefix = field(data, pos + 345, 155)
+        size_text = field(data, pos + 124, 12).strip
+        type = data.getbyte(pos + 156)
+        size = size_text.empty? ? 0 : size_text.to_i(8)
+        pos += 512
+        raise Error, "#{path}: not a tar file (a member runs past the end)" if pos + size > total
+        if type == 48 || type == 0 # '0' or NUL: a regular file
+          full = prefix.empty? ? name : "#{prefix}/#{name}"
+          base = full.split("/").last.to_s
+          raise Error, "#{path}: #{base} is in it twice" if files.key?(base)
+          files[base] = data.byteslice(pos, size) unless base.empty?
+        end
+        pos += (size + 511) / 512 * 512
+      end
+      raise Error, "#{path}: not a tar file with credentials in it" if files.empty?
+      files
+    end
+
+    # The text of a NUL-terminated header field. @api private
+    def self.field(data, pos, len)
+      n = 0
+      n += 1 while n < len && data.getbyte(pos + n) != 0
+      data.byteslice(pos, n).to_s
+    end
+
+    # base64 of s without line breaks (CRuby's [s].pack("m0")). @api private
+    def self.base64(s)
+      out = ""
+      n = s.bytesize
+      i = 0
+      while i < n
+        b0 = s.getbyte(i)
+        b1 = i + 1 < n ? s.getbyte(i + 1) : 0
+        b2 = i + 2 < n ? s.getbyte(i + 2) : 0
+        v = (b0 << 16) | (b1 << 8) | b2
+        out << BASE64[(v >> 18) & 63] << BASE64[(v >> 12) & 63]
+        out << (i + 1 < n ? BASE64[(v >> 6) & 63] : "=")
+        out << (i + 2 < n ? BASE64[v & 63] : "=")
+        i += 3
+      end
+      out
+    end
+
+    # The string fields of asterism.json without a JSON library (only for
+    # a build that has none). @api private
+    def self.json_strings(text)
+      h = {}
+      %w[format name kind router serial not_after fingerprint console issued_at].each do |k|
+        key = "\"#{k}\""
+        i = text.index(key)
+        next unless i
+        rest = text[i + key.size, text.size - i - key.size].to_s
+        colon = rest.index(":")
+        next unless colon
+        q1 = colon + 1
+        q1 += 1 while rest[q1] == " "
+        next unless rest[q1] == "\""
+        q2 = rest.index("\"", q1 + 1)
+        next unless q2
+        h[k] = rest[q1 + 1, q2 - q1 - 1]
+      end
+      h
+    end
+
+    def initialize(path, warn: true)
+      @path = path.to_s
+      check_mode if warn
+      files = read_tar
+      @info = parse_info(files["asterism.json"])
+      keys = files.keys.select { |f| f.end_with?(".key") }
+      raise Error, "#{@path}: no private key (<name>.key) in it" if keys.empty?
+      raise Error, "#{@path}: more than one private key in it (#{keys.sort.join(', ')})" if keys.size > 1
+      @name = @info["name"].to_s
+      @name = keys.first[0, keys.first.size - 4] if @name.empty?
+      @key_pem = files["#{@name}.key"] or raise Error, "#{@path}: the key is not named after #{@name} (#{keys.first})"
+      @cert_pem = files["#{@name}.pem"] or raise Error, "#{@path}: no certificate #{@name}.pem in it"
+      @ca_pem = files["ca.pem"] or raise Error, "#{@path}: no ca.pem in it"
+      @kind = @info["kind"]
+      @router = @info["router"].to_s.empty? ? nil : @info["router"].to_s
+      @not_after = @info["not_after"]
+      check_pair
+    end
+
+    # The zenoh configuration keys (a Hash for Session.open's config:):
+    # the CA, the certificate and the key as base64, and mutual TLS.
+    def zenoh_config
+      {
+        "#{TLS}/root_ca_certificate_base64" => b64(@ca_pem),
+        "#{TLS}/connect_certificate_base64" => b64(@cert_pem),
+        "#{TLS}/connect_private_key_base64" => b64(@key_pem),
+        "#{TLS}/enable_mtls" => true
+      }
+    end
+
+    def inspect
+      "#<Asterism::Credentials #{@name} #{@router || '(no router)'}#{@not_after ? " until #{@not_after}" : ''}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def b64(pem)
+      Credentials.base64(pem)
+    end
+
+    # The boards have no file modes (CRuby warns like ssh).
+    def check_mode; end
+
+    # The key pair is checked by CRuby (openssl); on the boards the router
+    # refuses a wrong one.
+    def check_pair; end
+
+    def read_tar
+      data = begin
+        ::File.open(@path, "r") { |f| f.read }
+      rescue StandardError => e
+        raise Error, "#{@path}: #{e.message}"
+      end
+      raise Error, "#{@path}: cannot be read" if data.nil?
+      raise Error, "#{@path}: too large for a credentials file" if data.bytesize > MAX_SIZE
+      Credentials.untar(data, @path)
+    end
+
+    def parse_info(text)
+      return {} if text.nil?
+      return Credentials.json_strings(text) unless Object.const_defined?(:JSON)
+      h = ::JSON.parse(text)
+      raise Error, "#{@path}: asterism.json is not an object" unless h.is_a?(Hash)
+      h
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "#{@path}: asterism.json: #{e.message}"
+    end
+  end
+end

data/mrblib/status.rb

@@ -0,0 +1,198 @@
+# An application's status: a small Hash of its own that changes while it
+# runs (how many tables are open, who is seated, a battery level), told by
+# the application itself.
+#
+#   Asterism.status(tables: 3, humans: 2)      # sets those fields, keeps the others
+#   Asterism.status({ "mahjong1" => {...} })   # the whole status (a Hash)
+#   Asterism.status                            # => {"tables" => 3, ...} or nil
+#   Asterism.status_of("games", "games")       # another application's, or nil
+#
+# Key: asterism/<node>/<app>/@status (docs/protocol.md 8). The application
+# answers queries there with its status, and puts it on the same key when
+# it changes (only then: the same status again puts nothing), at connect
+# and after a lost connection comes back. An application that never set a
+# status declares nothing there and answers nothing.
+#
+# The value is a MessagePack map with str keys; the values are any values
+# of the protocol nested at most MAX_DEPTH levels below the map, and the
+# whole map packs into MAX_BYTES at most. It is not the profile
+# (profile.rb): a profile says once what a node is; a status changes.
+module Asterism
+  module Status
+    KEY = "@status"
+    MAX_BYTES = 1024  # the packed map
+    MAX_DEPTH = 4     # levels of arrays and maps below the map
+
+    # A received status, cleaned: the entries with a non-empty str key; nil
+    # when it is not a map or packs into more than MAX_BYTES.
+    def self.check(h)
+      return nil unless h.is_a?(Hash)
+      out = {}
+      h.each { |k, v| out[k] = v if k.is_a?(String) && !k.empty? }
+      begin
+        return nil if ::MessagePack.pack(out).bytesize > MAX_BYTES
+      rescue
+        return nil
+      end
+      out
+    end
+
+    # [node, app, status] of a notice put on asterism/<node>/<app>/@status
+    # (key and payload as a subscriber gets them), or nil when it is not one.
+    def self.parse(key, payload)
+      parts = key.to_s.split("/")
+      return nil unless parts.size == 4 && parts[0] == ROOT && parts[3] == KEY
+      st = check(Codec.unpack(payload))
+      st ? [parts[1], parts[2], st] : nil
+    end
+
+    # The checks of Asterism.status: a copy with String keys, or
+    # ArgumentError with the reason.
+    # @api private
+    def self.check!(h)
+      raise ArgumentError, "status: expected a Hash, got #{h.class}" unless h.is_a?(Hash)
+      out = {}
+      h.each do |k, v|
+        key = k.is_a?(Symbol) ? k.to_s : k
+        unless key.is_a?(String) && !key.empty?
+          raise ArgumentError, "status: the keys are Strings or Symbols (not empty), got #{k.inspect}"
+        end
+        raise ArgumentError, "status #{key}: nested deeper than #{MAX_DEPTH} levels" if too_deep?(v, 1)
+        begin
+          out[key] = Codec.check(v)
+        rescue EncodeError => e
+          raise ArgumentError, "status #{key}: #{e.message}"
+        end
+      end
+      n = Codec.pack(out).bytesize
+      raise ArgumentError, "status: #{n} bytes packed (#{MAX_BYTES} at most)" if n > MAX_BYTES
+      out
+    end
+
+    # @api private
+    def self.too_deep?(v, level)
+      if v.is_a?(Array) || v.is_a?(Hash)
+        return true if level > MAX_DEPTH
+        if v.is_a?(Array)
+          v.each { |e| return true if too_deep?(e, level + 1) }
+        else
+          v.each { |k, e| return true if too_deep?(k, level + 1) || too_deep?(e, level + 1) }
+        end
+      end
+      false
+    end
+  end
+
+  # This application's status. With a Hash, it is the whole status; with
+  # keywords, those fields change (nil removes one) and the others stay;
+  # both: the keywords on top of the Hash. Returns the status. Without
+  # arguments, returns it (nil when none was set). Raises ArgumentError for
+  # a status it does not accept (see Asterism::Status).
+  #
+  # Kept across connect and close (it belongs to the process, or the VM on
+  # a board). While connected, a change is put on asterism/<node>/<app>/@status;
+  # setting the same status again puts nothing.
+  def self.status(h = nil, **fields)
+    if h.nil? && fields.empty?
+      return @status ? @status.dup : nil
+    end
+    base = h.nil? ? (@status ? @status.dup : {}) : Status.check!(h)
+    fields.each do |k, v|
+      if v.nil?
+        base.delete(k.to_s)
+      else
+        base[k.to_s] = v
+      end
+    end
+    @status = Status.check!(base)
+    tell_status(false)
+    @status.dup
+  end
+
+  # Another application's status (Asterism::Status.check has cleaned it),
+  # or nil when it does not answer in time (no status set, an older
+  # version of Asterism, an application that is gone). timeout: in seconds
+  # (or timeout_ms:), 2.0 by default. Waits like a call (polling, answering
+  # calls meanwhile); raises Disconnected when not connected. This
+  # application's own status comes without the network.
+  def self.status_of(node, app, timeout: nil, timeout_ms: nil)
+    f = status_async(node, app, timeout, timeout_ms)
+    begin
+      raw = f.raw_value
+    rescue Disconnected
+      raise
+    rescue Error
+      return nil # no answer in time, or not MessagePack
+    end
+    Status.check(raw)
+  end
+
+  # @api private
+  def self.status_async(node, app, timeout, timeout_ms)
+    node = check_name("node", node)
+    app = check_name("app", app)
+    ms = time_ms("Asterism.status_of", timeout, timeout_ms, nil, DEFAULT_TIMEOUT_MS)
+    path = "#{node}/#{app}/#{Status::KEY}"
+    if @session && node == @node && app == @app
+      return Future.answered(path, "status", Codec.pack(@status)) if @status
+      return Future.answered(path, "status", Codec.pack(nil))
+    end
+    begin
+      g = session!.get("#{ROOT}/#{path}", timeout_ms: ms)
+    rescue Asterism::Zenoh::Error => e
+      lost_if_closed(e.message)
+      raise Disconnected, e.message
+    end
+    Future.new(path, "status", g, now_ms + ms, ms)
+  end
+
+  # The applications alive now ("<node>/<app>", from their liveliness
+  # tokens; this one included) whose path matches the pattern (* is one
+  # chunk, ** any number).
+  def self.apps(pattern = "*/*")
+    list = []
+    return list unless @session
+    own = "#{@node}/#{@app}"
+    list << own if glob?(pattern, own)
+    @apps.each_key { |path| list << path if path != own && glob?(pattern, path) }
+    list
+  end
+
+  # Puts the status on its key while connected: when it changed since the
+  # last put of this connection, or always with force (a connection that
+  # came back). Declares the status queryable with the first put.
+  # @api private
+  def self.tell_status(force)
+    s = @session
+    return unless s && @status
+    bytes = Codec.pack(@status)
+    return if !force && !@status_put.nil? && @status_put == bytes
+    key = "#{ROOT}/#{@node}/#{@app}/#{Status::KEY}"
+    @status_queryable ||= s.queryable(key, depth: 4)
+    s.put(key, bytes)
+    @status_put = bytes
+  rescue Asterism::Zenoh::Error
+    nil # the next poll notices a lost connection
+  end
+
+  # @api private
+  def self.answer_status
+    qa = @status_queryable
+    return unless qa && qa.pending > 0
+    queries = qa.each_pending
+    i = 0
+    while i < queries.size
+      q = queries[i]
+      i += 1
+      begin
+        q.reply("#{ROOT}/#{@node}/#{@app}/#{Status::KEY}", Codec.pack(@status || {}))
+      ensure
+        begin
+          q.finish
+        rescue Asterism::Zenoh::Error
+          # the session went away meanwhile
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asterism
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Katsuhiko Kageyama
 autorequire: 
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2026-10-13 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asterism-zenoh
@@ -48,7 +48,8 @@ description: Proxies for objects exposed by other Ruby processes and boards, a R
   2 node speaking rmw_zenoh's wire format, CDR and generated message types. Pure Ruby;
   the same files are the mrbgem for mruby / PicoRuby.
 email: 
-executables: []
+executables:
+- asterism
 extensions: []
 extra_rdoc_files: []
 files:
@@ -144,7 +145,17 @@ files:
 - data/msgs/visualization_msgs/msg/MarkerArray.rb
 - data/msgs/visualization_msgs/msg/MeshFile.rb
 - data/msgs/visualization_msgs/msg/UVCoordinate.rb
+- exe/asterism
 - lib/asterism.rb
+- lib/asterism/cli.rb
+- lib/asterism/cli/allow.rb
+- lib/asterism/cli/complete.rb
+- lib/asterism/cli/hz.rb
+- lib/asterism/cli/literal.rb
+- lib/asterism/cli/mcp.rb
+- lib/asterism/cli/nouns.rb
+- lib/asterism/cli/survey.rb
+- lib/asterism/cli/text.rb
 - lib/asterism/cruby.rb
 - lib/asterism/cruby/credentials.rb
 - lib/asterism/cruby/objects.rb
@@ -154,10 +165,12 @@ files:
 - lib/asterism/version.rb
 - mrblib/asterism.rb
 - mrblib/cdr.rb
+- mrblib/credentials.rb
 - mrblib/future.rb
 - mrblib/profile.rb
 - mrblib/proxy.rb
 - mrblib/ros.rb
+- mrblib/status.rb
 - tools/asterism_msggen.rb
 homepage: https://github.com/ruby-asterism/asterism
 licenses: