libbeachcomber 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e3f8623a804a5828f59b45a4a7ed6bf284c95452033e3332f4b345efd402ddc
-  data.tar.gz: 207c9db90e610f24f1b6a66622b8f8229426b5133ac14e23e6a3b3510cf9de31
+  metadata.gz: 8f5895c44fbc17e34a043845428bffda24b355679d6d02bfa322b81f90a732ca
+  data.tar.gz: c3b583ca4c94cf046a015c0ee914ae77113d83d670392bb9e5fd0a5e1b4d4529
 SHA512:
-  metadata.gz: 1691f1a84d23711074e4b9561aca4650a6ed1ba01439b1aac4ad3597ce1f1b9a5482959d232ef4bb8eba347f8beee185d764a1adff8fe0c2484b47344ed9500c
-  data.tar.gz: 8e603b6892e91b3c49b5b8ae98061050814b5a0524db9295f62cd7540c600a342a0d3d59a3eda066fde66999253bf22ea3943eb87e6ba3436a06f88c95999578
+  metadata.gz: fe43031c1ea0b00bab8a280fa61bcef5de14473b88e2c036d3af9063945bde5e87f3858d37fa6a48954d567551c1568831c05655140063cda6f0c5aa1f1a39ba
+  data.tar.gz: 71baf44b81f858af49b1dc2db54f3949f5003d0b00ab4f02add2e3b193155748dec8ca1c3154d491a46e69aaa9825c47898efa493a2b2a06ba433897dbb1f328

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/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.0
+  version: 0.6.0
 platform: ruby
 authors:
 - NavistAu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-14 00:00:00.000000000 Z
+date: 2026-05-28 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