libbeachcomber 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 828cc2e242605a1780d4fe4bb1dcd860b1ff8055af6e1fe468d77d8277410f08
+  data.tar.gz: 052b6205a895eaccbb65c86257dcaaa427ee651a7446cb0afcf81dd71507f706
+SHA512:
+  metadata.gz: 52eee270039542c05ece9bcbf63c5057f915b1fa56be399bfb2c1e38d3c6c4381d37b1bd0cdd4634380bcc5d97f1b8071ed8fae7abf75d213dc9e47ac41d677d
+  data.tar.gz: 64608926fdca4fb02c8fdbbc943f15d4219a5fd2051818a6c84c58d6f9a3bd5a0b04cc3d9fb9e3bbd2fa4498c901e012d3f050cc0371c15036f869d14b592c58

data/lib/beachcomber/client.rb

@@ -0,0 +1,220 @@
+require 'socket'
+require 'json'
+
+require_relative 'discovery'
+require_relative 'errors'
+require_relative 'result'
+
+module Beachcomber
+  DEFAULT_TIMEOUT = 0.1 # seconds (100 ms)
+
+  # Session holds a persistent connection to the daemon and sends multiple
+  # requests over the same socket.
+  #
+  # Obtain a Session via {Client#session}:
+  #
+  #   client.session do |s|
+  #     s.set_context('/repo')
+  #     r = s.get('git.branch')
+  #   end
+  #
+  # Not thread-safe; use one session per thread.
+  class Session
+    def initialize(socket, timeout)
+      @socket  = socket
+      @timeout = timeout
+    end
+
+    # Sets the default path for subsequent queries on this connection.
+    #
+    # @param path [String]
+    def set_context(path)
+      roundtrip({ op: 'context', path: path })
+      nil
+    end
+
+    # Reads a cached value.
+    #
+    # @param key [String] e.g. "git.branch" or "git"
+    # @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)
+    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 }
+      req[:path] = path if path
+      roundtrip(req)
+      nil
+    end
+
+    # Lists available providers.
+    #
+    # @return [Result]
+    def list
+      roundtrip({ op: 'list' })
+    end
+
+    # Returns daemon status.
+    #
+    # @return [Result]
+    def status
+      roundtrip({ op: 'status' })
+    end
+
+    # Closes the underlying socket connection.
+    def close
+      @socket.close unless @socket.closed?
+    end
+
+    private
+
+    def roundtrip(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)
+    end
+
+    def parse_response(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
+
+      ok     = resp['ok']
+      data   = resp['data']
+      age_ms = (resp['age_ms'] || 0).to_i
+      stale  = resp['stale'] == true
+      error  = resp['error']
+
+      unless ok
+        raise ServerError, (error || 'unknown error')
+      end
+
+      Result.new(ok: ok, data: data, age_ms: age_ms, stale: stale, error: error)
+    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.
+  #
+  # Examples:
+  #
+  #   client = Beachcomber::Client.new
+  #   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
+    end
+
+    # Reads a cached value.
+    #
+    # @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
+    def get(key, path: nil)
+      req = { op: 'get', key: key }
+      req[:path] = path if path
+      roundtrip(req)
+    end
+
+    # Forces the daemon to recompute a provider/key.
+    #
+    # @param key [String]
+    # @param path [String, nil]
+    # @raise [DaemonNotRunning]
+    # @raise [ServerError]
+    def poke(key, path: nil)
+      req = { op: 'poke', key: key }
+      req[:path] = path if path
+      roundtrip(req)
+      nil
+    end
+
+    # Lists available providers registered with the daemon.
+    #
+    # @return [Result]
+    def list
+      roundtrip({ op: 'list' })
+    end
+
+    # Returns scheduler and cache status from the daemon.
+    #
+    # @return [Result]
+    def status
+      roundtrip({ op: 'status' })
+    end
+
+    # 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    = dial
+      session = Session.new(sock, @timeout)
+      yield session
+    ensure
+      session&.close
+    end
+
+    private
+
+    def roundtrip(req)
+      sock = dial
+      begin
+        s = Session.new(sock, @timeout)
+        s.send(:roundtrip, req)
+      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))
+
+      begin
+        sock.connect(addr)
+      rescue Errno::ENOENT, Errno::ECONNREFUSED, Errno::EACCES
+        sock.close
+        raise DaemonNotRunning.new(@socket_path)
+      end
+
+      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

@@ -0,0 +1,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
+  #   3. /tmp/beachcomber-<uid>/sock
+  module Discovery
+    # @return [String] the discovered or best-guess socket path
+    def self.socket_path
+      xdg = ENV['XDG_RUNTIME_DIR']
+      if xdg && !xdg.empty?
+        candidate = File.join(xdg, 'beachcomber', 'sock')
+        return candidate if File.exist?(candidate)
+      end
+
+      uid  = Process.uid
+      dir  = "beachcomber-#{uid}"
+      base = ENV.fetch('TMPDIR', nil) || '/tmp'
+      File.join(base, dir, 'sock')
+    end
+  end
+end

