Server(fix[socket]): Check socket path length

why: A tmux socket is a UNIX domain socket, so its path is capped by
`sockaddr_un` -- 107 bytes on Linux, 103 on macOS. tmux reports an
overrun as `error connecting to <path> (File name too long)`, which
names the path but not how far over it is, nor which variable made it
that long. The overrun is usually inherited rather than typed: a deep
pytest `tmp_path`, an XDG runtime dir, a nested worktree.

what:
- Add `exc.SocketPathTooLong` carrying the path, the byte count, how
  far over the limit it is, and the environment variable it came from.
- Measure each route where tmux itself resolves it. A `socket_path` is
  passed through unchanged as `-S<path>`, so it is settled at
  construction and refused there. A `socket_name` resolves against
  `$TMUX_TMPDIR`, which tmux re-reads at exec rather than when the
  Server was built, so measuring it at construction would check a value
  with no bearing on what tmux binds -- it is measured per command
  instead, where `colors` is already checked.
- Add `Server.socket_args()` and build every tmux spawn from it. The
  flags were previously reconstructed in four places -- `cmd`,
  `raise_if_dead`, the format-query layer and the control-mode client,
  the last two spawning tmux themselves -- so a check on any one of
  them would have covered part of the surface.
- Resolve a bare server's socket the way a bare tmux client does,
  preferring `$TMUX` over `$TMUX_TMPDIR`. Inside a pane tmux never
  consults the directory, so measuring it would refuse a server tmux
  reaches without difficulty.
- Constructing a named or bare Server has no side effect, so
  `is_alive()` still answers for a server that cannot be reached, and
  `raise_if_dead()` still reports why.

Fixes #725

Author: tony

CHANGES

