j dZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl mZddlZddlZddlZddlmZmZddlmZmZmZmZmZmZmZmZmZmZm Z m!Z!m"Z"dRd Z#dSdZ$dTdZ%dUdVdZ&dUdWdZ'dXdZ(dZ)dYdZ*dZ+dZ,dZdZ-d Z.d!Z/e0hd"Z1d#Z2e j3Z4d[d&Z5d\d*Z6d]d,Z7e.fd^d0Z8d1de.fd_d4Z9d`dad5Z:dbd7Z;dcd:ZdfdgdEZ?dhddFdidGZ@dUdjdIZAdJZBdkdLZCdUdMdNdldPZDddQlEmFZFmGZGdS)mzCDownload and cache the patched Firefox binary from GitHub Releases.) annotationsN)Path)BINARY_ENTRY_RELRELEASE_URL_TEMPLATE) AssetEngineMismatchSUPPORTED_LEGSSUPPORTED_PLATFORMSSeal SealError SealMismatch active_sealread_engine_identity read_stamp resource_root verify_engine write_stampreturn str | Nonec~tjdptjdS)NSTEALTHFOX_GITHUB_TOKEN GITHUB_TOKEN)osenvirongetGC:\Projects\Muse2API\.venv\Lib\site-packages\invisible_core/download.py _github_tokenr *s* :>>3 4 4 V ~8V8VVrtemplatestrtuple[str, str]ctjd|}|std||d|dfS)z0Extract (owner, repo) from RELEASE_URL_TEMPLATE.z-https://github\.com/([^/]+)/([^/]+)/releases/zcannot parse owner/repo from r)rematch RuntimeErrorgroup)r!ms r_parse_owner_repor+.sS A8LLA IG8GGHHH 771::qwwqzz !!rrctjd}|rt|Stt jdS)a Directory where all cached binaries live. INVISIBLE_PLAYWRIGHT_CACHE_DIR overrides it. It was set by the test suite and read nowhere, so "isolated" cache tests were operating on the developer's real cache; honouring it makes them hermetic on every OS. INVISIBLE_PLAYWRIGHT_CACHE_DIRzinvisible-playwright)rrrr platformdirsuser_cache_dir)overrides r cache_rootr16sFz~~>??HH~~  +,BCC D DDrseal Seal | Nonecr|p t}t|jd|jd|jz S)zThe cache directory IS the identity: tag, base version and BuildID. A different seal names a different directory, so a warm tree belonging to a different expectation is not rejected, it is never looked at. _)rr1tagupstream_versionbuild_id)r2ss rcache_dir_for_sealr:Cs>  A </` URL returns 404 even with a token, so we resolve via the API: list assets for the release tag, find the one matching `asset_name`, and use its API URL with `Accept: application/octet-stream` (which 302-redirects to a signed URL). For public repos the direct URL still works without a token. )r6assetzhttps://api.github.com/repos//z/releases/tags/chtjddid}||S)N Authorizationtoken )headerstimeout)requestsrraise_for_status)rapitokens r_askz _resolve_asset_url.._askhs? L8H8H8H&ISU V V V rzthe release index for assetsnameurlzasset z not found in release )r rformatr+ _with_retriesjsonrr() r6r>ownerreporMrJarKrLs @@r_resolve_asset_urlrWVs OOE F#*s*EEEE#$899KE4 L% L L$ L Ls L LC  d:S::;;A VVXX\\(B ' ' 55==J & &U8OOO ' K KKCKK L LLrrPc d}|drW|dddr)t|ddd}d|d|dd|d g}||tkr|d |d d d d d d dgz }n |d |dgz }t d|S)aWhat to say when the engine archive is not there. WHY THIS EXISTS. A 404 surfaced as `requests.exceptions.HTTPError: 404 Client Error` and nothing else - no tag, no cause, no remedy. Reported as issue #51 on 2026-08-01 by somebody whose install came from a git pin predating firefox-14, when the binaries moved to the source repo. They did the work themselves: found that the tags existed, that no release did, and that the URL template named a repo hosting nothing. That investigation is the message's job, not the reporter's. AND IT STOPS AT A MESSAGE, DELIBERATELY. 18.10.0 shipped a version of this that ran `pip install --upgrade` on the caller's environment and then told them to re-run. It worked, and it is the wrong shape: a library that installs things while it is running mutates an environment nobody asked it to touch, ignores whatever lockfile put that version there, and inside a container rewrites an image layer at runtime. Removed in 18.11.0. Detecting the state and saying what to run is the whole job; running it is the caller's. The two cases are genuinely different and the message says which one it is. An OLD tag cannot be fixed by waiting: those releases were removed on purpose, so the pin has to move. A CURRENT tag missing its asset is something else - a re-cut release, a pruned asset - and worth reporting. Nzfirefox--rzthe engine archive for z is not published: z -> HTTP 404z tried z^ the tag comes from the release seal inside invisible-core, not from anything you configured.z is one of the engine releases that were REMOVED on purpose, so that everybody runs one engine rather than a long tail of old ones. It is not coming back and no amount of retrying will find it.zYou are running a version of this package that predates the move. That usually means an install pinned to a git ref rather than to a release - including a pin inside some other project that depends on this one.zG pip install --upgrade invisible-playwright # or invisible-firefoxzIf the pin is not yours to move, the project that owns it has to move it: a git ref from before the move can never download an engine again.z is a current release, so this is not the retired-engine case. Either the asset was pruned from the release or the release was re-cut without it. Worth reporting, with this message. ) startswithsplitisdigitintOLDEST_PUBLISHED_TAG_NUMBERchrjoin)r6r>rPnumberliness r_missing_release_messagerf{s.0F ~~j!!+ciiQ&7&7&:&B&B&D&D+SYYsA&&q)** S#RR*RRR3 # E f'BBB  M M M  R  U  U     F F F   r77<<  rINVISIBLE_DOWNLOAD_DEADLINEg @floatc tjt}||st S t |S#t$r%ttd|dt dddwxYw)zESeconds allowed for one download. Zero or negative removes the bound.N=z9 is not a number of seconds. Unset it for the default of .0fz/s, or set it to 0 to remove the bound entirely.) rrrDOWNLOAD_DEADLINE_ENVstripDOWNLOAD_DEADLINE_DEFAULTrh ValueErrorr()raws r_download_deadlinerqs *... / /C {#))++{(( Szz $ < gN@messageNonec>t|tjddS)NT)fileflush)printsysstderr)rys r_noters ' $//////rexc BaseExceptionboolct|tjrt|jdd}|t vSt|tjtjtjj fS)aRDoes this failure say "ask again", or does it say something? Pure: no clock, no network, no state, so the answer can be checked against known-bad inputs without a server. Everything it does not recognise is permanent, which is the safe direction: an unknown failure is reported once rather than repeated three times. status_codeN) isinstancerH HTTPErrorgetattrresponseTRANSIENT_STATUSConnectionErrorTimeout exceptionsChunkedEncodingError)rstatuss r _is_transientrsj#x)***}d;;))) cH4h6F$/DF G GGr float | Nonec@tt|dddipi}|d}|dS tt|}n#t $rYdSwxYwt dt|tS)z>The server's own answer to "when should I ask again", or None.rNrFz Retry-Afterg) rrrhr"rmromaxminRETRY_AFTER_CAP_S)rrpvaluesecondss r _retry_afterrs '#z400)R @ @ FBC GGM " "E }tE ((**++ tt  sC!233 4 44s.A,, A:9A:whatattemptsr`ctd|dzD]} |cS#t$r}||kst|s.|dkr't|rt|d|d||t |}|t |dz }t d|d|d|d|d |d d t|Yd}~d}~wwxYwdS) aRun ``call()``, and run it again while the failure says to ask again. ``what`` names the thing being fetched, for the note and for the failure. A permanent failure is re-raised untouched on the first attempt, so callers that read a status code off it - the 404 branch in ``ensure_binary`` - still see the exception they expect. ``attempts`` is the CALLER's, and one attempt is a legitimate answer. Asking again is only worth its wall clock to someone who has nothing better to do with the failure; a caller holding a good enough copy already has something better, and waiting ten seconds to reach a fallback it was going to take anyway is a cost with no buyer. See ``_geoip_db.ensure_geoip_mmdb``. rz failed z times; the last attempt said: Nz z : attempt  of z failed (z); asking again in rkr9)range Exceptionrr(rDOWNLOAD_BACKOFF_Sr_SLEEP)callrrattemptrwaits rrRrR s](HqL)) 466MMM   (""-*<*<"Q;;=#5#5;&''''!$''((-01$$D|)'A+6 :t::w::H::::.29::: ; ; ; 4LLLLLLLL s # C BCC dst chunk_sizecltfdddd|S)aDownload ``url`` to ``dst``, asking again when the failure is transient. ``dst`` is truncated at the start of every attempt, so a retry starts from byte zero: there is no resume here, and the failure that wants one - a socket dropping most of the way through a 262 MB transfer - is not the failure this was written for. Callers download into a temporary directory and only move the tree into the cache after the sha256 matches, so a half-written file from a dead attempt is never adopted. ``attempts`` defaults to the engine's policy because that is the caller with nothing to fall back on. It is a parameter and not a constant read inside because this function is shared, and a shared primitive that carries one caller's policy imposes it on the other: ``_geoip_db`` had already written down the opposite answer and would have inherited a ten-second wait on the way to a fallback it was taking anyway. c(tSN)_download_once)rrprogressrPsrz _download_file..XsS*h!O!OrrAr)rRrsplit)rPrrrrs```` r_download_filerFsG$ OOOOOOOC++B/ ; ;;rc|jddi}t}|r"|dr d||d<d|d<t }t j}tj|dd| 5}| t|j d pd } d } t|d 5} | |D]} | rG| | | t| z } | || | n#t $rYnwxYwt j|z } |d kru| |kro| |dt'd|dddd|dd| d| pdd| ddt*d  d d d n #1swxYwYd d d d S#1swxYwYd S)aHOne attempt. If ``progress`` is given it is called with ``(bytes_done, total_bytes)`` as the download proceeds (total is 0 when the server sends no Content-Length). Bounded by ``DOWNLOAD_DEADLINE_ENV`` across the whole transfer; see that constant for why the per-read timeout below cannot do it. That bound is per attempt, and the RuntimeError it raises is deliberately NOT transient: a link slow enough to run out the deadline is not a link that a second full download would beat, and retrying it would multiply the very wait the bound exists to cap.Tparentsexist_okzhttps://api.github.com/rDrCzapplication/octet-streamAccept<)streamrGrFzContent-LengthrwbN) missing_okzthe download of rArrz passed its rkz s deadline: rzan unknown number ofz bytes after z^s. The per-read timeout cannot catch this - a connection that trickles never trips one. Raise zE if the link really is this slow, or set it to 0 to remove the bound.)parentmkdirr r]rqtime monotonicrHrrIr`rFopen iter_contentwritelenrcloseunlinkr(rrl)rPrrrrFrLlimitstartedrJtotaldonefchunkelapseds rrr\s JTD111 G OOE 7 9::7#3E#3#3 6  EnG c$G D D DK AIMM"2338q99 #t__ K 33 K K!GGENNNCJJ&D+!$HT51111(!!! D! .**W41995GGIIIJJ$J///&J3::c1+=+=b+AJJ <JJ26JJ :$:JJ#MJJ "7 JJJKKK! K K K K K K K K K K K K K K K K KKKKKKKKKKKKKKKKKKs] AG2AG D+*G+ D8 5G7D8 8BG G2G G2!G "G22G69G6pathctj}t|d5tfddD]}|| dddn #1swxYwY|S)Nrbc.dS)Nr)read)rsrrz_sha256_file..s!&&//rr)hashlibsha256riterupdate hexdigest)rhrrs @r _sha256_filersA dD  Q1111377  E HHUOOOO  ;;==s,AA"%A"textdict[str, str]c*i}|D]{}|}|r|dr.|}t |dkr&|dd}|d||<||S)N#r%r*r) splitlinesrmr]r^rlstrip)routlinepartskeys r_parse_checksumsrsC!!  zz|| ts++    u::??)""3''CQxCH Jrarchivec|dd|jdkrDtj|5}||ddddS#1swxYwYdS|jds |jdvrEtj|d5}||ddddS#1swxYwYdStd|)NTrz.zipz.tar.gz>.gz.tgzzr:gzzunknown archive format: ) rsuffixzipfileZipFile extractallrOendswithtarfilerr()rrzftfs r_extractrskIIdTI***~ _W % %  MM#                        y ) )AW^-N-N \'6 * * b MM#                     ?g??@@@s#AA!ACC Cr r@r version_dir Path | Nonecg}|r||t|jz }||kr)|r|||D]}||jz }|s" t ||d|j|n=#t$r0}td|d|j tj Yd}~td}~wwxYw|j rt|dz }|r]t||j kr!td|dtj n$td |jd tj ||kr3 t!j|||||jz }}n#t$$rYnwxYwt'|||jdd td |d|dtj t ||d|j|cSdS)avUse a tree that is already on disk if it IS the sealed build. Covers every warm cache in the field (flat cache_root()/ layout) and a content-keyed tree whose stamp was lost. Verified -> moved onto the content-keyed name and stamped, no download. Not verified -> left exactly where it is (it may belong to the other product) and the cold path runs. zexisting cache sourcer@zinvisible-core: not adopting z: )r|Nzomni.jazQ: omni.ja content does not match the sealed payload (superseded or modified tree)zinvisible-core: z: this platform's asset has no sealed omni.ja digest, so the payload bytes are not content-verified; adoption rests on application.ini, platform.ini and the juggler markersTr@ asset_sha256adoptedz5invisible-core: adopted the engine already cached at z (z); no download neededzadopted )existsappendr1r6 entry_relrrOr r~summaryrr omni_sha256rrlowerrreplaceOSErrorrdescribe) r2r@r candidateslegacydentryeomnis r_adopt_existing_cachersJ'+&&& \\DH $F &!!! 'S'SEO#||~~    %.H.H.HPU V V V V V    B!BBqyBB T T T T HHHH     # '')3D{{}} d!3!3!9!9!;!;u?P?V?V?X?X!X!XJaJJJPSPZ\\\\ NQVNNNz # # # #    1k***& eo(E5    At5:D$OOOO 9a99--//999?Bz K K K K UD1DAF1D1DERRRRRR 4s*B22 C,<&C''C,%!G GGrootlistcL|p t}|sgS|p tj}g}|D]}|r|jds1|jddd}|sgt|}|tj ks ||rtj |d|s|||S)aRemove the `.tmp--` trees left by downloads whose process is gone. A download extracts into a directory named after its pid and, when it starts again, removes only that one. A process killed during `verifying` or `extracting` therefore leaves up to the whole tree behind, and until this existed nothing ever looked at it again. The MCP server's prefetch (0.13.0) made the case ordinary: a client that closes the server in the first minute of its first session kills a download in flight. A tree whose pid is alive belongs to a download in flight, in this process or another, and is left alone. A reused pid keeps an orphan for one more round, which is the conservative side. Returns what was removed. .tmp-rZrrT ignore_errors)r1is_dirpsutil pid_existsiterdirrOr]rr_r`rgetpidshutilrmtreerr)raliveremoved candidatepid_textpids rsweep_orphaned_tmprs  :<((a004!!  (mm ")++  s   it4444!! & NN9 % % % Nr)r2c d2fd }|p t}|9||jkr.td|d|d |d |d |jrt d |jd tj}|tvrM|dkrtdtd|dd dtDd| |tj}t|}||jz }t#t%t'|} | rM| d|jkr/|rt/||d|j|St3|||} | | St5|j|j} t%d|jdt7jz } t;j| dt?j 5} tC| |jz }|d tE| ||n[#tFj$$rI}tK|j&dddkrtOtQ|j|j| |d}~wwxYw|d tS|}|*|j+*kr+tOd!|jd"|jd#|d$|j+d% |d&tY|| dddn #1swxYwY| |jz }|s(t;j| dtOd'|t;j|d t7j-| |nh#t\$r[}|rt;j| dn&tOd(|d)| d*|d+|j/d,z d-d. |Yd}~nd}~wwxYwta|||j|j+d/0t/||d1|j|S)3aReturn a verified path to the sealed Firefox executable. Download if needed. `version`, when given, must be the sealed tag: this core is paired with exactly one build and cannot coherently install another. ``progress``, if given, is called with ``(bytes_done, total_bytes)`` while the (large) archive downloads, for a UI progress bar. ``status``, if given, is called with a phase string ("downloading" | "verifying" | "extracting") so a UI can show what the post-100% (silent, no byte-progress) steps are doing - the SHA256 check + the archive extraction can take tens of seconds with no download progress, and otherwise look frozen at 100%. pr"rrzcJ |dS#t$rYdSwxYwdSr)r)rrs r_phasezensure_binary.._phasesI   q       s   Nz!this invisible-core is sealed to z; it cannot install z. The prefs, the spoofed User-Agent and the protocol expectations in this package were generated for the sealed build, so pairing them with another engine would ship a browser whose claim contradicts itself. To drive a7 anyway, generate a seal for that build and point this package at it: python -m invisible_core seal --binary -o my.seal.json set INVISIBLE_SEAL_FILE=my.seal.json The User-Agent and the prefs then move with the seal, so the pair stays coherent. (A release of invisible-core sealed to z would also work, if one exists. It does not for tags that predate the seal, which is why the route above is given first: it works for any build you have on disk.)zthe active seal (a) is a LOCAL seal with no published assets, so there is nothing to download. Pass binary_path= pointing at the build this seal was generated from. (INVPW_BINARY_PATH is NOT read by this library - the test scripts and run_e2e.py translate it into binary_path=, so it only works under them. Corrected 2026-08-19; the same false promise was removed from invisible_playwright/_engine.py on 2026-08-14, and naming an env var the code never reads sends the reader hunting in the wrong function.)darwinaYmacOS is no longer a supported platform: no Mac binaries have been published since firefox-21, and this package downloads none. Seals from earlier releases still carry the macOS assets - they stay readable as history - but a new start on a Mac stops here instead of attempting a download that does not exist. Nothing changes on Windows or Linux.z3this platform is not one we publish an engine for: z. The declared legs are z, c3 K|] }d|zV dS)z%s/%sNr).0gs r z ensure_binary..Rs&CCqw{CCCCCCr. seal_digestz cache hit rr rZTr  downloading)rri verifyingzpayload mismatch for z under tag z : got z expected z (from the seal shipped inside invisible-core) The asset published under this tag is not the payload this core was sealed against: the tag was re-cut, or the download was corrupted. Refusing to use it. extractingz#binary not found after extraction: z1could not move the verified download into place: z from z to z The download is COMPLETE and its sha256 matches the seal, so it is kept where it is: move that directory onto the destination by hand, or re-run once whatever holds the destination has exited. Deleting it would cost another irkz MB for nothing.Frzfresh download )rr"rrz)1rr6rris_localr originrplatformr NotImplementedErrorrcr asset_formachiner:rrr1rrdigestrrrOrrWrrrrtempfileTemporaryDirectoryrrrHrrrr(rfrrrrrrsizer)r;rrr2rplatr@rrstampr url_archivetmp_dirtd archive_pathractual tmp_entryrs ` r ensure_binaryr; s  ;==Dw$(22 O  O O O O   O O7> O O O   $ } V U  U U UVV V N1P1PX]^^^^#D%==G$TXuz::Kll=TX== ===G M'....  $ & &("Bxx%*, } N ; x H H H H H! N N Ns|]D99S@@7%*7B D DEEJM N N {l++ <<>>U\//11 1 1' ''tx''$''#l'''  |w'''-(((((((((((((((0%/)I     N gT2222LLLMMM M+T2222 7K((((  <<>>  M' 6 6 6 6 6SASS!SS%SS ',jG&<R SSS  7 6 6 6 6( T%,X]^^^^ -Q{?O-Q-QY^ _ _ __sQ#L?6I L? J!AJJ!!BL??MM'N== P"APP"tuplec|p t} |tjtj}t ||jz }|sdSt||d|d| fS#t$r}d|j fcYd}~Sd}~wt$r}dt|fcYd}~Sd}~wwxYw)zB(ok, detail) for the sealed engine's cache. Never raises. For UIs.)Fznot downloadedz status checkrTFN)rr-rr+r.r:rrrrr rrr")r2r9r@rrs r engine_statusr>s  A CL(*:*<*<=="1%%7||~~ -,,eQ~UCCCCajjll## """ qy!!!!!!! s1vvs6AB0(B C#B1+C1 C>CCCc#Kt}|sdSt|D]}|r#|jdvs|jdr:d}ttj D]A}||z r( t||z }n#t$rd}YnwxYwnB||fVdS)zFYield (dir, identity_or_None) for every engine tree in the cache root.N>geoipr ) r1rsortedrrrOr]setrvaluesrr)rridentrels riter_cached_enginesrFs <C C C rOc>||kp||dzS)a^Does cache directory `name` hold the engine of release `tag`? Two layouts, one predicate: the legacy flat `` and the content-keyed `__`. The separator is REQUIRED, otherwise a bare startswith makes `firefox-180_...` a match for a seal on `firefox-18` and clear_cache deletes another release's engine. r5)r])rOr6s r_tree_belongs_to_tagrHs# 3; 4$//#)444rF) everythingrIc|rdn||ntj}g}tD]G\}}|st|j|r+t j|d||H|S)z=Remove engine trees only. Never the cache root, never geoip/.NTr )rr6rFrHrOrrr)r6rIwantrr_idents r clear_cacherMs R443?CC @QDG(** 6  -afd;;  M!4 0 0 0 0 NN1    Nr)ensure_geoip_mmdbgeoip_mmdb_path)rr)r!r"rr#)rrr)r2r3rr)r;rrr)r6r"r>r"rr")r6r"r>r"rPr"rr")rrh)ryr"rrz)rrrr)rrrr)rr"rr`) rPr"rrrr`rr`rrz)rN)rPr"rrrr`rrz)rrrr")rr"rr)rrrrrrz)r2r r@rrrrr)NN)rrrr )NNN)r;rr2r3rr)r2r3rr<)rOr"r6r"rr)r6rrIrrr )H__doc__ __future__rrrr+r&rrrr0rrpathlibrr.rrH constantsrrr2rr r r r r rrrrrrrr r+r1r:r=rWrarfrlrnrqDOWNLOAD_ATTEMPTSr frozensetrrsleeprrrrrRrrrrrrrr;r>rFrHrM _geoip_dbrNrOrrrrXs.II""""""     >======="WWWW"""" E E E EGGGGG"""""MMMMD!9999H6"@  9;;;<<  0000GGGG$ 5 5 5 5 4E#####L;BD#4;;;;;,/K/K/K/K/Kd     A A A A7777tDS`)-S`S`S`S`S`S`l(&5555eH:999999999r