tailctl 0.1.0__py3-none-any.whl

tailctl/liveness.py

@@ -0,0 +1,137 @@
+"""Two-factor process liveness for tailctl holders and waiters.
+
+A holder is alive iff its PID is still running AND that process's create-time
+matches the value recorded when the holder was registered. The create-time
+check is what defeats PID reuse: macOS recycles PIDs aggressively, so a bare
+``os.kill(pid, 0)`` can wrongly report a dead session as alive.
+
+The module is structured around a ``ProcessTable`` protocol so the production
+code uses ``psutil`` and tests use ``FakeProcessTable`` — simulating PID reuse
+in real OS processes is unreliable on macOS.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import psutil
+
+
+class ProcessTable(Protocol):
+    """Minimal interface needed to capture and verify a process identity.
+
+    ``create_time`` is float seconds since epoch (locale-independent,
+    sub-second resolution). ``is_alive`` does the (pid, create_time) two-factor
+    check that PID reuse cannot fool.
+    """
+
+    def create_time(self, pid: int) -> float: ...
+
+    def is_alive(self, pid: int, expected_create_time: float) -> bool: ...
+
+    def pids_for_socket(self, socket_path: str) -> list[int]: ...
+
+
+@dataclass(frozen=True)
+class ProcessIdentity:
+    """A captured (pid, create_time) pair.
+
+    Pass the resulting identity into ``ProcessTable.is_alive`` to test
+    whether the same process is still running.
+    """
+
+    pid: int
+    create_time: float
+
+    @classmethod
+    def capture(cls, table: ProcessTable, pid: int) -> ProcessIdentity:
+        return cls(pid=pid, create_time=table.create_time(pid))
+
+
+class PsutilProcessTable:
+    """Production implementation of ``ProcessTable`` backed by psutil."""
+
+    def create_time(self, pid: int) -> float:
+        return psutil.Process(pid).create_time()
+
+    def is_alive(self, pid: int, expected_create_time: float) -> bool:
+        try:
+            proc = psutil.Process(pid)
+        except psutil.NoSuchProcess:
+            return False
+        try:
+            actual = proc.create_time()
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            return False
+        # Allow a small tolerance since create_time is float, but PID reuse on
+        # macOS happens on second-ish boundaries — a tight epsilon is enough.
+        return abs(actual - expected_create_time) < 0.001
+
+    def pids_for_socket(self, socket_path: str) -> list[int]:
+        """Pids of running tailscaled daemons bound to ``socket_path``.
+
+        Matched by an exact ``--socket=<path>`` argv token. Used to find a
+        leaked daemon that still holds an instance's UDS but has no live
+        registry row (spawn race, a row dropped without killing the pid, or
+        create_time drift hiding it from the two-factor check) — it would
+        otherwise wedge the next spawn with ``address already in use``.
+        """
+        needle = f"--socket={socket_path}"
+        found: list[int] = []
+        for proc in psutil.process_iter(["pid", "cmdline"]):
+            try:
+                cmdline = proc.info.get("cmdline") or []
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                continue
+            if needle in cmdline:
+                found.append(proc.info["pid"])
+        return found
+
+
+class FakeProcessTable:
+    """Test double for ``ProcessTable``.
+
+    Construct with a dict mapping pid → create_time. Use ``kill(pid)`` to
+    remove a process, and ``reuse(pid, new_create_time)`` to simulate a new
+    process being assigned the same PID — the key case real OS APIs make
+    hard to test deterministically.
+    """
+
+    def __init__(self, processes: dict[int, float] | None = None) -> None:
+        self._procs: dict[int, float] = dict(processes or {})
+        self._sockets: dict[int, str] = {}
+
+    def create_time(self, pid: int) -> float:
+        if pid not in self._procs:
+            raise LookupError(f"pid {pid} not in fake process table")
+        return self._procs[pid]
+
+    def is_alive(self, pid: int, expected_create_time: float) -> bool:
+        if pid not in self._procs:
+            return False
+        return abs(self._procs[pid] - expected_create_time) < 0.001
+
+    def pids_for_socket(self, socket_path: str) -> list[int]:
+        return [
+            pid
+            for pid, sock in self._sockets.items()
+            if sock == socket_path and pid in self._procs
+        ]
+
+    # --- test helpers ---
+
+    def kill(self, pid: int) -> None:
+        self._procs.pop(pid, None)
+        self._sockets.pop(pid, None)
+
+    def attach_socket(self, pid: int, socket_path: str) -> None:
+        """Record that ``pid`` is bound to ``socket_path`` (for orphan tests)."""
+        self._sockets[pid] = socket_path
+
+    def reuse(self, pid: int, new_create_time: float) -> None:
+        """Simulate PID reuse: same pid, different create_time."""
+        self._procs[pid] = new_create_time
+
+    def spawn(self, pid: int, create_time: float) -> None:
+        self._procs[pid] = create_time

tailctl/log.py

@@ -0,0 +1,43 @@
+"""Append-only JSON log with a single-generation 10 MB rotation.
+
+Every coordinator action (acquire, release, switch, reconciliation, reap,
+rollback escalation) writes one JSON object per line. Format is intentionally
+simple: a single object, no nesting beyond the immediate keys.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from tailctl import paths
+
+ROTATE_AT_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+def append(record: dict[str, Any], *, log_path: Path | None = None) -> None:
+    """Append one record. Rotates if the file would exceed ``ROTATE_AT_BYTES``."""
+    target = log_path or paths.log_jsonl()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    _rotate_if_needed(target)
+    line = json.dumps(record, separators=(",", ":"), sort_keys=True) + "\n"
+    with open(target, "a", encoding="utf-8") as fh:
+        fh.write(line)
+
+
+def _rotate_if_needed(target: Path) -> None:
+    try:
+        size = target.stat().st_size
+    except FileNotFoundError:
+        return
+    if size < ROTATE_AT_BYTES:
+        return
+    rotated = paths.log_jsonl_rotated() if target == paths.log_jsonl() else target.with_suffix(
+        target.suffix + ".1"
+    )
+    # Overwrite any prior rotation generation; we keep exactly one.
+    if rotated.exists():
+        rotated.unlink()
+    os.replace(target, rotated)

