j*Q\dZddlmZddlZddlZddlZddlmZmZddl m Z m Z m Z m Z mZdZ ddlZn #e$rdZYnwxYwGddZd%d Zd dd&dZd'dZd(d)dZGddeZGddeZGdd eZd!Z eZn #e$rdZYnwxYwd*d+d$ZdS),aMake a browser tree die when the process that launched it does. SHARED BY EVERY PRODUCT THAT LAUNCHES A BROWSER, which is why it lives here - written when there were two: each of them launched the patched Firefox and each of them had the same problem; the automation wrapper solved it in 2026-07-26 and the profile manager did not, so on 2026-07-27 the manager still leaked its ENTIRE tree every single time it was killed - measured at eight surviving processes, three runs out of three, 100%. Two copies of this would have been two chances to fix it once. The manager was deleted 2026-08-18; the module is unchanged by that, because it was never written FOR a fixed count of consumers. THE BUG IT EXISTS FOR --------------------- Twelve runs of one test left eleven browsers alive. The first diagnosis blamed "any path where teardown does not run cleanly", lumping three situations together; measured separately, only one of them leaks. An exception out of the ``with`` block does NOT leak - teardown runs, the driver cleans up, zero survivors over an interleaved A/B. The leak is the KILLED-RUNNER path, where teardown never executes at all: launch, kill, count - eight survivors, then twelve. For the manager the equivalent is the user closing the app, the OS ending it, or a crash: all the same case, and none of them reaches anything the app could have written. Nothing written inside a teardown method can reach that, so the guarantee has to come from the operating system. On Windows a job object with KILL_ON_JOB_CLOSE does exactly it: the launching process holds the only handle, and when it ends by any means the kernel terminates the job's members. Processes created inside a job join it automatically, so content processes spawned later need no tracking. THE DESIGN ---------- Four pieces with one responsibility each, so the Win32 layer is not tangled with the policy and neither is tangled with any launcher: SessionToken identity. Mints itself, stamps an environment, and answers whether a given process is ours. find_processes the search. terminate immediate cleanup, returning a COUNT. LifetimeGuard the strategy. ``JobObjectGuard`` on Windows, ``NullGuard`` everywhere else and whenever the mechanism is unavailable. ``os.name`` is tested in exactly one place - ``guard_for()`` - so no caller branches on the platform. NullGuard is a Null Object in the strict sense: it satisfies the interface and REPORTS that it guarantees nothing (``bound == 0``, ``guaranteed is False``) rather than quietly doing nothing and looking successful. WHY A TOKEN AND NOT A SEARCH ---------------------------- The manager used to find its browser by matching the ``-profile`` directory, which works because it owns that path - but the wrapper cannot, because Playwright creates the profile and never says where. Everything else available - "a firefox that appeared after we started", "a firefox running our binary" - is a heuristic, and it invites the one failure a reaper must never have: on a fleet, several sessions start on the same binary within the same second, and a wrong guess kills a healthy browser belonging to someone else. So each session mints a random token and puts it in the browser's environment. Children inherit it, so every process in the tree carries it, and a process either has this session's token or it does not. Verified on Windows, where the launcher stub made this necessary: ``psutil.Process.environ()`` reads a same-user process's block and children show the inherited value. The rule throughout: act on POSITIVE identification only. A process whose environment cannot be read is left alone. Leaking a browser is a bug; killing someone else's is an incident, and only one of the two is recoverable. ) annotationsN)ABCabstractmethod)AnyIterableListMappingOptionalINVPW_SESSION_TOKENcheZdZdZdZdddZedd Zdd ZddZ d dZ d!dZ d"dZ d#dZ dS)$ SessionTokenanWhat makes a process ours, and the only thing that does. A value object: two tokens are equal when their values are, and an EMPTY token is falsy and matches nothing. That last part is load-bearing rather than defensive tidiness - without it, a session that failed before minting one would sweep every process whose variable happens to be empty. valuerstrreturnNonec||_dSNr)selfrs GC:\Projects\Historical\venv\Lib\site-packages\invisible_core/process.py__init__zSessionToken.__init__js  'SessionToken'c<|tjdS)N)secrets token_hex)clss rmintzSessionToken.mintmss7$R(()))rboolc*t|jSr)r!rrs r__bool__zSessionToken.__bool__qDJrotherobjectcLt|to|j|jkSr) isinstancer r)rr&s r__eq__zSessionToken.__eq__ts %..L5;$*3LLrintc*t|jSr)hashrr#s r__hash__zSessionToken.__hash__wr%rc0|rd|jdddndS)Nz SessionToken(z...)zSessionToken(empty)rr#s r__repr__zSessionToken.__repr__zs)7;V3tz"1"~3333AVVrenvMapping[str, str]dictcBt|}|j|t<|S)z;A copy of ``env`` the browser will pass on to its children.)r4r TOKEN_VAR)rr2outs rstampzSessionToken.stamp}s3iiI rprocrc|sdS |t|jkS#t$rYdSwxYw)zTrue only when the environment can be READ and holds this token. Every failure answers False. A process we cannot inspect is a process we do not touch. F)environgetr6r Exception)rr9s rmatcheszSessionToken.matchess[  5 <<>>%%i00DJ> >   55 s4; A A N)r)rrrr)rr)rr!)r&r'rr!)rr+)rr)r2r3rr4r9rrr!)__name__ __module__ __qualname____doc__ __slots__r classmethodr r$r*r.r1r8r>rrr r _sI***[*    MMMM    WWWW      rr tokenr List[Any]ctsgSfdtjdgD}d|Dd d|fd d |S) zEvery live process carrying ``token``, deepest child first. Deepest-first so that terminating in order reaches the content processes before the parent that would otherwise orphan or restart them. Nc>g|]}||SrF)r>).0prGs r z"find_processes..s* I I I1 a8H8H IQ I I Irpidch|] }|j SrF)rN)rKrLs r z!find_processes..s ! ! !aAE ! ! !rr9rrcN |S#t$rYdSwxYwr)ppidr=r9s r_parentzfind_processes.._parents7 99;;    44 s  $$c|vSrrF)rLrTpidss rz find_processes..sWWQZZ4/rT)keyreverse)r9rrr)psutil process_itersort)rGfoundrTrVs` @@rfind_processesr^s ~U~  J I I I+UG44 I I IE ! !5 ! ! !D JJ/////J>>> Lr@timeoutprocs Iterable[Any]rafloatr+ct|}|sdS|D]'} |#t$rY$wxYw|} tj||\}}n#t$rYnwxYw|D]'} |#t$rY$wxYw|r( tj|dn#t$rYnwxYwt |S)zGraceful terminate, then kill the survivors. Returns how many were sent. A count rather than nothing, so a caller can tell "nothing was leaked" from "the reaper did not run" - two outcomes that look identical from outside. rr`?)list terminater=rZ wait_procskilllen)rbrar9alive_s rrhrhs= KKE q  NN        D  E $UG<<<55        IIKKKK    D     eS 1 1 1 1 1    D  u::sB. ;;A A('A(0B BBB// B<;B<r9rr!c|tdS |o!|tjkS#t$rYdSwxYw)aCross-OS liveness for one process. False when gone OR a zombie. A zombie answers ``is_running()`` True on POSIX, and reading that as alive is how a UI shows a profile RUNNING forever after its browser has died. Came from the manager, which is where that was learned. NF)rZ is_runningstatus STATUS_ZOMBIEr=rSs rrlrls^ |v~u  JT[[]]f6J%JJ uus5A AA$@ctj|z}tj|krtt||S)zTerminate the tree now, for teardowns that DO get to run. Kept even where ``bind`` guarantees the kill, because a browser that refuses ``close()`` should not wait for this process to exit. r`)rhr^)rrGras rreapzLifetimeGuard.reaps ..@@@@rN)rGr r|rdrr+)rGr rardrr+) r@rArBrCr{__annotations__rr~rrFrrrzrzsBBJ9=PPPPP^P=@AAAAAAAArrzc2eZdZdZdZddddd ZdddZdS) NullGuardaNo OS-level guarantee here, and it says so instead of implying one. The honest answer on platforms without the mechanism and on any failure to obtain it. ``reap`` still works: it is inherited, because immediate cleanup is not the part that needs a kernel. Frrrfr|settlerGr r|rdrrr+cdSNrrF)rrGr|rs rr~zNullGuard.bind sqrNr2c *ddl}|j|fd|i|S)zAn ordinary spawn, and it says so by being a NullGuard. Same signature as the real one so no caller branches on the platform - that is the whole point of the Null implementation. rNr2) subprocessPopen)rargvr2 popen_kwargsrs r spawn_intozNullGuard.spawn_intos0 z>>#>>>>rrGr r|rdrrdrr+)r@rArBrCr{r~rrFrrrrsgJ9= '+???????rrceZdZdZdZdZdZdZdZd d Z e d!dZ dddd"dZ dddZ ed#dZd$dZdS)%JobObjectGuarda'Windows. The kernel empties the job when our last handle closes. The handle is held for the life of the guard and never closed explicitly: closing it is precisely the event that kills the job, so the process exiting - by any route, including being killed - is what triggers it. Ti handlerkernel32rrcH||_||_t|_dSr)_handle _kernel32set_adopted)rrrs rrzJobObjectGuard.__init__+s ! UU r'LifetimeGuard'c ddl}|dd}|dd}|stSt }|j|j_|||j | || |}|s#| |tS|||S#t$rtcYSwxYw)z:A guard, or a NullGuard if the mechanism is not available.rNrT)use_last_error)ctypesWinDLLCreateJobObjectWr_ExtendedLimitInformation_KILL_ON_JOB_CLOSEBasicLimitInformation LimitFlagsSetInformationJobObject_EXTENDED_LIMIT_INFORMATIONbyrefsizeof CloseHandler=)rrrrinfooks rcreatezJobObjectGuard.create0s  MMM}}Z}EEH..tT::F # {{",..D474JD & 1117 T""FMM$$7$7B #$$V,,, {{"3vx(( (   ;;    sACBC CC10C1rrrfrrGr r|rdrr+c|sdStj|z}d}d}tj|krd}t|D]O}|j|jvr||jr$|j|j|dz }P||z }tj} |rd}n|r|| }n | |z |krn+tjdtj|k|S)aWait for the tree to appear, then adopt ALL of it. The wait exists because the driver spawns the browser asynchronously. The token makes it exact rather than a guess about how long that takes. WHY IT KEEPS SCANNING AFTER THE FIRST SUCCESS. Until 2026-07-27 this loop did `if bound: break`, so it adopted whatever existed at the first instant anything existed, and returned. Processes appearing a moment later escaped unless Windows added them automatically - which it only does for CHILDREN of a job member, and on Windows `firefox.exe` is a launcher stub that exits, re-parenting the real browser away from anything that was adopted. Measured by killing the runner mid-session and counting survivors: four runs gave sync 0/0/0/0 and async 2/0/0/2. Intermittent, ~50% on the async path, 0% on the sync one - not because the two APIs differ here, but because their timing does, which is exactly the shape that makes a race look like a working feature. So it now scans until a full pass adds nothing for `settle` seconds, bounded by `wait`. The cost is about a second on launch; the thing it buys is that "the kernel is holding this tree" stops being a coin flip. rNrg?)rtrur^rNr_adoptaddrv) rrGr|rrwbound quiet_sinceaddedr9nows rr~zJobObjectGuard.bindGs!2 1>##d*'+ n))E&u--  8t},,;;tx((M%%dh///QJE UNE.""C "  &"%KK;&&00 Jt   /n))0 rNrc ddl}d}|dd|z} |j|f||d|}n #t$r|j|fd|i|cYSwxYw ||jst d|j|jn,#t$r| |j|cYSwxYw| |j|S)aStart a process ALREADY INSIDE the job, so its whole tree is born in it. This exists because adopting afterwards does not work for this browser, and the measurement is unambiguous. On the profile manager's launch path, `AssignProcessToJobObject` returns **ERROR_ACCESS_DENIED (5)** for six of the eight processes and ERROR_NOT_ENOUGH_QUOTA (1816) for a seventh: Firefox puts its own content processes into its own sandbox jobs, and a process already in a job that does not permit nesting cannot be added to another one. Only the top process could be adopted, and the tree survived the kill 8 out of 8, three runs of three. Creating the process suspended, assigning it, and only then resuming it inverts that: everything it spawns is created inside our job from the start, which is the case Windows does support. `psutil` does the resume because `subprocess.Popen` does not expose the thread handle needed for `ResumeThread`. Falls back to an ordinary spawn if anything here fails - a launch that works without a guarantee beats a guarantee that refuses to launch. rN creationflags)r2rr2z,the process could not be assigned to the job) rpoprr=rrNOSErrorrr_resume)rrr2rr_CREATE_SUSPENDEDflagsr9s rrzJobObjectGuard.spawn_intosE* &  !447HH C#:#D4c44&244DD C C C#:#DBBcB\BB B B B C ;;tx(( NLMMM M  dh ' ' ' '    LL " " "KKK   TX s"3AAAB&CCrNc ddl}||dS#t$rYdSwxYwr)rZProcessresumer=)rN_pss rrzJobObjectGuard._resumesY  KK   # # % % % % %    DD s +/ ==r!c*|j|j|jzd|}|sdS t |j|j||j|S#|j|wxYw)NF)r OpenProcess_PROCESS_SET_QUOTA_PROCESS_TERMINATEr!AssignProcessToJobObjectrr)rrNrs rrzJobObjectGuard._adopts++  #d&= =uc   5 /77 fMM N & &v . . . .DN & &v . . . .s ,A66B)rrrrrr)rrr)rNr+rr)rNr+rr!)r@rArBrCr{rrrrrrErr~r staticmethodrrrFrrrrsJ"##### [,:> 666666p'+(((((T\ / / / / / /rrcddlddlmGfddjGfddjGfdd j}|S) z@The Win32 layout, built once and only when ctypes is importable.rN)wintypesc,eZdZfddDZdS)*_define_job_structures..IoCountersc"g|] }|jf SrF) c_ulonglong)rKnrs rrMz5_define_job_structures..IoCounters.s3BBBQ*+BBBr)ReadOperationCountWriteOperationCountOtherOperationCountReadTransferCountWriteTransferCountOtherTransferCountN)r@rArB_fields_)rsr IoCountersrsABBBBABBBrrc eZdZdjfdjfdjfdjfdjfdjfdjfdjfd jfg Zd S) *_define_job_structures..BasicLimitPerProcessUserTimeLimitPerJobUserTimeLimitrMinimumWorkingSetSizeMaximumWorkingSetSizeActiveProcessLimitAffinity PriorityClassSchedulingClassN) r@rArB c_longlongDWORDc_size_tPOINTERc_ulongr)rrsr BasicLimitrs~ &(9 : "F$5 6 8> * $fo 6 $fo 6 !8> 2 77 8 hn -  /  rrc`eZdZdfdfdjfdjfdjfdjfgZdS)-_define_job_structures..ExtendedLimitrIoInfoProcessMemoryLimitJobMemoryLimitPeakProcessMemoryUsedPeakJobMemoryUsedN)r@rArBrr)rrrsr ExtendedLimitrsN $j 1 z " !6? 3 v / $fo 6 &/ 2  rr)rr Structure)rrrrrs @@@@r_define_job_structuresrsMMMBBBBBBBV%BBB         V%             (    rplatform str | Nonec| tjn|}|dksttt St S)zThe only place the platform is tested. Every caller gets a LifetimeGuard and never asks which one it is: the Null implementation satisfies the same interface, so no launcher code branches on Windows. Nnt)osnamerZrrrr)rrs r guard_forrsC&277HD t||v~)B)J{{  " ""r)rGr rrH)rbrcrardrr+r?)rr)rGr rardrr!r)rrrrz)rC __future__rrrrtabcrrtypingrrrr r r6rZr=r r^rhrlrxrzrrrrrrFrrrsMCCH#"""""  ########99999999999999 " MMMM FFF ////////hD9<@    %%%%%AAAAACAAA&????? ???2a/a/a/a/a/]a/a/a/H"""J% 6 6 8 8%%% $% # # # # # # #s3== BB$#B$