yamine 0.21.2 → 0.22.0

data/lib/yamine/cli/routes.rb

@@ -36,14 +36,7 @@ module Yamine
         routes = ctx.store.load_routes
         port = ctx.proxy_port
         tls = ctx.proxy_tls
-        entries = routes.map do |r|
-          { hostname: r["hostname"],
-            url: Hostname.url(r["hostname"], port: port, tls: tls),
-            target: r["target"], kind: r["kind"],
-            pid: r["pid"], agent: r["agent"],
-            supervised: !r["spec"].nil?,
-            alive: alive_state(ctx, r) }
-        end
+        entries = routes.map { |r| entry_for(ctx, r, port: port, tls: tls) }
         if json
           require "json"
           puts JSON.generate({ routes: entries, proxy_port: port, tls: tls })
@@ -61,6 +54,25 @@ module Yamine
         puts
       end
 
+      # One route as `yamine list` reports it.
+      #
+      # `pid` stays the route's recorded owner (the yamine process that
+      # registered it — that is what routes.json holds and what
+      # `yamine stop` and the ownership gate compare), and `backend_pid`
+      # is added beside it because `alive` is now the app's state: an
+      # agent reading `alive: running` next to a `pid` that has since
+      # exited could not tell which process the verdict was about. Both
+      # are in the payload, so nothing that was readable is lost.
+      def entry_for(ctx, route, port:, tls:)
+        { hostname: route["hostname"],
+          url: Hostname.url(route["hostname"], port: port, tls: tls),
+          target: route["target"], kind: route["kind"],
+          pid: route["pid"], backend_pid: ctx.backend_pid_for(route),
+          agent: route["agent"],
+          supervised: !route["spec"].nil?,
+          alive: alive_state(ctx, route) }
+      end
+
       # Shared discovery: `get --all` lists every live route (any owner)
       # with its URL and agent, so one agent can find another's services
       # without coupling. `--json` emits the same stable keys as list.
@@ -89,24 +101,64 @@ module Yamine
         end
       end
 
+      # Liveness of the APP, not of the yamine process that registered
+      # the route. `route["pid"]` is that process's own pid — Runner
+      # passes Process.pid at every add_route call site — and it outlives
+      # the app it booted, so asking it whether the app is alive answered
+      # a different question. Every crashed backend read as "running",
+      # in the one command an agent would reach for to find out. The
+      # app's pid is in the sidecar the boot wrote
+      # (state_dir/backend-<hostname>.pid), the same file `yamine stop`
+      # reads for exactly this reason.
+      #
+      # Five states, and the split that matters is running vs
+      # backend-gone:
+      #
+      #   running       the app's process is there
+      #   backend-gone  the CLI is still up, the app it booted is not
+      #   owner-gone    nothing is there and no app pid was recorded
+      #   unknown       no app pid recorded, and the route's own process
+      #                 is — unknowable, deliberately not "down"
+      #   reachable /   a static alias (pid 0) names no process at all,
+      #   unreachable   so it reports the probe and nothing else
+      #
+      # `unknown` is the honest answer for a route with no sidecar: one
+      # written by a yamine old enough not to write sidecars, or by a
+      # boot that died between registering the route and writing the
+      # file. There is no evidence of a dead app there, and calling it
+      # down would have every pre-existing route on the machine read as
+      # broken after an upgrade.
       def alive_state(ctx, route)
-        if route["pid"] == 0
-          ctx.backend_alive?(route) ? "reachable" : "unreachable"
-        elsif ProxyControl.pid_alive?(route["pid"])
-          "running"
-        else
-          "owner-gone"
-        end
+        return ctx.backend_alive?(route) ? "reachable" : "unreachable" if route["pid"] == 0
+
+        backend = ctx.backend_pid_for(route)
+        return owner_state(ctx, route) if backend.nil?
+
+        ProxyControl.pid_alive?(backend) ? "running" : "backend-gone"
       rescue StandardError
         "unknown"
       end
 
+      # What we know with no app pid to ask: whether the process that
+      # registered the route is still there. `owner-gone` keeps the
+      # meaning it has always had — the route outlived its owner, which
+      # is the case load_routes leaves behind for `yamine prune`.
+      def owner_state(ctx, route)
+        ProxyControl.pid_alive?(route["pid"]) ? "unknown" : "owner-gone"
+      end
+
+      # The human line. The pid shown next to the state is the one the
+      # state is about: the app's, when there is one. Printing the route
+      # owner's pid beside "running" is how a dead app kept reading as a
+      # healthy one.
       def label_for(entry)
         owner = entry[:agent] ? " #{entry[:agent]}" : ""
         if entry[:pid] == 0
           "(alias, #{entry[:alive]}#{owner})"