tailctl/paths.py

@@ -0,0 +1,79 @@
+"""Filesystem path resolution for tailctl runtime state.
+
+All on-disk state lives under a single root directory, defaulting to
+``~/.tailctl`` and overridable via the ``TAILCTL_HOME`` environment variable.
+The override is what makes tests hermetic: a test sets ``TAILCTL_HOME`` to a
+tmp dir and every path-returning function in this module follows it.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_ENV_VAR = "TAILCTL_HOME"
+_DEFAULT_HOME = "~/.tailctl"
+
+
+def home() -> Path:
+    """Return the tailctl state root directory.
+
+    Honors ``$TAILCTL_HOME`` if set, falling back to ``~/.tailctl``.
+    """
+    return Path(os.environ.get(_ENV_VAR, _DEFAULT_HOME)).expanduser()
+
+
+def profiles_yaml() -> Path:
+    return home() / "profiles.yaml"
+
+
+def state_json() -> Path:
+    return home() / "state.json"
+
+
+def state_lock() -> Path:
+    """Separate lock file; never atomic-renamed.
+
+    The flock is held on this file's inode so that an atomic rename of
+    ``state.json`` itself does not orphan the lock.
+    """
+    return home() / "state.json.lock"
+
+
+def instances_json() -> Path:
+    """Registry of running per-profile userspace tailscaled instances."""
+    return home() / "instances.json"
+
+
+def instances_lock() -> Path:
+    """Separate lock file for the instances registry (never atomic-renamed)."""
+    return home() / "instances.json.lock"
+
+
+def instances_dir() -> Path:
+    """Root for per-instance runtime dirs (socket + statedir + logs)."""
+    return home() / "instances"
+
+
+def instance_dir(profile: str) -> Path:
+    """Per-profile runtime dir holding its tailscaled socket, statedir, logs."""
+    return instances_dir() / profile
+
+
+def log_jsonl() -> Path:
+    return home() / "log.jsonl"
+
+
+def log_jsonl_rotated() -> Path:
+    return home() / "log.1.jsonl"
+
+
+def fixtures_dir() -> Path:
+    return home() / "fixtures"
+
+
+def ensure_home() -> Path:
+    """Create the state root if it doesn't exist; return its path."""
+    h = home()
+    h.mkdir(parents=True, exist_ok=True)
+    return h

tailctl/profiles.py

