libbeachcomber 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdf64a93d0d40da45446e6a7e4151cdf7e491365a3c38fc4c5a64832ecf46e2d
-  data.tar.gz: 241b2cf966cb502874f507dd8b702423a5bb5e202598f728abf3d0580fb4eabd
+  metadata.gz: 9913f2904d89a4bdff62c16c549796236c3b4ed9a12bcaed23d1eefbdd080a39
+  data.tar.gz: 50cf3b189a487242bd2e9259b41a41097bc58030e75bd731025db02a219a1f10
 SHA512:
-  metadata.gz: 99d78e72b22a5cbc0fef051fb231e8372f2803ec747b453ec598a843740c778d6ed4b0241cdf3182feb625d249a95010269e1901ef6131d31e242aee60741fff
-  data.tar.gz: a10938a4d29aa829b056528840ee18099cf3883bf95b34dd3d9f8bc1bab4a08e912c10495835a53fbd11e95e58f424e670b91eeda43006f57f6c04f36a3229f5
+  metadata.gz: b4eb991a7205ea712c21d7033d5a88335edd4f1599e53ea1a95ebd32d8d640110e1b22928a283d2c8e3ba367927d0beff54150bd1a54ccbef1bd52023340104e
+  data.tar.gz: 9ede8d2296696e916b499766a18394bce4e87a7948e082dd12a23ca30968572886cf1fae9608e8160657755936c532f95cd118f37b36467ded51bb2eb1328623

data/lib/beachcomber/client.rb

@@ -1,15 +1,101 @@
-require 'socket'
 require 'json'
 
-require_relative 'discovery'
+require_relative 'ffi'
 require_relative 'errors'
 require_relative 'result'
+require_relative 'types'
+require_relative 'watch_stream'
 
 module Beachcomber
-  DEFAULT_TIMEOUT = 0.1 # seconds (100 ms)
+  DEFAULT_TIMEOUT = 0.1 # seconds (100 ms) — matches libbeachcomber's own default.
 
