libbeachcomber 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65ff0e037911901a14cbb995047fe1c36ae9a8a3e9702b3483f8c39956a37725
-  data.tar.gz: d59492cc46a941bcfa704a095ac66dc9ee3af4dd680e91d8c241d88336b7dd98
+  metadata.gz: 49948fed9514c126aa098f0d469d9d00b455dfee1e295734459aa19d3d5e72be
+  data.tar.gz: 8d0ae8bc11f78cada0741b3cd2a668dc1a97d2a68299ca9fc37acb1d6a2806ba
 SHA512:
-  metadata.gz: bd86083b020f22e8503e3a5560c8bc2783a7c3a4248df69ce8da147b65a536832f4c689d91604f4ae27c12be340fd4829923df8c2e6044aa3d60ad676989f8d6
-  data.tar.gz: 77253cc43d62a984d64f99401c1f26e21007ce2cb369c2b7959d972ff5d19feece7d6e831dfafcff9bcf583c91f3666ba29c82e66e630ac9ee45450ccd9dd982
+  metadata.gz: a6e7f9bfbd336707802e4d45b9a797cf2ba6ee393fded7e674932a87be8d37169709af1142a0620b5087be38b6a3a7d47f26e5750e422cd0786bcb203f327c67
+  data.tar.gz: 62d84ba78bd44bcdff01f7ec990b5f3ba6ffa8760de1f7d8f83ed9b58c6682f79e51c756b401f5f0e96baa9957cee0991e3b5654196d0506efc1c4e39319d2f1

data/lib/beachcomber/client.rb

@@ -44,29 +44,74 @@ module Beachcomber
       roundtrip(req)
     end
 
+    # Reads a cached value with protocol flags.
+    #
+    # @param key [String]
+    # @param path [String, nil]
+    # @param force [Boolean] bypass cache and recompute
+    # @param wait [Boolean] block until a fresh value is available
+    # @return [Result]
+    def get_with_flags(key, path: nil, force: false, wait: false)
+      req = { op: 'get', key: key }
+      req[:path]  = path if path
+      req[:force] = true if force
+      req[:wait]  = true if wait
+      roundtrip(req)
+    end
+
     # Forces the daemon to recompute a provider/key.
     #
     # @param key [String]
     # @param path [String, nil]
-    def poke(key, path: nil)
-      req = { op: 'poke', key: key }
+    def refresh(key, path: nil)
+      req = { op: 'refresh', key: key }
       req[:path] = path if path
       roundtrip(req)
       nil
     end
 
-    # Lists available providers.
+    # Returns cache rows from the daemon.
     #
-    # @return [Result]
-    def list
-      roundtrip({ op: 'list' })
+    # @return [Array<CacheRow>]
+    def status
+      resp_obj = roundtrip_raw({ op: 'status' })
+      parse_cache_rows(resp_obj)
     end
 
-    # Returns daemon status.
+    # Sends a hello handshake and returns server info.
     #
-    # @return [Result]
-    def status
-      roundtrip({ op: 'status' })
+    # @return [HelloInfo]
+    def hello
+      resp = roundtrip_raw({ op: 'hello' })
+      parse_hello(resp)
+    end
+
+    # Writes a value into the daemon cache.
+    #
+    # @param key [String]
+    # @param data [Object, nil]
+    # @param ttl [Numeric, nil] time-to-live in seconds
+    # @param path [String, nil]
+    # @return [nil]
+    def put(key, data = nil, ttl: nil, path: nil)
+      req = { op: 'put', key: key }
+      req[:data] = data unless data.nil?
+      req[:ttl]  = ttl  if ttl
+      req[:path] = path if path
+      roundtrip(req)
+      nil
+    end
+
+    # Introspects a daemon subsystem.
+    #
+    # @param subject [String] one of the IntrospectSubject constants
+    # @param duration_secs [Numeric, nil]
+    # @return [IntrospectResponse]
+    def introspect(subject, duration_secs: nil)
+      req = { op: 'introspect', subject: subject.to_s }
+      req[:duration_secs] = duration_secs if duration_secs
+      resp = roundtrip_raw(req)
+      parse_introspect(subject.to_s, resp)
     end
 
     # Closes the underlying socket connection.
@@ -77,15 +122,20 @@ module Beachcomber
     private
 
     def roundtrip(req)
+      resp = roundtrip_raw(req)
+      build_result(resp)
+    end
+
+    def roundtrip_raw(req)
       line = JSON.generate(req) + "\n"
       @socket.write(line)
       raw = @socket.gets
       raise ProtocolError, "connection closed before response" if raw.nil?
 
-      parse_response(raw.chomp)
+      parse_response_hash(raw.chomp)
     end
 
-    def parse_response(raw)
+    def parse_response_hash(raw)
       begin
         resp = JSON.parse(raw)
       rescue JSON::ParserError => e