@@ -0,0 +1,71 @@
+"""Profile data type and lookup table.
+
+Profiles are the user's logical name → ``(account_id, tailnet, exit_node)``
+mapping. ``config.py`` (next PR up) constructs ``Profiles`` from
+``profiles.yaml``; the coordinator only depends on this lightweight type.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class PortForward:
+    """A native-TCP forward for a profile.
+
+    Under the userspace-per-identity model, a profile's tailnet may host
+    services (ClickHouse, Postgres, …) that native clients reach by connecting
+    to a stable ``127.0.0.1:<local_port>``. The forwarder relays that local
+    port through the profile's userspace tailscaled to ``remote_host:remote_port``.
+    ``local_port`` is optional; when 0/None the instance allocates a free port.
+    The resolved port is exported to ``tailctl run`` subprocesses as
+    ``<SERVICE>_ADDR=127.0.0.1:<local_port>`` (service upper-cased).
+    """
+
+    service: str
+    remote_host: str
+    remote_port: int
+    local_port: int = 0
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    account_id: str
+    tailnet: str | None = None
+    exit_node: str | None = None
+    expected_egress_ip: str | None = None
+    # Userspace-model fields:
+    accept_routes: bool = True
+    port_forwards: tuple[PortForward, ...] = field(default_factory=tuple)
+    # Name of an env var holding a Tailscale auth key for this profile's
+    # tailnet (sourced from BWS). When set and present in the environment,
+    # first login is non-interactive (no browser URL). Absent → fall back to
+    # the interactive one-time login.
+    auth_key_env: str | None = None
+
+
+class UnknownProfileError(KeyError):
+    """Profile name does not exist in profiles.yaml."""
+
+
+@dataclass(frozen=True)
+class Profiles:
+    """Read-only profile table with a configured default."""
+
+    default_name: str
+    by_name: dict[str, Profile]
+
+    def get(self, name: str) -> Profile:
+        try:
+            return self.by_name[name]
+        except KeyError as exc:
+            raise UnknownProfileError(name) from exc
+
+    @property
+    def default(self) -> Profile:
+        return self.get(self.default_name)
+
+    def names(self) -> list[str]:
+        return sorted(self.by_name.keys())

tailctl/registry.py

@@ -0,0 +1,180 @@
+"""On-disk registry of running userspace tailscaled instances.
+
+Replaces the global ``state.json`` coordination model. There is no shared
+network to coordinate anymore: each profile that a session needs gets its own
+userspace ``tailscaled`` (own socket, statedir, SOCKS/HTTP proxy ports), and
+several run simultaneously. This registry is a lightweight table — NOT a state
+machine — recording which profiles have a live instance, the ports they expose,
+their port-forwards, and a refcount so multiple sessions can share one instance.
+
+The locking discipline mirrors ``state.py``: an exclusive ``fcntl.flock`` on a
+SEPARATE ``instances.json.lock`` file, with the registry itself read/mutated/
+written atomically via ``tmp + os.replace``.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from tailctl import paths
+
+REGISTRY_SCHEMA_VERSION = 1
+
+
+@dataclass
+class Forward:
+    """One active port-forward for an instance."""
+
+    service: str
+    local_port: int
+    remote_host: str
+    remote_port: int
+    pid: int | None = None  # relay subprocess pid (None until started)
+    create_time: float | None = None
+
+
+@dataclass
+class Holder:
+    """A live claim on an instance by some owning process.
+
+    The refcount is ``len(holders)``; each holder is identified by a two-factor
+    ``(owner_pid, owner_create_time)`` so a crashed owner's claim can be reaped
+    (and PID reuse can't resurrect it). ``up`` adds a holder; ``down`` removes
+    the caller's; ``reap`` drops dead-owner holders and stops orphaned daemons.
+    """
+
+    owner_pid: int
+    owner_create_time: float
+    since: str = ""
+
+
+@dataclass
+class Instance:
+    """A running per-profile userspace tailscaled, plus its forwards/holders."""
+
+    profile: str
+    pid: int
+    create_time: float
+    socket: str
+    statedir: str
+    socks_port: int
+    http_port: int
+    created_at: str = ""
+    forwards: list[Forward] = field(default_factory=list)
+    holders: list[Holder] = field(default_factory=list)
+    # False while the daemon is registered but awaiting first login; flips True
+    # once exit node + forwards are applied. Distinguishes a pending instance
+    # (which already has a holder) from a finalized one.
+    finalized: bool = True
+    # Epoch seconds when the last holder released gracefully — starts the linger
+    # window during which the warm daemon is kept for fast reuse. None while held
+    # (or when the owner crashed: then reap stops it immediately, no grace).
+    released_at: float | None = None
+
+    @property
+    def refcount(self) -> int:
+        return len(self.holders)
+
+
+@dataclass
+class Registry:
+    schema_version: int = REGISTRY_SCHEMA_VERSION
+    generation: int = 0
+    instances: dict[str, Instance] = field(default_factory=dict)
+
+
+class RegistryCorruptError(RuntimeError):
+    """instances.json could not be parsed."""
+
+
+def _registry_from_dict(data: dict[str, Any]) -> Registry:
+    if data.get("schema_version") not in (None, REGISTRY_SCHEMA_VERSION):
+        raise ValueError(
+            f"unrecognized registry schema_version: {data.get('schema_version')!r}; "
+            f"expected {REGISTRY_SCHEMA_VERSION}"
+        )
+    instances: dict[str, Instance] = {}
+    _fields = (
+        "profile", "pid", "create_time", "socket", "statedir",
+        "socks_port", "http_port", "created_at", "finalized", "released_at",
+    )
+    for name, body in (data.get("instances") or {}).items():
+        forwards = [Forward(**f) for f in body.get("forwards", [])]
+        holders = [Holder(**h) for h in body.get("holders", [])]
+        # Only pass known scalar fields; drop anything else (e.g. a legacy
+        # ``refcount`` key, now a derived property).
+        known = {k: body[k] for k in _fields if k in body}
+        instances[name] = Instance(forwards=forwards, holders=holders, **known)
+    return Registry(
+        schema_version=REGISTRY_SCHEMA_VERSION,
+        generation=int(data.get("generation", 0)),
+        instances=instances,
+    )
+
+
+class RegistryStore:
+    """Atomic, flock-coordinated access to instances.json.
+
+    Same contract as ``state.StateStore``: ``transaction()`` yields a mutable
+    ``Registry`` written on clean exit; ``read()`` is a lock-free snapshot.
+    """
+
+    def __init__(
+        self, *, registry_path: Path | None = None, lock_path: Path | None = None
+    ) -> None:
+        self._path = registry_path or paths.instances_json()
+        self._lock_path = lock_path or paths.instances_lock()
+
+    @contextmanager
+    def transaction(self) -> Iterator[Registry]:
+        self._lock_path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(self._lock_path, os.O_RDWR | os.O_CREAT, 0o600)
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+            reg = self._read_unlocked()
+            yield reg
+            reg.generation += 1
+            self._write_unlocked(reg)
+        finally:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            finally:
+                os.close(fd)
+
+    def read(self) -> Registry:
+        return self._read_unlocked()
+
+    def _read_unlocked(self) -> Registry:
+        if not self._path.exists():
+            return Registry()
+        try:
+            data = json.loads(self._path.read_text())
+        except json.JSONDecodeError as exc:
+            raise RegistryCorruptError(
+                f"registry at {self._path} is not valid JSON: {exc}"
+            ) from exc
+        if not isinstance(data, dict):
+            raise RegistryCorruptError(f"registry at {self._path} is not a JSON object")
+        return _registry_from_dict(data)
+
+    def _write_unlocked(self, reg: Registry) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
+        payload = json.dumps(
+            {
+                "schema_version": reg.schema_version,
+                "generation": reg.generation,
+                "instances": {n: asdict(i) for n, i in reg.instances.items()},
+            },
+            indent=2,
+            sort_keys=True,
+        )
+        tmp.write_text(payload)
+        os.replace(tmp, self._path)