-  # Session holds a persistent connection to the daemon and sends multiple
-  # requests over the same socket.
+  # Response-shaping helpers shared by Client and Session: the ABI's JSON
+  # payload shapes are identical regardless of which handle made the call.
+  module ResponseParsing
+    private
+
+    def build_result(payload)
+      Result.new(
+        ok: true,
+        data: payload['data'],
+        age_ms: (payload['age_ms'] || 0).to_i,
+        stale: payload['stale'] == true,
+        error: nil,
+      )
+    end
+
+    def parse_hello(data)
+      HelloInfo.new(
+        protocol_version: data['protocol_version'].to_s,
+        daemon_version: data['daemon_version'].to_s,
+      )
+    end
+
+    def parse_cache_rows(data)
+      raise ProtocolError, 'status data is not an array' unless data.is_a?(Array)
+
+      data.map { |row| build_cache_row(row) }
+    end
+
+    def build_cache_row(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'],
+        polls_elapsed: row['polls_elapsed'],
+        failure: row['failure'],
+        source: row['source'],
+      )
+    end
+
+    def parse_daemon_health(data)
+      reaper = data['reaper']
+      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),
+        watch_backend: data['watch_backend'],
+        reaper: reaper && Reaper.new(
+          armed: reaper['armed'],
+          visibility: reaper['visibility'],
+          sweeps: reaper['sweeps'],
+          reaped: reaper['reaped'],
+          kill_denied: reaper['kill_denied'],
+        ),
+        verdicts: (data['verdicts'] || []).map do |v|
+          Verdict.new(level: v['level'].to_s, message: v['message'].to_s)
+        end,
+      )
+    end
+
+    def parse_introspect(subject, 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
+
+    def json_or_nil(value)
+      value ? JSON.generate(value) : nil
+    end
+  end
+
+  # Session holds a persistent connection to the daemon, held open by the
+  # shared library, for {#get}/{#get_with_flags}/{#put}/{#set_context}.
   #
   # Obtain a Session via {Client#session}:
   #
@@ -18,18 +104,30 @@ module Beachcomber
   #     r = s.get('git.branch')
   #   end
   #
-  # Not thread-safe; use one session per thread.
+  # {#refresh}, {#status}, {#hello} and {#introspect} are also available for
+  # API-compatibility with the pre-ABI client, but the C ABI provides no
+  # session-scoped equivalents for them (only get/put/set_context reuse the
+  # persistent connection — see Task 3.6 of the client-ABI plan); they route
+  # through the parent Client's connection instead, one-shot per call.
+  #
+  # The underlying handle is guarded by the library's own mutex: a
+  # concurrent caller on the same session gets {Beachcomber::BusyError}
+  # rather than blocking or interleaving requests.
   class Session
-    def initialize(socket, timeout)
-      @socket  = socket
-      @timeout = timeout
+    include ResponseParsing
+
+    def initialize(handle, client_handle)
+      @handle = handle
+      @client_handle = client_handle
+      @closed = false
     end
 
-    # Sets the default path for subsequent queries on this connection.
+    # Sets the default path for subsequent {#get}/{#get_with_flags} queries
+    # on this connection.
     #
     # @param path [String]
     def set_context(path)
-      roundtrip({ op: 'context', path: path })
+      Beachcomber::FFI.call!(:bc_session_set_context, @handle, path)
       nil
     end
 
@@ -39,9 +137,7 @@ module Beachcomber
     # @param path [String, nil] optional working-directory override
     # @return [Result]
     def get(key, path: nil)
-      req = { op: 'get', key: key }
-      req[:path] = path if path
-      roundtrip(req)
+      build_result(Beachcomber::FFI.call!(:bc_session_get, @handle, key, path, 0))
     end
 
     # Reads a cached value with protocol flags.
@@ -52,11 +148,8 @@ module Beachcomber
     # @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)
+      flags = (force ? Beachcomber::FFI::GET_FORCE : 0) | (wait ? Beachcomber::FFI::GET_WAIT : 0)
+      build_result(Beachcomber::FFI.call!(:bc_session_get, @handle, key, path, flags))
     end
 
     # Forces the daemon to recompute a provider/key.
@@ -64,9 +157,7 @@ module Beachcomber
     # @param key [String]
     # @param path [String, nil]
     def refresh(key, path: nil)
-      req = { op: 'refresh', key: key }
-      req[:path] = path if path
-      roundtrip(req)
+      Beachcomber::FFI.call!(:bc_refresh, @client_handle, key, path)
       nil
     end
 
@@ -74,31 +165,26 @@ module Beachcomber
     #
     # @return [Array<CacheRow>]
     def status
-      resp_obj = roundtrip_raw({ op: 'status' })
-      parse_cache_rows(resp_obj)
+      parse_cache_rows(Beachcomber::FFI.call!(:bc_status, @client_handle))
     end
 
     # Sends a hello handshake and returns server info.
     #
     # @return [HelloInfo]
     def hello
-      resp = roundtrip_raw({ op: 'hello' })
-      parse_hello(resp)
+      parse_hello(Beachcomber::FFI.call!(:bc_hello, @client_handle))
     end
 
-    # Writes a value into the daemon cache.
+    # Writes a value into the daemon cache on this session's connection.
+    # +data = nil+ clears the entry.
     #
     # @param key [String]
     # @param data [Object, nil]
-    # @param ttl [Numeric, nil] time-to-live in seconds
+    # @param ttl [Numeric, String, nil] time-to-live
     # @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)
+      Beachcomber::FFI.call!(:bc_session_put, @handle, key, JSON.generate(data), ttl&.to_s, path)
       nil
     end
 
@@ -108,120 +194,23 @@ module Beachcomber
     # @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)
+      options_json = duration_secs ? JSON.generate(duration_secs: duration_secs) : nil
+      data = Beachcomber::FFI.call!(:bc_introspect, @client_handle, subject.to_s, options_json)
+      parse_introspect(subject.to_s, data)
     end
 
-    # Closes the underlying socket connection.
+    # Closes the underlying connection. Idempotent.
     def close
-      @socket.close unless @socket.closed?
-    end
-
-    private
+      return if @closed
 
-    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_hash(raw.chomp)
-    end
-
-    def parse_response_hash(raw)
-      begin
-        resp = JSON.parse(raw)
-      rescue JSON::ParserError => e
-        raise ProtocolError, "malformed JSON: #{e.message}"
-      end
-
-      unless resp.is_a?(Hash)
-        raise ProtocolError, "expected JSON object, got #{resp.class}"
-      end
-
-      unless resp['ok']
-        raise ServerError, (resp['error'] || 'unknown error')
-      end
-
-      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
-
-    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
+      @closed = true
+      Beachcomber::FFI.close_session(@handle)
     end
   end
 
-  # Client sends individual requests, opening a fresh socket connection for
-  # each call. For workloads that issue many queries per invocation, use
-  # {#session} to reuse a persistent connection.
+  # Client sends individual requests through the shared library, which owns
+  # socket handling, framing and JSON mapping. For workloads that issue many
+  # queries per invocation, use {#session} to reuse a persistent connection.
   #
   # Examples:
   #
@@ -229,11 +218,29 @@ module Beachcomber
   #   result = client.get('git.branch', path: '/repo')
   #   puts result.data if result.hit?
   class Client
-    # @param socket_path [String, nil] explicit socket path; auto-discovered when nil
-    # @param timeout [Numeric] connect/read timeout in seconds (default 0.1)
-    def initialize(socket_path: nil, timeout: DEFAULT_TIMEOUT)
-      @socket_path = socket_path || Discovery.socket_path
-      @timeout     = timeout
+    include ResponseParsing
+
+    # @param socket_path [String, nil] explicit socket path; library default
+    #   discovery applies when nil.
+    # @param timeout [Numeric, nil] socket read/write timeout in seconds
+    #   (default 0.1 / 100ms, matching the library's own default).
+    # @param autostart [Boolean, nil] attempt to start the daemon if it isn't
+    #   running. When nil (the default) the shared library's default applies
+    #   (autostart on); pass false to disable. The library only autostarts
+    #   when the socket path is auto-discovered — never for an explicit
+    #   socket_path.
+    def initialize(socket_path: nil, timeout: DEFAULT_TIMEOUT, autostart: nil)
+      options = {}
+      options[:autostart] = autostart unless autostart.nil?
+      options[:socket_path] = socket_path if socket_path
+      options[:timeout_ms] = (timeout * 1000).round if timeout
+
+      @handle = Beachcomber::FFI.new_client(JSON.generate(options))
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@handle))
+    end
+
+    def self.finalizer(handle)
+      proc { Beachcomber::FFI.free_client(handle) }
     end
 
     # Reads a cached value.
