Gralkor.OrphanReaper (gralkor v1.1.0)

Copy Markdown View Source

Pre-OTP cleanup for a stale uvicorn left bound to Gralkor's port.

Intended to run before the OTP supervision tree starts — specifically before Gralkor.Server's boot sequence, whose :port_in_use check refuses to clean up foreign holders and crashes.

Rationale: a BEAM abort (Ctrl+C → a, SIGKILL, crash) doesn't reliably run Gralkor.Server.terminate/2, which is the only path that SIGTERMs the uvicorn OS pid. So aborts sometimes leave uvicorn orphaned (reparented to launchd) with port 4000 still bound. The reaper looks for such an orphan, verifies it is ours (command line contains gralkor/priv/server), and SIGKILLs it. If the holder is anything else, the reaper raises — we don't kill foreign processes.

System.cmd/3 is injectable via opts[:shell] so the logic is unit-testable without side effects.

Summary

Types

shell()

@type shell() :: (String.t(), [String.t()], keyword() -> {String.t(), integer()})

Functions

reap(opts \\ [])

@spec reap(keyword()) :: :ok | no_return()