data/lib/beachcomber/errors.rb

@@ -0,0 +1,28 @@
+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})")
+    end
+  end
+
+  # Raised when the daemon responds with ok: false.
+  class ServerError < Error
+    attr_reader :message
+
+    def initialize(message)
+      @message = message
+      super("beachcomber: daemon error: #{message}")
+    end
+  end
+
+  # Raised when a response cannot be parsed.
+  class ProtocolError < Error
+    def initialize(detail)
+      super("beachcomber: protocol error: #{detail}")
+    end
+  end
+end

data/lib/beachcomber/result.rb

@@ -0,0 +1,81 @@
+module Beachcomber
+  # Wraps a daemon response.
+  #
+  # A result can represent a cache hit (data present), a miss (ok but no data),
+  # or an error (ok: false — though errors are normally raised as ServerError).
+  #
+  # Examples:
+  #
+  #   result = client.get('git.branch', path: '/repo')
+  #   if result.hit?
+  #     puts result.data    # "main"
+  #     puts result.age_ms  # 42
+  #   end
+  #
+  #   # hash data access
+  #   result = client.get('git', path: '/repo')
+  #   puts result['branch']
+  class Result
+    # @return [Boolean] whether the daemon reported success
+    attr_reader :ok
+
+    # @return [Object, nil] decoded payload (String, Integer, Hash, Array, etc.)
+    attr_reader :data
+
+    # @return [Integer] age of the cached value in milliseconds
+    attr_reader :age_ms
+
+    # @return [String, nil] error message when ok is false
+    attr_reader :error
+
+    def initialize(ok:, data:, age_ms:, stale:, error:)
+      @ok     = ok
+      @data   = data
+      @age_ms = age_ms
+      @stale  = stale
+      @error  = error
+    end
+
+    # @return [Boolean]
+    def ok?
+      @ok
+    end
+
+    # @return [Boolean] true when the response carried data (cache hit)
+    def hit?
+      @ok && !@data.nil?
+    end
+
+    # @return [Boolean] true when the response was successful but had no data
+    def miss?
+      @ok && @data.nil?
+    end
+
+    # @return [Boolean] true when the cached value is stale
+    def stale?
+      @stale
+    end
+
+    # Delegates field access to the data hash.
+    #
+    # @param key [String] field name
+    # @return [Object, nil]
+    # @raise [TypeError] if data is not a Hash
+    def [](key)
+      unless @data.is_a?(Hash)
+        raise TypeError, "Result#[] requires hash data, got #{@data.class}"
+      end
+
+      @data[key]
+    end
+
+    def inspect
+      parts = ["ok=#{@ok}"]
+      parts << "data=#{@data.inspect}" unless @data.nil?
+      parts << "age_ms=#{@age_ms}" if @age_ms > 0
+      parts << "stale=true" if @stale
+      parts << "error=#{@error.inspect}" if @error
+      "#<Beachcomber::Result #{parts.join(', ')}>"
+    end
+  end
+end

data/lib/beachcomber.rb

@@ -0,0 +1,28 @@
+require_relative 'beachcomber/errors'
+require_relative 'beachcomber/result'
+require_relative 'beachcomber/discovery'
+require_relative 'beachcomber/client'
+
+# Beachcomber is a Ruby client for the beachcomber daemon.
+#
+# The daemon caches shell-environment data (git state, hostname, battery, …)
+# and serves it over a Unix domain socket using newline-delimited JSON.
+#
+# Quick start:
+#
+#   require 'beachcomber'
+#
+#   client = Beachcomber::Client.new
+#   result = client.get('git.branch', path: '/path/to/repo')
+#   puts result.data if result.hit?
+#
+# Persistent session (one connection, multiple queries):
+#
+#   client.session do |s|
+#     s.set_context('/path/to/repo')
+#     r1 = s.get('git.branch')
+#     r2 = s.get('git.dirty')
+#   end
+module Beachcomber
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: libbeachcomber
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- NavistAu
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-01 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.).
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/beachcomber.rb
+- lib/beachcomber/client.rb
+- lib/beachcomber/discovery.rb
+- lib/beachcomber/errors.rb
+- lib/beachcomber/result.rb
+homepage: https://github.com/NavistAu/beachcomber
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/NavistAu/beachcomber/tree/main/sdks/ruby
+  bug_tracker_uri: https://github.com/NavistAu/beachcomber/issues
+  changelog_uri: https://github.com/NavistAu/beachcomber/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the beachcomber shell-data daemon
+test_files: []