@@ -241,12 +248,10 @@ module Beachcomber
     # @param key [String] e.g. "git.branch" or "git"
     # @param path [String, nil] optional working-directory context
     # @return [Result]
-    # @raise [DaemonNotRunning] when the socket cannot be reached
-    # @raise [ServerError] when the daemon returns ok: false
+    # @raise [Beachcomber::DaemonNotRunning] when the socket cannot be reached
+    # @raise [Beachcomber::ServerError] when the daemon returns ok: false
     def get(key, path: nil)
-      req = { op: 'get', key: key }
-      req[:path] = path if path
-      with_session { |s| s.send(:roundtrip, req) }
+      build_result(Beachcomber::FFI.call!(:bc_get, @handle, key, path, 0))
     end
 
     # Reads a cached value with protocol flags.
@@ -257,19 +262,16 @@ module Beachcomber
     # @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) }
+      flags = (force ? Beachcomber::FFI::GET_FORCE : 0) | (wait ? Beachcomber::FFI::GET_WAIT : 0)
+      build_result(Beachcomber::FFI.call!(:bc_get, @handle, key, path, flags))
     end
 
     # Forces the daemon to recompute a provider/key.
     #
     # @param key [String]
     # @param path [String, nil]
-    # @raise [DaemonNotRunning]
-    # @raise [ServerError]
     def refresh(key, path: nil)
-      req = { op: 'refresh', key: key }
-      req[:path] = path if path
-      with_session { |s| s.send(:roundtrip, req) }
+      Beachcomber::FFI.call!(:bc_refresh, @handle, key, path)
       nil
     end
 
@@ -277,25 +279,31 @@ module Beachcomber
     #
     # @return [Array<CacheRow>]
     def status
-      with_session { |s| s.status }
+      parse_cache_rows(Beachcomber::FFI.call!(:bc_status, @handle))
     end
 
     # Sends a hello handshake and returns server info.
     #
     # @return [HelloInfo]
     def hello
-      with_session { |s| s.hello }
+      parse_hello(Beachcomber::FFI.call!(:bc_hello, @handle))
     end
 
-    # Writes a value into the daemon cache.
+    # Writes a value into the daemon cache. +data = nil+ clears the entry
+    # without dropping the registry entry.
     #
     # @param key [String]
     # @param data [Object, nil]
-    # @param ttl [Numeric, nil] time-to-live in seconds
+    # @param ttl [Numeric, String, nil] time-to-live (e.g. "60s")
     # @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) }
+      if data.nil?
+        Beachcomber::FFI.call!(:bc_put_null, @handle, key, path)
+      else
+        Beachcomber::FFI.call!(:bc_put, @handle, key, JSON.generate(data), ttl&.to_s, path)
+      end
+      nil
     end
 
     # Introspects a daemon subsystem.