@@ -96,17 +146,76 @@ module Beachcomber
         raise ProtocolError, "expected JSON object, got #{resp.class}"
       end
 
-      ok     = resp['ok']
-      data   = resp['data']
-      age_ms = (resp['age_ms'] || 0).to_i
-      stale  = resp['stale'] == true
-      error  = resp['error']
+      unless resp['ok']
+        raise ServerError, (resp['error'] || 'unknown error')
+      end
 
-      unless ok
-        raise ServerError, (error || 'unknown error')
+      resp
+    end
+
+    def build_result(resp)
+      Result.new(
+        ok:     resp['ok'],
+        data:   resp['data'],
+        age_ms: (resp['age_ms'] || 0).to_i,
+        stale:  resp['stale'] == true,
+        error:  resp['error'],
+      )
+    end
+
+    def parse_hello(resp)
+      data = resp["data"] || {}
+      HelloInfo.new(
+        protocol_version: data["protocol_version"].to_s,
+        daemon_version:   data["daemon_version"].to_s,
+      )
+    end
+
+    def parse_cache_rows(resp)
+      arr = resp["data"]
+      raise ProtocolError, "status data is not an array" unless arr.is_a?(Array)
+      arr.map do |row|
+        CacheRow.new(
+          provider:           row["provider"].to_s,
+          field:              row["field"],
+          path:               row["path"],
+          value:              row["value"],
+          age_ms:             Integer(row["age_ms"] || 0),
+          stale:              row["stale"] == true,
+          kind:               row["kind"],
+          poll_interval_secs: row["poll_interval_secs"],
+          keep_alive_polls:   row["keep_alive_polls"],
+          fsevents_reinstate: row["fsevents_reinstate"],
+          failure:            row["failure"],
+          source:             row["source"],
+        )
       end
+    end
 
-      Result.new(ok: ok, data: data, age_ms: age_ms, stale: stale, error: error)
+    def parse_daemon_health(data)
+      DaemonHealth.new(
+        pid:             Integer(data["pid"] || 0),
+        version:         data["version"].to_s,
+        uptime_secs:     Integer(data["uptime_secs"] || 0),
+        socket_path:     data["socket_path"].to_s,
+        config_path:     data["config_path"],
+        requests_total:  Integer(data["requests_total"] || 0),
+        in_flight:       Integer(data["in_flight"] || 0),
+        active_watchers: Integer(data["active_watchers"] || 0),
+        cache_entries:   Integer(data["cache_entries"] || 0),
+        verdicts: (data["verdicts"] || []).map do |v|
+          Verdict.new(level: v["level"].to_s, message: v["message"].to_s)
+        end,
+      )
+    end
+
+    def parse_introspect(subject, resp)
+      data = resp["data"]
+      if subject == IntrospectSubject::DAEMON && data.is_a?(Hash)
+        IntrospectResponse.new(subject: subject, daemon: parse_daemon_health(data), other: nil)
+      else
+        IntrospectResponse.new(subject: subject, daemon: nil, other: data)
+      end
     end
   end
 
@@ -137,7 +246,18 @@ module Beachcomber
     def get(key, path: nil)
       req = { op: 'get', key: key }
       req[:path] = path if path
-      roundtrip(req)
+      with_session { |s| s.send(:roundtrip, req) }
+    end
+
+    # Reads a cached value with protocol flags.
+    #
+    # @param key [String]
+    # @param path [String, nil]
+    # @param force [Boolean] bypass cache and recompute
+    # @param wait [Boolean] block until a fresh value is available
+    # @return [Result]
+    def get_with_flags(key, path: nil, force: false, wait: false)
+      with_session { |s| s.get_with_flags(key, path: path, force: force, wait: wait) }
     end
 
     # Forces the daemon to recompute a provider/key.
@@ -146,25 +266,59 @@ module Beachcomber
     # @param path [String, nil]
     # @raise [DaemonNotRunning]
     # @raise [ServerError]
-    def poke(key, path: nil)
-      req = { op: 'poke', key: key }
+    def refresh(key, path: nil)
+      req = { op: 'refresh', key: key }
       req[:path] = path if path
-      roundtrip(req)
+      with_session { |s| s.send(:roundtrip, req) }
       nil
     end
 
-    # Lists available providers registered with the daemon.
+    # Returns cache rows from the daemon.
     #
-    # @return [Result]
-    def list
-      roundtrip({ op: 'list' })
+    # @return [Array<CacheRow>]
+    def status
+      with_session { |s| s.status }
     end
 
-    # Returns scheduler and cache status from the daemon.
+    # Sends a hello handshake and returns server info.
     #
