@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.40.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_lock.py

@@ -0,0 +1,308 @@
+"""One copy of a service, locked before any side effect (LC-01, DEC-0057): the instance lock, the supervisor marker
+in both its forms, and the wait budget under a supervisor. Part of the service kit (FAA-65, layer L3)."""
+from __future__ import annotations
+
+import errno
+import hashlib
+import ntpath
+import os
+import posixpath
+import re
+import socket
+import sys
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Sequence
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+from fabric_base import (
+    SUPERVISOR_ENV,
+    ServiceError,
+    WINDOWS,
+    _O_BINARY,
+)
+from fabric_platform import (
+    _close_handle,
+    _create_first_pipe,
+    _pipe_exists,
+)
+from fabric_paths import (
+    ensure_private_dir,
+)
+
+
+EXIT_ALREADY_RUNNING = 75
+
+
+LOCK_WAIT_SUPERVISED_SECONDS = 300.0
+
+
+LOCK_BACKOFF_FIRST_SECONDS = 0.5
+
+
+LOCK_BACKOFF_MAX_SECONDS = 30.0
+
+
+class AlreadyRunning(ServiceError):
+    def __init__(self, holder_pid: Optional[int], lock_path: Path):
+        self.holder_pid = holder_pid
+        self.lock_path = lock_path
+        # FAC-SEM-078: a copy that cannot learn the holder's pid says the holder is unknown.
+        who = "process %d" % holder_pid if holder_pid else "an unknown process"
+        super().__init__("Another copy is already running (%s holds %s)." % (who, lock_path))
+
+
+class InstanceLock:
+    """Exclusive flock on <data>/service.lock, taken BEFORE any side effect.
+
+    Binding a port is not a lock: a second copy that resumes jobs before its
+    bind fails has already done damage. The lock is released by the kernel when
+    the process dies, so a crash never leaves it stale.
+    """
+
+    def __init__(self, data_dir: Path):
+        self.path = Path(data_dir) / "service.lock"
+        self._fd: Optional[int] = None
+        self._name: Any = None
+
+    #: Windows locks a byte range, not the file: one byte far past the pid the file holds, so the
+    #: holder may rewrite the pid and another process may still read it (locking past the end of
+    #: a file is allowed there).
+    WINDOWS_LOCK_OFFSET = 1 << 30
+
+    def acquire(self) -> "InstanceLock":
+        ensure_private_dir(self.path.parent)
+        fd = os.open(str(self.path), os.O_RDWR | os.O_CREAT | _O_BINARY, 0o600)
+        try:
+            if WINDOWS:
+                import msvcrt
+
+                os.lseek(fd, self.WINDOWS_LOCK_OFFSET, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                os.lseek(fd, 0, os.SEEK_SET)
+            else:
+                import fcntl
+
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as exc:
+            os.close(fd)
+            if exc.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES, getattr(errno, "EDEADLOCK", -1)):
+                raise AlreadyRunning(_read_pid(self.path), self.path) from None
+            raise
+        try:
+            self._name = _hold_lock_name(self.path)
+        except BaseException:
+            os.close(fd)
+            raise
+        os.ftruncate(fd, 0)
+        os.write(fd, str(os.getpid()).encode())
+        os.fsync(fd)
+        self._fd = fd
+        return self
+
+    def release(self) -> None:
+        if self._fd is not None:
+            os.close(self._fd)
+            self._fd = None
+        if self._name is not None:
+            _drop_lock_name(self._name)
+            self._name = None
+
+
+def lock_name(lock_path: Path, platform: str = sys.platform) -> Optional[str]:
+    """The name the Node kit holds for this lock file; None where it holds none (macOS: O_EXLOCK)."""
+    if platform.startswith("linux"):
+        digest = hashlib.sha256(posixpath.abspath(str(lock_path)).encode()).hexdigest()[:32]
+        return "\0fabric-service-" + digest
+    if platform == "win32":
+        # Windows paths compare without case: C:\Users and c:\users are one lock.
+        digest = hashlib.sha256(ntpath.normcase(ntpath.abspath(str(lock_path))).encode()).hexdigest()[:32]
+        return "\\\\.\\pipe\\fabric-service-" + digest
+    return None
+
+
+def _hold_lock_name(lock_path: Path) -> Any:
+    name = lock_name(lock_path)
+    if name is None:
+        return None
+    if WINDOWS:
+        handle = _create_first_pipe(name)
+        if handle is None:
+            raise AlreadyRunning(_read_pid(lock_path), lock_path)
+        return handle
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    try:
+        sock.bind(name)
+    except OSError as exc:
+        sock.close()
+        if exc.errno == errno.EADDRINUSE:
+            raise AlreadyRunning(_read_pid(lock_path), lock_path) from None
+        raise
+    # Held by its descriptor, like the file lock: a socket object would close when collected.
+    return sock.detach()
+
+
+def _drop_lock_name(held: Any) -> None:
+    if WINDOWS:
+        _close_handle(held)
+    else:
+        os.close(held)
+
+
+def lock_name_held(lock_path: Path) -> Optional[bool]:
+    """True when some process holds the lock's name (a running service of either kit); None where there is no name
+    to hold. It only looks — /proc/net/unix on Linux, WaitNamedPipeW on Windows — and never takes the name, so a
+    probe cannot make a service that is starting at that moment fail."""
+    name = lock_name(lock_path)
+    if name is None:
+        return None
+    if WINDOWS:
+        return _pipe_exists(name)
+    try:
+        with open("/proc/net/unix", encoding="utf-8", errors="replace") as table:
+            return any(line.rstrip("\n").endswith(" @" + name[1:]) for line in table)
+    except OSError:
+        return None
+
+
+def _read_pid(path: Path) -> Optional[int]:
+    try:
+        text = path.read_text().strip()
+        return int(text) if re.fullmatch(r"[0-9]{1,10}", text, re.ASCII) else None
+    except OSError:
+        return None
+
+
+#: The managers a supervisor marker may name (DEC-0057): the three systems' supervisors and Project Observatory's node.
+SUPERVISORS = ("launchd", "systemd", "task-scheduler", "node")
+
+
+#: The argument form of the marker, for a supervisor whose start carries no environment (a Scheduled Task's action).
+SUPERVISOR_ARG = "--fabric-supervisor"
+
+
+def _marker_arguments(argv: Sequence[Any]) -> List[str]:
+    """The marker values an argument vector carries after the executable and before ``--``. A bare
+    ``--fabric-supervisor`` followed by nothing, by ``--`` or by another ``--…`` flag is a marker with an empty value
+    and consumes nothing."""
+    values: List[str] = []
+    index = 1
+    while index < len(argv):
+        item = argv[index]
+        if item == "--":
+            break
+        if item == SUPERVISOR_ARG:
+            following = argv[index + 1] if index + 1 < len(argv) else None
+            if isinstance(following, str) and not following.startswith("--"):
+                values.append(following)
+                index += 1
+            else:
+                values.append("")
+        elif isinstance(item, str) and item.startswith(SUPERVISOR_ARG + "="):
+            values.append(item[len(SUPERVISOR_ARG) + 1:])
+        index += 1
+    return values
+
+
+def supervisor_marker(env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> Dict[str, Any]:
+    """How this copy was started (DEC-0057), from ``FABRIC_SERVICE_SUPERVISOR=<manager>`` and
+    ``--fabric-supervisor <manager>`` / ``--fabric-supervisor=<manager>`` (``env`` and ``argv`` default to this process's):
+
+    - ``{"kind": "supervised", "manager", "forms"}`` — every marker present names the same manager of SUPERVISORS;
+    - ``{"kind": "conflict", "values", "forms"}`` — the markers disagree: the copy is unsupervised and exits 75 at once,
+      before it takes the lock (an empty or bare argument beside a variable disagrees with it);
+    - ``{"kind": "manual", "forms", "unreadable"?}`` — no marker (only an empty variable counts as none), or one that
+      names no manager.
+
+    A copy never infers supervision from its parent process. The contract's ``supervisorMarker``."""
+    env = os.environ if env is None else env
+    argv = sys.argv if argv is None else argv
+    variable = env.get(SUPERVISOR_ENV) if isinstance(env, dict) or hasattr(env, "get") else None
+    from_env = [variable] if isinstance(variable, str) and variable != "" else []
+    from_args = _marker_arguments(list(argv) if isinstance(argv, (list, tuple)) else [])
+    forms = (["environment"] if from_env else []) + (["argument"] if from_args else [])
+    values: List[str] = []
+    for value in from_env + from_args:
+        if value not in values:
+            values.append(value)
+    if len(values) > 1:
+        return {"kind": "conflict", "values": values, "forms": forms}
+    if not values:
+        return {"kind": "manual", "forms": forms}
+    if values[0] in SUPERVISORS:
+        return {"kind": "supervised", "manager": values[0], "forms": forms}
+    return {"kind": "manual", "unreadable": values[0], "forms": forms}
+
+
+def lock_wait_budget_seconds(marker: Dict[str, Any]) -> float:
+    """How long a copy started so may wait for the lock: 300 s when supervised, else not at all."""
+    return LOCK_WAIT_SUPERVISED_SECONDS if marker.get("kind") == "supervised" else 0.0
+
+
+def marker_conflict_message(marker: Dict[str, Any]) -> str:
+    """The one sentence a copy whose markers disagree exits with, naming the markers present."""
+    shown = ", ".join(repr(v) for v in marker["values"])
+    if marker["forms"] == ["environment", "argument"]:
+        return "%s and %s disagree (%s); not starting unsupervised." % (SUPERVISOR_ENV, SUPERVISOR_ARG, shown)
+    return "%s is given with different values (%s); not starting unsupervised." % (SUPERVISOR_ARG, shown)
+
+
+def supervised(env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> bool:
+    """True when a supervisor that restarts on exit started this process and said so with the marker
+    (``launchd_plist`` and ``systemd_unit`` set the variable, ``task_xml`` writes the argument, a node sets either)."""
+    return supervisor_marker(env, argv)["kind"] == "supervised"
+
+
+def supervised_by_launchd(env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> bool:
+    """True when launchd started this process from a plist written by ``launchd_plist``.
+
+    The plist says so explicitly (``FABRIC_SERVICE_SUPERVISOR=launchd``); the parent process or
+    ``XPC_SERVICE_NAME`` is not evidence — a terminal inside an app carries one too."""
+    return supervisor_marker(env, argv).get("manager") == "launchd"
+
+
+def add_supervisor_argument(parser: Any) -> Any:
+    """Let a service's own argparse parser accept the marker in both spellings, and a bare one, and ignore it
+    (DEC-0057: argparse exits 2 on an unknown flag). The kit reads the marker from ``sys.argv`` itself."""
+    import argparse
+    parser.add_argument(SUPERVISOR_ARG, nargs="?", const="", default=None, help=argparse.SUPPRESS)
+    return parser
+
+
+def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *,
+                         sleep: Callable[[float], None] = time.sleep,
+                         clock: Callable[[], float] = time.monotonic,
+                         env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> InstanceLock:
+    """Take the lock or exit 75 with one sentence naming the holder (DEC-0057, FAC-SEM-078).
+
+    Markers that disagree exit 75 at once, before the lock, naming them. Started by hand (no
+    marker), a held lock exits 75 at once. Under a supervisor that restarts on exit an immediate
+    exit is a respawn every few seconds, forever; so a supervised copy first backs off in-process
+    (0.5 s doubling to 30 s, ``LOCK_WAIT_SUPERVISED_SECONDS`` in all), takes over if the holder
+    leaves, and exits 75 only when the wait runs out. Nothing has been touched while it waits.
+    ``wait_seconds`` overrides the choice (0 = never wait); ``env`` and ``argv`` default to this process's."""
+    marker = supervisor_marker(env, argv)
+    if marker["kind"] == "conflict":
+        print(marker_conflict_message(marker), file=sys.stderr)
+        raise SystemExit(EXIT_ALREADY_RUNNING)
+    if wait_seconds is None:
+        wait_seconds = lock_wait_budget_seconds(marker)
+    deadline = clock() + max(0.0, wait_seconds)
+    delay = LOCK_BACKOFF_FIRST_SECONDS
+    announced = False
+    while True:
+        try:
+            return InstanceLock(data_dir).acquire()
+        except AlreadyRunning as exc:
+            remaining = deadline - clock()
+            if remaining <= 0:
+                print(str(exc), file=sys.stderr)
+                raise SystemExit(EXIT_ALREADY_RUNNING)
+            if not announced:
+                print("%s Waiting up to %.0f s for it to exit." % (exc, remaining), file=sys.stderr, flush=True)
+                announced = True
+            sleep(min(delay, remaining))
+            delay = min(delay * 2, LOCK_BACKOFF_MAX_SECONDS)

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_logs.py

@@ -0,0 +1,202 @@
+"""Logs and stopping (LC-01, LC-12): a rotating log, a capped stdout log, the stop signal and the drain.
+Part of the service kit (FAA-65, layer L3)."""
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+import signal
+import threading
+import time
+import traceback
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Sequence
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+from fabric_base import (
+    DRAIN_SECONDS,
+    ServiceError,
+    _O_BINARY,
+    now_iso,
+)
+from fabric_paths import (
+    ensure_private_dir,
+)
+
+
+DRAIN_GRACE_SECONDS = 2.0
+
+
+EXIT_HARD_STOP = 70
+
+
+# LC-12: logs rotate by size, 5 x 5 MB by default.
+LOG_MAX_BYTES = 5 * 1024 * 1024
+
+
+LOG_BACKUPS = 5
+
+
+class RotatingLog:
+    """One structured log: JSON lines rotated by size (5 x 5 MB by default), files 0600 in a
+    0700 directory. ``service.jsonl`` -> ``.1`` ... ``.<backups>``; the oldest falls off.
+
+    Never pass a token, a cookie, a login code or a request body that may carry one."""
+
+    def __init__(self, path: Path, max_bytes: int = LOG_MAX_BYTES, backups: int = LOG_BACKUPS):
+        if max_bytes < 256 or backups < 1:
+            raise ServiceError("A rotating log needs max_bytes >= 256 and at least one backup.")
+        self.path = Path(path)
+        self.max_bytes = max_bytes
+        self.backups = backups
+        self._lock = threading.Lock()
+
+    def _line(self, record: Dict[str, Any]) -> bytes:
+        data = (json.dumps(record, ensure_ascii=False) + "\n").encode()
+        if len(data) <= self.max_bytes:
+            return data
+        record = dict(record, truncated=True)
+        message = str(record.get("message", ""))
+        while message:
+            message = message[: len(message) // 2]
+            record["message"] = message
+            data = (json.dumps(record, ensure_ascii=False) + "\n").encode()
+            if len(data) <= self.max_bytes:
+                return data
+        return (json.dumps({"at": record.get("at"), "level": record.get("level"), "message": "",
+                            "truncated": True}) + "\n").encode()
+
+    def write(self, level: str, message: str, **fields: Any) -> None:
+        record: Dict[str, Any] = {"at": now_iso(), "level": str(level), "message": str(message)}
+        record.update(fields)
+        data = self._line(record)
+        with self._lock:
+            ensure_private_dir(self.path.parent)
+            try:
+                size = self.path.stat().st_size
+            except FileNotFoundError:
+                size = 0
+            if size and size + len(data) > self.max_bytes:
+                self._rotate()
+            fd = os.open(str(self.path), os.O_WRONLY | os.O_APPEND | os.O_CREAT | _O_BINARY, 0o600)
+            try:
+                os.write(fd, data)
+            finally:
+                os.close(fd)
+
+    def _rotate(self) -> None:
+        for index in range(self.backups - 1, 0, -1):
+            older = Path("%s.%d" % (self.path, index))
+            if older.exists():
+                os.replace(older, "%s.%d" % (self.path, index + 1))
+        os.replace(self.path, "%s.1" % self.path)
+
+
+def cap_stdout_log(path: Path, max_bytes: int = LOG_MAX_BYTES) -> bool:
+    """Call once at start: a launchd stdout file over ``max_bytes`` is copied to ``<path>.1`` and
+    truncated in place. launchd holds the file open for append, so a rename would leave it
+    writing to the old name; truncation keeps its descriptor valid. Returns True when capped."""
+    path = Path(path)
+    try:
+        size = path.stat().st_size
+    except FileNotFoundError:
+        return False
+    if size <= max_bytes:
+        return False
+    backup = Path("%s.1" % path)
+    shutil.copyfile(path, backup)
+    os.chmod(backup, 0o600)
+    with open(path, "r+b") as handle:
+        handle.truncate(0)
+    return True
+
+
+class Stopping(ServiceError):
+    """The service is stopping and takes no new work."""
+
+
+class Drain:
+    """SIGTERM/SIGINT: stop taking new work, drain in-flight work until ``deadline``, then hand
+    over with ``on_stop(drained)``. A hand-over that hangs is cut by a hard exit
+    (``EXIT_HARD_STOP``) ``grace`` seconds later, so quit reaches exit inside the lifecycle bound.
+
+        drain = fs.Drain()
+        drain.install(lambda drained: server.shutdown(),
+                      on_stopping=lambda: log.append("service.stopping", "info", "Stopping."))
+        with drain.work():          # raises fs.Stopping once a stop has begun
+            ...
+    """
+
+    def __init__(self, deadline: float = DRAIN_SECONDS, grace: float = DRAIN_GRACE_SECONDS):
+        self.deadline = deadline
+        self.grace = grace
+        self._cond = threading.Condition()
+        self._inflight = 0
+        self._stopping = False
+
+    @property
+    def stopping(self) -> bool:
+        return self._stopping
+
+    @property
+    def inflight(self) -> int:
+        return self._inflight
+
+    @contextlib.contextmanager
+    def work(self):
+        with self._cond:
+            if self._stopping:
+                raise Stopping("The service is stopping and takes no new work.")
+            self._inflight += 1
+        try:
+            yield
+        finally:
+            with self._cond:
+                self._inflight -= 1
+                self._cond.notify_all()
+
+    def request_stop(self) -> bool:
+        """Refuse new work from now on; False when a stop had already begun."""
+        with self._cond:
+            if self._stopping:
+                return False
+            self._stopping = True
+            return True
+
+    def wait(self, timeout: Optional[float] = None) -> bool:
+        """Wait for in-flight work to finish; True when it did inside ``timeout``."""
+        end = None if timeout is None else time.monotonic() + timeout
+        with self._cond:
+            while self._inflight > 0:
+                left = None if end is None else end - time.monotonic()
+                if left is not None and left <= 0:
+                    return False
+                self._cond.wait(left)
+            return True
+
+    def install(self, on_stop: Callable[[bool], None], *, on_stopping: Optional[Callable[[], None]] = None,
+                signals: Sequence[int] = (signal.SIGTERM, signal.SIGINT)) -> "Drain":
+        """Install the handlers (main thread only). A second signal changes nothing: the hard-exit
+        timer already holds the deadline."""
+        def handler(_signum: int, _frame: Any) -> None:
+            if self.request_stop():
+                threading.Thread(target=self._stop, args=(on_stopping, on_stop), daemon=True).start()
+
+        for sig in signals:
+            signal.signal(sig, handler)
+        return self
+
+    def _stop(self, on_stopping: Optional[Callable[[], None]], on_stop: Callable[[bool], None]) -> None:
+        hard = threading.Timer(self.deadline + self.grace, os._exit, args=(EXIT_HARD_STOP,))
+        hard.daemon = True
+        hard.start()
+        if on_stopping is not None:
+            try:
+                on_stopping()
+            except Exception:  # a failing stop notice must not stop the drain
+                traceback.print_exc()
+        on_stop(self.wait(self.deadline))