@@ -304,90 +312,63 @@ module Beachcomber
     # @param duration_secs [Numeric, nil]
     # @return [IntrospectResponse]
     def introspect(subject, duration_secs: nil)
-      with_session { |s| s.introspect(subject, duration_secs: duration_secs) }
+      options_json = duration_secs ? JSON.generate(duration_secs: duration_secs) : nil
+      data = Beachcomber::FFI.call!(:bc_introspect, @handle, subject.to_s, options_json)
+      parse_introspect(subject.to_s, data)
+    end
+
+    # Resolves a virtual field ("provider.field") or a provider's path
+    # expression ("provider") client-side, exactly as `comb get`'s
+    # resolution layer does. `cache.*` refs the expression makes are fetched
+    # live through this client.
+    #
+    # @param key [String] "provider.field" or a bare provider name
+    # @param cwd [String] required — path-expression evaluation has no
+    #   ambient fallback; the library never reads the process's own cwd.
+    # @param env [Hash, nil] env var values `env.*` refs resolve against
+    # @param overrides [Hash, nil] expression overrides, keyed
+    #   "provider.field" or a bare provider name
+    # @return [Object, nil] the resolved value, or nil on a path-expression miss
+    def resolve(key, cwd:, env: nil, overrides: nil)
+      Beachcomber::FFI.call!(:bc_resolve, @handle, key, cwd, json_or_nil(env), json_or_nil(overrides))
+    end
+
+    # Evaluates an arbitrary expression string against `env.*`/`cache.*`
+    # refs, using the same evaluator {#resolve} uses for a declared field.
+    #
+    # @param template [String]
+    # @param cwd [String] required, matching {#resolve}
+    # @param env [Hash, nil]
+    # @param overrides [Hash, nil]
+    # @return [String]
+    def eval_expression(template, cwd:, env: nil, overrides: nil)
+      Beachcomber::FFI.call!(:bc_eval, @handle, template, cwd, json_or_nil(env), json_or_nil(overrides))
     end
 
-    # Opens a persistent watch subscription. Returns a WatchStream (Enumerable).
-    # The caller is responsible for closing the stream.
+    # 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)
+      handle = Beachcomber::FFI.new_watch(@handle, key, path)
+      raise Beachcomber::Error, 'bc_watch_open returned NULL (allocation failure)' if handle.nil? || handle.null?
+
+      WatchStream.new(handle)
     end
 
-    # Opens a persistent session and yields it to the block. The connection is
-    # closed automatically when the block returns (even on exception).
+    # Opens a persistent session and yields it to the block. The connection
+    # is closed automatically when the block returns (even on exception).
     #
     # @yield [Session]
     # @return the block's return value
     def session
-      sock = open_socket
-      sess = Session.new(sock, @timeout)
+      handle = Beachcomber::FFI.new_session(@handle)
+      sess = Session.new(handle, @handle)
       yield sess
     ensure
       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 with_session(&block)
-      sock = open_socket
-      begin
-        s = Session.new(sock, @timeout)
-        block.call(s)
-      ensure
-        sock.close unless sock.closed?
-      end
-    end
-
-    def open_socket
-      begin
-        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
-
-    # Packs a Float (seconds) into the C timeval structure expected by setsockopt.
-    def timeval(seconds)
-      secs  = seconds.to_i
-      usecs = ((seconds - secs) * 1_000_000).to_i
-      [secs, usecs].pack('l_2')
-    end
   end
 end

data/lib/beachcomber/discovery.rb

@@ -6,21 +6,18 @@ module Beachcomber
   # 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
+  #   2. /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.
+  # There is no existence probe and no session-scoped environment is
+  # consulted ($TMPDIR, $XDG_RUNTIME_DIR): 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 resolved socket path
     def self.socket_path
       sock = ENV['BEACHCOMBER_SOCKET']
       return sock if sock && !sock.empty?
 
-      xdg = ENV['XDG_RUNTIME_DIR']
-      return File.join(xdg, 'beachcomber', 'sock') if xdg && !xdg.empty?
-
       File.join('/tmp', "beachcomber-#{Process.uid}", 'sock')
     end
   end

data/lib/beachcomber/errors.rb

@@ -2,27 +2,126 @@ module Beachcomber
   # Base class for all Beachcomber errors.
   class Error < StandardError; end
 