-    # @return [Result]
-    def status
-      roundtrip({ op: 'status' })
+    # @return [HelloInfo]
+    def hello
+      with_session { |s| s.hello }
+    end
+
+    # Writes a value into the daemon cache.
+    #
+    # @param key [String]
+    # @param data [Object, nil]
+    # @param ttl [Numeric, nil] time-to-live in seconds
+    # @param path [String, nil]
+    # @return [nil]
+    def put(key, data = nil, ttl: nil, path: nil)
+      with_session { |s| s.put(key, data, ttl: ttl, path: path) }
+    end
+
+    # Introspects a daemon subsystem.
+    #
+    # @param subject [String] one of the IntrospectSubject constants
+    # @param duration_secs [Numeric, nil]
+    # @return [IntrospectResponse]
+    def introspect(subject, duration_secs: nil)
+      with_session { |s| s.introspect(subject, duration_secs: duration_secs) }
+    end
+
+    # Opens a persistent watch subscription. Returns a WatchStream (Enumerable).
+    # The caller is responsible for closing the stream.
+    #
+    # @param key [String]
+    # @param path [String, nil]
+    # @return [WatchStream]
+    def watch(key, path: nil)
+      sock = open_socket
+      req  = { op: 'watch', key: key }
+      req[:path] = path if path
+      sock.write(JSON.generate(req) + "\n")
+      WatchStream.new(sock)
     end
 
     # Opens a persistent session and yields it to the block. The connection is
@@ -173,40 +327,59 @@ module Beachcomber
     # @yield [Session]
     # @return the block's return value
     def session
-      sock    = dial
-      session = Session.new(sock, @timeout)
-      yield session
+      sock = open_socket
+      sess = Session.new(sock, @timeout)
+      yield sess
     ensure
-      session&.close
+      sess&.close
+    end
+
+    RETRY_BACKOFFS = [0.250, 0.500, 1.000].freeze
+
+    # Connect to a Unix socket with 3 retries (250ms/500ms/1s exponential).
+    # Retries on ECONNREFUSED and ENOENT only — other errors surface immediately.
+    # Intended to cover the brief restart window when the daemon is restarting.
+    #
+    # @param sock_path [String] absolute path to the Unix domain socket
+    # @return [UNIXSocket]
+    # @raise [Errno::ECONNREFUSED, Errno::ENOENT] after all retries are exhausted
+    def self._connect_with_retry(sock_path)
+      last_error = nil
+      RETRY_BACKOFFS.each do |backoff|
+        begin
+          return UNIXSocket.new(sock_path)
+        rescue Errno::ECONNREFUSED, Errno::ENOENT => e
+          last_error = e
+          sleep backoff
+        end
+      end
+      # Final attempt — raises if still failing.
+      UNIXSocket.new(sock_path)
     end
 
     private
 
-    def roundtrip(req)
-      sock = dial
+    def with_session(&block)
+      sock = open_socket
       begin
         s = Session.new(sock, @timeout)
-        s.send(:roundtrip, req)
+        block.call(s)
       ensure
         sock.close unless sock.closed?
       end
     end
 
-    def dial
-      sock = Socket.new(:UNIX, :STREAM)
-      addr = Socket.pack_sockaddr_un(@socket_path)
-
-      # Apply timeout to both connect and subsequent reads/writes.
-      sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, timeval(@timeout))
-      sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, timeval(@timeout))
-
+    def open_socket
       begin
-        sock.connect(addr)
-      rescue Errno::ENOENT, Errno::ECONNREFUSED, Errno::EACCES
-        sock.close
+        sock = self.class._connect_with_retry(@socket_path)
+      rescue Errno::ENOENT, Errno::ECONNREFUSED, Errno::EACCES => e
         raise DaemonNotRunning.new(@socket_path)
       end
 
+      # Apply timeouts to the connected socket.
+      sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, timeval(@timeout))
+      sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, timeval(@timeout))
+
       sock
     end
 

data/lib/beachcomber/discovery.rb

@@ -3,23 +3,25 @@ require 'etc'
 module Beachcomber
   # Discovers the Unix socket path for the beachcomber daemon.
   #
-  # Discovery order:
-  #   1. $XDG_RUNTIME_DIR/beachcomber/sock  (if set and the path exists)
-  #   2. $TMPDIR/beachcomber-<uid>/sock
+  # Mirrors the daemon's bind-path resolution (Config::resolve_socket_path),
+  # minus the config-file step which is daemon-only. Discovery order:
+  #   1. $BEACHCOMBER_SOCKET  (if set and non-empty)
+  #   2. $XDG_RUNTIME_DIR/beachcomber/sock  (if XDG_RUNTIME_DIR is set)
   #   3. /tmp/beachcomber-<uid>/sock
+  #
+  # There is no existence probe and $TMPDIR is not consulted: the result is the
+  # single path the daemon binds for the same environment. Non-standard setups
+  # point clients at the daemon via BEACHCOMBER_SOCKET.
   module Discovery
