samagotchi 0.121.0 → 0.121.1

data/lib/samagotchi/worker_link.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require_relative "owner_lock"
+require_relative "version"
+require_relative "worker_sidecar"
+require_relative "bridge_client"
+require_relative "chi_invocation"
+
+module Samagotchi
+  # Whether a session's worker can be reached, and how: the one question
+  # every client asks before it talks to a worker's Bridge (a TUI attaching,
+  # chi web's relays and stream, `chi send`, a restart, `chi update`). It
+  # answers a typed outcome instead of a sidecar or nil, so nobody reads
+  # bridge.json by hand. The rule is the owner lock plus the sidecar's pid,
+  # never a port probe:
+  # - Live: a worker holds the lock and its sidecar names its pid (a sidecar
+  #   with no pid: an older worker's, the lock alone) (#client makes the one
+  #   client for it);
+  # - Starting: a worker holds the lock but has no sidecar of its own yet (or
+  #   the lock's record is still being written); stuck when it has held it
+  #   past START_LIMIT without one;
+  # - Leaving: the worker closed its Bridge and holds the lock for its last work;
+  # - Skew: a worker whose sidecar speaks a newer PROTOCOL than this chi;
+  # - Stale: a sidecar, but the lock is free (or a chi REPL holds it, which
+  #   writes none): its worker died;
+  # - None: no worker and no sidecar, or a chi REPL.
+  # A kernel releases a dead worker's lock, so a free lock is the proof of
+  # death a TCP probe never gave (a port can be reused by another session's
+  # Bridge).
+  module WorkerLink
+    # The sidecar protocol this chi speaks; a sidecar with a bigger one is a
+    # newer worker's (Skew).
+    PROTOCOL = 1
+
+    # Seconds a worker may hold the lock without publishing its Bridge before
+    # Starting is stuck (SessionManager::WORKER_START_GRACE).
+    START_LIMIT = 30.0
+
+    # The sidecar's file name in a session folder.
+    FILE = WorkerSidecar::FILE
+
+    # A worker whose Bridge answers: its sidecar says how to reach it.
+    Live = Data.define(:sidecar, :owner) do
+      def initialize(sidecar:, owner: nil) = super
+
+      def live? = true
+      def worker_owned? = true
+
+      # The client for this worker (BridgeClient.for_sidecar: its port and its
+      # secret from this one read).
+      # @return [BridgeClient]
+      def client(session_id, host: BridgeClient::HOST, read_timeout: BridgeClient::READ_TIMEOUT)
+        BridgeClient.for_sidecar(session_id, sidecar, host: host, read_timeout: read_timeout)
+      end
+
+      def port = sidecar.port
+      def epoch = sidecar.epoch
+      def version = sidecar.version
+      def features = sidecar.features
+      def started_at = sidecar.started_at
+    end
+
+    # A worker holds the lock and has not published its Bridge (yet).
+    Starting = Data.define(:owner, :stuck) do
+      def initialize(owner:, stuck: false) = super
+
+      def live? = false
+      def worker_owned? = true
+    end
+
+    # A worker holds the lock with its Bridge closed (OwnerLock::Owner#leaving?).
+    Leaving = Data.define(:owner) do
+      def live? = false
+      def worker_owned? = true
+
+      # Seconds of its leave still to run.
+      def left = owner.leave_left
+    end
+
+    # No worker: no sidecar in the session folder, and no worker's lock (a
+    # chi REPL's, +owner+, is no worker's).
+    None = Data.define(:owner) do
+      def initialize(owner: nil) = super
+
+      def live? = false
+      def worker_owned? = false
+    end
+
+    # A sidecar no worker stands behind: the lock is free (reason :lock_free).
+    Stale = Data.define(:sidecar, :reason, :owner) do
+      def initialize(sidecar:, reason:, owner: nil) = super
+
+      def live? = false
+      def worker_owned? = false
+    end
+
+    # A worker whose sidecar's protocol is newer than this chi's (reason
+    # :protocol): it must not be driven by this chi.
+    Skew = Data.define(:sidecar, :owner, :reason) do
+      def live? = false
+      def worker_owned? = true
+
+      def message(session_id, via: ChiInvocation::HERE)
+        "session #{session_id}'s worker runs chi #{sidecar.version || "?"} (protocol #{sidecar.protocol}), " \
+          "newer than this chi #{Samagotchi::VERSION} (protocol #{PROTOCOL}): restart " \
+          "#{via.remote? ? via.web : "chi web"} or update this chi"
+      end
+    end
+
+    module_function
+
+    def not_live(session_id) = "no live worker for session #{session_id}"
+
+    # @param session_dir [String]
+    # @param unlink [Boolean] remove a Stale sidecar (the clients that would
+    #   talk to it; never one a worker may be writing); false is a read-only
+    #   look (`chi update`, a restart's poll)
+    # @param owner [OwnerLock::Owner, nil, :read] the lock's holder as the
+    #   caller already read it (nil: free); :read reads it here
+    # @return [Live, Starting, Leaving, None, Stale, Skew]
+    def resolve(session_dir, unlink:, owner: :read, host: BridgeClient::HOST)
+      owner = OwnerLock.owner(session_dir) if owner == :read
+      stamp = file_stamp(session_dir)
+      sidecar = WorkerSidecar.read(session_dir)
+      return unowned(session_dir, sidecar, owner, stamp, unlink) if owner.nil? || owner.tui?
+      return Starting.new(owner: owner, stuck: false) unless owner.worker?
+      return Leaving.new(owner: owner) if owner.leaving?
+      return Starting.new(owner: owner, stuck: stuck?(owner)) unless ours?(sidecar, owner)
+      return Skew.new(sidecar: sidecar, owner: owner, reason: :protocol) if sidecar.protocol.to_i > PROTOCOL
+
+      Live.new(sidecar: sidecar, owner: owner)
+    end
+
+    # @return [BridgeClient, nil] a client for the session's Live worker
+    def client(session_id, session_dir:, unlink: true, host: BridgeClient::HOST, read_timeout: BridgeClient::READ_TIMEOUT)
+      link = resolve(session_dir, unlink: unlink, host: host)
+      link.live? ? link.client(session_id, host: host, read_timeout: read_timeout) : nil
+    end
+
+    # Wait for a worker (a freshly spawned one) to publish its Bridge: the
+    # first Live for which +until+ holds within +timeout+ seconds (polled
+    # every +interval+), else the last outcome seen. +until+ tells a new
+    # worker from the one a restart asked to leave (its sidecar is Live too).
+    # @param _session_id [String] the session waited for (as .client's; the
+    #   outcome's #client takes it again)
+    # @param until [#call, nil] ->(live) { … }; nil takes any Live
+    # @param give_up [#call, nil] ->(outcome) { … }: stop at the first
+    #   outcome it holds for (a waker's "no worker owns it any more")
+    # @return [Live, Starting, Leaving, None, Stale, Skew] the outcome it
+    #   stopped at, else the last one seen
+    def await(_session_id, session_dir:, timeout:, unlink: true, interval: BridgeClient::SPAWN_POLL_INTERVAL,
+              until: nil, give_up: nil, host: BridgeClient::HOST)
+      wanted = binding.local_variable_get(:until) # a keyword: no plain read
+      last = nil
+      found = BridgeClient.poll(timeout, interval: interval) do
+        last = resolve(session_dir, unlink: unlink, host: host)
+        last if (last.live? && (wanted.nil? || wanted.call(last))) || give_up&.call(last)
+      end
+      found || last
+    end
+
+    # The session folders under +state_dir+ that hold a sidecar (live or not),
+    # in order.
+    # @return [Array<String>]
+    def each_dir(state_dir)
+      Dir[File.join(state_dir, "*", WorkerSidecar::FILE)].sort.map { |path| File.dirname(path) }
+    end
+
+    # A sidecar is the lock holder's own when it names its pid (or none: an
+    # older worker's) and a port.
+    def ours?(sidecar, owner)
+      return false unless sidecar&.port&.positive?
+
+      sidecar.pid.nil? || sidecar.pid == owner.pid
+    end
+    private_class_method :ours?
+
+    def stuck?(owner)
+      started = Time.iso8601(owner.started_at.to_s)
+      Time.now - started > START_LIMIT
+    rescue ArgumentError
+      false
+    end
+    private_class_method :stuck?
+
+    def unowned(session_dir, sidecar, owner, stamp, unlink)
+      return None.new(owner: owner) unless sidecar
+
+      unlink_unchanged(session_dir, stamp) if unlink
+      Stale.new(sidecar: sidecar, reason: :lock_free, owner: owner)
+    end
+    private_class_method :unowned
+
+    def file_stamp(session_dir)
+      stat = File.stat(WorkerSidecar.path(session_dir))
+      [stat.ino, stat.mtime]
+    rescue SystemCallError
+      nil
+    end
+    private_class_method :file_stamp
+
+    # Remove the sidecar only if it is the file that was read: a new worker's
+    # write is a new inode (AtomicFile renames).
+    def unlink_unchanged(session_dir, stamp)
+      return if stamp.nil? || file_stamp(session_dir) != stamp
+
+      FileUtils.rm_f(WorkerSidecar.path(session_dir))
+    end
+    private_class_method :unlink_unchanged
+  end
+end