-  # Raised when the daemon socket cannot be reached.
-  class DaemonNotRunning < Error
-    def initialize(socket_path)
-      super("beachcomber daemon is not running (socket: #{socket_path})")
+  # Raised when libbeachcomber cannot be located. Names every location tried,
+  # in order, per the shared discovery contract.
+  class LibraryNotFound < Error; end
+
+  # Raised when a loaded libbeachcomber is missing a required bc_* symbol.
+  # Names the symbol and the bc_version() of what was actually loaded.
+  class MissingSymbol < Error; end
+
+  # Base class for every `ok: false` envelope the library returns, plus the
+  # library-level conditions (bad_flags, busy, panic, version_skew) it can
+  # raise outside the CombError variant set.
+  #
+  # +kind+ is the stable, machine-readable slug from the envelope's
+  # +error.kind+ field (e.g. "server_error", "daemon_not_running"). The
+  # message always includes the loaded library's bc_version().
+  class CombError < Error
+    attr_reader :kind
+
+    def initialize(kind, message)
+      @kind = kind
+      super("beachcomber: #{message} (kind=#{kind}, lib_version=#{safe_version})")
+    end
+
+    private
+
+    def safe_version
+      Beachcomber::FFI.version
+    rescue StandardError
+      'unknown'
+    end
+  end
+
+  # FFI-boundary conditions (no CombError variant on the Rust side).
+  class BadFlagsError < CombError
+    def initialize(message)
+      super('bad_flags', message)
+    end
+  end
+
+  class BusyError < CombError
+    def initialize(message)
+      super('busy', message)
+    end
+  end
+
+  class PanicError < CombError
+    def initialize(message)
+      super('panic', message)
+    end
+  end
+
+  class VersionSkewError < CombError
+    def initialize(message)
+      super('version_skew', message)
     end
   end
 
-  # Raised when the daemon responds with ok: false.
-  class ServerError < Error
-    attr_reader :message
+  # One class per `CombError` variant on the Rust side (see
+  # libbeachcomber-ffi/src/envelope.rs).
+  class DaemonNotRunning < CombError
+    def initialize(message)
+      super('daemon_not_running', message)
+    end
+  end
 
+  class ConnectionFailedError < CombError
     def initialize(message)
-      @message = message
-      super("beachcomber: daemon error: #{message}")
+      super('connection_failed', message)
     end
   end
 
-  # Raised when a response cannot be parsed.
-  class ProtocolError < Error
-    def initialize(detail)
-      super("beachcomber: protocol error: #{detail}")
+  class IoError < CombError
+    def initialize(message)
+      super('io_error', message)
     end
   end
+
+  # Raised when a response cannot be parsed as valid JSON, or the daemon
+  # rejects malformed input.
+  class ProtocolError < CombError
+    def initialize(message)
+      super('parse_error', message)
+    end
+  end
+
+  # Raised when the daemon returns ok: false for an op it actually executed.
+  class ServerError < CombError
+    def initialize(message)
+      super('server_error', message)
+    end
+  end
+
+  class TimeoutError < CombError
+    def initialize(message)
+      super('timeout', message)
+    end
+  end
+
+  # error.kind slug -> exception class. Kept in sync with
+  # libbeachcomber-ffi/src/envelope.rs's ErrorKind enum.
+  KIND_TO_CLASS = {
+    'bad_flags' => BadFlagsError,
+    'busy' => BusyError,
+    'panic' => PanicError,
+    'version_skew' => VersionSkewError,
+    'daemon_not_running' => DaemonNotRunning,
+    'connection_failed' => ConnectionFailedError,
+    'io_error' => IoError,
+    'parse_error' => ProtocolError,
+    'server_error' => ServerError,
+    'timeout' => TimeoutError,
+  }.freeze
+
+  # Raises the idiomatic exception for an envelope's error.kind/error.message.
+  # An unrecognised kind (future ABI additions) still raises CombError with
+  # that kind preserved, rather than failing to raise at all.
+  def self.raise_for_error(kind, message)
+    klass = KIND_TO_CLASS[kind]
+    raise klass.new(message) if klass
+
+    raise CombError.new(kind, message)
+  end
 end

data/lib/beachcomber/ffi.rb

