Documentation
¶
Overview ¶
Package daemon runs `loom serve`, the process that owns a global config dir's sessions (daemon stage 3B), and finds it for its clients.
One daemon serves one global dir. It holds an flock on <globalDir>/loom.lock for its whole life (the OS releases it when the process exits, crash included) and records in it who it is and where it listens (Record): clients read the socket's path from there rather than computing it, since their environment may differ from the daemon's. The lock lives in the global dir, not beside the socket, so two processes whose environments would put the socket in different places still exclude each other; and it is the path the TUI's own takeover lock used, so a loom from before the daemon and a daemon exclude each other too.
Index ¶
- Variables
- func CrashLogPath(globalDir string) string
- func LockPath(globalDir string) string
- func LogPath(globalDir string) string
- func Serve(o Options) error
- func SocketPath(globalDir string) (string, error)
- func Stop(globalDir string, timeout time.Duration) error
- func StopPID(globalDir string, pid int, timeout time.Duration) error
- func TakeLock(globalDir string) (release func(), err error)
- func TmuxServer(globalDir string) (string, error)
- func TryAcquire(globalDir string, rec Record) (*Lock, Record, error)
- type Lock
- type Options
- type Record
Constants ¶
This section is empty.
Variables ¶
var ErrDidNotStart = errors.New("the loom daemon did not start")
ErrDidNotStart: a daemon Connect spawned exited before it served.
var ErrHeld = errors.New("another loom process holds the lock")
ErrHeld is TryAcquire's answer while another process holds the lock.
var ErrNoDaemon = errors.New("no loom daemon is running")
ErrNoDaemon: ConnectNoSpawn found no daemon holding the lock.
var ErrNotRunning = errors.New("no loom daemon is running")
ErrNotRunning is Stop's answer when no daemon serves the global dir.
var ErrRunning = errors.New("a loom daemon is already running")
ErrRunning is Serve's answer when a daemon already serves the global dir.
Functions ¶
func CrashLogPath ¶
CrashLogPath is where globalDir's daemon writes a runtime crash (a fatal error, an unrecovered panic on a goroutine), which no log line records.
func Serve ¶
Serve runs globalDir's daemon until o.Stop is closed (it then says bye to every client, stops listening, waits for in-flight lifecycle jobs while their replies still reach the clients, saves every workspace, closes the connections and returns nil) or the model is gone (a panic: it returns that error, saying no bye and saving nothing, since the model's state is unknown, and its clients reconnect as after a crash). In order: it takes the lock (ErrRunning when another daemon holds it), boots the model, keeps the boot's notices for the first client, starts the loop and its tick, listens on its socket (SocketPath, mode 0600, recorded in the lock), and serves every connection with an rpc.Server. It listens only once booted, so a socket that answers is a daemon that is ready.
func SocketPath ¶
SocketPath is where globalDir's daemon listens, its directory made ready (0700, owned by this user): $XDG_RUNTIME_DIR/loom/<hash>.sock when the user has a runtime dir; else <globalDir>/run/serve.sock when that path fits a socket address; else /tmp/loom-<uid>/<hash>.sock, as tmux keeps its own. <hash> names the global dir, resolved, so each global dir (a loomdev sandbox's included) gets a daemon of its own. Only the daemon calls it: it records the path in its lock (Record.Socket), and clients dial what the record says, since their environment may differ from the daemon's.
func Stop ¶
Stop stops globalDir's daemon gracefully and waits, up to timeout, until its process has exited. It signals the pid its lock record names rather than asking over the socket, so it works whatever protocol the daemon speaks (a newer loom replacing an older daemon). ErrNotRunning when no daemon holds the lock; a loom from before the daemon holding it is left alone.
func StopPID ¶
StopPID is Stop for the daemon that is process pid: the one a client dialed and found older than itself. When the lock is free by now, or another process holds it, it signals nothing and returns ErrNotRunning: that daemon has gone, and the one holding the lock now (another client may have just started it, replacing the same old daemon) is not the one compared.
func TakeLock ¶
TakeLock takes globalDir's lock for a command that changes its state itself, with no daemon to ask (`loom reset` while none runs, `workspace migrate`), and returns the function that lets it go. Who holds it decides the answer:
- a live daemon, listening or still booting (liveHolder), is ErrRunning at once: the command is the daemon's to make; a record naming a socket whose daemon has gone is not, since a probe leaves the last holder's record behind;
- a live loom from before the daemon, or another live loom command holding it this way, is refused, naming it;
- anyone else (a client's ReadRecord probe, which leaves the last holder's record, or a process that has not written its own yet) is waited out for up to takeLockWait, then refused.
Its record names this process with no socket, as a daemon still booting does, so a daemon started meanwhile stands down and a client waits, and it keeps the tmux server the last daemon named, which the next one keeps (TmuxServer).
func TmuxServer ¶
TmuxServer is the tmux server a daemon for globalDir is to use (its socket's path): the last daemon's (its record's Tmux) while that server still runs, else the one this process's environment selects (tmux.ResolveServer). A daemon started from another environment (an ssh login without TMUX_TMPDIR, a client inside another tmux server, a newer loom replacing an older daemon) must find the agents where they run: on another server it would find every session dead and relaunch each agent there, two to a worktree.
Types ¶
type Lock ¶
type Lock struct {
// contains filtered or unexported fields
}
Lock is a held lock.
type Options ¶
type Options struct {
// GlobalDir is the global config dir the daemon serves.
GlobalDir string
// NewModel builds the model, not yet booted: Serve boots it once it
// holds the lock, so no two models ever load one global dir. The notices
// it returns (a registry that would not load, say) are kept for the
// first client with the boot's.
NewModel func() (*core.Model, []core.Notice, error)
// Build names this binary in the lock record (rpc.Build).
Build string
// Tmux is the tmux server the model's sessions run on (its socket's
// path; TmuxServer chooses it), which the daemon's hello names so its
// clients use it too, and its record so the next daemon keeps it. The
// caller pins it for this process first (tmux.UseServer).
Tmux string
// Stop is closed to stop the daemon gracefully (on SIGTERM, from
// `loom serve stop` or a newer loom replacing it).
Stop <-chan struct{}
// LockWait is how long to wait for a lock held by no live loom process
// (a client's ReadRecord probing it, say); one a live daemon holds is
// ErrRunning at once (acquire). 0 means 5s.
LockWait time.Duration
// QuiesceTimeout bounds the wait for in-flight lifecycle jobs when
// stopping (core.Loop.Quiesce). 0 means 30s.
QuiesceTimeout time.Duration
// WatchInterval is how often the daemon checks its socket file still
// exists (a runtime dir removed at logout, a tmp cleaner) and listens
// again if not. 0 means 2s: a client gives up on a silent daemon after
// seconds, and a check is one Lstat.
WatchInterval time.Duration
// Serving, when set, is called once the daemon listens: a test seam.
Serving func(loop *core.Loop, socket string)
}
Options configure Serve.
type Record ¶
type Record struct {
PID int `json:"pid"`
TTY string `json:"tty,omitempty"`
Started time.Time `json:"started"`
// Socket is the unix socket the daemon listens on.
Socket string `json:"socket,omitempty"`
// Build names the daemon's binary (rpc.Build).
Build string `json:"build,omitempty"`
// Host is the machine the daemon runs on: a global dir shared over a
// network filesystem must not have a pid signalled on the wrong host.
Host string `json:"host,omitempty"`
// Tmux is the tmux server the daemon's sessions run on (its socket's
// path), which the next daemon keeps while it runs (TmuxServer).
Tmux string `json:"tmux,omitempty"`
}
Record is what the lock file says about the process holding it. A daemon fills Build when it takes the lock and Socket once it listens; a loom TUI from before the daemon wrote only the first three, in the same JSON, so a record with neither is such a TUI (IsPreDaemon).
func Connect ¶
Connect dials globalDir's daemon, starting one when none runs, and returns the connection and the daemon's lock record. It reads the lock: a daemon holding it is dialed at the socket it recorded; a daemon still booting (it listens only once booted) is waited for, a live one up to bootTimeout; a live loom TUI from before the daemon holding it is refused; and with no holder it starts one (spawn) and waits for it. It retries, backing off, until a daemon answers or timeout passes. The spawner does not take the lock: two clients starting a daemon each is harmless, since the second daemon finds the first's lock and stands down, and both clients dial the first. A daemon that fails before it takes the lock (its nesting guard refused, say) fails Connect at once, quoting what it logged. It makes the global dir first, which the daemon starts in: a first launch with a new LOOM_GLOBAL_DIR, or LOOM_HOME and no ~/.loom yet, would otherwise fail to start any. A daemon it started that exits before serving is ErrDidNotStart.
func ConnectNoSpawn ¶
ConnectNoSpawn is Connect that never starts a daemon: a TUI waiting for one after a graceful stop. With no holder of the lock it returns ErrNoDaemon at once, and it waits for a booting daemon no longer than timeout (its caller polls again).
func ReadRecord ¶
ReadRecord reads globalDir's lock record, whoever holds it (zero when it can't be read). Held reports whether a process holds the lock now.
A record is rewritten in place (a rename would give the lock file a new inode, which the lock is on), so a reader can meet it half-written: a held lock whose record won't parse is read again for a moment.
func (Record) IsDaemon ¶
IsDaemon reports whether r is the record of a daemon that listens. One still booting has written its build but no socket yet.
func (Record) IsPreDaemon ¶
IsPreDaemon reports whether r is the record of a loom TUI from before the daemon: it names a process, but neither a socket nor a build. A record read mid-write names no process, and is neither this nor a daemon's.