data/lib/samagotchi/worker_sidecar.rb

@@ -2,7 +2,6 @@
 
 require "json"
 require "fileutils"
-require "socket"
 require_relative "atomic_file"
 
 module Samagotchi
@@ -14,15 +13,15 @@ module Samagotchi
   # one worker identity: the epoch in every event id, so a remote client
   # tells a restarted worker apart; nil from a worker before it), and its
   # Bridge's secret (every request names it in X-Chi-Bridge, Bridge#secret_ok?;
-  # nil from a worker before it, which asks for none). The Bridge writes it
-  # on start
-  # and removes it on stop; one a dead worker left stays until a client's
-  # probe finds its port closed (.live with unlink: true).
+  # nil from a worker before it, which asks for none), the pid of the worker
+  # process that wrote it (WorkerLink: it is Live only under the owner lock
+  # of that pid; nil from an older worker) and the WorkerLink::PROTOCOL it
+  # speaks (nil from an older one). The Bridge writes it on start and removes
+  # it on stop (only its own, by epoch); one a dead worker left stays until
+  # a client finds the lock free (WorkerLink.resolve with unlink: true).
   class WorkerSidecar < Data.define(:port, :bind, :session_id, :started_at, :version, :input_format, :features,
-                                    :epoch, :secret)
+                                    :epoch, :secret, :pid, :protocol)
     FILE = "bridge.json"
