workmap 0.1.0__py3-none-any.whl

workmap/multiplexer.py

@@ -0,0 +1,201 @@
+"""What a terminal multiplexer is holding, and the only place that runs `tmux`.
+
+`terminal.py` is the emulator you are sitting in front of. This is the one
+running inside it. `drivers/` is the only place that speaks AppleScript; this
+is the only place that speaks tmux, and the parallel is deliberate.
+
+It is one module rather than a package with a contract, because it only ever
+*reads*. workmap will never retitle a pane, move one or close one, so there is
+nothing here shaped like the driver contract. It becomes a package the day two
+modules would have to answer the same question two different ways. That is not
+a claim about how many multiplexers exist: it is that a multiplexer nobody has
+written code for is protected by construction, because anything that cannot be
+asked ends up in `unasked` and keeps everything under it. A missing
+implementation degrades to the old behaviour rather than to danger, which is
+what makes one module enough.
+
+The question is: **which live panes exist, and which process does each hold.**
+
+A pane matters because it is somewhere a person can still get back to. That is
+what makes it different from a closed tab, and it is why an unattached pane
+counts: surviving the terminal is the whole point of a multiplexer, and `tmux
+attach` reaches a detached session, which is exactly what an orphan cannot
+offer.
+
+Finding the servers and finding their sockets are two problems, and only the
+first is easy. The process table already names every running multiplexer, so
+there is nothing to search for. For the sockets, the obvious answer, listing
+tmux's socket directory, is the wrong one: it misses `tmux -S /some/path`
+entirely, it misses a `$TMUX_TMPDIR` set in somebody else's environment, and
+it finds sockets of servers that have died, which are then asked and answer
+nothing. Ask the running servers instead. One `lsof` over the pids already in
+hand returns each one's socket path, wherever it lives. Measured: a `-S` path
+comes back the same way. It can still name a socket that has been unlinked,
+because a server that unlinks its own socket is still holding it open, and
+that costs one query that fails into the protective answer rather than a whole
+directory of them.
+
+The obvious cheaper rule, "a process with a controlling terminal is one
+somebody can get back to", was measured and is false. A child of a pty whose
+master has closed keeps reporting that tty in `ps`, indefinitely: with the
+master open it read ttys010, and after closing the master, and again a second
+later, it still read ttys010. A closed Terminal tab and a closed tmux pane are
+exactly that shape, so a tty proves nothing about whether anybody can reach a
+process, and a tool that believed otherwise would go blind to the very
+orphans it exists to find. tmux naming a pane is evidence. A tty is not.
+
+Measured on this machine: `live_panes()` over ~1000 processes takes 1.8ms and
+starts no subprocess when no multiplexer is running, and 28.6ms when one is
+(one `lsof` at ~19ms, one `tmux` query at ~6ms), against a scan of about a
+second.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .config import addressable
+from .model import multiplexer_name
+from .procs import run_partial, unix_socket_paths
+
+# Only tmux can say which processes its panes hold. Measured against the
+# screen this machine ships (4.00.03): `screen -ls` names sessions and says
+# attached or detached and stops there; `screen -Q`, which could have
+# answered, arrived in 4.5; and screen 4 talks over FIFOs rather than unix
+# sockets, so there is not even a socket to find. zellij, dtach, abduco and
+# byobu are not measured at all. All five degrade the same way, to being asked
+# nothing, which leaves their whole server holding everything under it. That
+# is the conservative answer, and for screen it is the only one available.
+CAN_BE_ASKED = frozenset({"tmux"})
+
+# pane_pid, pane_dead and session_attached are fixed-width fields and go
+# first; the name goes last, because a session name is text somebody chose and
+# may contain spaces, and this is read with a bounded split. Same reason `ps`
+# is asked for `lstart` in front of the command in procs.process_snapshot().
+_PANE_FORMAT = ("#{pane_pid} #{pane_dead} #{session_attached} "
+                "#{session_name}:#{window_index}.#{pane_index}")
+
+
+@dataclass(frozen=True)
+class Pane:
+    pid: int
+    where: str      # "tmux work:1.0", for the sentence a person reads
+    attached: bool
+
+
+@dataclass(frozen=True)
+class Panes:
+    """What the multiplexers on this machine are holding.
+
+    Three answers rather than two, because a server that answered and a server
+    that could not be asked hold different amounts:
+
+      live      each pane holds its own subtree
+      asked     these servers hold only what they are showing
+      unasked   these servers hold everything under them, as they always did
+    """
+    live: list = field(default_factory=list)
+    asked: list = field(default_factory=list)
+    unasked: list = field(default_factory=list)
+
+
+def live_panes(rows: list[dict]) -> Panes:
+    """Every pane a running multiplexer holds, and how much each server keeps.
+
+    `unasked` is the important part. A multiplexer that could not be
+    questioned is not the same as one holding nothing, and it has to be
+    treated as holding everything under it. Every way of failing to ask ends
+    up there and none of them has to be recognised separately: the multiplexer
+    is not tmux, `lsof` could not read the process, `tmux` is not on PATH, the
+    server went away between the process table and the query, the socket path
+    was too long for the kernel, the query timed out, or the answer did not
+    parse. The set is built by starting with every multiplexer and taking away
+    only the ones that named at least one live pane, so a way of failing that
+    nobody thought of still lands in it.
+    """
+    mux = [(r["pid"], multiplexer_name(r["cmd"])) for r in rows
+           if multiplexer_name(r["cmd"])]
+    if not mux:
+        # The reason this reads the process table first: on a machine with no
+        # multiplexer running, a scan does not gain a single subprocess.
+        # Checked by a test that fails if anything is run here.
+        return Panes()
+
+    askable = [pid for pid, name in mux if name in CAN_BE_ASKED]
+    unasked = {pid for pid, name in mux if name not in CAN_BE_ASKED}
+
+    sockets = unix_socket_paths(askable)
+    live: list = []
+    answered: set = set()
+    for path in sorted({p for paths in sockets.values() for p in paths}):
+        found = _panes_on(path)
+        if found:
+            answered.add(path)
+            live.extend(found)
+
+    asked = []
+    for pid in askable:
+        # A server counts as asked only if one of its own sockets named a live
+        # pane. A tmux *client* holds a connection rather than a listening
+        # socket, so it usually names nothing and lands in `unasked`, which
+        # costs nothing: a client's subtree is the connection and no more, and
+        # the terminal it is sitting in already holds it.
+        if any(path in answered for path in sockets.get(pid, ())):
+            asked.append(pid)
+        else:
+            unasked.add(pid)
+    return Panes(live=live, asked=asked, unasked=sorted(unasked))
+
+
+def _panes_on(socket_path: str) -> list:
+    """The live panes on one socket. Empty means the server could not be asked.
+
+    A live tmux server always has at least one pane: it exits when its last
+    one closes. So an empty answer is never a server holding nothing, it is a
+    query that failed, and confusing the two would drop the hold on every
+    process in every pane of a live server. `tmux` prints "no server running"
+    and "error connecting" to stderr and exits non-zero with nothing on
+    stdout, so there is no separate error to read: the emptiness is the
+    signal, and reading it that way covers every other way of coming back with
+    nothing as well.
+    """
+    raw = run_partial(
+        ["tmux", "-S", socket_path, "list-panes", "-a", "-F", _PANE_FORMAT],
+        timeout=3.0,
+    )
+    return parse_panes(raw)
+
+
+def parse_panes(raw: str) -> list:
+    """tmux's answer, read back.
+
+    Kept apart from running tmux so it can be tested against output a real
+    tmux produced rather than output somebody invented.
+    """
+    out: list = []
+    for line in raw.splitlines():
+        parts = line.split(None, 3)
+        if len(parts) < 4 or not parts[0].isdigit():
+            continue
+        # A dead pane is one tmux is still showing after its process exited,
+        # which `remain-on-exit` leaves behind. Its pane_pid names a process
+        # that is gone, and macOS hands pids back out, so treating it as live
+        # would sooner or later hold an unrelated process that inherited the
+        # number.
+        if parts[1] != "0":
+            continue
+        out.append(Pane(pid=int(parts[0]),
+                        where=f"tmux {_plain(parts[3])}",
+                        attached=parts[2] != "0"))
+    return out
+
+
+def _plain(name: str) -> str:
+    """A session name with nothing in it that can move a cursor.
+
+    This ends up beside a confirmation prompt somebody is about to answer, and
+    a session name is text they typed, so it can carry an escape sequence
+    exactly as a profile name or a project name can. Cleaned at this boundary
+    rather than at each place it is printed, by the same rule that decides
+    whether a project name is safe to put on a terminal.
+    """
+    return name if addressable(name) else "a session"