Documentation
¶
Overview ¶
Package process starts, finds and stops the processes shinyctl runs: the R process of each copy and the load balancer. It tells a recorded process from a stranger that reused its number (by command line, started-at and port), checks that a port is free and who holds it, waits for a copy to accept connections, watches for an exit, and measures memory. It decides nothing about what should run; that is package reconcile.
Index ¶
- Constants
- Variables
- func AliveAll(spec manifest.AppSpec, apps []state.AppState) []bool
- func AppLogPath(spec manifest.AppSpec) (string, error)
- func CheckSocketPath(path string) error
- func CheckSocketPaths() error
- func ConfigDir() (string, error)
- func CopyLogPath(spec manifest.AppSpec, n int) (string, error)
- func EnsureAPIRunning() error
- func HasCommandLine(pid int, substr string) bool
- func IsAlive(spec manifest.AppSpec, app state.AppState) bool
- func IsReady(host string, port int) bool
- func LaunchDetached(path string, args []string, logPath string) (int, error)
- func LingerWarning() string
- func ListenUnix(path string) (net.Listener, error)
- func LogPath() (string, error)
- func PIDRunning(app state.AppState) bool
- func PickPort(taken map[int]bool, free func(port int) bool, start int) (int, error)
- func PortAvailable(host string, port int) error
- func PortAvailableAlongside(host string, port int) error
- func PortStart() int
- func ProxyDir() (string, error)
- func RSS(pids []int) map[int]int64
- func RegistryPath() (string, error)
- func RotateLog(path string, max int64) (bool, error)
- func RunAppExpression(entrypoint string, port int, host string) string
- func SocketDialable(path string) bool
- func SocketPath() (string, error)
- func Start(spec manifest.AppSpec, copy, port, revision int) (state.AppState, <-chan Exit, error)
- func StartDetached(path string, args []string, logPath string) (*exec.Cmd, error)
- func Stop(app state.AppState, fallbacks ...string) (signaled bool, err error)
- func StopIf(pid int, ours func() bool) (signaled bool, err error)
- func WatchExit(spec manifest.AppSpec, app state.AppState) (<-chan struct{}, error)
- type CopyLog
- type Exit
- type Owner
Constants ¶
const InternalHost = "127.0.0.1"
InternalHost is the address an app's R process binds. It is behind the load balancer, which listens on the app's own host and port, so nothing else on the network can reach the process directly.
const MaxLogSize = 1 << 30
MaxLogSize is the size a log file may reach before RotateLog turns it over: 1 GiB. Applies to each app's own log and to shinyctl-api's. One previous generation is kept (`<name>.1`), so the worst case on disk is twice this per log.
const MaxSocketPath = 103
MaxSocketPath is the longest Unix socket path that can be bound on every supported system: sockaddr_un.sun_path is 104 bytes on macOS including the terminating NUL (108 on Linux).
const StopWait = stopGrace + killGrace
StopWait is the longest StopIf takes to end a process: the SIGTERM grace period, then the wait after SIGKILL.
Variables ¶
var ErrNotOurs = errors.New("the process is gone or is not the app's")
ErrNotOurs is what WatchExit returns for a process that is already gone or is not the one app records.
var ErrWatchUnsupported = errors.New("watching a process for its exit is not supported here")
ErrWatchUnsupported is what WatchExit returns where the system has no way to watch a process that is not our child. Other errors come from the system refusing (an old Linux kernel, a sandbox).
Functions ¶
func AliveAll ¶
AliveAll is IsAlive for each of apps, with the command lines of all of them read together: from /proc on Linux, with one ps call elsewhere. The result is in the order of apps.
func AppLogPath ¶
AppLogPath returns the path to copy 1's log file, which is also the one an app with a single copy has: see CopyLogPath.
func CheckSocketPath ¶
CheckSocketPath returns a clear error for a socket path that is too long to bind, instead of the OS's "invalid argument". The paths are under the home directory, which the user chose.
func CheckSocketPaths ¶
func CheckSocketPaths() error
CheckSocketPaths checks that both Unix sockets shinyctl-api and the load balancer bind, api.sock and proxy/admin.sock, fit in a socket path. They live under the home directory, so a long one fails every start; checking both up front gives the reason, where the second would otherwise fail after the first was already bound.
func CopyLogPath ¶
CopyLogPath returns the path to the log file of copy n of an app, ~/.shinyctl/logs/<app-group>-<app-name>.log for copy 1 (the name an app had before it could have copies) and <app-group>-<app-name>@<n>.log for the others. The name comes from group and name so two apps under the same shinyctl-api never share one; app names may not contain "@", so a copy's file can't be taken for another app's. Creates ~/.shinyctl/logs if needed.
func EnsureAPIRunning ¶
func EnsureAPIRunning() error
EnsureAPIRunning makes sure shinyctl-api is reachable over its Unix socket, launching it detached in the background (the ssh-agent pattern) if it isn't already. It returns once the socket is actually dialable, or an error if it never comes up.
func HasCommandLine ¶
HasCommandLine reports whether the process at pid's command line contains substr (shinyctl-api also uses it to recognise the load balancer's process). Treats a failure to even look it up (e.g. the process exited in the gap between the liveness check above and this call) as "can't confirm identity" — false, the conservative choice given this exists specifically to avoid false positives.
func IsAlive ¶
IsAlive reports whether app's recorded process is genuinely still running — not just whether some process exists at that PID. A dead process's PID can be recycled by the OS for an unrelated process; syscall.Kill(pid, 0) alone can't tell the difference. Checking the running command line against the entrypoint closes that gap cheaply and portably (from /proc on Linux and from `ps` elsewhere, in either case read without regard to the locale; see commandLine), unlike reading the OS's own process-start-time.
The entrypoint recorded in app wins over spec's: after a re-apply, spec describes the replacement, and the recorded process must still be recognised so it can be stopped instead of orphaned. spec's entrypoint is the fallback for records written before Start recorded one. If both are empty, the identity check is skipped — callers without a spec handy still get the plain PID check.
func IsReady ¶
IsReady reports whether something is actually accepting TCP connections on host:port yet — distinct from IsAlive's PID-level check. A Shiny app can be alive (the R process exists) for a while before it's actually ready to serve, if it's loading a large dataset at startup; this is purely a display signal for `status`, never a restart/promotion input.
Dials the address the app actually bound, not a fixed 127.0.0.1: an app bound to one specific interface isn't listening on loopback at all, and would otherwise show as "starting" forever.
func LaunchDetached ¶
LaunchDetached is StartDetached for a caller that has no use for the process afterwards, and wants only its PID.
func LingerWarning ¶
func LingerWarning() string
LingerWarning returns a human-readable warning if this process risks being killed when the current user logs out, or "" if there's nothing to warn about — either because systemd lingering is already enabled, or because this isn't a systemd-managed Linux machine where the concern even applies (e.g. macOS, which has no loginctl at all).
func ListenUnix ¶
ListenUnix opens a Unix domain socket listener at path. If a socket file already exists there but nothing is actually listening on it (e.g. left behind by a crash), it's removed and replaced. If something genuinely is listening, ListenUnix refuses to start a second instance rather than silently taking over — two shinyctl-api processes racing on state.json is exactly the single-writer problem this whole design exists to avoid.
func PIDRunning ¶
PIDRunning reports whether app's recorded PID exists, without saying whose process it is. Callers use it to tell "nothing is running" from "something is, but it isn't the app" after Stop declines to signal.
func PickPort ¶
PickPort returns the first port in the internal range, scanning from start and wrapping around, that is not in taken and that free accepts. taken holds the ports other apps have recorded, which may belong to processes that are down at the moment, so they are never handed out twice; free asks the OS about the rest. A start outside the range is brought into it.
func PortAvailable ¶
PortAvailable reports whether host:port is free to bind on this machine right now, by actually binding it briefly. Meant to be checked only immediately before launching a process that's about to try to bind it itself — turns "Rscript exited, go dig through its log to find out httpuv couldn't bind" into a clear, immediate error instead. Doesn't close the window between this check and the real bind entirely — something else could still grab the port in between — it narrows it, the same way the PID-reuse guard narrows rather than closes its own gap.
The network is chosen from the address family, never the ambiguous "tcp" form: a bare net.Listen("tcp", ":port") can resolve to an IPv6 wildcard socket on a dual-stack machine, which does *not* collide with an existing IPv4-only listener on the same port number. Found live: a leftover R process really was holding the port (confirmed via lsof), but the "tcp"/"" version of this check reported it as available anyway, silently defeating the whole point of the check. Binding exactly what Shiny will bind — same family, same address — is what makes the answer mean something.
For a specific (non-wildcard) host the answer is best-effort: whether binding 127.0.0.1:P succeeds while something holds 0.0.0.0:P depends on the OS's SO_REUSEADDR rules (Go sets it on listeners), and macOS and Linux disagree. A collision this misses still surfaces as a Start failure through the same crash-backoff path, just with a worse message.
func PortAvailableAlongside ¶
PortAvailableAlongside is PortAvailable for a port the load balancer's own listener on the same app already holds: it binds with SO_REUSEPORT, as the load balancer's sockets do, so that socket doesn't count against the address while another program's does. It is what a move of an app's host on the same port is checked with.
func PortStart ¶
func PortStart() int
PortStart is where this user's port scan begins: a point of its own, from the user id, and a small random step. Everyone starting at the bottom of the range would have two users' shinyctl-api daemons, which both pick the lowest free port, hand the same port to two new copies at about the same time.
func ProxyDir ¶
ProxyDir returns ~/.shinyctl/proxy, where the load balancer keeps its settings, lock and control socket, creating it if needed.
func RSS ¶
RSS returns the resident memory, in bytes, of each of pids that ps can see. One ps call covers all of them: status asks for every app at once, and a process spawn per app on every query would add up. A PID that is gone is simply absent from the result, and so is every PID if ps itself fails — memory is informational, never worth failing a status over.
func RegistryPath ¶
RegistryPath returns the path shinyctl-api persists its registry of applied apps to, creating ~/.shinyctl if needed.
func RotateLog ¶
RotateLog turns path over if it has grown past max: the current contents are copied to `path.1` (replacing whatever was there) and path itself is truncated to zero. It reports whether a rotation happened. A missing file is simply "nothing to rotate."
Copy-then-truncate, rather than the usual rename-and-reopen, because the process writing the log isn't ours to signal: an R process holds its log open from exec until exit, and shinyctl-api can't hand it a new descriptor. Truncation works with that instead of against it — the child's descriptor is O_APPEND, and O_APPEND writes always land at the current end of file, so after the truncate its next line starts the fresh log at offset zero. The cost is the same one logrotate's `copytruncate` accepts: anything written in the gap between the copy finishing and the truncate is lost.
func RunAppExpression ¶
RunAppExpression is the R expression that runs an app: the one command line Start launches, so that what identifies a process afterwards (see inCommandLine) is derived from the same text.
func SocketDialable ¶
SocketDialable reports whether something is actually listening at path right now.
func SocketPath ¶
SocketPath returns the path to shinyctl-api's Unix domain socket, creating ~/.shinyctl if needed.
func Start ¶
Start launches copy number copy of spec's app, an R process on InternalHost:port, and returns its initial state (that copy, on that port, started at revision), plus a channel that receives a single Exit the instant the process exits — for any reason, crash or otherwise. The caller can block on it to react to death immediately instead of waiting for the next periodic liveness check.
The copy's log gets a marker line before R starts, so a log that holds several starts can be read as separate runs.
func StartDetached ¶
StartDetached starts path with args as a background process, fully detached from the caller: a new session (via setsid), so it survives the caller's process group and controlling terminal going away, with its output appended to logPath instead of inherited from the caller. It does not wait for the child to exit; the caller can, through the returned command.
func Stop ¶
Stop terminates app's recorded process and only returns once it's actually gone: SIGTERM first, then SIGKILL if the process is still around after stopGrace. The caller's next step is clearing the record from state.json, and a record cleared while the process is still running (and still holding its port) turns the next apply's port check into a phantom crash. A PID that's already gone (ESRCH) is treated as success — "make sure it's stopped" trivially holds if it already is.
It signals only while the process is identifiably the app's own (see isOurs; fallbacks are for records that predate the recorded entrypoint), and checks again before SIGKILL, because the grace period is long enough for a process that exited to have its PID handed to a stranger. signaled=false means there was nothing of ours to stop (no PID, already gone, or someone else's); that counts as success.
func StopIf ¶
StopIf is Stop for a process that isn't an app's, such as the load balancer: SIGTERM, SIGKILL after the same grace period, each signal only while ours reports that pid is still the process the caller means.
func WatchExit ¶
WatchExit returns a channel that is closed when app's recorded process exits. It works for any process, not only our children: it is how a process left behind by an earlier run is noticed the instant it dies. It costs one goroutine and one descriptor until the process exits, and both are released then.
The handle is opened before the identity is checked, not after. A handle names one process, whichever one held the PID when it was opened; it never moves to a later process that reuses the PID. So if the process the handle names is the app's (checked next, as IsAlive does), the exit it reports is the app's, and if the PID was reused before the handle was opened the check fails and the handle is closed. Checking first would leave a gap in which the app could die and its PID be taken before the handle was opened.
An error means nothing is being watched: ErrNotOurs, ErrWatchUnsupported or whatever the system said; the caller falls back to checking regularly.
Types ¶
type Owner ¶
type Owner int
Owner says whose a listening socket is.
const ( // OwnerUnknown: it can't be told (another system, or the lookup failed). // Callers fall back to what they knew before: the port accepts // connections. OwnerUnknown Owner = iota // OwnerNone: nothing listens on the port. OwnerNone // OwnerSelf: the process asked about, or one it started, holds the // listening socket. OwnerSelf // OwnerOther: another process holds it. OwnerOther )
func PortOwner ¶
PortOwner says whether the socket that listens on the internal port belongs to the copy at pid: held by pid itself or by a process descended from it (an R that started a worker, a wrapper that started R). A copy counts as ready only when it does, so a stranger that took the port first, another user's shinyctl-api picking the same internal port, is never taken for the copy. The lookup is by the system's own tables: /proc on Linux, lsof on macOS (there is no way to ask the kernel for it without cgo that is stable across macOS releases, and lsof is part of every macOS); elsewhere it can't be told and says so.