-    # @return [String] the discovered or best-guess socket path
+    # @return [String] the resolved socket path
     def self.socket_path
+      sock = ENV['BEACHCOMBER_SOCKET']
+      return sock if sock && !sock.empty?
+
       xdg = ENV['XDG_RUNTIME_DIR']
-      if xdg && !xdg.empty?
-        candidate = File.join(xdg, 'beachcomber', 'sock')
-        return candidate if File.exist?(candidate)
-      end
+      return File.join(xdg, 'beachcomber', 'sock') if xdg && !xdg.empty?
 
-      uid  = Process.uid
-      dir  = "beachcomber-#{uid}"
-      base = ENV.fetch('TMPDIR', nil) || '/tmp'
-      File.join(base, dir, 'sock')
+      File.join('/tmp', "beachcomber-#{Process.uid}", 'sock')
     end
   end
 end

data/lib/beachcomber/types.rb

@@ -0,0 +1,32 @@
+module Beachcomber
+  HelloInfo = Struct.new(:protocol_version, :daemon_version, keyword_init: true)
+  CacheRow = Struct.new(
+    :provider, :field, :path, :value, :age_ms, :stale,
+    :kind, :poll_interval_secs, :keep_alive_polls, :fsevents_reinstate, :failure,
+    :source,
+    keyword_init: true
+  )
+  Verdict = Struct.new(:level, :message, keyword_init: true)
+  DaemonHealth = Struct.new(
+    :pid, :version, :uptime_secs, :socket_path, :config_path,
+    :requests_total, :in_flight, :active_watchers, :cache_entries, :verdicts,
+    keyword_init: true
+  )
+  WatchEvent = Struct.new(:data, :age_ms, :stale, keyword_init: true)
+
+  module IntrospectSubject
+    DAEMON    = "daemon"
+    PROVIDERS = "providers"
+    CONFIG    = "config"
+    CACHE     = "cache"
+    LIFECYCLE = "lifecycle"
+    WATCHES   = "watches"
+    TIMERS    = "timers"
+    DEMAND    = "demand"
+    PROCS     = "procs"
+  end
+
+  # Introspect response wrapper. For DAEMON subject: #daemon is populated.
+  # For others: #other holds the raw Hash/Array.
+  IntrospectResponse = Struct.new(:subject, :daemon, :other, keyword_init: true)
+end

data/lib/beachcomber/watch_stream.rb

@@ -0,0 +1,50 @@
+module Beachcomber
+  class WatchStream
+    include Enumerable
+
+    def initialize(socket)
+      @socket = socket
+    end
+
+    # Yields a WatchEvent per emitted change.
+    def each
+      return enum_for(:each) unless block_given?
+      while (line = @socket.gets)
+        line.strip!
+        next if line.empty?
+        resp = JSON.parse(line)
+        unless resp["ok"]
+          raise ServerError, resp["error"] || "watch error"
+        end
+        yield WatchEvent.new(
+          data:   resp["data"],
+          age_ms: Integer(resp["age_ms"] || 0),
+          stale:  resp["stale"] == true,
+        )
+      end
+    end
+
+    # Read the next event; returns nil on connection close.
+    def next_event
+      loop do
+        line = @socket.gets
+        return nil if line.nil?
+        line.strip!
+        next if line.empty?
+        resp = JSON.parse(line)
+        unless resp["ok"]
+          raise ServerError, resp["error"] || "watch error"
+        end
+        return WatchEvent.new(
+          data:   resp["data"],
+          age_ms: Integer(resp["age_ms"] || 0),
+          stale:  resp["stale"] == true,
+        )
+      end
+    end
+
+    def close
+      @socket.close
+    end
+  end
+end

data/lib/beachcomber.rb

@@ -1,6 +1,8 @@
 require_relative 'beachcomber/errors'
 require_relative 'beachcomber/result'
+require_relative 'beachcomber/types'
 require_relative 'beachcomber/discovery'
+require_relative 'beachcomber/watch_stream'
 require_relative 'beachcomber/client'
 
 # Beachcomber is a Ruby client for the beachcomber daemon.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libbeachcomber
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - NavistAu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-21 00:00:00.000000000 Z
+date: 2026-05-29 00:00:00.000000000 Z
 dependencies: []
 description: Communicates with the beachcomber daemon over a Unix domain socket to
   query cached shell-environment data (git state, hostname, battery, etc.).
@@ -22,6 +22,8 @@ files:
 - lib/beachcomber/discovery.rb
 - lib/beachcomber/errors.rb
 - lib/beachcomber/result.rb
+- lib/beachcomber/types.rb
+- lib/beachcomber/watch_stream.rb
 homepage: https://github.com/NavistAu/beachcomber
 licenses:
 - MIT