tailctl/signals.py

@@ -0,0 +1,52 @@
+"""Signal handling for the wait loop.
+
+When a session sitting in ``coord.acquire`` receives SIGINT or SIGTERM (e.g.
+the user hits Ctrl-C, or the parent shell kills the tailctl process), we
+remove the session from the waiters list under the lock and re-elect the
+named handoff if we were the chosen successor. Then we re-raise the default
+disposition so the process actually exits.
+
+This module installs handlers on import-time only when ``install_handlers`` is
+called — leaving import side-effect free for tests that don't need them.
+"""
+
+from __future__ import annotations
+
+import signal
+from collections.abc import Callable
+from typing import Any
+
+# Callbacks registered by Coordinator.install_signal_handlers (one per wait).
+_cleanups: list[Callable[[], None]] = []
+_previous_handlers: dict[int, Any] = {}
+
+
+def push_cleanup(fn: Callable[[], None]) -> None:
+    """Register a cleanup to run on SIGINT/SIGTERM. Pops back automatically
+    when ``pop_cleanup`` is called."""
+    _cleanups.append(fn)
+
+
+def pop_cleanup() -> None:
+    if _cleanups:
+        _cleanups.pop()
+
+
+def _handler(signum: int, frame: Any) -> None:
+    while _cleanups:
+        try:
+            _cleanups.pop()()
+        except Exception:
+            # Best-effort: keep popping even on individual cleanup failure.
+            continue
+    # Re-raise default disposition by re-installing the previous handler
+    # and re-sending the signal.
+    prev = _previous_handlers.get(signum, signal.SIG_DFL)
+    signal.signal(signum, prev)
+    signal.raise_signal(signum)
+
+
+def install_handlers() -> None:
+    """Install SIGINT + SIGTERM handlers. Safe to call repeatedly."""
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        _previous_handlers[sig] = signal.signal(sig, _handler)