| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835 |
- """Checkout custody for the updater's children (R2): the ONE spawn policy for every git (and the
- Node build) an update starts.
- The checkout kernel lock (``update_lock``) must stay held while any process of the update tree
- can still write the checkout, and must NOT leak into processes that outlive the update:
- * Every updater git call carries ``-c gc.autoDetach=false -c maintenance.auto=false``: git never
- forks a detached gc/maintenance child that would inherit (POSIX) or outlive (Windows) the lock.
- * POSIX: the lock fd is inherited ONLY by git commands that mutate the worktree, index or refs
- locally (:data:`LOCAL_MUTATORS`, run with ``core.fsmonitor=false`` so no fsmonitor daemon
- starts under them, with no credential helper and no repository hooks). Network/credential commands (fetch,
- ls-remote, credential) and readers run without it: a ``git credential-cache--daemon`` they
- start never holds the checkout. A partial clone's mutator would lazily fetch the objects a move
- needs as a child holding the fd (and start the daemon under it), so before a move the objects
- are fetched without the fd and with the user's helpers (:func:`_prefetch_for_move`); a lazy
- fetch the prefetch missed still runs, just without a helper. A killed fetch that leaves
- ``*.lock`` ref files or ``shallow.lock`` is recovered by the stale-lock rules (``gitlock.release_dead_fetch_locks``
- once its update is proven dead, ``gitlock.clear_stale_git_locks`` by age otherwise).
- * Windows has no fd inheritance: while this process holds (or joined) the checkout lock, every
- child started here is created SUSPENDED, assigned to the update's kill-on-close job and only
- then resumed, so it and everything it spawns die with the lock owner. The Node build goes
- through ``pm.progress.run_contained`` (whose Popen it never sees): :func:`contained_command`
- wraps it in a stdlib launcher that joins the job before it starts node and, once node exits,
- terminates and waits out everything node left running (C3): a normal release never frees the
- checkout under a build descendant.
- * Windows fails CLOSED (D2): a child the job refuses is never run. The msvcrt byte lock belongs
- to the process that took it — an inherited handle does not keep it, the kernel unlocks it when
- the owner exits — so nothing else could fence a writer outside the job: after the owner's
- death the lock would be free while it still wrote. A refused bind kills the still-suspended
- child; a refused launcher join exits before it starts node; either raises
- :class:`CustodyRefused`, a clear refusal of that step instead of an unfenced writer.
- Every updater git runner (``update_cmd._git_run``, ``update_cmd_git._git_run``,
- ``update_cmd_stash``, ``update_cmd_check``, ``gitlock``, ``update_cmd_commit``,
- ``_early_recovery``'s restore) calls :func:`run_git`.
- Not covered, on purpose: the read-only release/check readers (``source_releases``,
- ``source_check``: ``ls-remote``, ``cherry``, ``rev-parse``) run their own probes; they never get
- the lock fd and write nothing, so they cannot leak or outlive custody of the checkout.
- """
- from __future__ import annotations
- import contextlib
- import logging
- import os
- import subprocess
- import sys
- from collections.abc import Sequence
- import itertools
- logger = logging.getLogger(__name__)
- # No detached child: `git gc --auto` / `maintenance run --auto --detach` would otherwise fork a
- # daemonized repack after any command that writes objects (commit, merge, fetch, stash).
- GIT_NO_DETACH = ("-c", "gc.autoDetach=false", "-c", "maintenance.auto=false")
- # Local mutators only (they hold the lock fd): never start an fsmonitor daemon under it, and no
- # credential helper — a promisor lazy fetch under a mutator would start `git
- # credential-cache--daemon` holding the fd for its lifetime (900 s by default, m3). No repository
- # hooks either (F1): a hook inherits the fd, and one that backgrounds a process (a post-merge
- # daemon) kept a completed update's checkout locked until it exited. Per command only: the
- # repository's own hook configuration is untouched.
- _MUTATOR_CONFIG = ("-c", "core.fsmonitor=false", "-c", "credential.helper=", "-c", f"core.hooksPath={os.devnull}")
- # git subcommands that write the worktree, the index or refs on THIS machine. Only these inherit
- # the checkout lock fd: if the updater dies mid-command, the checkout stays locked until git exits.
- # No `pull` (fetch + merge: its network half must not hold the fd; the updater fetches, then
- # merges). `gc` packs refs (and its repack writes the object store); `pack-objects` is the pack
- # tidy's merge, whose output the update moves into the object store.
- LOCAL_MUTATORS = frozenset({
- "add", "am", "apply", "checkout", "checkout-index", "cherry-pick", "clean", "commit", "gc",
- "merge", "mv", "pack-objects", "read-tree", "rebase", "reset", "restore", "revert", "rm", "stash",
- "switch", "update-index", "update-ref", "symbolic-ref", "tag", "branch", "worktree",
- })
- # Mutators that move the checkout to another commit: what they read from a promisor remote is
- # fetched first, without the fd (_prefetch_for_move).
- _MOVES = frozenset({"checkout", "merge", "read-tree", "reset", "switch"})
- # Global options before the subcommand that take a separate value argument.
- _GLOBAL_WITH_VALUE = frozenset({"-c", "-C", "--git-dir", "--work-tree", "--namespace", "--exec-path",
- "--config-env", "--super-prefix", "--attr-source", "--list-cmds"})
- _CREATE_SUSPENDED = 0x00000004
- class CustodyRefused(OSError):
- """Windows would not put an update child in the update's kill-on-close job, so the child was
- never run (D2): outside the job it could outlive a killed update and write the checkout after
- the checkout lock is free."""
- def __init__(self, argv: Sequence[str], cause: object) -> None:
- import os
- name = os.path.basename(str(argv[0])) if argv else "child"
- self.reason = (
- f"Windows would not put `{name}` in this update's process job ({cause}), so it was not "
- "run: a checkout writer outside the job could outlive a killed update and write the "
- "checkout after its lock is released.")
- super().__init__(f"{self.reason} {_RETRY.format(command='the command')}")
- _RETRY = ("Run {command} again from a regular terminal, outside any sandbox or tool that confines "
- "the processes it starts.")
- # This run's custody (m2): whether an update child already ran in custody, and the first refusal.
- # Many readers swallow an OSError (a reader's None, a best-effort probe), so a refusal can end
- # the update as a misleading downstream error; the command's failure path prints
- # :func:`refusal_notice` instead.
- _RUN: dict = {"ran": False, "refused": None}
- def _refuse(argv: Sequence[str], cause: object, *, receipted: bool = False) -> CustodyRefused:
- """The :class:`CustodyRefused` for ``argv``: logged, noted in the receipt (unless the caller
- already did) and kept as this run's first refusal."""
- argv = list(argv) if isinstance(argv, (list, tuple)) else [argv]
- exc = CustodyRefused(argv, cause)
- detail = f"{exc.reason}: {' '.join(str(arg) for arg in argv[:2])}"
- if not receipted:
- logger.warning("Refused update child: %s", detail)
- with contextlib.suppress(Exception):
- from hermes_cli.update_receipt import record_step
- record_step("update_custody", False, detail)
- if _RUN["refused"] is None:
- _RUN["refused"] = (exc, not _RUN["ran"] and not _past_commit())
- return exc
- def _past_commit() -> bool:
- """The update reached its commit point: its receipt records the ``apply`` stage (the
- completion child resumes that receipt). No receipt is open before an update begins, nor in
- the parent after its completion child returned, which starts no update child."""
- try:
- from hermes_cli.update_receipt import _current
- current = _current.get()
- except Exception: # health: allow BLE001 -- fail closed: unknown = past commit, never "nothing changed"
- return True
- return current is not None and any(stage.get("name") == "apply" for stage in current.data.get("stages") or ())
- def refusal_notice(command: str = "hermes update") -> str | None:
- """What the command's failure path prints when this run refused an update child (m2), in
- place of whatever generic error the refusal turned into downstream; ``None`` otherwise."""
- if _RUN["refused"] is None:
- return None
- exc, unchanged = _RUN["refused"]
- outcome = ("Nothing was changed: no update step had run yet." if unchanged else
- "Update steps before it had already run.")
- return f"✗ `{command}` stopped: {exc.reason}\n {outcome}\n {_RETRY.format(command=f'`{command}`')}"
- def git_subcommand(args: Sequence[str]) -> str | None:
- """The subcommand in ``args`` (everything after the git executable), skipping global options."""
- it = iter(args)
- for arg in it:
- if arg in _GLOBAL_WITH_VALUE:
- next(it, None)
- elif not arg.startswith("-"):
- return arg
- return None
- def is_local_mutator(args: Sequence[str]) -> bool:
- return git_subcommand(args) in LOCAL_MUTATORS
- def git_argv(git_cmd: Sequence[str], args: Sequence[str]) -> list[str]:
- """``git_cmd + args`` with the custody config inserted before the subcommand."""
- git_cmd, args = list(git_cmd), list(args)
- extra = GIT_NO_DETACH + (_MUTATOR_CONFIG if is_local_mutator(git_cmd[1:] + args) else ())
- return [*git_cmd, *extra, *args]
- def _held() -> dict | None:
- try:
- from hermes_cli import update_lock
- except Exception: # health: allow BLE001 -- a torn tree's half-written module raises anything; no updater runs
- return None
- return update_lock._HELD
- def _death_signal_preexec():
- """Linux: a ``preexec_fn`` making the child die (SIGKILL) with the updater thread that waits
- on it. For the git children that do NOT hold the lock fd (fetch, ls-remote, readers): a
- killed owner must not leave a fetch rewriting refs under the next lock owner. The ruling's
- stale-lock rules recover a fetch killed mid-write. ``None`` elsewhere (Windows: the job;
- macOS has no parent-death signal: :func:`run_git` puts a fetch under :func:`_owner_watch`)."""
- if not sys.platform.startswith("linux"):
- return None
- import ctypes
- import os
- prctl = ctypes.CDLL(None, use_errno=True).prctl # resolved before fork: the child only calls
- parent = os.getpid()
- def _arm():
- prctl(1, 9, 0, 0, 0) # PR_SET_PDEATHSIG, SIGKILL
- if os.getppid() != parent: # the owner died between fork and prctl
- os._exit(137)
- return _arm
- def _custody_kwargs(inherit_lock: bool, kwargs: dict) -> dict:
- fds = _lock_fds(inherit_lock)
- if fds:
- kwargs["pass_fds"] = tuple(dict.fromkeys((*kwargs.get("pass_fds", ()), *fds)))
- elif not inherit_lock and _held() is not None and "preexec_fn" not in kwargs:
- arm = _death_signal_preexec()
- if arm is not None:
- kwargs["preexec_fn"] = arm
- return kwargs
- def _lock_fds(inherit_lock: bool) -> tuple[int, ...]:
- if not inherit_lock or sys.platform == "win32":
- return ()
- from hermes_cli.update_lock import custody_spawn_kwargs
- return tuple(custody_spawn_kwargs().get("pass_fds", ()))
- def _bind_suspended(proc: subprocess.Popen) -> None:
- """Assign a CREATE_SUSPENDED child to the update's kill-on-close job, then resume it.
- Suspended until bound, so nothing it spawns can escape the job. A refused bind kills the
- child before it ran a single instruction and raises :class:`CustodyRefused` (D2: never an
- unfenced writer); a failed resume kills the child."""
- from hermes_cli.update_lock import _bind_to_kill_on_close_job, resume_suspended_child
- try:
- _bind_to_kill_on_close_job(proc)
- except OSError as exc:
- proc.kill()
- proc.wait()
- raise _refuse(proc.args, exc) from exc
- resume_suspended_child(proc)
- _RUN["ran"] = True
- def popen(argv: Sequence[str], *, inherit_lock: bool = False, **kwargs) -> subprocess.Popen:
- """``subprocess.Popen`` in the update tree's custody (see the module doc)."""
- if sys.platform == "win32" and _held() is not None:
- kwargs["creationflags"] = kwargs.get("creationflags", 0) | _CREATE_SUSPENDED
- proc = subprocess.Popen(list(argv), **kwargs)
- try:
- _bind_suspended(proc)
- except BaseException:
- with contextlib.suppress(OSError):
- proc.kill()
- raise
- return proc
- return subprocess.Popen(list(argv), **_custody_kwargs(inherit_lock, kwargs))
- def run(argv: Sequence[str], *, inherit_lock: bool = False, **kwargs) -> subprocess.CompletedProcess:
- """``subprocess.run`` in the update tree's custody. Off Windows (or outside an update) it IS
- ``subprocess.run`` with the caller's kwargs untouched, plus the lock fd for mutators (or the
- parent-death signal for the rest); on Windows inside an update it is the same contract over
- :func:`popen`, so the child is job-bound before it runs."""
- if not (sys.platform == "win32" and _held() is not None):
- return subprocess.run(list(argv), **_custody_kwargs(inherit_lock, kwargs)) # noqa: PLW1510 -- forwarding wrapper: callers pass subprocess kwargs via **kwargs (check may arrive through it); an explicit check=False would raise TypeError
- input, timeout = kwargs.pop("input", None), kwargs.pop("timeout", None)
- check = kwargs.pop("check", False)
- if input is not None:
- kwargs["stdin"] = subprocess.PIPE
- if kwargs.pop("capture_output", False):
- kwargs["stdout"] = kwargs["stderr"] = subprocess.PIPE
- with popen(argv, **kwargs) as proc:
- try:
- stdout, stderr = proc.communicate(input, timeout=timeout)
- except subprocess.TimeoutExpired as exc:
- # git.exe's git-remote-https inherits the pipes: kill the tree, not git.exe alone (and
- # never the job: it also holds the update's other children).
- from hermes_cli._subprocess_compat import kill_and_drain
- drained = kill_and_drain(proc, _DRAIN_SECONDS)
- if drained is not None:
- exc.stdout, exc.stderr = drained
- raise
- except BaseException:
- proc.kill()
- raise
- code = proc.poll()
- if check and code:
- raise subprocess.CalledProcessError(code, proc.args, output=stdout, stderr=stderr)
- return subprocess.CompletedProcess(proc.args, code, stdout, stderr)
- def popen_post_commit(argv: Sequence[str], *, label: str, **kwargs) -> subprocess.Popen:
- """``subprocess.Popen`` for a checkout writer that runs after the update committed (the
- historical takeover's ``update_finish``). POSIX: the lock fd. Windows inside an update:
- created suspended and bound to the update's kill-on-close job before it runs. A refused bind
- must not fail a committed update, so the child still runs, never silently (printed and
- receipted) and never unfenced: it joins the checkout lock holding its own lease (R5b)."""
- if not (sys.platform == "win32" and _held() is not None):
- return subprocess.Popen(list(argv), **_custody_kwargs(True, kwargs))
- from hermes_cli.update_lock import bind_child_to_update_tree, resume_suspended_child
- kwargs["creationflags"] = kwargs.get("creationflags", 0) | _CREATE_SUSPENDED
- proc = subprocess.Popen(list(argv), **kwargs)
- try:
- refusal = bind_child_to_update_tree(proc)
- if refusal is not None:
- detail = (f"the update's job would not take the {label} ({refusal}), so it runs outside "
- "the job, holding its own checkout lease")
- print(f" ⚠ {detail}", flush=True)
- with contextlib.suppress(Exception):
- from hermes_cli.update_receipt import record_step
- record_step("update_custody", False, detail)
- resume_suspended_child(proc)
- except BaseException:
- proc.kill()
- proc.wait()
- raise
- return proc
- # How long a timed-out child's output may still drain after its tree was killed.
- _DRAIN_SECONDS = 5
- def run_git(git_cmd: Sequence[str], args: Sequence[str], **kwargs) -> subprocess.CompletedProcess:
- """THE updater git runner: custody config in argv, the lock fd only into local mutators,
- Windows job binding inside an update. ``kwargs`` are ``subprocess.run``'s."""
- argv = git_argv(git_cmd, args)
- mutator = is_local_mutator(argv[1:])
- if mutator:
- _prefetch_for_move(list(git_cmd), list(args), kwargs)
- if sys.platform != "win32" and _held() is not None and "preexec_fn" not in kwargs \
- and _death_signal_preexec() is None:
- # No parent-death signal (macOS): the tree runner owns git AND the helpers it starts. A
- # local mutator holds the lock fd and finishes its write if the owner dies, as on Linux.
- return _run_owner_watched(argv, _custody_kwargs(mutator, kwargs), watch_owner=not mutator)
- return run(argv, inherit_lock=mutator, **kwargs)
- # git without the lock fd (a fetch's network half must not hold it, m3) dies with its owner: on
- # Linux by the parent-death signal; where there is none (macOS) by this watchdog (R3), or a fetch
- # would go on rewriting refs and leave live `*.lock` files under the next owner.
- # The watchdog: stdin is a pipe only the owner writes. A byte = the child finished; EOF with no
- # byte = the owner died (the kernel closed its end), so SIGKILL the child's whole process group
- # (git and the helpers it started: git-remote-https, index-pack, pack-objects), as
- # PR_SET_PDEATHSIG would for the child alone. It holds no lock fd and runs in its own session.
- _OWNER_WATCH = (
- "import os, signal, sys\n"
- "if not os.read(0, 1):\n"
- " try:\n"
- " os.killpg(int(sys.argv[1]), signal.SIGKILL)\n" # windows-footgun: ok -- POSIX only (run_git gates win32 out)
- " except OSError:\n"
- " pass\n"
- )
- def _owner_watch(pid: int):
- """Start the parent-death stand-in for child ``pid``; returns the callable that dismisses it
- once the child is done, or ``None`` when it could not start (logged: the fetch still runs, as
- it did before; only the owner's death mid-fetch is then unfenced)."""
- import os
- read_end, write_end = os.pipe() # non-inheritable: no other child keeps the owner's end open
- try:
- watcher = subprocess.Popen([sys.executable, "-I", "-S", "-c", _OWNER_WATCH, str(pid)], stdin=read_end,
- # detached-spawn: ok — the owner-death watchdog itself: it must outlive the owner to kill the fetch
- stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)
- except OSError as exc:
- os.close(write_end)
- logger.warning("Could not watch update child %s for its owner's death: %s", pid, exc)
- return None
- finally:
- os.close(read_end)
- def dismiss() -> None:
- with contextlib.suppress(OSError): # the watcher already gone: nothing left to tell it
- os.write(write_end, b"x")
- os.close(write_end)
- with contextlib.suppress(subprocess.TimeoutExpired): # it exits on the byte; never block on it
- watcher.wait(timeout=5)
- return dismiss
- def _kill_tree(proc: subprocess.Popen) -> None:
- """SIGKILL ``proc``'s process group: the child leads it (``start_new_session``), and while it
- is unreaped its pid, hence the group id, cannot be reused. Once reaped (``communicate`` reaps
- on a Ctrl-C inside its wait window) the id may already name another session, so it is never
- signalled; ``returncode`` is read, not ``poll()``ed, since polling would reap a live zombie
- and skip the helpers a timed-out git leaves running."""
- import os
- import signal
- if proc.returncode is not None:
- return
- with contextlib.suppress(OSError): # already gone
- os.killpg(proc.pid, signal.SIGKILL) # windows-footgun: ok -- POSIX only (run_git gates win32 out)
- def _run_owner_watched(argv: Sequence[str], kwargs: dict, *, watch_owner: bool = True) -> subprocess.CompletedProcess:
- """``subprocess.run`` for updater git where no parent-death signal exists, under
- :func:`_owner_watch` while it runs. git leads a session of its own, so a timeout, a cancel or
- the owner's death ends its helpers with it, not git's pid alone (#144439)."""
- input, timeout = kwargs.pop("input", None), kwargs.pop("timeout", None)
- check = kwargs.pop("check", False)
- if input is not None:
- kwargs["stdin"] = subprocess.PIPE
- if kwargs.pop("capture_output", False):
- kwargs["stdout"] = kwargs["stderr"] = subprocess.PIPE
- # detached-spawn: ok — awaited; _owner_watch kills a fetch's group on owner death, and a mutator must finish its write
- with subprocess.Popen(list(argv), start_new_session=True, **kwargs) as proc:
- dismiss = _owner_watch(proc.pid) if watch_owner else None
- try:
- stdout, stderr = proc.communicate(input, timeout=timeout)
- except subprocess.TimeoutExpired as exc:
- _kill_tree(proc)
- try:
- exc.stdout, exc.stderr = proc.communicate(timeout=_DRAIN_SECONDS)
- except subprocess.TimeoutExpired:
- # A helper git started still holds the pipes: leave them to the reader threads.
- proc.stdin = proc.stdout = proc.stderr = None
- raise
- except BaseException:
- _kill_tree(proc)
- raise
- finally:
- if dismiss is not None:
- dismiss()
- code = proc.poll()
- if check and code:
- raise subprocess.CalledProcessError(code, proc.args, output=stdout, stderr=stderr)
- return subprocess.CompletedProcess(proc.args, code, stdout, stderr)
- def _partial_clone(git_cmd: Sequence[str], kwargs: dict) -> bool:
- """The repository has a promisor remote (``extensions.partialClone``), read from disk."""
- from pathlib import Path
- from hermes_cli.update_lock import _git_common_dir
- cwd = kwargs.get("cwd")
- for flag, value in itertools.pairwise(git_cmd):
- if flag == "-C":
- cwd = Path(cwd or ".") / value
- common = _git_common_dir(Path(cwd or "."))
- try:
- return common is not None and "partialclone" in \
- (common / "config").read_text(encoding="utf-8-sig", errors="replace").lower()
- except OSError:
- return False
- def _prefetch_for_move(git_cmd: list[str], args: list[str], kwargs: dict) -> None:
- """Partial clones: fetch what a move to another commit will read — the target's changed trees
- and blobs — WITHOUT the lock fd and with the user's credential helpers, so the mutator (which
- has neither helper nor reason to fetch) never starts a lazy fetch or a credential daemon under
- the fd (m3). ``git diff HEAD <target>`` reads exactly the trees and blobs that differ from the
- checked-out tree; the rest is local. Best effort: a miss only leaves a helper-less lazy fetch."""
- sub = git_subcommand(args)
- if sub not in _MOVES or not _partial_clone(git_cmd, kwargs):
- return
- common = {key: kwargs[key] for key in ("cwd", "env") if key in kwargs}
- def resolve(*query: str, stdin: str | None = None) -> str | None:
- out = run(git_argv(git_cmd, list(query)), capture_output=True, text=True, encoding="utf-8",
- errors="replace", input=stdin, **({} if stdin is not None else {"stdin": subprocess.DEVNULL}),
- **common)
- return out.stdout.strip() if out.returncode == 0 and out.stdout.strip() else None
- try:
- targets = []
- for arg in args[args.index(sub) + 1:]:
- if arg == "--":
- break
- if not arg.startswith("-"):
- targets.append(resolve("rev-parse", "--verify", "-q", f"{arg}^{{commit}}"))
- targets = [target for target in dict.fromkeys(targets) if target]
- if not targets:
- return
- # An unborn HEAD (a fresh clone) has nothing checked out: diff from the empty tree.
- base = resolve("rev-parse", "--verify", "-q", "HEAD^{commit}") \
- or resolve("hash-object", "-t", "tree", "--stdin", stdin="")
- for target in targets:
- if base and target != base:
- run(git_argv(git_cmd, ["diff", "--binary", "--no-ext-diff", "--no-textconv", base, target]),
- stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, **common)
- except (OSError, ValueError, subprocess.SubprocessError) as exc:
- logger.debug("Could not prefetch the objects for git %s: %s", sub, exc)
- # A stdlib launcher for children whose Popen the updater never sees (``run_contained``): it
- # joins the job named by an inherited handle, starts the real command suspended with the same
- # stdio, runs it only once it is in the job, and drops that handle (only the owner's handle may
- # keep the job open). A refused join, or a command outside the job, never runs (D2): the launcher says so on stderr, writes the notice to the report file
- # (argv[2]) — run_contained captures the child's stderr, so stderr alone is not seen (m1) — and
- # exits; the updater logs the notice, notes it in the receipt and raises CustodyRefused.
- # The command also runs in a kill-on-close job of the launcher's own, nested in the update job
- # (review C3): once the command exits, the launcher terminates that job — whatever npm / the
- # builder started and left running — and waits until no process of it is left before it
- # returns, so the caller never releases the checkout while a build descendant still writes.
- # Only the command's tree: the update job also holds the update's other children. The Windows
- # twin of the POSIX launcher below (_REAP_TREE); the nested job's handle closing (a killed
- # launcher) kills the tree too.
- _CUSTODY_UNAVAILABLE = "hermes: update custody unavailable"
- _REFUSED_EXIT = 87
- _JOIN_JOB = (
- "import ctypes, subprocess, sys, time\n"
- "k = ctypes.WinDLL('kernel32', use_last_error=True)\n"
- "k.AssignProcessToJobObject.argtypes = [ctypes.c_void_p, ctypes.c_void_p]\n"
- "k.GetCurrentProcess.restype = ctypes.c_void_p\n"
- "k.CloseHandle.argtypes = [ctypes.c_void_p]\n"
- "k.CreateJobObjectW.restype = ctypes.c_void_p\n"
- "k.SetInformationJobObject.argtypes = [ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p, ctypes.c_ulong]\n"
- "k.TerminateJobObject.argtypes = [ctypes.c_void_p, ctypes.c_uint]\n"
- "k.QueryInformationJobObject.argtypes = [ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p, ctypes.c_ulong,\n"
- " ctypes.c_void_p]\n"
- "h = ctypes.c_void_p(int(sys.argv[1]))\n"
- "def refuse(why):\n"
- f" note = '{_CUSTODY_UNAVAILABLE} (%s); the command was not run' % why\n"
- " sys.stderr.write(note + '\\n')\n"
- " sys.stderr.flush()\n"
- " try:\n"
- " with open(sys.argv[2], 'w', encoding='utf-8') as report:\n"
- " report.write(note)\n"
- " except OSError:\n"
- " pass\n"
- f" sys.exit({_REFUSED_EXIT})\n"
- "if not k.AssignProcessToJobObject(h, k.GetCurrentProcess()):\n"
- " refuse('could not join the update job: %d' % ctypes.get_last_error())\n"
- # JOBOBJECT_EXTENDED_LIMIT_INFORMATION (KILL_ON_JOB_CLOSE) and the BASIC_ACCOUNTING record
- # whose ActiveProcesses says when the command's tree is gone.
- "class Basic(ctypes.Structure):\n"
- " _fields_ = [('times', ctypes.c_int64 * 2), ('flags', ctypes.c_uint32), ('ws', ctypes.c_size_t * 2),\n"
- " ('procs', ctypes.c_uint32), ('affinity', ctypes.c_size_t), ('classes', ctypes.c_uint32 * 2)]\n"
- "class Limits(ctypes.Structure):\n"
- " _fields_ = [('basic', Basic), ('io', ctypes.c_uint64 * 6), ('memory', ctypes.c_size_t * 4)]\n"
- "class Usage(ctypes.Structure):\n"
- " _fields_ = [('times', ctypes.c_int64 * 4), ('faults', ctypes.c_uint32), ('total', ctypes.c_uint32),\n"
- " ('active', ctypes.c_uint32), ('terminated', ctypes.c_uint32)]\n"
- "tree = k.CreateJobObjectW(None, None)\n"
- "limits = Limits()\n"
- "limits.basic.flags = 0x2000\n"
- "if not tree or not k.SetInformationJobObject(tree, 9, ctypes.byref(limits), ctypes.sizeof(limits)):\n"
- " refuse('could not create the job for the command tree: %d' % ctypes.get_last_error())\n"
- # Verify, never assume the topology: a packaged interpreter (Store Python) joins, but starts a
- # program outside its package with desktop-app breakaway, so the command leaves every job
- # that permits breakaway, as the update job does (restarted gateways break away). Start the
- # command suspended; if Windows says it is outside the job, put it in explicitly (F80), and
- # run it only once it is in (F54): a command the job will not take is refused, never run.
- "k.IsProcessInJob.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.POINTER(ctypes.c_int)]\n"
- "p = subprocess.Popen(sys.argv[3:], stdin=subprocess.DEVNULL, creationflags=0x4)\n"
- "def in_job():\n"
- " inside = ctypes.c_int(0)\n"
- " return k.IsProcessInJob(ctypes.c_void_p(int(p._handle)), h, ctypes.byref(inside)) and inside.value\n"
- "if not in_job() and not (k.AssignProcessToJobObject(h, ctypes.c_void_p(int(p._handle))) and in_job()):\n"
- " p.kill()\n"
- " p.wait()\n"
- " refuse('the command would start outside the update job')\n"
- "if not k.AssignProcessToJobObject(tree, ctypes.c_void_p(int(p._handle))):\n"
- " error = ctypes.get_last_error()\n"
- " p.kill()\n"
- " p.wait()\n"
- " refuse('could not hold the command tree in a job: %d' % error)\n"
- "k.CloseHandle(h)\n"
- "nt = ctypes.WinDLL('ntdll')\n"
- "nt.NtResumeProcess.argtypes = [ctypes.c_void_p]\n"
- "if nt.NtResumeProcess(ctypes.c_void_p(int(p._handle))) != 0:\n"
- " p.kill()\n"
- "code = p.wait()\n"
- # C3: nothing the command started outlives it; return only once its whole tree is gone.
- "k.TerminateJobObject(tree, 1)\n"
- "usage, end = Usage(), time.monotonic() + 10\n"
- "while time.monotonic() < end:\n"
- " if not k.QueryInformationJobObject(tree, 1, ctypes.byref(usage), ctypes.sizeof(usage), None):\n"
- " break\n"
- " if not usage.active:\n"
- " break\n"
- " time.sleep(0.02)\n"
- "sys.exit(code)\n"
- )
- def _report_refused_join(report: str, argv: Sequence[str]) -> str | None:
- """Make a refused job join visible: a warning (errors.log) and a receipt step. The notice,
- or None when the child joined (or never ran the launcher)."""
- import os
- try:
- with open(report, encoding="utf-8-sig") as fh:
- note = fh.read().strip()
- except OSError:
- note = ""
- finally:
- with contextlib.suppress(OSError):
- os.unlink(report)
- if not note:
- return None
- logger.warning("%s: %s", note, " ".join(str(arg) for arg in argv[:2]))
- with contextlib.suppress(Exception):
- from hermes_cli.update_receipt import record_step
- record_step("update_custody", False, f"{note}: {' '.join(str(arg) for arg in argv[:2])}")
- return note
- def _join_launcher_python() -> str:
- """The interpreter for the job-joining launcher: the real one, never a venv redirector.
- A venv's ``Scripts\\python.exe`` is a redirector: it starts the base interpreter as its own
- child, inside a job of its own. That child cannot join the update's job once the job holds a
- process from another job hierarchy (the updater's git children): ``AssignProcessToJobObject``
- fails with ERROR_ACCESS_DENIED (5). And the redirector, never joined, keeps its inherited copy
- of the job handle open, so the job would not close when the owner dies. The launcher is
- stdlib-only (``-I -S``), so the base interpreter runs it as is.
- """
- import os
- base = getattr(sys, "_base_executable", None)
- if base and os.path.isfile(base):
- return base
- return sys.executable
- # POSIX twin of the launcher (N13, review L1/L6). Node marks the donated lock fd close-on-exec,
- # so nothing node starts (npm, esbuild, sh) keeps the checkout locked: custody of them rests on
- # this stdlib parent, which holds the fd until no descendant of the command is left.
- # * The command stays in the CALLER's process group: every group kill that stops a build (a
- # Ctrl-C'd completion child's ``killpg``, Desktop's ``kill(-pid)``) reaches node and everything
- # under it that did not start a session of its own. The custodian leaves that group (E): a
- # SIGKILL of the group would otherwise kill it too, and a descendant in a session of its own
- # would go on writing with the checkout lock free. It outlives the kill, settles the tree as
- # below, and only then exits (releasing the fd).
- # * Linux: the custodian is a child subreaper, so a descendant orphaned by node's exit (or by any
- # intermediate's) is re-parented to it, never to init. Once node exits it SIGKILLs and reaps
- # its children until none is left; it only signals its own unreaped children, so no pid it
- # kills can have been reused (never a ``killpg`` of an already reaped leader's group).
- # * Elsewhere (macOS has no subreaper) it records node's descendant tree from ``ps`` while node
- # runs and, once node exits, kills every recorded process whose start time still matches,
- # plus what they started. Best effort: a process born and orphaned between two samples escapes.
- # * SIGINT/SIGTERM/SIGHUP are forwarded to node (a node still running 10 s later is killed); the
- # descendants are then killed as above.
- # * The custodian is NOT the process the runner sees (R4): ``subprocess.run`` SIGKILLs its own
- # child when Ctrl-C reaches the caller, and no group separation survives a direct kill. The
- # runner's child only forks the custodian (own group) and relays signals to it and its exit
- # status back; it leaves the caller's group too, or a terminal's Ctrl-C would reach node twice. Killed, it leaves the custodian to settle: node gets the same 10 s it gets after
- # a forwarded signal (it is usually still cleaning up from the same Ctrl-C), then the tree is
- # killed as above and only then is the fd dropped.
- _REAP_TREE = r"""
- import os, signal, subprocess, sys, time
- KILL = signal.SIGKILL # windows-footgun: ok - POSIX-only launcher
- fds = tuple(int(fd) for fd in sys.argv[1].split(','))
- caller = os.getpgrp()
- if caller != os.getpid():
- os.setpgid(0, 0)
- stand_in = os.getpid()
- custodian = os.fork()
- if custodian:
- def relay(signum, frame):
- try:
- os.kill(custodian, signum)
- except OSError:
- pass
- for name in ('SIGINT', 'SIGTERM', 'SIGHUP'):
- signal.signal(getattr(signal, name), relay)
- code = os.waitstatus_to_exitcode(os.waitpid(custodian, 0)[1])
- sys.exit(code if code >= 0 else 128 - code)
- os.setpgid(0, 0)
- me = os.getpid()
- reaper = False
- if sys.platform.startswith('linux'):
- try:
- import ctypes
- reaper = ctypes.CDLL(None, use_errno=True).prctl(36, 1, 0, 0, 0) == 0 # PR_SET_CHILD_SUBREAPER
- except (OSError, AttributeError):
- reaper = False
- def children():
- found = []
- for entry in os.listdir('/proc'):
- if not entry.isdigit():
- continue
- try:
- with open('/proc/%s/stat' % entry, 'rb') as fh:
- stat = fh.read()
- if int(stat[stat.rindex(b')') + 2:].split()[1]) == me:
- found.append(int(entry))
- except (OSError, ValueError, IndexError):
- continue
- return found
- def table():
- try:
- out = subprocess.run(['ps', '-A', '-o', 'pid=,ppid=,stat=,lstart='], stdin=subprocess.DEVNULL,
- capture_output=True, text=True, errors='replace', timeout=10).stdout
- except (OSError, subprocess.SubprocessError):
- return {}
- rows = {}
- for line in out.splitlines():
- parts = line.split(None, 3)
- if len(parts) == 4 and parts[0].isdigit() and parts[1].isdigit() and not parts[2].startswith('Z'):
- rows[int(parts[0])] = (int(parts[1]), parts[3].strip())
- return rows
- seen = {}
- def sample(root):
- rows = table()
- tree = {pid for pid, start in seen.items() if rows.get(pid, (0, None))[1] == start}
- if root is not None:
- tree.add(root)
- grew = True
- while grew:
- grew = False
- for pid, (ppid, start) in rows.items():
- if ppid in tree and pid not in tree:
- tree.add(pid)
- seen[pid] = start
- grew = True
- return [pid for pid, start in seen.items() if rows.get(pid, (0, None))[1] == start]
- def kill(pids):
- for pid in pids:
- try:
- os.kill(pid, KILL)
- except OSError:
- pass
- p = subprocess.Popen(sys.argv[2:], pass_fds=fds, process_group=caller)
- got = []
- def forward(signum, frame):
- got.append(signum)
- try:
- p.send_signal(signum)
- except OSError:
- pass
- for name in ('SIGINT', 'SIGTERM', 'SIGHUP'):
- signal.signal(getattr(signal, name), forward)
- deadline = None
- while True:
- try:
- code = p.wait(timeout=0.5)
- break
- except subprocess.TimeoutExpired:
- pass
- if not reaper:
- sample(p.pid)
- if got or os.getppid() != stand_in:
- deadline = deadline or time.monotonic() + 10
- if time.monotonic() > deadline:
- p.kill()
- end = time.monotonic() + 10
- while time.monotonic() < end:
- live = children() if reaper else sample(None)
- if not live:
- break
- kill(live)
- while reaper:
- try:
- if not os.waitpid(-1, os.WNOHANG)[0]:
- break
- except ChildProcessError:
- break
- time.sleep(0.02)
- sys.exit(code if code >= 0 else 128 - code)
- """
- @contextlib.contextmanager
- def contained_command(argv: Sequence[str], *, inherit_lock: bool = True, root=None):
- """``(argv, kwargs)`` for a checkout writer started by a runner that hides its Popen (the Node
- build in ``pm.progress.run_contained``). POSIX: the lock fd (this process's, or one it
- inherited for checkout ``root``), under a launcher that keeps the command in the caller's
- process group and kills every descendant left when it exits (:data:`_REAP_TREE`).
- Windows inside an update: the command runs under a launcher that joins the update's
- kill-on-close job first and returns only once no process the command started is left (C3);
- when the job cannot be handed over or the join is refused, the command never runs and
- :class:`CustodyRefused` is raised (D2)."""
- argv = list(argv)
- if not (sys.platform == "win32" and _held() is not None):
- from hermes_cli.update_lock import checkout_lock_fds
- fds = tuple(checkout_lock_fds(root)) if inherit_lock and root is not None else _lock_fds(inherit_lock)
- if fds:
- argv = [sys.executable, "-I", "-S", "-c", _REAP_TREE, ",".join(map(str, fds)), *argv]
- yield argv, ({"pass_fds": fds} if fds else {})
- return
- try:
- handle = _inheritable_job_handle()
- except OSError as exc:
- raise _refuse(argv, exc) from exc
- import os
- import tempfile
- fd, report = tempfile.mkstemp(prefix="hermes-custody-", suffix=".txt")
- os.close(fd)
- try:
- info = subprocess.STARTUPINFO()
- info.lpAttributeList = {"handle_list": [handle]}
- yield ([_join_launcher_python(), "-I", "-S", "-c", _JOIN_JOB, str(handle), report, *argv],
- {"startupinfo": info})
- finally:
- import ctypes
- ctypes.WinDLL("kernel32").CloseHandle(ctypes.c_void_p(handle))
- note = _report_refused_join(report, argv)
- if note:
- cause = note.removeprefix(f"{_CUSTODY_UNAVAILABLE} (").partition(")")[0]
- raise _refuse(argv, cause, receipted=True)
- _RUN["ran"] = True
- def _inheritable_job_handle() -> int:
- """An inheritable duplicate of the update's kill-on-close job handle (Windows). Raises
- ``OSError`` when the job cannot be created or duplicated."""
- import ctypes
- from hermes_cli.update_lock import update_tree_job
- try:
- job = update_tree_job()
- kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
- kernel32.GetCurrentProcess.restype = ctypes.c_void_p
- kernel32.DuplicateHandle.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p,
- ctypes.POINTER(ctypes.c_void_p), ctypes.c_ulong, ctypes.c_int,
- ctypes.c_ulong]
- me, dup = kernel32.GetCurrentProcess(), ctypes.c_void_p()
- # DUPLICATE_SAME_ACCESS, inheritable
- if not kernel32.DuplicateHandle(me, job, me, ctypes.byref(dup), 0, True, 0x2):
- raise ctypes.WinError(ctypes.get_last_error())
- return int(dup.value)
- except OSError as exc:
- logger.warning("Could not hand the update's job to a build child: %s", exc)
- raise
|