@@ -0,0 +1,261 @@
+require 'fiddle'
+require 'json'
+require 'rbconfig'
+
+module Beachcomber
+  # Loads libbeachcomber and exposes the bc_* C ABI as callable
+  # Fiddle::Function objects, plus JSON-envelope decoding shared by
+  # Client/Session/WatchStream.
+  #
+  # Discovery order (the shared contract every dynamic-language binding
+  # follows):
+  #
+  #   1. $BEACHCOMBER_LIB
+  #   2. ../lib/<libname> relative to the resolved `comb` on $PATH
+  #   3. the platform default dynamic-linker search path
+  #
+  # `../lib/` beside `comb` is checked before the system path deliberately:
+  # library and binary ship together, so the copy next to the `comb` you
+  # would actually run is the matching one, and a stale system-wide copy
+  # must not win.
+  #
+  # A failure to find or load the library, or a missing required symbol, is
+  # a loud error naming every location tried (or the missing symbol) plus
+  # the loaded library's bc_version() where known. There is no silent
+  # fallback to a subprocess transport.
+  module FFI
+    LIB_BASENAME =
+      case RbConfig::CONFIG['host_os']
+      when /darwin/i
+        'libbeachcomber.dylib'
+      when /linux/i
+        'libbeachcomber.so'
+      else
+        raise Beachcomber::Error, "unsupported platform: #{RbConfig::CONFIG['host_os']}"
+      end
+
+    # The 22 bc_* symbols this binding calls, checked at load (not on first
+    # use) so a version-skewed or partial install fails loudly up front.
+    REQUIRED_SYMBOLS = %w[
+      bc_version bc_client_new bc_client_free bc_string_free
+      bc_get bc_put bc_put_null bc_refresh bc_status bc_introspect bc_hello
+      bc_resolve bc_eval
+      bc_session_open bc_session_close bc_session_get bc_session_put bc_session_set_context
+      bc_watch_open bc_watch_next bc_watch_cancel bc_watch_free
+    ].freeze
+
+    GET_FORCE = 1 << 0
+    GET_WAIT  = 1 << 1
+
+    VOIDP = Fiddle::TYPE_VOIDP
+    INT   = Fiddle::TYPE_INT
+    VOID  = Fiddle::TYPE_VOID
+
+    class << self
+      attr_reader :library_path
+    end
+
+    # Finds `comb` on $PATH the way a shell would, resolving symlinks (a
+    # Homebrew-linked binary, for instance) so `../lib/` is computed
+    # relative to where the binary actually lives.
+    def self.resolved_comb_path
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
+        next if dir.nil? || dir.empty?
+
+        candidate = File.join(dir, 'comb')
+        next unless File.file?(candidate) && File.executable?(candidate)
+
+        return File.realpath(candidate)
+      end
+      nil
+    rescue Errno::ENOENT, Errno::EACCES
+      nil
+    end
+
+    def self.candidate_beside_comb
+      comb = resolved_comb_path
+      return nil unless comb
+
+      File.expand_path(File.join(File.dirname(comb), '..', 'lib', LIB_BASENAME))
+    end
+
+    # Loads the library (idempotent) and returns the Fiddle::Handle.
+    def self.load!
+      return @handle if defined?(@handle) && @handle
+
+      tried = []
+
+      env_lib = ENV['BEACHCOMBER_LIB']
+      if env_lib && !env_lib.empty?
+        tried << env_lib
+        handle = try_open(env_lib)
+        return finish_load!(handle, env_lib) if handle
+      end
+
+      candidate = candidate_beside_comb
+      if candidate
+        tried << candidate
+        handle = try_open(candidate)
+        return finish_load!(handle, candidate) if handle
+      end
+
+      tried << "#{LIB_BASENAME} (platform default search path)"
+      handle = try_open(LIB_BASENAME)
+      return finish_load!(handle, LIB_BASENAME) if handle
+
+      raise Beachcomber::LibraryNotFound,
+            "could not locate #{LIB_BASENAME}; tried: #{tried.join(', ')}"
+    end
+
+    def self.try_open(path)
+      Fiddle.dlopen(path)
+    rescue Fiddle::DLError
+      nil
+    end
+    private_class_method :try_open
+
+    def self.finish_load!(handle, path)
+      @handle       = handle
+      @library_path = path
+      check_symbols!
+      bind_functions!
+      @handle
+    end
+    private_class_method :finish_load!
+
+    def self.symbol_present?(name)
+      @handle[name]
+      true
+    rescue Fiddle::DLError
+      false
+    end
+    private_class_method :symbol_present?
+
+    def self.check_symbols!
+      missing = REQUIRED_SYMBOLS.reject { |sym| symbol_present?(sym) }
+      return if missing.empty?
+
+      raise Beachcomber::MissingSymbol,
+            "#{@library_path} is missing required symbol(s): #{missing.join(', ')} " \
+            "(bc_version=#{safe_version_for_error})"
+    end
+    private_class_method :check_symbols!
+
+    def self.safe_version_for_error
+      return 'unknown' unless symbol_present?('bc_version')
+
+      fn = Fiddle::Function.new(@handle['bc_version'], [], VOIDP)
+      ptr = fn.call
+      ptr.null? ? 'unknown' : ptr.to_s
+    rescue StandardError
+      'unknown'
+    end
+    private_class_method :safe_version_for_error
+
+    def self.bind_functions!
+      @fn = {
+        bc_version: fnew('bc_version', [], VOIDP),
+        bc_client_new: fnew('bc_client_new', [VOIDP], VOIDP),
+        bc_client_free: fnew('bc_client_free', [VOIDP], VOID),
+        bc_string_free: fnew('bc_string_free', [VOIDP], VOID),
+        bc_get: fnew('bc_get', [VOIDP, VOIDP, VOIDP, INT], VOIDP),
+        bc_put: fnew('bc_put', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_put_null: fnew('bc_put_null', [VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_refresh: fnew('bc_refresh', [VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_status: fnew('bc_status', [VOIDP], VOIDP),
+        bc_introspect: fnew('bc_introspect', [VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_hello: fnew('bc_hello', [VOIDP], VOIDP),
+        bc_resolve: fnew('bc_resolve', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_eval: fnew('bc_eval', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_session_open: fnew('bc_session_open', [VOIDP], VOIDP),
+        bc_session_close: fnew('bc_session_close', [VOIDP], VOID),
+        bc_session_get: fnew('bc_session_get', [VOIDP, VOIDP, VOIDP, INT], VOIDP),
+        bc_session_put: fnew('bc_session_put', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_session_set_context: fnew('bc_session_set_context', [VOIDP, VOIDP], VOIDP),
+        bc_watch_open: fnew('bc_watch_open', [VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_watch_next: fnew('bc_watch_next', [VOIDP, INT], VOIDP),
+        bc_watch_cancel: fnew('bc_watch_cancel', [VOIDP], VOID),
+        bc_watch_free: fnew('bc_watch_free', [VOIDP], VOID),
+      }
+    end
+    private_class_method :bind_functions!
+
+    def self.fnew(name, args, ret)
+      Fiddle::Function.new(@handle[name], args, ret)
+    end
+    private_class_method :fnew
+
+    # The loaded library's build version. Static string; never freed.
+    def self.version
+      load!
+      ptr = @fn[:bc_version].call
+      ptr.null? ? '' : ptr.to_s
+    end
+
+    # Calls a void*(...)-returning bc_* function, reads the NUL-terminated
+    # JSON result, frees it via bc_string_free, and returns the raw JSON
+    # string. Not for bc_version, whose result must never be freed.
+    def self.raw_call(sym, *args)
+      load!
+      fn = @fn.fetch(sym) { raise ArgumentError, "unknown bc_* function #{sym}" }
+      ptr = fn.call(*args)
+      raise Beachcomber::Error, "unexpected NULL pointer from #{sym}" if ptr.nil? || ptr.null?
+
+      json = ptr.to_s
+      @fn[:bc_string_free].call(ptr)
+      json
+    end
+
+    # Like raw_call, but decodes the {"ok":...} envelope and raises the
+    # idiomatic exception for ok:false, returning only the op's `data` on
+    # success. Not for bc_watch_next, whose envelope has a different shape.
+    def self.call!(sym, *args)
+      envelope = JSON.parse(raw_call(sym, *args))
+      unless envelope['ok']
+        err = envelope['error'] || {}
+        Beachcomber.raise_for_error(err['kind'] || 'server_error', err['message'] || 'unknown error')
+      end
+      envelope['data']
+    end
+
+    # Opaque-handle constructors. These return a raw pointer (BcClient*,
+    # BcSession*, BcWatch*), not a JSON envelope — never NULL except
+    # BcWatch* on allocation failure.
+    def self.new_client(options_json)
+      load!
+      @fn[:bc_client_new].call(options_json)
+    end
+
+    def self.new_session(client_handle)
+      load!
+      @fn[:bc_session_open].call(client_handle)
+    end
+
+    def self.new_watch(client_handle, key, path)
+      load!
+      @fn[:bc_watch_open].call(client_handle, key, path)
+    end
+
+    # Void-returning teardown calls (null-safe on the C side; harmless if
+    # called more than once from a Ruby finalizer racing an explicit close).
+    def self.free_client(handle)
+      load!
+      @fn[:bc_client_free].call(handle)
+    end
+
+    def self.close_session(handle)
+      load!
+      @fn[:bc_session_close].call(handle)
+    end
+
+    def self.cancel_watch(handle)
+      load!
+      @fn[:bc_watch_cancel].call(handle)
+    end
+
+    def self.free_watch(handle)
+      load!
+      @fn[:bc_watch_free].call(handle)
+    end
+  end
+end

data/lib/beachcomber/types.rb

@@ -2,14 +2,16 @@ 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,
+    :kind, :poll_interval_secs, :keep_alive_polls, :fsevents_reinstate, :polls_elapsed,
+    :failure, :source,
     keyword_init: true
   )
   Verdict = Struct.new(:level, :message, keyword_init: true)
+  Reaper = Struct.new(:armed, :visibility, :sweeps, :reaped, :kill_denied, keyword_init: true)
   DaemonHealth = Struct.new(
     :pid, :version, :uptime_secs, :socket_path, :config_path,
-    :requests_total, :in_flight, :active_watchers, :cache_entries, :verdicts,
+    :requests_total, :in_flight, :active_watchers, :cache_entries,
+    :watch_backend, :reaper, :verdicts,
     keyword_init: true
   )
   WatchEvent = Struct.new(:data, :age_ms, :stale, keyword_init: true)

data/lib/beachcomber/watch_stream.rb

@@ -1,50 +1,70 @@
 module Beachcomber
+  # Iterates events from a bc_watch_open handle. Create via
+  # {Client#watch} rather than directly.
+  #
+  # bc_watch_next distinguishes five outcomes: event, timeout, eof,
+  # cancelled, error. #next_event folds timeout/eof/cancelled into a single
+  # nil (matching the previous socket-based API's "nil means the stream is
+  # over" contract) and raises the idiomatic exception for error. Pass an
+  # explicit +timeout_ms+ to observe timeouts distinctly.
   class WatchStream
     include Enumerable
 
-    def initialize(socket)
-      @socket = socket
+    def initialize(handle)
+      @handle = handle
+      @closed = false
     end
 
-    # Yields a WatchEvent per emitted change.
+    # Yields a WatchEvent per emitted change until the stream ends.
     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,
-        )
+
+      while (event = next_event)
+        yield event
       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,
+    # Waits for the next event. +timeout_ms+: -1 (default) blocks
+    # indefinitely, 0 polls once, >0 waits that long.
+    #
+    # @return [WatchEvent, nil] nil on end-of-stream (daemon closed the
+    #   connection, the watch was cancelled, or the wait elapsed).
+    def next_event(timeout_ms = -1)
+      json = Beachcomber::FFI.raw_call(:bc_watch_next, @handle, timeout_ms)
+      envelope = JSON.parse(json)
+
+      unless envelope['ok']
+        err = envelope['error'] || {}
+        Beachcomber.raise_for_error(err['kind'] || 'server_error', err['message'] || 'unknown error')
+      end
+
+      case envelope['outcome']
+      when 'event'
+        payload = envelope['data']
+        WatchEvent.new(
+          data: payload['data'],
+          age_ms: (payload['age_ms'] || 0).to_i,
+          stale: payload['stale'] == true,
         )
+      when 'timeout', 'eof', 'cancelled'
+        nil
+      else
+        raise Beachcomber::ProtocolError, "unknown watch outcome: #{envelope['outcome'].inspect}"
       end
     end
 
+    # Unblocks a pending or future #next_event call. Safe to call from
+    # another thread while a call is in flight.
+    def cancel
+      Beachcomber::FFI.cancel_watch(@handle)
+      nil
+    end
+
     def close
-      @socket.close
+      return if @closed
+
+      @closed = true
+      Beachcomber::FFI.free_watch(@handle)
     end
   end
 end

data/lib/beachcomber.rb

@@ -1,4 +1,5 @@
 require_relative 'beachcomber/errors'
+require_relative 'beachcomber/ffi'
 require_relative 'beachcomber/result'
 require_relative 'beachcomber/types'
 require_relative 'beachcomber/discovery'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libbeachcomber
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - NavistAu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-08-23 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.).
@@ -21,6 +21,7 @@ files:
 - lib/beachcomber/client.rb
 - lib/beachcomber/discovery.rb
 - lib/beachcomber/errors.rb
+- lib/beachcomber/ffi.rb
 - lib/beachcomber/result.rb
 - lib/beachcomber/types.rb
 - lib/beachcomber/watch_stream.rb