+        elsif entry[:backend_pid]
+          "(backend #{entry[:backend_pid]}, #{entry[:alive]}#{owner})"
         else
-          "(pid #{entry[:pid]}, #{entry[:alive]}#{owner})"
+          "(owner #{entry[:pid]}, #{entry[:alive]}#{owner})"
         end
       end
 
@@ -115,6 +167,7 @@ module Yamine
       # report the probe, not a process.
       def route_label(ctx, route)
         entry = { pid: route["pid"], alive: alive_state(ctx, route) }
+        entry[:backend_pid] = ctx.backend_pid_for(route)
         label_for(entry)
       end
 
@@ -247,13 +300,37 @@ module Yamine
         2
       end
 
-      # Touch tmp/restart.txt so a supervised managed app reboots.
-      def restart(_ctx, _args)
+      # Touch tmp/restart.txt so a supervised app's backend is stopped.
+      #
+      # What happens next is not the same for every route, so it is said
+      # rather than assumed: a managed socket app is rebooted on the next
+      # request, while a `yamine start` app is stopped and has to be
+      # started again (the daemon cannot rebuild a tcp backend — see
+      # Supervisor#rebootable?). The old one-liner promised a reboot for
+      # both, and for a tcp route nothing was even watching the file.
+      def restart(ctx, _args)
         path = File.join(Dir.pwd, "tmp", "restart.txt")
         require "fileutils"
         FileUtils.mkdir_p(File.dirname(path))
         FileUtils.touch(path)
-        puts "Touched #{path} — managed app restarts on next request."
+        puts "Touched #{path}."
+        # The routes this directory registered, found by spec.dir rather
+        # than by resolving the app: the file was written either way, and
+        # a directory with no config/local.yml must not turn a no-op into
+        # a config error.
+        here = File.expand_path(Dir.pwd)
+        entries = ctx.store.load_routes.select { |r| r.dig("spec", "dir") == here }
+        if entries.empty?
+          puts "No yamine app is registered for this directory — nothing will be restarted."
+          return
+        end
+        entries.each do |entry|
+          if entry["kind"] == "socket"
+            puts "#{entry["hostname"]} reboots on the next request."
+          else
+            puts "#{entry["hostname"]} will be stopped; start it again with `yamine start`."
+          end
+        end
       end
 
       # Tail the shared app log (default 50 lines); --follow streams.

data/lib/yamine/cli/system.rb

@@ -946,23 +946,33 @@ module Yamine
 
               yamine start              # block until every route is healthy, then supervise
               yamine start --no-wait   # fire-and-forget (register routes immediately)
+              yamine start --detach    # boot in the background, return once the app is healthy
               yamine start --json       # machine-readable result payload (--wait only)
               yamine start -- --help   # pass --help to the app, not here
 
             Options are passed through to the boot path:
               --variant <v> --tld <tld> --force --app-port <port>
-              --wait (alias, default) --no-wait --json
+              --wait (alias, default) --no-wait --json --detach
 
             Default waits: every process is spawned concurrently, each
             healthcheck (or TCP accept when none is declared) is polled,
             routes are registered only when all are healthy, and `ready:`
             is printed with exit 0. On failure everything spawned is
             killed, the failed process + its log tail is printed, and
-            the CLI exits 1 — no half-booted routes. `--no-wait` keeps
-            the old fire-and-forget path.
+            the CLI exits 1 — no half-booted routes. `--no-wait` keeps the
+            old fire-and-forget path.
+
+            --detach forks the boot: the child owns the tree, its pid is
+            the one recorded in routes.json, and this process waits for
+            the app to answer, prints the URL, that pid and the log path
+            under the state dir, then exits 0. It is idempotent — a tree
+            already running for this directory is reported, not started
+            again. --no-wait is ignored with it: the point of detaching is
+            that the command returns once the app is actually serving.
 
             Setup failures become hard errors pointing at `yamine setup`;
             non-interactive CI without a running proxy exits immediately.
+
           HELP
           return
         end

