j$dZddlmZddlZddlZddlZddlZddlZddlZddl m Z m Z m Z dZ dZGddeZGd d eZGd d ZGd dZGddeZGddZdZdZdddddd%d$ZdS)&uThe connection to Juggler: the pipe, with no Node in between. THE CONTRACT, read from `juggler/pipe/nsRemoteDebuggingPipe.cpp` and not guessed: - messages are JSON delimited by a ZERO BYTE, not a newline (`ReaderLoop` accumulates until it finds `'\0'`); - on POSIX the descriptors are **hardwired to 3 and 4**: `const int readFD = 3; const int writeFD = 4;`. They are not negotiated; - on Windows there are NO descriptors: they are HANDLEs read from the environment, `GetEnvironmentVariableA("PW_PIPE_READ", ...)` plus `atoi`, so the value must be passed in DECIMAL and the handle must be made inheritable; - the names are from the BROWSER's point of view: its `PW_PIPE_READ` is what IT reads from, i.e. where WE write. ⛔ And the flag `-juggler-pipe` must appear on the command line, or on Windows the handles never get armed at all and the pipe breaks at the launcher -> parent transition. ⛔ THE READINESS SIGNAL DOES NOT TRAVEL OVER THE PIPE. The browser prints `Juggler listening to the pipe` on stdout, and that line comes out of a `dump()` that a `MOZILLA_OFFICIAL` build disables: a disabled `dump()` RETURNS SUCCESSFULLY without writing. The fix lives in the Firefox source (`30-upstream-playwright-patches.md`), not here. Anyone reading a long timeout at launch should look there first. State: first piece. Opens the connection, sends commands, receives responses and events. Not yet a client: no lifecycle, no frames, no actionability. ) annotationsN)AnyCallableOptionalzJuggler listening to the pipeceZdZdZdS) ProtocolErroruThe browser refused a command. Carries its message, not ours. ⛔ `checkScheme` is CLOSED WORLD: an undeclared field is not ignored, it is rejected, and it happens at RUNTIME. The browser's message is the only thing that says which field. N__name__ __module__ __qualname____doc__YC:\Projects\Historical\venv\Lib\site-packages\invisible_playwright/_juggler/connection.pyr r .srr ceZdZdZdS)TargetClosedErroruThe thing a call was aimed at is gone: a disposed object, or the browser itself, whose pipe has closed. ⛔ THE CLASS NAME IS THE CONTRACT, not decoration. `reply_error` puts `type(failure).__name__` in the error payload, and `_helper.parse_error` turns that exact string into the fork's `TargetClosedError` on the client - which is the ONLY thing `_page.py`'s `close()` swallows: except Exception as e: if is_target_closed_error(e): return Anything else propagates. So closing a page whose context was closed first - `context.close()` cascades, then a fixture teardown calls `page.close()`, which is an ordinary shape and not a misuse - raised a hard error here on 2026-08-28, the day closed pages started being disposed at all. ⛔ AND IT LIVES HERE, ONE LAYER DOWN FROM WHERE IT WAS BORN, BECAUSE A CLOSED PIPE IS A CLOSED TARGET TOO. Until 0.15.0 the dispatcher raised this for a disposed guid, while the connection answered a pipe that had closed with a nameless error - `the pipe closed`, `the pipe is closed` - which `parse_error` turned into the fork's plain `Error`. The same fact, the browser is gone, reached a caller as two different classes, and the caller that had to tell "the page refused" from "the browser died" (the AIHawk server's retry) was reduced to matching the sentences. Measured 2026-09-14. One class, raised by both layers, and exported from the public API so a caller can catch the TYPE. Nr rrrrr7srrc8eZdZdZdZddZddZdd ZdddZdS) ProcessOutputuThe browser's stdout and stderr, read for the WHOLE life of the process by ONE reader, keeping the last lines. ⛔ WHY IT EXISTS, measured on 2026-09-25 ([B229]). The two streams go into one pipe, and it used to be read only until the readiness line and never again. A pipe has a fixed buffer - the Windows default, since it is created with size 0 - so once Firefox had written a buffer's worth after startup, its next write BLOCKED, and so did whichever of its threads was writing. Forced with `devtools.console.stdout.content`: a page logging 2 KB still answered, one logging 8 KB never answered again, with 5085 bytes sitting unread in the pipe. The browser stayed alive and silent, with no error anywhere. Ordinary browsing on Windows writes little (76 bytes over ten real sites), which is why it went unseen: it is a clock that runs out in long sessions, on Linux where GTK and fontconfig talk, or with any log on. ⛔ ONE READER, NOT A SECOND ONE ADDED AFTER THE FIRST. Readiness is a question asked of this object (`wait_for_ready`), not a loop of its own on the same stream: two readers of one pipe split its lines between them. The kept lines are the only account of why a browser stopped. They were already what a failed STARTUP printed; now the same lines are there when the pipe closes in the middle of a session (`Connection.send`). returnNonecddl}||_||j|_t j|_d|_d|_ t j |j dd|_ |j dS)Nr)maxlenFTzbrowser-output)targetdaemonname) collections_streamdequeKEEP_lines threading Condition_cv_ready_eofThread_pump_threadstart)selfstreamrs r__init__zProcessOutput.__init__ps !''ty'99 &((   'tz$-=???  rc t|jjdD]}|ddd}|j5|r|j|t|vrd|_ |j dddn #1swxYwYn#ttf$rYnwxYw|j5d|_|j ddddS#1swxYwYdS#|j5d|_|j dddw#1swxYwYwxYw)Nrutf-8replacez T)iterrreadlinedecoderstripr%stripr"append_READYr& notify_allOSError ValueErrorr')r,rawtexts rr)zProcessOutput._pump{s# &DL1377 * *zz'955<D?CDCD!D  DDE !E  E E EE EtimeoutfloatboolcBtj|z}|j5|js|js|mtjdz}|jsOtj|kr8|jd|jstj|k8nS|tjz }|dkrn6|jt|d|js|j|jcdddS#1swxYwYdS)aTrue when the readiness line arrived within `timeout`. False when it did not, or when the process exited first - in which case whatever it managed to print is drained before answering, because the last line before an exit is usually the one that says why.Ng?皙?r)time monotonicr%r&r'pollwaitmin)r,processr>deadlinedrainlefts rwait_for_readyzProcessOutput.wait_for_readys\ >##g- X  k /$) /<<>>- N,,s2E"i,DN,<,r?rr@)rM)rNrOrrP) r r r rr!r.r)rLrSrrrrrUsz0 D    &&&&"&*******rrc2eZdZdZddZddZddZdd ZdS)EventListenersuWho is subscribed to a connection's events, and how one is delivered. ⛔ ONE IMPLEMENTATION, USED BY THE REAL CONNECTION AND BY THE FAKES. The tests stand a stub connection in front of `Lifecycle` and `InjectedScript`, and if that stub carried its own idea of what subscribing means, the tests would be measuring the stub. Inheriting it is what makes a green test say something about the code that ships. rrcRg|_tj|_g|_dSrR) _listenersr#Lock_listeners_lockhandler_errors)r,s rr.zEventListeners.__init__s+$!#(~//%'rc|j5||jvr|j|ddddS#1swxYwYdS)zSubscribe to every event. Registering twice is a no-op, not two deliveries: a handler called twice for one event announces a frame twice, and that reads as the browser having sent it twice.N)rZrXr7r,fns r add_listenerzEventListeners.add_listeners ! + +((&&r*** + + + + + + + + + + + + + + + + + +s $9==c|j5 |j|n#t$rYnwxYwddddS#1swxYwYdS)u#Unsubscribe. ⛔ CALLING THIS IS NOT OPTIONAL HOUSEKEEPING: it is the half of the fix that keeps the list from growing without bound, and a subscriber that forgets it leaks for the life of the browser - which is the defect this registry exists to close, reintroduced.N)rZrXremover;r]s rremove_listenerzEventListeners.remove_listeners  !   &&r****                      s,A%A 2A2AA Amethodstrparamsdictsession Optional[str]c.|j5t|j}dddn #1swxYwY|D]^} ||||#t$rA}t |jdkr|j|d|Yd}~Wd}~wwxYwdS)uDeliver one event to every subscriber, iteratively. ⛔ ONE LISTENER'S FAILURE MUST NOT COST THE OTHERS THEIR EVENT. In the chain this replaces, a subscriber that raised took every subscriber BELOW it down with the same event, because the delivery to the rest was the last statement of the one that raised. Here each call is isolated: the failure is recorded and the loop carries on. N : )rZrPrX Exceptionlenr[r7)r,rcrerg subscribersr^failures rdispatch_eventzEventListeners.dispatch_events  ! 0 0t//K 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 M MB M667++++ M M Mt*++b00'..66677/KLLL M M Ms#)-- A B7B  BNrT)rcrdrerfrgrhrr)r r r rr.r_rbrprrrrVrVst''''8++++    MMMMMMrrVcjeZdZdZdfd ZddZdd Zdd Z d d!dZ d"d#dZ d$dZ d%d&dZ xZ S)' Connectionz&A pipe to an already-launched Firefox.Nct||_||_||_d|_i|_tj|_ tj|_ d|_ d|_ d|_ tj|jd|_|jdS)NrFT)rr)superr. _to_browser _from_browser_process_next_id_pendingr#rY_lock _write_lock_closed_erroroutputr( _read_loop_readerr+)r, to_browser from_browserrH __class__s rr.zConnection.__init__s %)  )+ ^%% %>++ /3 04  'ttLLL  rrrc d} |jsptj|jd}|snS||z }t|vr>|td\}}|r||t|v>|jpn#t$r}||_Yd}~nd}~wwxYwd|_|j 5t|j }|j dddn #1swxYwY|D]3\}}|ddddi|4dS#d|_|j 5t|j }|j dddn #1swxYwY|D]3\}}|ddddi|4wxYw) NriTerrorrzthe pipe closed)rmessage)r|osreadrvNULsplit_deliverr:r}rzrPryvaluesclearr7set)r,bufferchunkr<ependingreadyboxs rrzConnection._read_loop s l + 2E::%Vmm"(,,sA"6"6KC+ c***Vmm l +   DKKKKKK  DL & &t}335566 ##%%% & & & & & & & & & & & & & & &&   s G.A1B&D&DEFFF    DL & &t}335566 ##%%% & & & & & & & & & & & & & & &&   s G.A1B&D&DEFFF  shA7A<;D7< BB D7BD7(AC44C8;C87GAF GF GF :Gr<bytesc0 tj|d}n#t$rYdSwxYw|d}|X|d}|r?|||dpi|ddS|j5|j|d}dddn #1swxYwY|0|\}}| || dSdS)Nr0idrcre sessionId) jsonloadsr4rlgetrprzrypopr7r)r,r<msgmsg_idrcentryrrs rrzConnection._deliver*sa *SZZ0011CC    FF  >WWX&&F :&##FCGGH,=,=,C$'GGK$8$8::: F Z 4 4M%%fd33E 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4  JE3 JJsOOO IIKKKKK  s'* 881CC Crdcg}d}|j- |j}n#t$rd}YnwxYw||d|z|j|jng}|r5|ddd|Dz|rdd|zndS)zThe exit code and the browser's last lines, when there are any. "the pipe is closed" alone names neither: it is what a browser that crashed, one that was killed and one that was closed on purpose all look like from here.Nzthe browser exited with code %szits last output:  c3 K|] }d|zV dSz Nr.0rs r z)Connection._why_closed..`s&9S9S&1*9S9S9S9S9S9Srz )rwrErlr7r~rSjoin)r,partscoderSs r _why_closedzConnection._why_closedOs  = $ }))++       LL:TA B B B%)[%@rcreOptional[dict]rgrhr>r?rcJ|jr-td|jpd||j5|xjdz c_|j}g}t j}||f|j|<dddn #1swxYwY|||pid}|r||d<| || |sN|j5|j |ddddn #1swxYwYtd||fz|d} d| vrq| d} | d d kr(t|d | d | t|d | d | | d S)Nzthe pipe is closed: rrrrcrerze%s: no response in %.0fs. If this is the FIRST command, look at the readiness signal before the pipe.rrrrrkrresult)r|rr}rrzrxr#Eventry_writerFrr r) r,rcrergr>rrrrresponsers rsendzConnection.sendds` < O##'+{'8b'8$:J:J:L:L:L%NOO O Z 1 1 MMQ MM]F CO%%E%*CLDM& !) 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1*"Vv|LL  '&C  Czz'"" % 0 0 !!&$/// 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0@7#$%% %q6 h  !AuuV}} 333'FFFAEE)QfdprIs rrzConnection.closes #T%78  B       M  F>##g-ffhh4>#3#3h#>#> Jt   ffhh4>#3#3h#>#> 6688         s. ;;C44 DDrRrT)r<rrr)rrd)NNr) rcrdrerrgrhr>r?rr)NN)rcrdrerrgrhrr)rrfrr)r)r>r?rr) r r r rr.rrrrrrr __classcell__)rs@rrrrrs002:####J>>>>*:>=A,&,&,&,&,&\:>&*8---- rrrcBeZdZdZdZddZd Zdd ZdddZddZ e Z d S)_WindowsProcessasThe four things `launch` and `Connection.close` ask of a process, over a raw process handle. It exists because `subprocess.Popen` cannot name the DESKTOP a process is created on: CPython's `STARTUPINFO` carries `dwFlags`, `wShowWindow`, the three std handles and `lpAttributeList`, and nothing else - `lpDesktop` is not reachable from it. The hidden-desktop launch needs exactly that field, so the spawn below calls `CreateProcessW` itself and this is the handle it gives back, with the same surface the Popen used to have: `pid`, `poll()`, `returncode`, `wait()`, `terminate()`, `stdout`. ihandlerOpidrrc>||_||_||_d|_dSrR)_handlerstdout returncode)r,rrrs rr.z_WindowsProcess.__init__s"  )-rc8ddl}|ddS)Nrkernel32Tuse_last_error)ctypesWinDLL)r,rs r _kernel32z_WindowsProcess._kernel32s! }}Z}===r Optional[int]c|j|jrddl}ddlm}|d}|}|||j||r]|j |j krMt|j |_| ||jd|_|jS)Nrwintypes) rrrrDWORDrGetExitCodeProcessHANDLEbyrefvalue STILL_ACTIVErO CloseHandle)r,rrrk32s rrEz_WindowsProcess.polls ? "t| " MMM ' ' ' ' ' '>>!$$D..""C%%hoodl&C&C&,ll4&8&8:: !J$"333"%dj// = =>>>  rNr>Optional[float]c~ddlm}|jp|jri|dnt |dz}|||j||| }|)tj t|j |pd|S)Nrrli)rrrrrOrWaitForSingleObjectrrrE subprocessTimeoutExpiredrdr)r,r>rmsrs rrFz_WindowsProcess.waits###### ? "t| "&C$4G4GB NN   0 01N1N191C1C E E Eyy{{ <+CMM7.> @ @ @ @ @    r)rrOrrOrr)rrrR)r>rrrOrT) r r r rrr.rrErFrkillrrrrrs  L.... >>>         @@@@ DDDrrc %&'(ddl'ddl}ddl&ddlm(ddlm}'dd}&fd}&dd\}}&dd\} } |||| } }&dd\} } || } &} & | | | dd&j }&dd\}}||}& |t|}| |d}tt||d <tt| |d <G'(fd d 'j%G%'fd d'j}G(fdd'j}'j(j(j''jf|j_'j(j'j'j'j'j'jf|j_(j(j'j'j(j(j'j(j'j'|f |j_(jdz|| | ||}'d}|ddd'|'|j}||dd'|s'' '!d}||d||'"|dds'' '!|}'"||j#_$d|j#_%||j#_&| |j#_'||j#_(|r ||j#_)'*|'j|_+tYd}|-dt]|/dD|z|z}'0|tc|dz}'0tej3|g|z}d\}}|}|d|ddd||z|d'|'| } '!}!|4||| | ||fD]}"& |"| sa| || fD]}"& |"tk|!d||rd|zndd'6|!7| |j8tsj:|;| trj<d}#t{t|j>t|j?|#}$|;|d|;| trj<|$fS)uz`CreateProcessW` by hand, for the one field `subprocess` cannot set. The browser is created on the desktop named by `INVPW_DESKTOP` when the session asked to be hidden (`invisible_core._headless`), and on the caller's own desktop otherwise. That variable is consumed HERE and does not reach the browser: the engine never reads it. Everything else is what the `Popen` call used to do, made explicit: exactly five handles are inherited - the two Juggler pipe ends, the child's end of the stdout pipe, a second handle to that same end for stderr, and the read end of a pipe for stdin - through `PROC_THREAD_ATTRIBUTE_HANDLE_LIST`, so a second session starting in the same instant cannot hand its pipe ends to this browser and lose the ability to notice its own closing. `bInheritHandles=TRUE` with that list inherits those five and nothing else. ⛔ THE THREE STD HANDLES ARE SHAPED FOR FIREFOX'S LAUNCHER, and the first draft of this function got two of them wrong. `firefox.exe` runs first as a launcher that creates the real browser with a handle list of its own, built from its stdin, stdout and stderr plus the Juggler pipe (`browser/app/winlauncher/LauncherProcessWin.cpp`, `ProcThreadAttributes.h`). That list takes only DISK and PIPE handles, silently drops anything else while still naming it as a std handle, and is never de-duplicated - and Windows refuses a handle list with the same handle twice. A NUL device for stdin (a CHAR handle) and one handle for both stdout and stderr made the launcher's `CreateProcessW` fail with ERROR_INVALID_PARAMETER (Event Log, `LauncherProcessWin.cpp:580`); the launcher then disabled itself for that path in the registry (`|Browser` = 0) and ran on as the browser itself, so the session worked and `tests/test_first_launch_from_a_new_path.py` was the only thing that saw it. `Popen` never tripped it because CPython duplicates every std handle separately. So: stdin is the read end of a pipe whose write end is closed at once (EOF, and a PIPE type), and stderr is its own duplicate of the stdout pipe. rNr) DESKTOP_ENVrTrc}|||ddj}||S)u⛔ CPython's `_winapi.CreatePipe` calls Windows' CreatePipe with NULL security attributes, so the handles are NOT inheritable. Passing them in the handle list as they were made `CreateProcess` fail with `WinError 87 - The parameter is incorrect`, which does not name the cause. They get duplicated asking for inheritance, and the original is closed.rT)GetCurrentProcessDuplicateHandleDUPLICATE_SAME_ACCESSr)hcurrent_processnew_winapis r inheritablez#_spawn_windows..inheritable>sV"3355%%oq/&'w/LNNA r PW_PIPE_READ PW_PIPE_WRITEc4eZdZdjfdjfdjfdjfdjfdjfdjfdjfd jfd jfd jfd jfd jfdjfdjfdjfdjfdjfgZdS)$_spawn_windows..STARTUPINFOWcb lpReserved lpDesktoplpTitledwXdwYdwXSizedwYSize dwXCountChars dwYCountCharsdwFillAttributedwFlags wShowWindow cbReserved2 lpReserved2 hStdInput hStdOutput hStdErrorN) r r r rLPWSTRWORDc_void_pr_fields_)rrsr STARTUPINFOWrhs8>*\8?,K (/2Y4PHN+eX^-D/)X^1L$hn5$hn5&7/-1O"HM2"FO4 (/2!8?3 (/2 4rrc*eZdZdfdjfgZdS)&_spawn_windows..STARTUPINFOEXW StartupInfolpAttributeListN)r r r rr)rrsrSTARTUPINFOEXWrws("L1&8:rrcTeZdZdjfdjfdjfdjfgZdS)+_spawn_windows..PROCESS_INFORMATIONhProcesshThread dwProcessId dwThreadIdN)r r r rrrrsrPROCESS_INFORMATIONr{s=1Ix3O"HN3!8>24rrric3 K|] }d|zV dS)z%s=%sNr)rkvs rrz!_spawn_windows..s>HHbWr\HHHHHHrc6|dS)Nr)upper)r s rz _spawn_windows..s1 r)key)iizCreateProcessW failed for z on desktop %rrrkrb)@rmsvcrtrrinvisible_corerr CreatePiperrrrrfrrdrO StructurerrPOINTERc_size_t!InitializeProcThreadAttributeListargtypesUpdateProcThreadAttributeLPCWSTRr BOOLCreateProcessWrrcreate_string_bufferrWinErrorget_last_errorsizeofrrrr r r rcastrchrrsorteditemscreate_unicode_bufferrmr list2cmdlineDeleteProcThreadAttributeListr: FormatErrorr6rrfdopenopen_osfhandleO_RDONLYrrr)) executableargvenvr&rrrits_read our_writeour_read its_writeout_read out_writer err_writein_readin_writedesktoprr inheritedsizeattrs!proc_thread_attribute_handle_listsinulblock env_blockcmdlinecreate_unicode_environmentextended_startupinfo_presentpiokerrrrrrrrrs) @@@@r_spawn_windowsr\s%FMMMMMMNNN****** -- 4- 8 8C      ",,Q22Hi!,,Q22Hi%+h//Y1G1GiH ",,Q22Hi I&&I//11O''(7D(/(EGGI  **1a00GXk'""G !!! s))Cggk4((Gc(mm,,Cs9~~..C 4 4 4 4 4 4 4 4v' 4 4 4::::::::):::4444444f.444 v''6)C)2 &/&/.;C!* (/6?FO x~v8H(;<<#>C %1$h 9&/::I ??1  D))$1fll46H6HIII  ' ' 3 3E  0 01fll4>P>P Q Q7oof3355666(/%  ( ( 17 MM) $ $dD 2 27oof3355666   B n55BN"BN&BN )BN(BN+#* UFO< alive=[3] with 3 and 4 also kept -> alive=[3, 4] Fd 3 survived only by accident: the first `os.pipe()` in the parent happened to return 3, so it was already in the keep list and the `dup2` onto it was a no-op. Fd 4 was created by `dup2` and swept away - which is why the browser could ANNOUNCE itself (it had a read end on 3) and never receive anything (nothing owned the read end of OUR pipe once 4 died). ⛔ The remedy is to name 3 and 4 in `pass_fds` as well. They are not open in the parent and do not have to be: that list is a set of NUMBERS the child's sweep spares, not a set of parent handles. cdfdffD]5\}}||krtj||tj|d6dS)NT)rdup2set_inheritable)sourcerrDrGs rfix_descriptorsz%_spawn_posix..fix_descriptorssb$!)!}y!n= - -NFF'''  vt , , , , - -rr_r`)rC preexec_fnpass_fdsrstderr)rpiperPopenPIPESTDOUTr) rArBrCrErFrdrrDrGs @@r _spawn_posixrls4'))Hi'))Hi------. *,#$3 $,Y1"= * 8I K K KAHXHY h !!rTgN@)headless argv_extrarC ready_timeoutrArd profile_dirrmr@rnOptional[list]rCrror?rc dg}|r|dn|ddgz }|d|dgz }|t|pgz }|dt| tjn|}t jd krtnt}||||\} } } t| j } | | |} | gd d | Dpd }td | jdd |g|zd|t#| | | }| |_| |_|S)zKLaunches Firefox over the pipe and returns an already-ready connection.z -no-remotez -headlessz-wait-for-browserz -foregroundz-profilez -juggler-pipez-silentNwin32rc3 K|] }d|zV dSrrrs rrzlaunch..1s&==!&1*======rz (nothing)zTthe browser exited during startup, before the protocol could be used. exit code : z command :  z it printed: )r7rPrfrenvironsysplatformr\rlrrrLrErrS RuntimeErrorrrr ready_seenr~)rArprmrnrCrorBfull_envspawnrrrr~seencodacs rlaunchrs >D5 K     $m44Zo 66DD!r " ""DKK #+BJJ377H!lg55NNrs>#"""""   **********  (L ">">"BCG'+4!%1 1 1 1 1 1 1 1 r