-    # Seconds a liveness probe waits for the port to take a connect.
-    PROBE_TIMEOUT = 0.2
 
     def self.path(session_dir) = File.join(session_dir, FILE)
 
@@ -35,7 +34,8 @@ module Samagotchi
       port = data["port"]
       new(port: port.respond_to?(:to_i) ? port.to_i : 0, bind: data["bind"], session_id: data["session_id"],
           started_at: data["started_at"], version: data["version"], input_format: data["input_format"],
-          features: Array(data["features"]).map(&:to_s), epoch: data["epoch"]&.to_s, secret: secret_in(data["secret"]))
+          features: Array(data["features"]).map(&:to_s), epoch: data["epoch"]&.to_s, secret: secret_in(data["secret"]),
+          pid: integer_in(data["pid"]), protocol: integer_in(data["protocol"]))
     rescue JSON::ParserError, SystemCallError
       nil
     end
@@ -46,34 +46,10 @@ module Samagotchi
 
     def self.secret_in(value) = value.is_a?(String) && SECRET_SHAPE.match?(value) ? value : nil
 
-    # The sidecar of a worker whose Bridge takes a connect on its port, or
-    # nil. One whose port refuses (its worker died) is stale: +unlink+
-    # removes it (the clients that would talk to it), else it stays (a
-    # read-only look, like `chi update`'s).
-    # @return [WorkerSidecar, nil]
-    def self.live(session_dir, unlink:, host: "127.0.0.1", timeout: PROBE_TIMEOUT)
-      sidecar = read(session_dir)
-      return nil unless sidecar&.port&.positive?
-
-      begin
-        # Not Socket.tcp: with connect_timeout on macOS 26 it hands back the
-        # socket of a refused connect (the kernel's second connect() says
-        # EISCONN, SO_ERROR is unchecked), so a dead worker's port read as
-        # live. Ruby bug #22223, fixed in 3.4.11 / 4.0.7, not in 3.3.
-        # TCPSocket checks SO_ERROR and raises ECONNREFUSED on every Ruby,
-        # so this stays even once 3.3 is dropped.
-        TCPSocket.new(host, sidecar.port, connect_timeout: timeout).close
-        sidecar
-      rescue StandardError
-        FileUtils.rm_f(path(session_dir)) if unlink
-        nil
-      end
-    rescue StandardError
-      nil
-    end
+    def self.integer_in(value) = value.is_a?(Integer) ? value : nil
 
     def initialize(port:, bind: nil, session_id: nil, started_at: nil, version: nil, input_format: nil, features: [],
-                   epoch: nil, secret: nil) = super
+                   epoch: nil, secret: nil, pid: nil, protocol: nil) = super
 
     # The secret never shows in an inspect (a log line, an error's message).
     def inspect = "#<#{self.class.name} port=#{port} session_id=#{session_id.inspect} epoch=#{epoch.inspect}>"
@@ -81,14 +57,16 @@ module Samagotchi
 
     # Written whole or not at all, readable by this user only (0600 from the
     # moment the file exists, AtomicFile: no other account learns the
-    # worker's port or its secret from it); input_format, epoch and secret
-    # only when they name one.
+    # worker's port or its secret from it); input_format, epoch, secret, pid
+    # and protocol only when they name one.
     def write(session_dir)
       FileUtils.mkdir_p(session_dir)
       record = to_h.transform_keys(&:to_s)
       record.delete("input_format") if input_format.nil?
       record.delete("epoch") if epoch.nil?
       record.delete("secret") if secret.nil?
+      record.delete("pid") if pid.nil?
+      record.delete("protocol") if protocol.nil?
       AtomicFile.write(self.class.path(session_dir), "#{JSON.pretty_generate(record)}\n", perm: 0o600)
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.121.0
+  version: 0.121.1
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -197,6 +197,7 @@ files:
 - lib/samagotchi/bridge_client.rb
 - lib/samagotchi/bridge_client/event_stream.rb
 - lib/samagotchi/bridge_client/sse_parser.rb
+- lib/samagotchi/bridge_client/stream_open.rb
 - lib/samagotchi/bridge_client/stream_request.rb
 - lib/samagotchi/bridge_secret.rb
 - lib/samagotchi/broadcast/recipients.rb
@@ -890,6 +891,7 @@ files:
 - lib/samagotchi/worker.rb
 - lib/samagotchi/worker_idle_exit.rb
 - lib/samagotchi/worker_inbound.rb
+- lib/samagotchi/worker_link.rb
 - lib/samagotchi/worker_sidecar.rb
 - lib/samagotchi/worker_signals.rb
 - lib/samagotchi/worker_task_wakes.rb