@@ -45,6 +45,48 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Socket paths are measured before tmux sees them (#730)
+
+A tmux socket is a UNIX domain socket, so its path is capped by `sockaddr_un`
+— 107 bytes on Linux, 103 on macOS. {class}`~libtmux.Server` now measures the
+path and raises the new {exc}`~libtmux.exc.SocketPathTooLong`, carrying the
+byte count, how far over the limit it is, and where the length came from.
+tmux reports the overrun as `error connecting to <path> (File name too long)`,
+which names the path but not the numbers, nor which variable made it long.
+
+Where the measurement happens follows what tmux actually reads. A
+`socket_path` is passed through unchanged as `-S<path>`, so it is measured at
+construction, where the caller can still change it. A `socket_name` resolves
+against `$TMUX_TMPDIR` — which tmux re-reads when it runs, not when the
+{class}`~libtmux.Server` was built — so it is measured on each command
+instead. The inherited case is the one that bites: a pytest `tmp_path`, an XDG
+runtime dir, a nested worktree, a CI checkout under a long workspace prefix.
+The fix is a shorter socket directory: {func}`tempfile.mkdtemp` or a short
+`$TMUX_TMPDIR`. See {ref}`socket_path_length` for the pytest case.
+
+Naming a server that way stays free of side effects, so
+{meth}`~libtmux.Server.is_alive` keeps answering — an address the kernel
+cannot hold is one more way of not being alive — and
+{meth}`~libtmux.Server.raise_if_dead` keeps being the way to ask why.
+
+A bare {class}`~libtmux.Server` inside a tmux pane is left alone. tmux prefers
+`$TMUX` over `$TMUX_TMPDIR` when no socket is named, so a script running
+inside tmux is measured against the socket it will actually use rather than a
+directory tmux never consults.
+
+#### `Server.socket_args()` builds a server's socket flags (#730)
+
+{meth}`Server.socket_args() <libtmux.Server.socket_args>` returns the
+`-S`/`-L` flags that address a server, measuring the socket path on the way.
+Every libtmux path that spawns tmux — {meth}`~libtmux.Server.cmd`,
+{meth}`~libtmux.Server.raise_if_dead`, the format-query layer, the control-mode
+client — builds its argv from it, and code that shells out to tmux on a
+libtmux {class}`~libtmux.Server`'s behalf can do the same instead of
+reconstructing the flags from {attr}`~libtmux.Server.socket_name` and
+{attr}`~libtmux.Server.socket_path`.
+
 ### Fixes
 
 - {class}`~libtmux.Server` now reprs the socket path tmux resolves from

docs/api/testing/pytest-plugin/usage.md

@@ -112,6 +112,51 @@ True
 
 This is particularly useful when testing interactions between multiple tmux servers or when you need to verify behavior across server restarts.
 
+(socket_path_length)=
+
+### Socket paths and the UNIX socket limit
+
+A tmux socket is a UNIX domain socket, so its path is capped by `sockaddr_un`
+— 107 bytes on Linux, 103 on macOS. pytest's {fixture}`tmp_path` is nested
+deep by design (`/tmp/pytest-of-<user>/pytest-<n>/<test-name><n>`), so putting
+a socket under it — directly, or by pointing `TMUX_TMPDIR` at it — can overrun
+the limit on a long test name or a long temporary root. {class}`~libtmux.Server`
+measures an explicit `socket_path` as soon as it is passed and raises
+{exc}`~libtmux.exc.SocketPathTooLong` with the byte count, rather than letting
+tmux report `File name too long` with only the path to go on:
+
+```python
+>>> from libtmux import exc
+>>> from libtmux.server import Server as TmuxServer
+>>> deep_socket = "/tmp/" + "d" * 120 + "/sock"
+>>> try:
+...     TmuxServer(socket_path=deep_socket)
+... except exc.SocketPathTooLong as e:
+...     print(e.length)
+130
+```
+
+A `socket_name` is different: tmux resolves it against `$TMUX_TMPDIR` when it
+runs, so the length is only knowable at dispatch. Building the object is safe,
+and a test that only asks whether a server is there gets an answer instead of an
+exception — an unbindable address is one more way of not being alive:
+
+```python
+>>> from libtmux.server import Server as TmuxServer
+>>> with monkeypatch.context() as m:
+...     m.setenv("TMUX_TMPDIR", "/tmp/" + "d" * 120)
+...     TmuxServer(socket_name="deep").is_alive()
+False
+```
+
+The fixtures in this plugin sidestep it: {fixture}`server
+<libtmux.pytest_plugin.server>` and {fixture}`TestServer
+<libtmux.pytest_plugin.TestServer>` name their sockets with `socket_name`, which
+tmux resolves under its own short socket directory. In your own tests, keep
+`tmp_path` for files and reach for {func}`tempfile.mkdtemp` — which gives a
+short `/tmp/<random>` — when you need a socket path of your own, or point
+`TMUX_TMPDIR` somewhere short.
+
 (set_home)=
 
 ### Setting a temporary home directory

docs/topics/configuration.md

@@ -46,13 +46,16 @@ without you arranging anything.
 
 That leaves the two variables that *are* yours to set, and most people
 set neither. `TMUX_TMPDIR` is tmux's own — the directory it keeps sockets
-in. libtmux never reads it, but the tmux binary it shells out to does, so
-it shapes which server a bare {class}`~libtmux.Server` lands on; pass
-`socket_name` or `socket_path` when you would rather name the server
-outright. `LIBTMUX_TMUX_FORMAT_SEPARATOR` is the one variable libtmux
-itself defines: an advanced override for the separator (default `␞`) it
-uses internally to parse tmux's format output — you'd touch it only if
-that character ever collided with your own data.
+in. The tmux binary libtmux shells out to reads it, so it shapes which
+server a bare {class}`~libtmux.Server` lands on; pass `socket_name` or
+`socket_path` when you would rather name the server outright. libtmux
+reads it only to know where the socket lands, which is also how it can
+tell you that a deep `TMUX_TMPDIR` pushes the resolved path past what a
+UNIX socket address holds — {exc}`~libtmux.exc.SocketPathTooLong`, see
+{ref}`socket_path_length`. `LIBTMUX_TMUX_FORMAT_SEPARATOR` is the one
+variable libtmux itself defines: an advanced override for the separator
+(default `␞`) it uses internally to parse tmux's format output — you'd
+touch it only if that character ever collided with your own data.
 
 ## Format strings
 

src/libtmux/_internal/control_mode.py

@@ -64,16 +64,9 @@ def __enter__(self) -> Self:
 
         tmux_bin = self.server.tmux_bin or "tmux"
 
-        if self.server.socket_name is not None:
-            socket_args = ["-L", str(self.server.socket_name)]
-        elif self.server.socket_path is not None:
-            socket_args = ["-S", str(self.server.socket_path)]
-        else:
-            socket_args = []
-
         cmd = [
             tmux_bin,
-            *socket_args,
+            *self.server.socket_args(),
             "-C",
             "attach-session",
             "-t",

src/libtmux/_internal/env.py

@@ -34,10 +34,14 @@
 
 import os
 import pathlib
+import sys
 import typing as t
 
 from libtmux import exc
 
+if t.TYPE_CHECKING:
+    from libtmux._internal.types import StrPath
+
 TMUX: t.Final = "TMUX"
 """Environment variable tmux exports with ``socket_path,server_pid,session_id``."""
 
@@ -53,6 +57,20 @@
 DEFAULT_SOCKET_NAME: t.Final = "default"
 """Socket name tmux uses when neither ``-L`` nor ``-S`` was given."""
 
+# ``sun_path`` in ``struct sockaddr_un`` is a fixed-size char array, and the
+# stdlib publishes no constant for its size, so it is spelled out per platform.
+# The size is part of each platform's frozen ABI: 104 bytes on the BSD-derived
+# kernels (macOS, FreeBSD, OpenBSD, NetBSD), 108 on Linux and elsewhere. One
+# byte of it is the NUL terminator. The test suite probes the running kernel to
+# keep this honest, which reads better than bisecting for the limit at import
+# time.
+_SUN_PATH_SIZE: t.Final = (
+    104 if sys.platform.startswith(("darwin", "freebsd", "openbsd", "netbsd")) else 108
+)
+
+SOCKET_PATH_MAX_BYTES: t.Final = _SUN_PATH_SIZE - 1
+"""Bytes a tmux socket path may occupy on this platform."""
+
 
 def resolve_env(env: t.Mapping[str, str] | None = None) -> t.Mapping[str, str]:
     """Return *env*, defaulting to the live process environment.
@@ -131,6 +149,73 @@ def resolve_socket_path(
     )
 
 
+def check_socket_path_length(
+    socket_path: StrPath,
+    *,
+    socket_name: str | None = None,
+    env_var: str | None = None,
+    env_value: str | None = None,
+) -> None:
+    """Raise if *socket_path* is too long to be a UNIX socket address.
+
+    A tmux socket is a UNIX domain socket, so its path has to fit in
+    :data:`SOCKET_PATH_MAX_BYTES` -- a filesystem that accepts the path says
+    nothing about whether a socket can be bound at it. Length is counted in
+    *bytes*, as the kernel counts it, so a non-ASCII path runs out sooner than
+    its character count suggests.
+
+    Parameters
+    ----------
+    socket_path : str or :class:`os.PathLike`
+        Path to measure.
+    socket_name : str, optional
+        Socket name *socket_path* was resolved from, when it was resolved
+        rather than passed in. Recorded on the exception so the message can say
+        the length was inherited from ``$TMUX_TMPDIR``.
+    env_var : str, optional
+        Environment variable the socket directory came from, when one did.
+        Recorded on the exception so the message can name it.
+    env_value : str, optional
+        What that variable held, so the caller can see what to shorten.
+
+    Raises
+    ------
+    :exc:`~libtmux.exc.SocketPathTooLong`
+        When *socket_path* exceeds :data:`SOCKET_PATH_MAX_BYTES` bytes.
+
+    Examples
+    --------
+    >>> from libtmux._internal.env import (
+    ...     check_socket_path_length,
+    ...     SOCKET_PATH_MAX_BYTES,
+    ... )
+    >>> check_socket_path_length("/tmp/tmux-1000/default")
+
+    >>> try:
+    ...     check_socket_path_length("/tmp/" + "d" * 200 + "/sock")
+    ... except exc.SocketPathTooLong as e:
+    ...     (e.length, e.limit == SOCKET_PATH_MAX_BYTES)
+    (210, True)
+
+    A name that resolves somewhere too deep reports the name too:
+
+    >>> deep = resolve_socket_path("dev", env={"TMUX_TMPDIR": "/tmp/" + "d" * 200})
+    >>> try:
+    ...     check_socket_path_length(deep, socket_name="dev")
+    ... except exc.SocketPathTooLong as e:
+    ...     e.socket_name
+    'dev'
+    """
+    if len(os.fsencode(socket_path)) > SOCKET_PATH_MAX_BYTES:
+        raise exc.SocketPathTooLong(
+            socket_path,
+            SOCKET_PATH_MAX_BYTES,
+            socket_name=socket_name,
+            env_var=env_var,
+            env_value=env_value,
+        )
+
+
 def socket_path_from_env(env: t.Mapping[str, str] | None = None) -> str:
     """Return the tmux socket path recorded in ``$TMUX``.
 
@@ -188,6 +273,56 @@ def socket_path_from_env(env: t.Mapping[str, str] | None = None) -> str:
     return parts[0]
 
 
+def resolve_ambient_socket_path(env: t.Mapping[str, str] | None = None) -> pathlib.Path:
+    """Resolve the socket a *bare* tmux invocation talks to, in tmux's own order.
+
+    A tmux client given no ``-L`` or ``-S`` prefers ``$TMUX`` -- the socket of
+    the pane it is running inside -- and only falls back to computing a path
+    under ``$TMUX_TMPDIR`` when there is no pane. Measured against tmux 3.7b: a
+    bare client with ``$TMUX`` set connects even when ``$TMUX_TMPDIR`` names a
+    directory far too deep to bind, because it never looks there.
+
+    That order only holds for the bare client. Passing ``-L`` sends tmux to
+    ``$TMUX_TMPDIR`` regardless of ``$TMUX``, so a named socket resolves through
+    :func:`resolve_socket_path` instead.
+
+    Parameters
+    ----------
+    env : :class:`typing.Mapping`, optional
+        Environment to read. Defaults to :data:`os.environ`.
+
+    Returns
+    -------
+    :class:`pathlib.Path`
+        Socket path a bare tmux client would use.
+
+    Examples
+    --------
+    >>> from libtmux._internal.env import resolve_ambient_socket_path
+
+    Inside a pane, ``$TMUX`` names the socket outright:
+
+    >>> resolve_ambient_socket_path({"TMUX": "/tmp/tmux-1000/default,8421,0"})
+    PosixPath('/tmp/tmux-1000/default')
+
+    ``$TMUX_TMPDIR`` is not consulted when there is a pane to inherit from:
+
+    >>> resolve_ambient_socket_path(
+    ...     {"TMUX": "/tmp/sock,8421,0", "TMUX_TMPDIR": "/nowhere"}
+    ... )
+    PosixPath('/tmp/sock')
+
+    Outside tmux it falls back to the computed path:
+
+    >>> resolve_ambient_socket_path({})
+    PosixPath('/tmp/tmux-.../default')
+    """
+    try:
+        return pathlib.Path(socket_path_from_env(env))
+    except exc.NotInsideTmux:
+        return resolve_socket_path(env=env)
+
+
 def pane_id_from_env(env: t.Mapping[str, str] | None = None) -> str:
     """Return the pane id recorded in ``$TMUX_PANE``.