data/lib/yamine/cli.rb

@@ -83,6 +83,7 @@ module Yamine
 
         Usage:
           yamine start                 One-setup-and-go: setup if needed, then boot -> https://<app>.localhost
+          yamine start --detach        Same, in the background; returns once the app is healthy
           yamine setup                One-shot workstation setup without booting (run once)
           yamine                        Bare form of `start` — boots every process in config/local.yml
           yamine get <name>             Print URL for a service
@@ -103,10 +104,10 @@ module Yamine
           yamine hosts sync|clean       Manage /etc/hosts entries
           yamine kamal <variant>        Preview-deploy snippet for Kamal
           yamine stop                   Stop this app's backend + routes
-          yamine restart                Touch tmp/restart.txt
+          yamine restart                Touch tmp/restart.txt (a supervised app is stopped)
           yamine log [-F] [n]           Tail (or follow) log/development.log
 
-        Flags: --variant, --tld, --force, --app-port, --wait (default), --no-wait, --json, --branch
+        Flags: --variant, --tld, --force, --app-port, --wait (default), --no-wait, --detach, --json, --branch
         Env: YAMINE_VARIANT/TLD/PORT/STATE_DIR/AGENT, YAMINE_BRANCH=1
       HELP
     end

data/lib/yamine/process_tree.rb

@@ -57,9 +57,58 @@ module Yamine
     # "can't be called from trap context" — a stop path that only works
     # outside a trap is a stop that never happens on Ctrl-C.
     PGROUP_LEADERS = {}
+    # Exit statuses of what we spawned, by pid, filled in by the reaper
+    # that `detach` starts. Same reasoning, same shape, and the same
+    # bounded cost as PGROUP_LEADERS above: an entry is a few dozen bytes
+    # per process this one ever spawned, dropped by `forget` whenever
+    # the pid is signalled.
+    STATUSES = {}
 
     module_function
 
+    # Spawn a child and reap it without blocking us, keeping what it
+    # exited with. A drop-in for Process.detach — nobody waits on a live
+    # backend, a dead pid is all the boot needs — that also keeps the one
+    # thing only a reaper can know. Without it the answer dies with the
+    # child: `kill(0, pid)` says a process is gone and nothing says
+    # whether it exited 0 or was killed, so "web is down" is all a
+    # supervisor could ever report.
+    #
+    # Unlocked, like PGROUP_LEADERS, and a Hash read from a supervision
+    # thread: every operation is a single call the GVL makes atomic.
+    def detach(pid)
+      return pid unless pid.to_i.positive?
+
+      Thread.new do
+        _waited, status = ::Process.waitpid2(pid)
+        STATUSES[pid] = status
+      rescue SystemCallError
+        nil
+      end
+      pid
+    end
+
+    # Process::Status for a pid we spawned, or nil when there is nothing
+    # to report: not our child, or it has not been reaped yet.
+    #
+    # Never blocks, which is the whole point — the caller is a loop that
+    # has other routes to watch, and asking a live child how it is doing
+    # would hang it. So a status that has not arrived yet is nil, and the
+    # caller asks again on its next pass.
+    def status(pid)
+      recorded = STATUSES[pid]
+      return recorded if recorded
+
+      # Not one of ours to have reaped (a pid out of a route entry, a
+      # double in a test): ask the kernel. WNOHANG so a live pid is not
+      # waited on, and ECHILD — which is the answer for anything that is
+      # not a child of ours — is a nil, not a failure.
+      _waited, status = ::Process.waitpid2(pid, ::Process::WNOHANG)
+      status
+    rescue StandardError
+      nil
+    end
+
     # Spawn a boot process as its own group leader and record that it is
     # one. This is the only place a boot process is created, so "every
     # process we boot leads a group" is one fact in one place rather
@@ -85,8 +134,14 @@ module Yamine
       PGROUP_LEADERS.key?(pid)
     end
 
+    # Drop every record of a pid we have finished with. Both tables are
+    # about a spawn, not about a number that has to keep meaning one:
+    # leaving them behind is how a pid that later gets recycled gets
+    # signalled as a group it never led, or reported with an exit status
+    # that belongs to somebody else.
     def forget(pid)
       PGROUP_LEADERS.delete(pid)
+      STATUSES.delete(pid)
     end
 
     # Does this pid lead its own process group? Ours, if we spawned it.