| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286 |
- """Prenot@Mi plugin: one uploadable runtime file.
- Sections below were mechanically relocated from commit 62c2388.
- Maintain this file directly; tools/consolidate_ita_plugin.py is an audit
- of the initial move, not a build step. Shared host APIs remain shared.
- """
- from __future__ import annotations
- # ============================================================================
- # PROTOCOL (from plugins/ita_protocol.py)
- # ============================================================================
- """Pure Prenot@Mi protocol parsing and precommit validation.
- This module is the functional core of the Italy plugin. It deliberately owns
- no browser, network, session, OTP, or form-submission behavior. Callers pass
- already-captured, sanitized data in and receive immutable value objects back.
- """
- import json
- import html
- import re
- from dataclasses import dataclass, field
- from datetime import date, datetime, time as datetime_time
- from enum import Enum
- from typing import Any, Mapping, Sequence
- MAX_PROTOCOL_ITEMS = 512
- MAX_PROTOCOL_PAYLOAD_CHARS = 1_000_000
- MAX_LOOKAHEAD_MONTHS = 120
- _SITE_DATE_PATTERN = re.compile(r"^\d{2}/\d{2}/\d{4} 00:00:00$")
- PRENOTAMI_OTP_SENDER = "noreply-prenotami@esteri.it"
- _EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
- _OTP_CONTEXT_PATTERN = re.compile(
- r"(?<!\w)OTP\s+Code\s*:\s*([0-9]{6})(?!\w)",
- re.IGNORECASE,
- )
- class ItaProtocolError(ValueError):
- """Fail-closed protocol error with a stable, non-sensitive category."""
- def __init__(self, code: str, message: str, *, path: str = "") -> None:
- self.code = code
- self.path = path
- location = f" at {path}" if path else ""
- super().__init__(f"Italy protocol error [{code}]{location}: {message}")
- class ItaCapability(str, Enum):
- SERVICES_PROBE_ONLY = "services_probe_only"
- SINGLE_SCHENGEN_TOURISM = "single_schengen_tourism"
- class InventoryState(str, Enum):
- AVAILABLE = "available"
- UNAVAILABLE = "unavailable"
- @dataclass(frozen=True, slots=True)
- class CalendarScanConfig:
- lookahead_months: int
- @dataclass(frozen=True, slots=True)
- class FormControlConfig:
- control_id: str
- value: str
- labels: tuple[str, ...]
- @dataclass(frozen=True, slots=True)
- class OtpMailConfig:
- """Allowlisted cloud-mail query settings for one Italy route.
- The authorization mailbox is configured explicitly or derived per call
- from the current account, never cached on a shared route or included in
- diagnostic objects or log messages. The sender is
- fixed to Prenot@Mi's observed official address; a route may not widen the
- allowlist through configuration.
- """
- authorization_email: str | None = field(default=None, repr=False)
- subject_keywords: str = "OTP Code"
- body_keywords: str = "OTP Code:"
- expiry_seconds: int = 300
- authorization_source: str = "configured"
- def __post_init__(self) -> None:
- if self.authorization_source not in ("configured", "account"):
- raise ItaProtocolError(
- "otp_authorization_source_invalid",
- "authorization source must be configured or account",
- path="mail.authorization_source",
- )
- if self.authorization_source == "account":
- if self.authorization_email is not None:
- raise ItaProtocolError(
- "otp_authorization_source_conflict",
- "account source cannot also specify a fixed authorization mailbox",
- path="mail.authorization_email",
- )
- else:
- object.__setattr__(self, "authorization_email", self._require_mailbox(self.authorization_email))
- for field_name, expected in (("subject_keywords", "OTP Code"), ("body_keywords", "OTP Code:")):
- value = getattr(self, field_name)
- if not isinstance(value, str) or value.strip() != expected:
- raise ItaProtocolError(
- "otp_filter_invalid",
- "mail filters must match the observed Prenot@Mi OTP template",
- path=f"mail.{field_name}",
- )
- object.__setattr__(self, field_name, value.strip())
- if (
- not isinstance(self.expiry_seconds, int)
- or isinstance(self.expiry_seconds, bool)
- or not 1 <= self.expiry_seconds <= 300
- ):
- raise ItaProtocolError(
- "otp_expiry_invalid",
- "mail expiry must be an integer between 1 and 300 seconds",
- path="mail.expiry_seconds",
- )
- @staticmethod
- def _require_mailbox(value: Any) -> str:
- if not isinstance(value, str) or not _EMAIL_PATTERN.fullmatch(value.strip()):
- raise ItaProtocolError(
- "otp_authorization_email_invalid",
- "authorization mailbox must be a valid email address",
- path="mail.authorization_email",
- )
- return value.strip()
- def mailbox_for(self, account_email: str) -> str:
- """Bind per call; never mutate the route shared by pool instances.
- Account mode requires that each account's own inbox has an existing
- backend authorization. Configured mode preserves shared/forwarded
- inbox support; recipient filtering remains bound to the site account.
- """
- return self._require_mailbox(
- account_email if self.authorization_source == "account" else self.authorization_email
- )
- @dataclass(frozen=True, slots=True)
- class ItaRouteConfig:
- routing_key: str
- service_id: int
- capability: ItaCapability
- calendar_scan: CalendarScanConfig | None = None
- booking_type: FormControlConfig | None = None
- purpose: FormControlConfig | None = None
- mail: OtpMailConfig | None = None
- @dataclass(frozen=True, slots=True)
- class CalendarDay:
- day: date
- slots_free: int
- slots_remaining: int
- state: InventoryState
- def __post_init__(self) -> None:
- _require_date(self.day, "CalendarDay.day")
- slots_free = _require_int(self.slots_free, "CalendarDay.slots_free")
- slots_remaining = _require_int(
- self.slots_remaining,
- "CalendarDay.slots_remaining",
- )
- expected_state = _classify_inventory(
- slots_free,
- slots_remaining,
- path="CalendarDay",
- )
- if self.state is not expected_state:
- raise ItaProtocolError(
- "inventory_state_mismatch",
- "declared state differs from the slot counters",
- path="CalendarDay.state",
- )
- @property
- def is_available(self) -> bool:
- return self.state is InventoryState.AVAILABLE
- @dataclass(frozen=True, slots=True)
- class SlotCandidate:
- day: date
- start_time: datetime_time
- end_time: datetime_time
- slots_free: int
- slots_remaining: int
- state: InventoryState
- daily_calendar_id: str = field(repr=False)
- def __post_init__(self) -> None:
- _require_date(self.day, "SlotCandidate.day")
- start = _require_time(self.start_time, "SlotCandidate.start_time")
- end = _require_time(self.end_time, "SlotCandidate.end_time")
- if start >= end:
- raise ItaProtocolError(
- "time_range_invalid",
- "slot start time must be earlier than end time",
- path="SlotCandidate",
- )
- slots_free = _require_int(
- self.slots_free,
- "SlotCandidate.slots_free",
- )
- slots_remaining = _require_int(
- self.slots_remaining,
- "SlotCandidate.slots_remaining",
- )
- expected_state = _classify_inventory(
- slots_free,
- slots_remaining,
- path="SlotCandidate",
- )
- if self.state is not expected_state:
- raise ItaProtocolError(
- "inventory_state_mismatch",
- "declared state differs from the slot counters",
- path="SlotCandidate.state",
- )
- if (
- not isinstance(self.daily_calendar_id, str)
- or not self.daily_calendar_id.isdigit()
- or int(self.daily_calendar_id) <= 0
- ):
- raise ItaProtocolError(
- "daily_id_invalid",
- "runtime daily identifier must be a positive integer string",
- path="SlotCandidate.daily_calendar_id",
- )
- @property
- def is_available(self) -> bool:
- return self.state is InventoryState.AVAILABLE
- @property
- def time_label(self) -> str:
- return (
- f"{self.start_time.strftime('%H:%M')} - "
- f"{self.end_time.strftime('%H:%M')}"
- )
- @dataclass(frozen=True, slots=True)
- class DateSelectionState:
- planned_day: date
- matching_availability_count: int
- timeline_selected_days: tuple[date, ...]
- content_selected_days: tuple[date, ...]
- day_disabled: bool
- day_not_available: bool
- day_has_positive_state: bool
- def __post_init__(self) -> None:
- _require_date(self.planned_day, "DateSelectionState.planned_day")
- _require_nonnegative_int(
- self.matching_availability_count,
- "DateSelectionState.matching_availability_count",
- )
- _require_date_tuple(
- self.timeline_selected_days,
- "DateSelectionState.timeline_selected_days",
- )
- _require_date_tuple(
- self.content_selected_days,
- "DateSelectionState.content_selected_days",
- )
- for field_name in (
- "day_disabled",
- "day_not_available",
- "day_has_positive_state",
- ):
- _require_bool(
- getattr(self, field_name),
- f"DateSelectionState.{field_name}",
- )
- @dataclass(frozen=True, slots=True)
- class SlotSelectionState:
- active_slot_count: int
- active_is_candidate: bool
- active_has_unavailable_class: bool
- active_has_red_dot: bool
- active_hidden_input_count: int
- active_daily_id_matches_candidate: bool
- active_day_matches_candidate: bool
- active_time_matches_candidate: bool
- active_capacity_matches_candidate: bool
- def __post_init__(self) -> None:
- for field_name in (
- "active_slot_count",
- "active_hidden_input_count",
- ):
- _require_nonnegative_int(
- getattr(self, field_name),
- f"SlotSelectionState.{field_name}",
- )
- for field_name in (
- "active_is_candidate",
- "active_has_unavailable_class",
- "active_has_red_dot",
- "active_daily_id_matches_candidate",
- "active_day_matches_candidate",
- "active_time_matches_candidate",
- "active_capacity_matches_candidate",
- ):
- _require_bool(
- getattr(self, field_name),
- f"SlotSelectionState.{field_name}",
- )
- @dataclass(frozen=True, slots=True)
- class PrecommitApproval:
- """Immutable value returned by :func:`approve_precommit`."""
- calendar_day: CalendarDay
- candidate: SlotCandidate
- def resolve_route_config(
- apt_configs: Mapping[str, Any],
- routing_key: str,
- ) -> ItaRouteConfig:
- """Resolve one VFS/BLS-style ``apt_configs[routing_key]`` entry."""
- configs = _require_mapping(apt_configs, "apt_configs")
- key = _require_nonempty_string(routing_key, "routing_key")
- if key not in configs:
- raise ItaProtocolError(
- "route_missing",
- "no route is configured for the requested routing key",
- path="apt_configs",
- )
- raw_route = _require_mapping(configs[key], f"apt_configs.{key}")
- service_id = _require_positive_int(
- raw_route.get("service_id"),
- f"apt_configs.{key}.service_id",
- )
- raw_capability = _require_nonempty_string(
- raw_route.get("capability"),
- f"apt_configs.{key}.capability",
- )
- try:
- capability = ItaCapability(raw_capability)
- except ValueError as exc:
- raise ItaProtocolError(
- "capability_unsupported",
- "route capability is not supported",
- path=f"apt_configs.{key}.capability",
- ) from exc
- if capability is ItaCapability.SERVICES_PROBE_ONLY:
- return ItaRouteConfig(
- routing_key=key,
- service_id=service_id,
- capability=capability,
- )
- calendar_scan_raw = _require_mapping(
- raw_route.get("calendar_scan"),
- f"apt_configs.{key}.calendar_scan",
- )
- calendar_scan = CalendarScanConfig(
- lookahead_months=_require_lookahead_months(
- calendar_scan_raw.get("lookahead_months"),
- f"apt_configs.{key}.calendar_scan.lookahead_months",
- )
- )
- form_raw = _require_mapping(
- raw_route.get("form"),
- f"apt_configs.{key}.form",
- )
- booking_type = _parse_form_control(
- form_raw,
- prefix="booking_type",
- path=f"apt_configs.{key}.form",
- )
- purpose = _parse_form_control(
- form_raw,
- prefix="purpose",
- path=f"apt_configs.{key}.form",
- )
- mail = _parse_mail_config(
- raw_route.get("mail"),
- path=f"apt_configs.{key}.mail",
- )
- return ItaRouteConfig(
- routing_key=key,
- service_id=service_id,
- capability=capability,
- calendar_scan=calendar_scan,
- booking_type=booking_type,
- purpose=purpose,
- mail=mail,
- )
- def decode_double_json_array(
- payload: str,
- *,
- max_items: int = MAX_PROTOCOL_ITEMS,
- ) -> tuple[Mapping[str, Any], ...]:
- """Strictly decode the JSON-string-containing-a-JSON-array wire shape."""
- if not isinstance(payload, str) or not payload:
- raise ItaProtocolError(
- "payload_type",
- "payload must be a non-empty JSON string",
- )
- if len(payload) > MAX_PROTOCOL_PAYLOAD_CHARS:
- raise ItaProtocolError(
- "payload_too_large",
- "payload exceeds the local parsing limit",
- )
- if not _is_positive_int(max_items):
- raise ItaProtocolError(
- "max_items_invalid",
- "max_items must be a positive integer",
- )
- try:
- outer = json.loads(payload)
- except (TypeError, json.JSONDecodeError) as exc:
- raise ItaProtocolError(
- "outer_json_invalid",
- "outer JSON cannot be decoded",
- ) from exc
- if not isinstance(outer, str):
- raise ItaProtocolError(
- "payload_layer_count",
- "payload must contain exactly two JSON layers",
- )
- if len(outer) > MAX_PROTOCOL_PAYLOAD_CHARS:
- raise ItaProtocolError(
- "payload_too_large",
- "inner payload exceeds the local parsing limit",
- )
- try:
- items = json.loads(outer)
- except (TypeError, json.JSONDecodeError) as exc:
- raise ItaProtocolError(
- "inner_json_invalid",
- "inner JSON cannot be decoded",
- ) from exc
- if not isinstance(items, list):
- raise ItaProtocolError(
- "payload_layer_count",
- "inner JSON must be an array",
- )
- if len(items) > max_items:
- raise ItaProtocolError(
- "item_limit_exceeded",
- "response contains more items than the configured parsing limit",
- )
- result: list[Mapping[str, Any]] = []
- for index, item in enumerate(items):
- if not isinstance(item, Mapping):
- raise ItaProtocolError(
- "item_type",
- "every response item must be an object",
- path=f"items[{index}]",
- )
- result.append(item)
- return tuple(result)
- def parse_calendar_availability(
- payload: str,
- *,
- max_items: int = MAX_PROTOCOL_ITEMS,
- ) -> tuple[CalendarDay, ...]:
- """Parse and classify calendar-day capacity without guessing conflicts."""
- items = decode_double_json_array(payload, max_items=max_items)
- days: list[CalendarDay] = []
- seen_days: set[date] = set()
- for index, item in enumerate(items):
- path = f"availability[{index}]"
- parsed_day = _parse_site_date(
- _require_key(item, "DateLibere", path),
- f"{path}.DateLibere",
- )
- if parsed_day in seen_days:
- raise ItaProtocolError(
- "duplicate_calendar_day",
- "calendar response contains a duplicate date",
- path=path,
- )
- seen_days.add(parsed_day)
- slots_free = _require_int(
- _require_key(item, "SlotLiberi", path),
- f"{path}.SlotLiberi",
- )
- slots_remaining = _require_int(
- _require_key(item, "SlotRimanenti", path),
- f"{path}.SlotRimanenti",
- )
- state = _classify_inventory(
- slots_free,
- slots_remaining,
- path=path,
- )
- days.append(
- CalendarDay(
- day=parsed_day,
- slots_free=slots_free,
- slots_remaining=slots_remaining,
- state=state,
- )
- )
- return tuple(sorted(days, key=lambda item: item.day))
- def parse_time_slots(
- payload: str,
- *,
- max_items: int = MAX_PROTOCOL_ITEMS,
- ) -> tuple[SlotCandidate, ...]:
- """Parse TimeSlots items while keeping the runtime ID memory-only."""
- items = decode_double_json_array(payload, max_items=max_items)
- candidates: list[SlotCandidate] = []
- seen_ranges: set[tuple[date, datetime_time, datetime_time]] = set()
- seen_daily_ids: set[str] = set()
- for index, item in enumerate(items):
- path = f"time_slots[{index}]"
- parsed_day = _parse_site_date(
- _require_key(item, "Data", path),
- f"{path}.Data",
- )
- start_time = _parse_site_time(
- _require_key(item, "OrarioInizioFascia", path),
- f"{path}.OrarioInizioFascia",
- )
- end_time = _parse_site_time(
- _require_key(item, "OrarioFineFascia", path),
- f"{path}.OrarioFineFascia",
- )
- if start_time >= end_time:
- raise ItaProtocolError(
- "time_range_invalid",
- "slot start time must be earlier than end time",
- path=path,
- )
- slots_free = _require_int(
- _require_key(item, "SlotLiberi", path),
- f"{path}.SlotLiberi",
- )
- slots_remaining = _require_int(
- _require_key(item, "SlotRimanenti", path),
- f"{path}.SlotRimanenti",
- )
- state = _classify_inventory(
- slots_free,
- slots_remaining,
- path=path,
- )
- daily_id = str(
- _require_positive_int(
- _require_key(item, "IDCalendarioServizioGiornaliero", path),
- f"{path}.IDCalendarioServizioGiornaliero",
- )
- )
- time_range = (parsed_day, start_time, end_time)
- if time_range in seen_ranges:
- raise ItaProtocolError(
- "duplicate_time_range",
- "time-slot response contains a duplicate time range",
- path=path,
- )
- if daily_id in seen_daily_ids:
- raise ItaProtocolError(
- "duplicate_daily_id",
- "time-slot response reuses a runtime daily identifier",
- path=path,
- )
- seen_ranges.add(time_range)
- seen_daily_ids.add(daily_id)
- candidates.append(
- SlotCandidate(
- day=parsed_day,
- start_time=start_time,
- end_time=end_time,
- slots_free=slots_free,
- slots_remaining=slots_remaining,
- state=state,
- daily_calendar_id=daily_id,
- )
- )
- return tuple(
- sorted(
- candidates,
- key=lambda item: (item.day, item.start_time, item.end_time),
- )
- )
- def available_calendar_days(
- days: Sequence[CalendarDay],
- *,
- start_day: date | None = None,
- end_day: date | None = None,
- ) -> tuple[CalendarDay, ...]:
- """Return positive days in an inclusive date range, sorted ascending."""
- start, end = _validate_date_range(start_day, end_day)
- seen: set[date] = set()
- selected: list[CalendarDay] = []
- for index, item in enumerate(days):
- if not isinstance(item, CalendarDay):
- raise ItaProtocolError(
- "calendar_day_type",
- "days must contain CalendarDay values",
- path=f"days[{index}]",
- )
- if item.day in seen:
- raise ItaProtocolError(
- "duplicate_calendar_day",
- "days contain a duplicate date",
- path=f"days[{index}]",
- )
- seen.add(item.day)
- if item.is_available and _date_in_range(item.day, start, end):
- selected.append(item)
- return tuple(sorted(selected, key=lambda item: item.day))
- def available_slot_candidates(
- candidates: Sequence[SlotCandidate],
- *,
- start_day: date | None = None,
- end_day: date | None = None,
- ) -> tuple[SlotCandidate, ...]:
- """Filter and deterministically order positive Book-side candidates."""
- start, end = _validate_date_range(start_day, end_day)
- seen_ranges: set[tuple[date, datetime_time, datetime_time]] = set()
- selected: list[SlotCandidate] = []
- for index, item in enumerate(candidates):
- if not isinstance(item, SlotCandidate):
- raise ItaProtocolError(
- "slot_candidate_type",
- "candidates must contain SlotCandidate values",
- path=f"candidates[{index}]",
- )
- identity = (item.day, item.start_time, item.end_time)
- if identity in seen_ranges:
- raise ItaProtocolError(
- "duplicate_time_range",
- "candidates contain a duplicate time range",
- path=f"candidates[{index}]",
- )
- seen_ranges.add(identity)
- if item.is_available and _date_in_range(item.day, start, end):
- selected.append(item)
- return tuple(
- sorted(
- selected,
- key=lambda item: (
- item.day,
- -item.slots_free,
- item.start_time,
- item.end_time,
- ),
- )
- )
- def parse_otp_body(
- body: str,
- *,
- max_chars: int = MAX_PROTOCOL_PAYLOAD_CHARS,
- ) -> str:
- """Extract exactly one Prenot@Mi OTP from a cloud-mail body.
- The cloud endpoint returns a body-only string and may include both the
- plain-text and HTML MIME alternatives. HTML tags are replaced with
- spaces, then only the observed ``OTP Code:`` marker followed by six ASCII
- digits is accepted. Repeated identical matches (plain + HTML) are fine;
- different candidates fail closed. No caller should log ``body`` or the
- returned code.
- """
- if not isinstance(body, str) or not body.strip():
- raise ItaProtocolError(
- "otp_body_invalid",
- "OTP mail body must be a non-empty string",
- path="mail.body",
- )
- if not isinstance(max_chars, int) or isinstance(max_chars, bool) or max_chars <= 0:
- raise ItaProtocolError(
- "otp_body_limit_invalid",
- "OTP body limit must be a positive integer",
- path="mail.max_chars",
- )
- if len(body) > max_chars:
- raise ItaProtocolError(
- "otp_body_too_large",
- "OTP mail body exceeds the local parsing limit",
- path="mail.body",
- )
- # The existing cloud service can concatenate text/plain and text/html.
- # Projecting HTML to text avoids depending on a browser or executing any
- # markup while preserving the marker when tags surround the code.
- projected = html.unescape(re.sub(r"<[^>]{0,4096}>", " ", body))
- projected = re.sub(r"\s+", " ", projected).strip()
- matches = _OTP_CONTEXT_PATTERN.findall(projected)
- unique = tuple(dict.fromkeys(matches))
- if not unique:
- raise ItaProtocolError(
- "otp_not_found",
- "mail body did not contain the expected OTP marker",
- path="mail.body",
- )
- if len(unique) != 1:
- raise ItaProtocolError(
- "otp_ambiguous",
- "mail body contained multiple different OTP candidates",
- path="mail.body",
- )
- return unique[0]
- def month_starts(anchor_day: date, lookahead_months: int) -> tuple[date, ...]:
- """Return deterministic month starts for the configured scan window."""
- anchor = _require_date(anchor_day, "anchor_day")
- months = _require_lookahead_months(lookahead_months, "lookahead_months")
- result: list[date] = []
- year = anchor.year
- month = anchor.month
- for _ in range(months):
- result.append(date(year, month, 1))
- month += 1
- if month == 13:
- year += 1
- month = 1
- return tuple(result)
- def approve_precommit(
- calendar_day: CalendarDay,
- candidate: SlotCandidate,
- date_state: DateSelectionState,
- slot_state: SlotSelectionState,
- ) -> PrecommitApproval:
- """Approve final-button readiness only when every observed invariant holds."""
- if not isinstance(calendar_day, CalendarDay):
- raise ItaProtocolError(
- "precommit_type",
- "calendar_day must be a CalendarDay",
- )
- if not isinstance(candidate, SlotCandidate):
- raise ItaProtocolError(
- "precommit_type",
- "candidate must be a SlotCandidate",
- )
- if not isinstance(date_state, DateSelectionState):
- raise ItaProtocolError(
- "precommit_type",
- "date_state must be a DateSelectionState",
- )
- if not isinstance(slot_state, SlotSelectionState):
- raise ItaProtocolError(
- "precommit_type",
- "slot_state must be a SlotSelectionState",
- )
- checks = (
- (calendar_day.is_available, "calendar day is not positively available"),
- (candidate.is_available, "slot candidate is not positively available"),
- (calendar_day.day == candidate.day, "calendar and slot dates differ"),
- (
- date_state.planned_day == candidate.day,
- "selected date differs from the planned date",
- ),
- (
- date_state.matching_availability_count == 1,
- "planned date must map to exactly one availability item",
- ),
- (
- date_state.timeline_selected_days == (candidate.day,),
- "timeline must have exactly one matching selected date",
- ),
- (
- date_state.content_selected_days == (candidate.day,),
- "content must have exactly one matching selected date",
- ),
- (not date_state.day_disabled, "selected date is disabled"),
- (
- not date_state.day_not_available,
- "selected date has a negative availability marker",
- ),
- (
- date_state.day_has_positive_state,
- "selected date lacks the verified positive state",
- ),
- (
- slot_state.active_slot_count == 1,
- "there must be exactly one active slot",
- ),
- (
- slot_state.active_is_candidate,
- "active slot is not the approved candidate",
- ),
- (
- not slot_state.active_has_unavailable_class,
- "active slot has an unavailable class",
- ),
- (
- not slot_state.active_has_red_dot,
- "active slot has a negative red marker",
- ),
- (
- slot_state.active_hidden_input_count == 1,
- "active slot must contain exactly one runtime identifier input",
- ),
- (
- slot_state.active_daily_id_matches_candidate,
- "active slot runtime identifier differs from the candidate",
- ),
- (
- slot_state.active_day_matches_candidate,
- "active slot date differs from the candidate",
- ),
- (
- slot_state.active_time_matches_candidate,
- "active slot time differs from the candidate",
- ),
- (
- slot_state.active_capacity_matches_candidate,
- "active slot capacity differs from the candidate",
- ),
- )
- for passed, message in checks:
- if not passed:
- raise ItaProtocolError("precommit_rejected", message)
- return PrecommitApproval(calendar_day=calendar_day, candidate=candidate)
- def _parse_form_control(
- form: Mapping[str, Any],
- *,
- prefix: str,
- path: str,
- ) -> FormControlConfig:
- return FormControlConfig(
- control_id=_require_nonempty_string(
- form.get(f"{prefix}_control_id"),
- f"{path}.{prefix}_control_id",
- ),
- value=_require_nonempty_string(
- form.get(f"{prefix}_value"),
- f"{path}.{prefix}_value",
- ),
- labels=_require_string_tuple(
- form.get(f"{prefix}_labels"),
- f"{path}.{prefix}_labels",
- ),
- )
- def _parse_mail_config(
- raw_mail: Any,
- *,
- path: str,
- ) -> OtpMailConfig | None:
- if raw_mail is None:
- return None
- mail = _require_mapping(raw_mail, path)
- sender = mail.get("sender", PRENOTAMI_OTP_SENDER)
- if not isinstance(sender, str) or sender.strip().casefold() != PRENOTAMI_OTP_SENDER:
- raise ItaProtocolError(
- "otp_sender_not_allowlisted",
- "mail sender must match Prenot@Mi's official OTP address",
- path=f"{path}.sender",
- )
- return OtpMailConfig(
- authorization_email=mail.get("authorization_email"),
- subject_keywords=mail.get("subject_keywords", "OTP Code"),
- body_keywords=mail.get("body_keywords", "OTP Code:"),
- expiry_seconds=mail.get("expiry_seconds", 300),
- authorization_source=mail.get("authorization_source", "configured"),
- )
- def _classify_inventory(
- slots_free: int,
- slots_remaining: int,
- *,
- path: str,
- ) -> InventoryState:
- if slots_free > 0 and slots_remaining >= 0:
- return InventoryState.AVAILABLE
- if slots_free == 0 and slots_remaining < 0:
- return InventoryState.UNAVAILABLE
- raise ItaProtocolError(
- "inventory_conflict",
- "slot counters do not match an observed allowlisted state",
- path=path,
- )
- def _parse_site_date(value: Any, path: str) -> date:
- if not isinstance(value, str) or not _SITE_DATE_PATTERN.fullmatch(value):
- raise ItaProtocolError(
- "date_format",
- "date must match DD/MM/YYYY 00:00:00",
- path=path,
- )
- try:
- return datetime.strptime(value, "%d/%m/%Y %H:%M:%S").date()
- except ValueError as exc:
- raise ItaProtocolError(
- "date_invalid",
- "date is not a real calendar date",
- path=path,
- ) from exc
- def _parse_site_time(value: Any, path: str) -> datetime_time:
- mapping = _require_mapping(value, path)
- hours = _require_int(_require_key(mapping, "Hours", path), f"{path}.Hours")
- minutes = _require_int(
- _require_key(mapping, "Minutes", path),
- f"{path}.Minutes",
- )
- seconds = _require_int(mapping.get("Seconds", 0), f"{path}.Seconds")
- milliseconds = _require_int(
- mapping.get("Milliseconds", 0),
- f"{path}.Milliseconds",
- )
- if seconds != 0 or milliseconds != 0:
- raise ItaProtocolError(
- "time_precision",
- "sub-minute slot precision is not supported by the observed protocol",
- path=path,
- )
- try:
- return datetime_time(hour=hours, minute=minutes)
- except ValueError as exc:
- raise ItaProtocolError(
- "time_invalid",
- "slot time is outside the 24-hour clock",
- path=path,
- ) from exc
- def _validate_date_range(
- start_day: date | None,
- end_day: date | None,
- ) -> tuple[date | None, date | None]:
- start = _require_date(start_day, "start_day") if start_day is not None else None
- end = _require_date(end_day, "end_day") if end_day is not None else None
- if start is not None and end is not None and start > end:
- raise ItaProtocolError(
- "date_range_invalid",
- "start_day must not be later than end_day",
- )
- return start, end
- def _date_in_range(
- value: date,
- start_day: date | None,
- end_day: date | None,
- ) -> bool:
- return (
- (start_day is None or value >= start_day)
- and (end_day is None or value <= end_day)
- )
- def _require_mapping(value: Any, path: str) -> Mapping[str, Any]:
- if not isinstance(value, Mapping):
- raise ItaProtocolError(
- "mapping_required",
- "value must be an object",
- path=path,
- )
- return value
- def _require_key(mapping: Mapping[str, Any], key: str, path: str) -> Any:
- if key not in mapping:
- raise ItaProtocolError(
- "field_missing",
- "required field is missing",
- path=f"{path}.{key}",
- )
- return mapping[key]
- def _require_nonempty_string(value: Any, path: str) -> str:
- if not isinstance(value, str) or not value.strip():
- raise ItaProtocolError(
- "string_required",
- "value must be a non-empty string",
- path=path,
- )
- return value.strip()
- def _require_string_tuple(value: Any, path: str) -> tuple[str, ...]:
- if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
- raise ItaProtocolError(
- "labels_required",
- "labels must be a non-empty array of strings",
- path=path,
- )
- labels = tuple(
- _require_nonempty_string(item, f"{path}[{index}]")
- for index, item in enumerate(value)
- )
- if not labels:
- raise ItaProtocolError(
- "labels_required",
- "labels must be a non-empty array of strings",
- path=path,
- )
- if len(set(labels)) != len(labels):
- raise ItaProtocolError(
- "labels_duplicate",
- "labels must not contain duplicates",
- path=path,
- )
- return labels
- def _is_positive_int(value: Any) -> bool:
- return isinstance(value, int) and not isinstance(value, bool) and value > 0
- def _require_positive_int(value: Any, path: str) -> int:
- if not _is_positive_int(value):
- raise ItaProtocolError(
- "positive_integer_required",
- "value must be a positive integer",
- path=path,
- )
- return value
- def _require_int(value: Any, path: str) -> int:
- if not isinstance(value, int) or isinstance(value, bool):
- raise ItaProtocolError(
- "integer_required",
- "value must be an integer",
- path=path,
- )
- return value
- def _require_nonnegative_int(value: Any, path: str) -> int:
- number = _require_int(value, path)
- if number < 0:
- raise ItaProtocolError(
- "nonnegative_integer_required",
- "value must be a non-negative integer",
- path=path,
- )
- return number
- def _require_bool(value: Any, path: str) -> bool:
- if not isinstance(value, bool):
- raise ItaProtocolError(
- "boolean_required",
- "value must be a boolean",
- path=path,
- )
- return value
- def _require_lookahead_months(value: Any, path: str) -> int:
- months = _require_positive_int(value, path)
- if months > MAX_LOOKAHEAD_MONTHS:
- raise ItaProtocolError(
- "lookahead_too_large",
- "lookahead exceeds the local scan safety limit",
- path=path,
- )
- return months
- def _require_date(value: Any, path: str) -> date:
- if not isinstance(value, date) or isinstance(value, datetime):
- raise ItaProtocolError(
- "date_required",
- "value must be a date",
- path=path,
- )
- return value
- def _require_date_tuple(value: Any, path: str) -> tuple[date, ...]:
- if not isinstance(value, tuple):
- raise ItaProtocolError(
- "date_tuple_required",
- "value must be a tuple of dates",
- path=path,
- )
- for index, item in enumerate(value):
- _require_date(item, f"{path}[{index}]")
- return value
- def _require_time(value: Any, path: str) -> datetime_time:
- if not isinstance(value, datetime_time):
- raise ItaProtocolError(
- "time_required",
- "value must be a time",
- path=path,
- )
- if value.second != 0 or value.microsecond != 0:
- raise ItaProtocolError(
- "time_precision",
- "slot time must use minute precision",
- path=path,
- )
- return value
- # ============================================================================
- # CALENDAR_QUERY (from plugins/ita_calendar_query.py)
- # ============================================================================
- """Shared browser adapter for read-only Prenot@Mi Calendar queries.
- The pure wire-format rules live in :mod:`plugins.ita_protocol`. This module
- owns only the browser-facing mechanics that production Query and the Q-CAL
- diagnostic tool must share: one-shot listeners, strict packet metadata,
- native month navigation, the final-button guard, and bounded scanning.
- """
- import json
- import time
- from dataclasses import dataclass
- from datetime import date, datetime
- from typing import Any, Callable
- from urllib.parse import urljoin, urlparse
- CALENDAR_PATH = "/BookingCalendar"
- AVAILABILITY_PATH = "/BookingCalendar/RetrieveCalendarAvailability"
- MAX_QUERY_LOOKAHEAD_MONTHS = 120
- DEFAULT_MONTH_CLICK_INTERVAL_SECONDS = 1.5
- CALENDAR_GUARD_SCRIPT = r"""
- /* coordinate:ita-calendar-query-final-guard */
- const finalButtons = Array.from(
- document.querySelectorAll('#btnPrenotaNoOtp')
- );
- finalButtons.forEach((button) => {
- button.disabled = true;
- button.setAttribute('aria-disabled', 'true');
- button.dataset.coordinateFinalGuard = 'enabled';
- });
- const resources = performance.getEntriesByType('resource');
- return {
- path: window.location.pathname,
- calendarFunctionPresent:
- typeof window.CaricaTimelineOrizzontale === 'function',
- finalButtonCount: finalButtons.length,
- allFinalButtonsGuarded: finalButtons.every(
- (button) => button.disabled &&
- button.dataset.coordinateFinalGuard === 'enabled'
- ),
- finalRequestCount: resources.filter(
- (entry) => entry.name.includes(
- '/BookingCalendar/InsertNewBooking'
- )
- ).length,
- timeSlotRequestCount: resources.filter(
- (entry) => entry.name.includes(
- '/BookingCalendar/RetrieveTimeSlots'
- )
- ).length,
- };
- """
- NEXT_MONTH_CONTROL_SCRIPT = r"""
- /* coordinate:ita-calendar-query-next-month */
- const shouldClick = arguments[0] === true;
- const selector = '#datetimepicker th.dtpicker-next';
- const candidates = Array.from(document.querySelectorAll(selector));
- const isActionable = (element) => {
- if (
- !element.isConnected ||
- element.hasAttribute('disabled') ||
- element.getAttribute('aria-disabled') === 'true'
- ) {
- return false;
- }
- const style = window.getComputedStyle(element);
- if (
- style.display === 'none' ||
- style.visibility === 'hidden' ||
- style.pointerEvents === 'none' ||
- Number.parseFloat(style.opacity || '1') <= 0
- ) {
- return false;
- }
- const rect = element.getBoundingClientRect();
- const left = Math.max(0, rect.left);
- const right = Math.min(window.innerWidth, rect.right);
- const top = Math.max(0, rect.top);
- const bottom = Math.min(window.innerHeight, rect.bottom);
- if (right <= left || bottom <= top) return false;
- const topNode = document.elementFromPoint(
- (left + right) / 2,
- (top + bottom) / 2
- );
- return Boolean(topNode && (
- topNode === element || element.contains(topNode)
- ));
- };
- const actionable = candidates.filter(isActionable);
- let clicked = false;
- if (shouldClick && actionable.length === 1) {
- clicked = true;
- actionable[0].click();
- }
- return {
- pathMatches: window.location.pathname === '/BookingCalendar',
- candidateCount: candidates.length,
- actionableCount: actionable.length,
- clicked,
- };
- """
- class CalendarGateError(RuntimeError):
- """Fail-closed Calendar adapter error without sensitive response data."""
- class CalendarAuthenticationExpiredError(CalendarGateError):
- """An observed response explicitly rejected the authenticated session."""
- class CalendarRateLimitedError(CalendarGateError):
- """The server explicitly limited requests; callers must not rotate accounts."""
- class CalendarAccessDeniedError(CalendarGateError):
- """Permission or browser verification requires operator attention."""
- class CalendarTransientError(CalendarGateError):
- """A read failed without evidence that authentication or schema changed."""
- class CalendarNextMonthUnavailableError(CalendarGateError):
- """Raised when the native next-month control cannot be used safely."""
- def require_plain_nonnegative_int(value: object, name: str) -> int:
- if isinstance(value, bool) or not isinstance(value, int) or value < 0:
- raise CalendarGateError(f"{name} must be a nonnegative integer")
- return value
- def same_origin_path(raw_url: object) -> tuple[str, object]:
- parsed = urlparse(str(raw_url or ""))
- try:
- port = parsed.port
- except ValueError as exc:
- raise CalendarGateError(
- "Observed request used an unexpected origin"
- ) from exc
- if (
- parsed.scheme != "https"
- or parsed.hostname != "prenotami.esteri.it"
- or port not in (None, 443)
- or parsed.username is not None
- or parsed.password is not None
- ):
- raise CalendarGateError("Observed request used an unexpected origin")
- return parsed.path, parsed
- def header_value(headers: object, name: str) -> str:
- if not hasattr(headers, "items"):
- return ""
- for key, value in headers.items():
- if str(key).casefold() == name.casefold():
- return str(value)
- return ""
- @dataclass(frozen=True, slots=True)
- class CalendarProbeResult:
- days: tuple[CalendarDay, ...]
- selected_day: str
- def __post_init__(self) -> None:
- if not isinstance(self.selected_day, str) or not self.selected_day.strip():
- raise CalendarGateError("selected_day must be a non-empty string")
- if any(not isinstance(item, CalendarDay) for item in self.days):
- raise CalendarGateError("days must contain CalendarDay values")
- selected_month = self.selected_month
- if any(
- (item.day.year, item.day.month) != selected_month
- for item in self.days
- ):
- raise CalendarGateError(
- "Availability response escaped the requested month"
- )
- @property
- def item_count(self) -> int:
- return len(self.days)
- @property
- def available_days(self) -> tuple[CalendarDay, ...]:
- return available_calendar_days(self.days)
- @property
- def available_count(self) -> int:
- return len(self.available_days)
- @property
- def selected_month(self) -> tuple[int, int]:
- value = self.selected_day.strip()[:10]
- for date_format in ("%Y-%m-%d", "%d/%m/%Y"):
- try:
- parsed = datetime.strptime(value, date_format)
- except ValueError:
- continue
- return parsed.year, parsed.month
- raise CalendarGateError(
- "Availability selectedDay used an unknown date format"
- )
- def next_month_value(value: tuple[int, int]) -> tuple[int, int]:
- year, month = value
- return (year + 1, 1) if month == 12 else (year, month + 1)
- def month_text(value: tuple[int, int]) -> str:
- return f"{value[0]:04d}-{value[1]:02d}"
- @dataclass(frozen=True, slots=True)
- class CalendarQueryScanResult:
- """Result of scanning until the first positive month or the horizon end."""
- probes: tuple[CalendarProbeResult, ...]
- lookahead_months: int
- stop_reason: str
- def __post_init__(self) -> None:
- _validate_lookahead_months(self.lookahead_months)
- if not self.probes or any(
- not isinstance(probe, CalendarProbeResult)
- for probe in self.probes
- ):
- raise CalendarGateError(
- "Calendar query scan requires parsed probe results"
- )
- if len(self.probes) > self.lookahead_months:
- raise CalendarGateError(
- "Calendar query scan exceeded the configured horizon"
- )
- for previous, current in zip(self.probes, self.probes[1:]):
- if current.selected_month != next_month_value(
- previous.selected_month
- ):
- raise CalendarGateError(
- "Calendar request did not advance exactly one month"
- )
- if self.stop_reason == "first_available_month":
- if self.probes[-1].available_count == 0:
- raise CalendarGateError(
- "first-available stop requires a positive final probe"
- )
- if any(probe.available_count for probe in self.probes[:-1]):
- raise CalendarGateError(
- "Calendar query scanned beyond the first positive month"
- )
- elif self.stop_reason == "horizon_exhausted":
- if len(self.probes) != self.lookahead_months:
- raise CalendarGateError(
- "Calendar query ended before the configured horizon"
- )
- if any(probe.available_count for probe in self.probes):
- raise CalendarGateError(
- "Calendar query ignored a positive month"
- )
- else:
- raise CalendarGateError(
- "Calendar query scan used an unknown stop reason"
- )
- @property
- def scanned_months(self) -> int:
- return len(self.probes)
- @property
- def available_days(self) -> tuple[CalendarDay, ...]:
- if self.stop_reason != "first_available_month":
- return ()
- return self.probes[-1].available_days
- @property
- def earliest_available_date(self) -> date | None:
- return (
- self.available_days[0].day
- if self.available_days
- else None
- )
- def _validate_lookahead_months(value: object) -> int:
- if (
- isinstance(value, bool)
- or not isinstance(value, int)
- or not 1 <= value <= MAX_QUERY_LOOKAHEAD_MONTHS
- ):
- raise CalendarGateError(
- "lookahead_months must be between 1 and 120"
- )
- return value
- def listen_once(
- page: object,
- *,
- target: str,
- method: str,
- action: Callable[[], Any],
- timeout: float,
- ) -> object:
- """Listen around one native action and always stop the listener."""
- page.listen.start(target, method=method)
- try:
- action()
- packet = page.listen.wait(timeout=timeout)
- if not packet:
- raise CalendarTransientError(
- f"Expected {method} {target} was not observed"
- )
- return packet
- finally:
- page.listen.stop()
- def parse_availability_packet(packet: object) -> CalendarProbeResult:
- path, _ = same_origin_path(packet.url)
- if str(packet.method).upper() != "POST" or path != AVAILABILITY_PATH:
- raise CalendarGateError("Availability request method or path changed")
- response = packet.response
- status = response.status
- if type(status) is not int:
- raise CalendarGateError("Availability HTTP status was not an integer")
- if status in {301, 302, 303, 307, 308}:
- location = header_value(getattr(response, "headers", None), "Location")
- destination = urlparse(urljoin(packet.url, location))
- if location and destination.scheme == "https" and destination.hostname == "iam.esteri.it":
- raise CalendarAuthenticationExpiredError("Calendar response redirected to IAM")
- response_url = getattr(response, "url", None)
- if isinstance(response_url, str) and response_url:
- destination = urlparse(response_url)
- if destination.scheme == "https" and destination.hostname == "iam.esteri.it":
- raise CalendarAuthenticationExpiredError("Calendar response returned to IAM")
- response_path, _ = same_origin_path(response_url)
- if response_path != AVAILABILITY_PATH:
- raise CalendarGateError("Availability response reached an unexpected path")
- if status == 401:
- raise CalendarAuthenticationExpiredError("Calendar authentication expired")
- if status == 429:
- raise CalendarRateLimitedError("Calendar request was rate limited")
- if status == 403:
- raise CalendarAccessDeniedError("Calendar access requires operator attention")
- if status in {0, 408, 502, 503, 504}:
- raise CalendarTransientError("Calendar request temporarily failed")
- if status != 200:
- raise CalendarGateError("Availability response status was not 200")
- post_data = packet.request.postData
- if isinstance(post_data, str):
- try:
- post_data = json.loads(post_data)
- except json.JSONDecodeError as exc:
- raise CalendarGateError(
- "Availability request body was not JSON"
- ) from exc
- if not isinstance(post_data, dict) or set(post_data) != {
- "_Servizio",
- "selectedDay",
- }:
- raise CalendarGateError("Availability request keys changed")
- if isinstance(post_data["_Servizio"], bool) or not str(
- post_data["_Servizio"]
- ).strip():
- raise CalendarGateError("Availability runtime service id was empty")
- if (
- not isinstance(post_data["selectedDay"], str)
- or not post_data["selectedDay"].strip()
- ):
- raise CalendarGateError("Availability selectedDay was empty")
- try:
- days = parse_calendar_availability(packet.response.raw_body)
- except ItaProtocolError as exc:
- raise CalendarGateError(
- f"Availability response rejected ({exc.code})"
- ) from exc
- return CalendarProbeResult(
- days=days,
- selected_day=post_data["selectedDay"],
- )
- def validate_next_month_snapshot(
- raw: object,
- *,
- expected_clicked: bool,
- allow_unready: bool = False,
- ) -> dict[str, object]:
- """Require the exact, non-sensitive Calendar month-control shape."""
- if not isinstance(raw, dict):
- raise CalendarGateError(
- "Calendar next-month control did not return an object"
- )
- expected_keys = {
- "pathMatches",
- "candidateCount",
- "actionableCount",
- "clicked",
- }
- if set(raw) != expected_keys:
- raise CalendarGateError(
- "Calendar next-month control returned unexpected fields"
- )
- if raw["pathMatches"] is not True:
- raise CalendarGateError(
- "Calendar next-month control was evaluated outside Calendar"
- )
- candidate_count = require_plain_nonnegative_int(
- raw["candidateCount"],
- "candidateCount",
- )
- actionable_count = require_plain_nonnegative_int(
- raw["actionableCount"],
- "actionableCount",
- )
- if actionable_count > candidate_count:
- raise CalendarGateError(
- "Calendar next-month actionable count exceeded candidates"
- )
- if not isinstance(expected_clicked, bool):
- raise CalendarGateError("expected_clicked must be a boolean")
- if raw["clicked"] is not expected_clicked:
- raise CalendarGateError(
- "Calendar next-month click acknowledgement changed"
- )
- if actionable_count != 1 and not (
- allow_unready and actionable_count == 0
- ):
- raise CalendarGateError(
- "Calendar next-month control was not uniquely actionable"
- )
- return raw
- def click_next_month(
- page: object,
- *,
- timeout: float = 10,
- diagnostic: Callable[[object], None] | None = None,
- ) -> None:
- """Click only the unique visible Bootstrap day-view month control."""
- deadline = time.monotonic() + timeout
- last_raw: object = None
- while time.monotonic() < deadline:
- last_raw = page.run_js(NEXT_MONTH_CONTROL_SCRIPT, False)
- try:
- snapshot = validate_next_month_snapshot(
- last_raw,
- expected_clicked=False,
- allow_unready=True,
- )
- except CalendarGateError:
- if diagnostic:
- diagnostic(last_raw)
- raise
- if snapshot["actionableCount"] == 1:
- break
- time.sleep(0.25)
- else:
- if diagnostic:
- diagnostic(last_raw)
- raise CalendarNextMonthUnavailableError(
- "Calendar next-month control was not actionable before timeout"
- )
- clicked = page.run_js(NEXT_MONTH_CONTROL_SCRIPT, True)
- if diagnostic:
- diagnostic(clicked)
- validate_next_month_snapshot(clicked, expected_clicked=True)
- def refresh_calendar(page: object) -> None:
- page.refresh()
- page.wait.doc_loaded()
- def guard_calendar(page: object) -> dict[str, object]:
- """Disable the final button and reject any observed final request."""
- raw = page.run_js(CALENDAR_GUARD_SCRIPT)
- if not isinstance(raw, dict):
- raise CalendarGateError("Calendar guard did not return an object")
- expected = {
- "path": CALENDAR_PATH,
- "calendarFunctionPresent": True,
- "finalButtonCount": 1,
- "allFinalButtonsGuarded": True,
- "finalRequestCount": 0,
- }
- for key, expected_value in expected.items():
- if raw.get(key) != expected_value:
- raise CalendarGateError(f"Calendar guard rejected {key}")
- return raw
- def capture_initial_probe(page: object) -> CalendarProbeResult:
- packet = listen_once(
- page,
- target=AVAILABILITY_PATH,
- method="POST",
- action=lambda: refresh_calendar(page),
- timeout=30,
- )
- probe = parse_availability_packet(packet)
- guard_calendar(page)
- return probe
- def capture_next_probe(page: object) -> CalendarProbeResult:
- packet = listen_once(
- page,
- target=AVAILABILITY_PATH,
- method="POST",
- action=lambda: click_next_month(page),
- timeout=30,
- )
- probe = parse_availability_packet(packet)
- guard_calendar(page)
- return probe
- def scan_until_first_available_month(
- page: object,
- *,
- lookahead_months: int,
- log: Callable[[str], None] | None = None,
- month_click_interval_seconds: float = DEFAULT_MONTH_CLICK_INTERVAL_SECONDS,
- ) -> CalendarQueryScanResult:
- """Scan sequential months and stop immediately at the first positive one."""
- months = _validate_lookahead_months(lookahead_months)
- if (
- isinstance(month_click_interval_seconds, bool)
- or not isinstance(month_click_interval_seconds, (int, float))
- or month_click_interval_seconds < 0
- ):
- raise CalendarGateError(
- "month_click_interval_seconds must be nonnegative"
- )
- probes = [capture_initial_probe(page)]
- if log:
- log(
- "Italy Calendar probe "
- f"index=0 available={probes[0].available_count}"
- )
- if probes[0].available_count:
- return CalendarQueryScanResult(
- probes=tuple(probes),
- lookahead_months=months,
- stop_reason="first_available_month",
- )
- for index in range(1, months):
- if month_click_interval_seconds:
- time.sleep(month_click_interval_seconds)
- try:
- probe = capture_next_probe(page)
- except CalendarNextMonthUnavailableError as exc:
- raise CalendarGateError(
- "Calendar scan ended before the configured horizon"
- ) from exc
- if probe.selected_month != next_month_value(
- probes[-1].selected_month
- ):
- raise CalendarGateError(
- "Calendar request did not advance exactly one month"
- )
- probes.append(probe)
- if log:
- log(
- "Italy Calendar probe "
- f"index={index} available={probe.available_count}"
- )
- if probe.available_count:
- return CalendarQueryScanResult(
- probes=tuple(probes),
- lookahead_months=months,
- stop_reason="first_available_month",
- )
- return CalendarQueryScanResult(
- probes=tuple(probes),
- lookahead_months=months,
- stop_reason="horizon_exhausted",
- )
- # ============================================================================
- # CALENDAR_BOOK (from plugins/ita_calendar_book.py)
- # ============================================================================
- """Book-side Calendar response binding and native slot selection.
- The caller owns login, route continuity, date preferences and fresh packet
- capture in the applicant's browser. This adapter neither fetches inventory nor
- accepts a Query snapshot. A returned approval is a pre-final checkpoint, never
- permission to submit or evidence of a completed booking.
- """
- import json
- import time
- from dataclasses import dataclass, field
- from datetime import date, datetime
- from typing import Callable, Mapping
- TIME_SLOTS_PATH = "/BookingCalendar/RetrieveTimeSlots"
- RUNTIME_SERVICE_SCRIPT = r"""
- /* coordinate:ita-book-runtime-service */
- const controls = Array.from(document.querySelectorAll('#idServizio'));
- return {
- path: window.location.pathname,
- count: controls.length,
- value: controls.length === 1 ? controls[0].value : null,
- };
- """
- SLOT_SELECTION_SCRIPT = r"""
- /* coordinate:ita-book-slot-selection */
- const [serviceId, day, dailyId, timeLabel, capacity, shouldClick] = arguments;
- const normalize = (text) => String(text || '').replace(/\s+/g, ' ').trim();
- const service = Array.from(document.querySelectorAll('#idServizio'));
- const runtimeMatches = window.location.origin === 'https://prenotami.esteri.it' &&
- window.location.pathname === '/BookingCalendar' &&
- service.length === 1 && service[0].value === serviceId;
- const finalButtons = Array.from(document.querySelectorAll('#btnPrenotaNoOtp'));
- const finalGuarded = finalButtons.length === 1 && finalButtons[0].disabled &&
- finalButtons[0].dataset.coordinateFinalGuard === 'enabled';
- const timeline = Array.from(document.querySelectorAll('.events a.selected'));
- const content = Array.from(document.querySelectorAll('.events-content li.selected'));
- const links = Array.from(document.querySelectorAll('.events a[data-date]'))
- .filter((element) => element.dataset.date === day);
- const link = links.length === 1 ? links[0] : null;
- const datesMatch = timeline.length === 1 && content.length === 1 &&
- timeline[0].dataset.date === day && content[0].dataset.date === day;
- const firstSelectedMatches = datesMatch && document.querySelector('.selected') === timeline[0];
- const disabled = (element) => !element || element.hasAttribute('disabled') ||
- element.getAttribute('aria-disabled') === 'true' ||
- element.classList.contains('disabled') ||
- element.classList.contains('input-async-disabilitato');
- const dayNegative = !link || link.classList.contains('notAvailableDay');
- const dayPositive = Boolean(link && link.classList.contains('input-async-abilitato'));
- const inputs = (slot) => slot ? Array.from(slot.querySelectorAll('input')) : [];
- const idMatches = (slot) => {
- const fields = inputs(slot);
- return fields.length === 1 && fields[0].type === 'hidden' &&
- fields[0].id === 'idHiddenFasciaServizio' && fields[0].value === dailyId;
- };
- const timeMatches = (slot) => {
- const spans = slot ? slot.querySelectorAll('span') : [];
- return spans.length === 2 && normalize(spans[0].textContent) === timeLabel;
- };
- const capacityMatches = (slot) => {
- const spans = slot ? slot.querySelectorAll('span') : [];
- return spans.length === 2 && normalize(spans[1].textContent) === `(${capacity})`;
- };
- const negative = (slot) => !slot || slot.classList.contains('notAvailableFascia');
- const redDot = (slot) => Boolean(slot && slot.querySelector('.dotRed'));
- const actionable = (element) => {
- if (!element || !element.isConnected || disabled(element)) return false;
- const style = window.getComputedStyle(element);
- if (style.display === 'none' || style.visibility === 'hidden' ||
- style.pointerEvents === 'none' || Number.parseFloat(style.opacity || '1') <= 0) return false;
- const rect = element.getBoundingClientRect();
- const left = Math.max(0, rect.left), right = Math.min(window.innerWidth, rect.right);
- const top = Math.max(0, rect.top), bottom = Math.min(window.innerHeight, rect.bottom);
- if (right <= left || bottom <= top) return false;
- const hit = document.elementFromPoint((left + right) / 2, (top + bottom) / 2);
- return Boolean(hit && (hit === element || element.contains(hit)));
- };
- const slots = content.length === 1 ? Array.from(content[0].querySelectorAll('.fascia')) : [];
- const matches = slots.filter(idMatches);
- const candidate = matches.length === 1 ? matches[0] : null;
- const candidateReady = Boolean(candidate && !negative(candidate) && !redDot(candidate) &&
- timeMatches(candidate) && capacityMatches(candidate) && actionable(candidate));
- let active = Array.from(document.querySelectorAll('.fascia.act'));
- const alreadyActive = active.length === 1 && active[0] === candidate;
- let clicked = false;
- if (shouldClick === true && runtimeMatches && finalGuarded && datesMatch &&
- firstSelectedMatches && links.length === 1 && !disabled(link) && !dayNegative &&
- dayPositive && candidateReady && !alreadyActive) {
- candidate.click();
- clicked = true;
- }
- active = Array.from(document.querySelectorAll('.fascia.act'));
- const selected = active.length === 1 ? active[0] : null;
- return {
- runtimeMatches, finalGuarded, firstSelectedMatches,
- timelineDays: timeline.map((element) => element.dataset.date || ''),
- contentDays: content.map((element) => element.dataset.date || ''),
- matchingDateCount: links.length,
- dayDisabled: disabled(link), dayNegative, dayPositive,
- candidateCount: matches.length, candidateReady, clicked,
- activeCount: active.length,
- activeIsCandidate: Boolean(selected && selected === candidate),
- activeUnavailable: negative(selected), activeRedDot: redDot(selected),
- activeInputCount: inputs(selected).length,
- activeIdMatches: idMatches(selected),
- activeDayMatches: Boolean(selected && datesMatch && content[0].contains(selected)),
- activeTimeMatches: timeMatches(selected),
- activeCapacityMatches: capacityMatches(selected),
- };
- """
- class CalendarBookError(CalendarGateError):
- """A safe stage error; never includes response bodies or runtime IDs."""
- def __init__(self, message: str, *, http_status: int | None = None):
- super().__init__(message)
- self.http_status = http_status
- class CalendarServiceNotReadyError(CalendarBookError):
- """The service control stayed empty during a known initialization boundary."""
- _BOOL_FIELDS = {
- "runtimeMatches", "finalGuarded", "firstSelectedMatches", "dayDisabled",
- "dayNegative", "dayPositive", "candidateReady", "clicked",
- "activeIsCandidate", "activeUnavailable", "activeRedDot", "activeIdMatches",
- "activeDayMatches", "activeTimeMatches", "activeCapacityMatches",
- }
- _COUNT_FIELDS = {"matchingDateCount", "candidateCount", "activeCount", "activeInputCount"}
- _DATE_FIELDS = {"timelineDays", "contentDays"}
- def _runtime_id(value: object) -> str:
- if type(value) is int and value > 0:
- return str(value)
- if isinstance(value, str) and value and value == value.strip() and len(value) <= 128:
- return value
- raise CalendarBookError("Book runtime service identifier was invalid")
- def _read_calendar_service_value(page: object) -> str:
- path, _ = same_origin_path(page.url)
- if path != CALENDAR_PATH:
- raise CalendarBookError("Book selection requires the current Calendar page")
- raw = page.run_js(RUNTIME_SERVICE_SCRIPT)
- if not isinstance(raw, dict) or set(raw) != {"path", "count", "value"}:
- raise CalendarBookError("Book Calendar runtime context changed")
- if raw["path"] != CALENDAR_PATH or type(raw["count"]) is not int or raw["count"] != 1:
- raise CalendarBookError("Book Calendar requires one runtime service control")
- if not isinstance(raw["value"], str):
- raise CalendarBookError("Book Calendar runtime service control has no value")
- return raw["value"]
- def read_calendar_service(page: object) -> str:
- """Strict read for stable phases; empty values are never a valid identity."""
- return _runtime_id(_read_calendar_service_value(page))
- def wait_for_calendar_service(
- page: object, *, session_is_current: Callable[[], bool],
- expected_service: str | None = None, timeout: float = 5,
- ) -> str:
- """Await the site's field assignment without requesting or retrying anything.
- Call only after AVANTI or native Calendar loading. Stable-phase checks stay
- strict: only an exactly empty string is pending, not malformed identities,
- missing/duplicate controls, another service, or a changed applicant/tab.
- The deadline bounds polling; browser transport failures propagate normally.
- """
- if type(timeout) not in (int, float) or not 0 <= timeout < float("inf"):
- raise CalendarBookError("Book Calendar readiness timeout must be finite and nonnegative")
- if not callable(session_is_current):
- raise CalendarBookError("Book Calendar readiness requires a Session check")
- if expected_service is not None:
- expected_service = _runtime_id(expected_service)
- tab_id = getattr(page, "tab_id", None)
- if not isinstance(tab_id, str) or not tab_id:
- raise CalendarBookError("Book Calendar tab identity was unavailable")
- deadline = time.monotonic() + timeout
- def require_session() -> None:
- if session_is_current() is not True or getattr(page, "tab_id", None) != tab_id:
- raise CalendarBookError("Book applicant, route or browser Session changed")
- if same_origin_path(page.url)[0] != CALENDAR_PATH:
- raise CalendarBookError("Book readiness left the current Calendar page")
- while True:
- require_session()
- guard_calendar(page)
- value = _read_calendar_service_value(page)
- require_session()
- if value != "":
- service = _runtime_id(value)
- if expected_service is not None and service != expected_service:
- raise CalendarBookError("Book Calendar runtime service changed")
- return service
- remaining = deadline - time.monotonic()
- if remaining <= 0:
- raise CalendarServiceNotReadyError("Book Calendar service did not initialize before timeout")
- time.sleep(min(0.1, remaining))
- def _request_day(value: object) -> date:
- if isinstance(value, str):
- for date_format in ("%Y-%m-%d", "%d/%m/%Y"):
- try:
- return datetime.strptime(value, date_format).date()
- except ValueError:
- pass
- raise CalendarBookError("Book TimeSlots request date format changed")
- def parse_book_time_slots(
- packet: object, *, target_day: date, runtime_service_id: str,
- ) -> tuple[SlotCandidate, ...]:
- """Bind TimeSlots metadata to the selected day and current DOM service."""
- try:
- path, _ = same_origin_path(packet.url)
- if str(packet.method).upper() != "POST" or path != TIME_SLOTS_PATH:
- raise CalendarBookError("Book TimeSlots request method or path changed")
- if type(packet.response.status) is not int or packet.response.status != 200:
- raise CalendarBookError(
- "Book TimeSlots response status was not 200",
- http_status=packet.response.status if type(packet.response.status) is int else None,
- )
- body = packet.request.postData
- if isinstance(body, str):
- body = json.loads(body)
- if not isinstance(body, dict) or set(body) != {"selectedDay", "idService"}:
- raise CalendarBookError("Book TimeSlots request fields changed")
- if _runtime_id(body["idService"]) != runtime_service_id:
- raise CalendarBookError("Book TimeSlots request does not match the current service")
- if _request_day(body["selectedDay"]) != target_day:
- raise CalendarBookError("Book TimeSlots request does not match the target day")
- candidates = parse_time_slots(packet.response.raw_body)
- if any(item.day != target_day for item in candidates):
- raise CalendarBookError("Book TimeSlots response contains another day")
- return candidates
- except CalendarBookError:
- raise
- except ItaProtocolError as exc:
- raise CalendarBookError(f"Book TimeSlots protocol rejected ({exc.code})") from None
- except Exception:
- raise CalendarBookError("Book TimeSlots packet could not be validated") from None
- def _snapshot(page: object, service: str, target: date, candidate: SlotCandidate, *, click: bool) -> dict:
- raw = page.run_js(
- SLOT_SELECTION_SCRIPT, service, target.isoformat(), candidate.daily_calendar_id,
- candidate.time_label, candidate.slots_free, click,
- )
- if not isinstance(raw, dict) or set(raw) != _BOOL_FIELDS | _COUNT_FIELDS | _DATE_FIELDS:
- raise CalendarBookError("Book slot snapshot fields changed")
- if any(type(raw[key]) is not bool for key in _BOOL_FIELDS):
- raise CalendarBookError("Book slot snapshot boolean types changed")
- for key in _COUNT_FIELDS:
- require_plain_nonnegative_int(raw[key], key)
- for key in _DATE_FIELDS:
- if not isinstance(raw[key], list) or any(not isinstance(item, str) for item in raw[key]):
- raise CalendarBookError("Book selected-date snapshot types changed")
- return raw
- def _require_ready(raw: dict, target_day: date) -> None:
- positive = ("runtimeMatches", "finalGuarded", "firstSelectedMatches", "dayPositive", "candidateReady")
- if any(raw[key] is not True for key in positive):
- raise CalendarBookError("Book candidate is not safely selectable")
- if raw["dayDisabled"] or raw["dayNegative"]:
- raise CalendarBookError("Book selected day is marked unavailable")
- if raw["matchingDateCount"] != 1 or raw["candidateCount"] != 1:
- raise CalendarBookError("Book date or slot is not unique")
- expected = [target_day.isoformat()]
- if raw["timelineDays"] != expected or raw["contentDays"] != expected:
- raise CalendarBookError("Book timeline and content dates do not match the target")
- def _approve_selection_snapshot(
- calendar_day: CalendarDay, candidate: SlotCandidate, raw: dict,
- ) -> PrecommitApproval:
- _require_ready(raw, candidate.day)
- if raw["clicked"]:
- raise CalendarBookError("Book readback unexpectedly clicked")
- return approve_precommit(
- calendar_day, candidate,
- DateSelectionState(
- planned_day=candidate.day, matching_availability_count=1,
- timeline_selected_days=tuple(date.fromisoformat(item) for item in raw["timelineDays"]),
- content_selected_days=tuple(date.fromisoformat(item) for item in raw["contentDays"]),
- day_disabled=raw["dayDisabled"], day_not_available=raw["dayNegative"],
- day_has_positive_state=raw["dayPositive"],
- ),
- SlotSelectionState(
- active_slot_count=raw["activeCount"], active_is_candidate=raw["activeIsCandidate"],
- active_has_unavailable_class=raw["activeUnavailable"], active_has_red_dot=raw["activeRedDot"],
- active_hidden_input_count=raw["activeInputCount"],
- active_daily_id_matches_candidate=raw["activeIdMatches"],
- active_day_matches_candidate=raw["activeDayMatches"],
- active_time_matches_candidate=raw["activeTimeMatches"],
- active_capacity_matches_candidate=raw["activeCapacityMatches"],
- ),
- )
- def verify_precommit_selection(
- page: object, *, runtime_service: str, approval: PrecommitApproval,
- ) -> PrecommitApproval:
- """Read the current selected slot; never select, refresh, or submit anything.
- The caller still owns applicant/session binding and freshness of the Book
- inventory. This is a consistency check, not a reservation or inventory lock.
- """
- if not isinstance(approval, PrecommitApproval):
- raise CalendarBookError("Book selection requires a precommit approval")
- try:
- if read_calendar_service(page) != runtime_service:
- raise CalendarBookError("Book Calendar runtime service changed")
- raw = _snapshot(page, runtime_service, approval.candidate.day, approval.candidate, click=False)
- return _approve_selection_snapshot(approval.calendar_day, approval.candidate, raw)
- except CalendarBookError:
- raise
- except Exception:
- raise CalendarBookError("Book precommit readback failed") from None
- def select_slot_before_final(
- page: object, *, target_day: date, availability_packet: object, time_slots_packet: object,
- ) -> PrecommitApproval | None:
- """Select one positive slot from caller-captured Book packets; never submit.
- Both packets must be fresh captures from this page. Their content alone
- cannot prove capture time, applicant identity or route continuity. The
- orchestrator must establish these preconditions before calling this method.
- """
- if type(target_day) is not date:
- raise CalendarBookError("Book target day must be a date")
- try:
- service = read_calendar_service(page)
- guard_calendar(page)
- try:
- probe = parse_availability_packet(availability_packet)
- if probe.selected_month != (target_day.year, target_day.month):
- raise CalendarBookError("Book Availability belongs to another month")
- slots = parse_book_time_slots(
- time_slots_packet, target_day=target_day, runtime_service_id=service,
- )
- days = [item for item in probe.days if item.day == target_day]
- candidates = available_slot_candidates(slots, start_day=target_day, end_day=target_day)
- if not days or not days[0].is_available:
- if candidates:
- raise CalendarBookError("Book Availability and TimeSlots disagree")
- return None
- if not candidates:
- return None
- candidate = candidates[0]
- before = _snapshot(page, service, target_day, candidate, click=False)
- _require_ready(before, target_day)
- if before["clicked"]:
- raise CalendarBookError("Book read-only snapshot unexpectedly clicked")
- if not (before["activeCount"] == 1 and before["activeIsCandidate"]):
- acted = _snapshot(page, service, target_day, candidate, click=True)
- _require_ready(acted, target_day)
- if not acted["clicked"]:
- raise CalendarBookError("Book slot click was not acknowledged")
- after = _snapshot(page, service, target_day, candidate, click=False)
- return _approve_selection_snapshot(days[0], candidate, after)
- finally:
- guard_calendar(page)
- except CalendarBookError:
- raise
- except ItaProtocolError as exc:
- raise CalendarBookError(f"Book precommit rejected ({exc.code})") from None
- except Exception:
- raise CalendarBookError("Book Calendar selection or final guard failed") from None
- DATE_SELECTION_SCRIPT = r"""
- /* coordinate:ita-book-date-selection */
- const [serviceId, day, shouldClick] = arguments;
- const services = Array.from(document.querySelectorAll('#idServizio'));
- const runtimeMatches = window.location.origin === 'https://prenotami.esteri.it' &&
- window.location.pathname === '/BookingCalendar' && services.length === 1 &&
- services[0].value === serviceId;
- const buttons = Array.from(document.querySelectorAll('#btnPrenotaNoOtp'));
- const finalGuarded = buttons.length === 1 && buttons[0].disabled === true &&
- buttons[0].dataset.coordinateFinalGuard === 'enabled';
- const candidates = Array.from(document.querySelectorAll('.events a[data-date]'))
- .filter((link) => link.dataset.date === day);
- const link = candidates.length === 1 ? candidates[0] : null;
- const enabled = (element) => {
- if (!element || !element.isConnected || element.hasAttribute('disabled') ||
- element.getAttribute('aria-disabled') === 'true' ||
- element.classList.contains('disabled') || element.classList.contains('notAvailableDay') ||
- element.classList.contains('input-async-disabilitato') ||
- !element.classList.contains('input-async-abilitato')) return false;
- const style = window.getComputedStyle(element);
- // Calendar timeline links can have zero layout size while logically enabled.
- // The site's initialization uses HTMLElement.click(), as we do here, rather
- // than a pointer hit. Keep disabled/style checks and response/date readback;
- // do not require a clickable rectangle for this native date action.
- return style.display !== 'none' && style.visibility !== 'hidden' &&
- style.pointerEvents !== 'none' && Number.parseFloat(style.opacity || '1') > 0;
- };
- const timeline = Array.from(document.querySelectorAll('.events a.selected'));
- const content = Array.from(document.querySelectorAll('.events-content li.selected'));
- const selectedMatches = timeline.length === 1 && content.length === 1 &&
- timeline[0].dataset.date === day && content[0].dataset.date === day &&
- document.querySelector('.selected') === timeline[0];
- const candidateEnabled = enabled(link);
- let clicked = false;
- if (shouldClick === true && runtimeMatches && finalGuarded && candidateEnabled && !selectedMatches) {
- link.click();
- clicked = true;
- }
- return {runtimeMatches, finalGuarded, candidateCount: candidates.length,
- candidateEnabled, selectedMatches, clicked};
- """
- @dataclass(frozen=True, slots=True)
- class _CapturedMonth:
- probe: CalendarProbeResult
- availability_packet: object = field(repr=False)
- availability_service: str = field(repr=False)
- automatic_day: date | None = None
- automatic_slots_packet: object | None = field(default=None, repr=False)
- def book_date_preferences(user_inputs: Mapping[str, object]) -> tuple[date, date]:
- """Use the VFS preference keys and inclusive bounds without mutating inputs."""
- if not isinstance(user_inputs, Mapping):
- raise CalendarBookError("Book user inputs must be a mapping")
- dates = []
- for key, default in (("expected_start_date", "2000-01-01"),
- ("expected_end_date", "2100-01-01")):
- value = user_inputs.get(key, default)
- try:
- parsed = date.fromisoformat(value) if isinstance(value, str) else None
- except ValueError:
- parsed = None
- if parsed is None or parsed.isoformat() != value:
- raise CalendarBookError(f"Book {key} must use YYYY-MM-DD")
- dates.append(parsed)
- if dates[0] > dates[1]:
- raise CalendarBookError("Book date preference start exceeds end")
- return dates[0], dates[1]
- def _require_context(page: object, service: str, session_is_current: Callable[[], bool]) -> None:
- if session_is_current() is not True:
- raise CalendarBookError("Book applicant, route or browser Session changed")
- if read_calendar_service(page) != service:
- raise CalendarBookError("Book Calendar runtime service changed")
- guard_calendar(page)
- def _require_packet_tab(page: object, packet: object) -> None:
- tab = getattr(page, "tab_id", None)
- if not isinstance(tab, str) or not tab or getattr(packet, "tab_id", None) != tab:
- raise CalendarBookError("Book response did not belong to the current browser tab")
- if getattr(packet, "is_failed", False) is not False:
- raise CalendarBookError("Book browser request failed")
- def _post_body(packet: object) -> dict:
- body = packet.request.postData
- if isinstance(body, str):
- body = json.loads(body)
- if not isinstance(body, dict):
- raise CalendarBookError("Book request body was not an object")
- return body
- def _date_snapshot(page: object, service: str, day: date, *, click: bool = False) -> dict:
- raw = page.run_js(DATE_SELECTION_SCRIPT, service, day.isoformat(), click)
- boolean_keys = {"runtimeMatches", "finalGuarded", "candidateEnabled", "selectedMatches", "clicked"}
- if not isinstance(raw, dict) or set(raw) != boolean_keys | {"candidateCount"}:
- raise CalendarBookError("Book date control structure changed")
- if any(type(raw[key]) is not bool for key in boolean_keys):
- raise CalendarBookError("Book date control types changed")
- require_plain_nonnegative_int(raw["candidateCount"], "candidateCount")
- if not raw["runtimeMatches"] or not raw["finalGuarded"] or raw["candidateCount"] > 1:
- raise CalendarBookError("Book date control context was not unique and guarded")
- if not click and raw["clicked"]:
- raise CalendarBookError("Book date readback unexpectedly clicked")
- return raw
- def _wait_selected_day(page: object, service: str, day: date, *, timeout: float) -> None:
- deadline = time.monotonic() + timeout
- while True:
- raw = _date_snapshot(page, service, day)
- if raw["candidateCount"] == 1 and raw["selectedMatches"]:
- return
- if time.monotonic() >= deadline:
- raise CalendarBookError("Book selected date did not match the response before timeout")
- time.sleep(0.1)
- def _click_date(page: object, service: str, day: date, *, timeout: float) -> None:
- deadline = time.monotonic() + timeout
- while True:
- raw = _date_snapshot(page, service, day)
- if raw["selectedMatches"]:
- raise CalendarBookError("Book date is already selected without a fresh captured response")
- if raw["candidateCount"] == 1 and raw["candidateEnabled"]:
- break
- if time.monotonic() >= deadline:
- raise CalendarBookError("Book date control was not ready before timeout")
- time.sleep(0.1)
- acted = _date_snapshot(page, service, day, click=True)
- if not acted["clicked"]:
- raise CalendarBookError("Book date click was not acknowledged")
- def _capture_month(
- page: object, *, action: Callable[[], None], service: str,
- session_is_current: Callable[[], bool], timeout: float, dom_timeout: float,
- previous: _CapturedMonth | None = None,
- ) -> _CapturedMonth:
- """Capture Availability plus the site's automatic first-day TimeSlots."""
- _require_context(page, service, session_is_current)
- page.listen.start([AVAILABILITY_PATH, TIME_SLOTS_PATH], method="POST")
- try:
- action()
- wait_for_calendar_service(
- page, session_is_current=session_is_current,
- expected_service=service, timeout=min(dom_timeout, timeout),
- )
- _require_context(page, service, session_is_current)
- deadline = time.monotonic() + timeout
- captured = {}
- probe = None
- # Only two matching responses belong to one normal month-load action.
- for _ in range(2):
- remaining = deadline - time.monotonic()
- if remaining <= 0:
- raise CalendarBookError("Book month responses exceeded the time budget")
- packet = page.listen.wait(timeout=remaining, raise_err=False)
- if not packet:
- raise CalendarBookError("Book month response was not observed before timeout")
- _require_packet_tab(page, packet)
- status = packet.response.status
- if type(status) is not int or status != 200:
- raise CalendarBookError("Book Calendar response status was not 200",
- http_status=status if type(status) is int else None)
- path, _ = same_origin_path(packet.url)
- if path not in {AVAILABILITY_PATH, TIME_SLOTS_PATH} or path in captured:
- raise CalendarBookError("Book month produced an unexpected or duplicate response")
- captured[path] = packet
- if path == AVAILABILITY_PATH:
- probe = parse_availability_packet(packet)
- if previous and probe.selected_month != next_month_value(previous.probe.selected_month):
- raise CalendarBookError("Book Calendar did not advance exactly one month")
- if not probe.days or TIME_SLOTS_PATH in captured:
- break
- elif probe is not None:
- break
- if probe is None:
- raise CalendarBookError("Book month did not return Availability")
- availability_packet = captured[AVAILABILITY_PATH]
- availability_service = _runtime_id(_post_body(availability_packet).get("_Servizio"))
- if previous and availability_service != previous.availability_service:
- raise CalendarBookError("Book Availability runtime service changed")
- automatic = captured.get(TIME_SLOTS_PATH)
- automatic_day = None
- if probe.days:
- if automatic is None:
- raise CalendarBookError("Book automatic day response was not captured")
- automatic_day = _request_day(_post_body(automatic).get("selectedDay"))
- if automatic_day not in {item.day for item in probe.days}:
- raise CalendarBookError("Book automatic day escaped current Availability")
- auto_slots = parse_book_time_slots(automatic, target_day=automatic_day, runtime_service_id=service)
- auto_inventory = next(item for item in probe.days if item.day == automatic_day)
- if not auto_inventory.is_available and available_slot_candidates(auto_slots):
- raise CalendarBookError("Book automatic Availability and TimeSlots disagree")
- _wait_selected_day(page, service, automatic_day, timeout=dom_timeout)
- elif automatic is not None:
- raise CalendarBookError("Book empty Availability unexpectedly returned TimeSlots")
- _require_context(page, service, session_is_current)
- return _CapturedMonth(probe, availability_packet, availability_service, automatic_day, automatic)
- finally:
- page.listen.stop()
- def _try_day(
- page: object, month: _CapturedMonth, day: date, *, service: str,
- session_is_current: Callable[[], bool], timeout: float, dom_timeout: float,
- ) -> PrecommitApproval | None:
- _require_context(page, service, session_is_current)
- current_date = _date_snapshot(page, service, day)
- if day == month.automatic_day and current_date["selectedMatches"]:
- times_packet = month.automatic_slots_packet
- _wait_selected_day(page, service, day, timeout=dom_timeout)
- else:
- times_packet = listen_once(
- page, target=TIME_SLOTS_PATH, method="POST",
- action=lambda: _click_date(page, service, day, timeout=dom_timeout),
- timeout=timeout,
- )
- _require_packet_tab(page, times_packet)
- parse_book_time_slots(times_packet, target_day=day, runtime_service_id=service)
- _wait_selected_day(page, service, day, timeout=dom_timeout)
- slots = parse_book_time_slots(times_packet, target_day=day, runtime_service_id=service)
- candidates = available_slot_candidates(slots, start_day=day, end_day=day)
- if not candidates:
- # Inventory competition is not a protocol error. No slot was clicked.
- _require_context(page, service, session_is_current)
- return None
- deadline = time.monotonic() + dom_timeout
- while True:
- _require_context(page, service, session_is_current)
- raw = _snapshot(page, service, day, candidates[0], click=False)
- if not raw["runtimeMatches"] or not raw["finalGuarded"] or raw["candidateCount"] > 1:
- raise CalendarBookError("Book slot DOM changed its context or uniqueness")
- if raw["candidateReady"]:
- _require_ready(raw, day)
- break
- if time.monotonic() >= deadline:
- raise CalendarBookError("Book slot DOM did not match the response before timeout")
- time.sleep(0.1)
- approval = select_slot_before_final(
- page, target_day=day, availability_packet=month.availability_packet,
- time_slots_packet=times_packet,
- )
- _require_context(page, service, session_is_current)
- return approval
- def recheck_calendar_before_final(
- page: object, *, lookahead_months: int, start_day: date, end_day: date,
- session_is_current: Callable[[], bool], preferred_day: date | None = None,
- month_click_interval_seconds: float = DEFAULT_MONTH_CLICK_INTERVAL_SECONDS,
- timeout: float = 30, dom_timeout: float = 5,
- log: Callable[[str], None] | None = None,
- ) -> PrecommitApproval | None:
- """Fresh Book-only scan with an optional date hint; never submit a booking.
- There are at most two bounded passes: the hinted day, then an ascending
- fallback. The caller must attest the prepared applicant/route Session via
- session_is_current. No external snapshot or cached response is accepted.
- """
- try:
- # Use existing pure validators before starting any browser action.
- month_starts(date(2000, 1, 1), lookahead_months)
- if type(start_day) is not date or type(end_day) is not date:
- raise CalendarBookError("Book date bounds must be dates")
- available_calendar_days((), start_day=start_day, end_day=end_day)
- if preferred_day is not None and type(preferred_day) is not date:
- raise CalendarBookError("Book preferred day must be a date")
- for value in (timeout, dom_timeout, month_click_interval_seconds):
- if type(value) not in (int, float) or not 0 <= value < float("inf"):
- raise CalendarBookError("Book time budget must be finite and nonnegative")
- if timeout == 0 or not callable(session_is_current):
- raise CalendarBookError("Book requires a positive timeout and a Session check")
- service = read_calendar_service(page)
- _require_context(page, service, session_is_current)
- common = dict(service=service, session_is_current=session_is_current,
- timeout=timeout, dom_timeout=dom_timeout)
- def initial() -> _CapturedMonth:
- return _capture_month(page, action=lambda: refresh_calendar(page), **common)
- def advance(previous: _CapturedMonth) -> _CapturedMonth:
- if month_click_interval_seconds:
- time.sleep(month_click_interval_seconds)
- return _capture_month(page, action=lambda: click_next_month(page), previous=previous, **common)
- def positive_days(month: _CapturedMonth) -> tuple:
- return available_calendar_days(month.probe.days, start_day=start_day, end_day=end_day)
- first = initial()
- anchor = first.probe.selected_month
- current = first
- attempted = set()
- if preferred_day is not None and start_day <= preferred_day <= end_day:
- offset = (preferred_day.year - anchor[0]) * 12 + preferred_day.month - anchor[1]
- if 0 <= offset < lookahead_months:
- for _ in range(offset):
- current = advance(current)
- if preferred_day in {item.day for item in positive_days(current)}:
- attempted.add(preferred_day)
- approval = _try_day(page, current, preferred_day, **common)
- if approval is not None:
- return approval
- # A failed hint cannot cause a stale earlier month's response
- # to be reused. Restart the native scan once and recapture.
- first = initial()
- if (first.probe.selected_month != anchor or
- first.availability_service != current.availability_service):
- raise CalendarBookError("Book fallback restart changed the Calendar anchor")
- current = first
- for index in range(lookahead_months):
- if current.probe.selected_month > (end_day.year, end_day.month):
- return None
- days = positive_days(current)
- if log:
- log(f"Italy Book Calendar month={month_text(current.probe.selected_month)} candidates={len(days)}")
- for item in days:
- if item.day in attempted:
- continue
- attempted.add(item.day)
- approval = _try_day(page, current, item.day, **common)
- if approval is not None:
- return approval
- if current.probe.selected_month >= (end_day.year, end_day.month):
- return None
- if index + 1 < lookahead_months:
- current = advance(current)
- return None
- except CalendarBookError:
- raise
- except ItaProtocolError as exc:
- raise CalendarBookError(f"Book Calendar protocol rejected ({exc.code})") from None
- except Exception:
- raise CalendarBookError("Book Calendar recheck failed; no further action was attempted") from None
- finally:
- # Do not leave the final button enabled after a native refresh or error.
- try:
- if same_origin_path(page.url)[0] == CALENDAR_PATH:
- guard_calendar(page)
- except Exception:
- raise CalendarBookError("Book final-button guard could not be verified") from None
- # ============================================================================
- # BOOKING_FINAL (from plugins/ita_booking_final.py)
- # ============================================================================
- """Italy final-stage building blocks shared by production and local validation.
- ReservationSnapshot is an internal read-port contract, NOT a discovered website
- schema. A real adapter must prove identity, status and pagination completeness
- before this module can be enabled. Attempts are process-local; the existing
- Booker task pause handles uncertain outcomes. No automatic retry is provided.
- The opt-in local evidence gate adds a checkout-local fence and human confirmation;
- it observes unknown receipts without claiming that production success is proven.
- """
- import json
- import re
- import threading
- import time
- from dataclasses import dataclass, field
- from datetime import date
- from enum import Enum
- from typing import Callable
- from urllib.parse import parse_qsl, urljoin
- from vs_types import VSBookResult, BookingOutcomeUnknownError
- FINAL_PATH = "/BookingCalendar/InsertNewBooking"
- class FinalBookingError(RuntimeError):
- """Fixed messages only: do not include page text, requests or credentials."""
- class FinalOutcomeUnknown(FinalBookingError, BookingOutcomeUnknownError):
- def __init__(self):
- super().__init__("Italy final outcome requires read-only reconciliation")
- class ReservationState(str, Enum):
- ACTIVE = "active"
- CANCELLED = "cancelled"
- WAITLIST = "waitlist"
- UNKNOWN = "unknown"
- class SubmissionSignal(str, Enum):
- ACCEPTED = "accepted_hint"
- REJECTED = "rejected_hint"
- UNKNOWN = "unknown"
- def _final_text(value: object) -> bool:
- return (isinstance(value, str) and 0 < len(value) <= 256 and value == value.strip()
- and not any(ord(ch) < 32 or ord(ch) == 127 for ch in value))
- @dataclass(frozen=True, slots=True)
- class FinalTarget:
- applicant: str = field(repr=False)
- session_key: str = field(repr=False)
- tab_id: str = field(repr=False)
- routing_key: str
- service_id: str = field(repr=False)
- runtime_service: str = field(repr=False)
- approval: PrecommitApproval = field(repr=False)
- service_name: str | None = field(default=None, repr=False)
- def __post_init__(self):
- if not all(_final_text(getattr(self, key)) for key in (
- "applicant", "session_key", "tab_id", "routing_key", "service_id", "runtime_service",
- )):
- raise FinalBookingError("Italy final target identity is invalid")
- if not isinstance(self.approval, PrecommitApproval):
- raise FinalBookingError("Italy final requires a Book precommit approval")
- if self.service_name is not None and not _final_text(self.service_name):
- raise FinalBookingError("Italy final displayed service is invalid")
- day, slot = self.approval.calendar_day, self.approval.candidate
- if (not isinstance(day, CalendarDay) or not isinstance(slot, SlotCandidate)
- or day.day != slot.day or not day.is_available or not slot.is_available):
- raise FinalBookingError("Italy final target inventory is inconsistent")
- @dataclass(frozen=True, slots=True, repr=False)
- class VerifiedSubmission:
- """Native POST matched this exact session/tab/precommit; not a receipt field.
- Created from an observed packet, even when its RESPONSE schema is unknown.
- A caller must also enforce the one-request audit before passing it to a read port.
- """
- target: FinalTarget
- @dataclass(frozen=True, slots=True)
- class ReservationRecord:
- """Normalized by a verified, identity-bound site reader.
- time_label is an independently evidenced selected interval, not an interval
- inferred from appointment_time. A real receipt may expose only the assigned
- HH:mm time. That is enough to preserve cancelled history, not prove a new
- record belongs to the selected slot. Cancelled history may have an unbound
- service_id only with a fingerprint retaining all observed business facts.
- This exception never establishes a target-service or selected-slot binding.
- submission is a separate verified native-request witness, used by the bound
- real read port for new active receipts. It never rewrites the receipt fields.
- """
- reference: str = field(repr=False)
- service_id: str | None = field(repr=False)
- day: date
- time_label: str | None
- state: ReservationState
- appointment_time: str | None = None
- receipt_fingerprint: str | None = field(default=None, repr=False)
- submission: VerifiedSubmission | None = field(default=None, repr=False)
- def _valid_receipt_time(record: ReservationRecord) -> bool:
- interval, assigned = record.time_label, record.appointment_time
- if interval is None and assigned is None:
- return False
- if interval is not None and (
- not isinstance(interval, str)
- or re.fullmatch(r"(?:[01][0-9]|2[0-3]):[0-5][0-9] - (?:[01][0-9]|2[0-3]):[0-5][0-9]", interval) is None
- or interval[:5] >= interval[-5:]
- ):
- return False
- assigned_valid = assigned is None or (
- isinstance(assigned, str)
- and re.fullmatch(r"(?:[01][0-9]|2[0-3]):[0-5][0-9]", assigned) is not None
- )
- if not assigned_valid:
- return False
- # Negative consistency check only: containment never creates a binding.
- return interval is None or assigned is None or interval[:5] <= assigned <= interval[-5:]
- @dataclass(frozen=True, slots=True)
- class ReservationSnapshot:
- applicant: str = field(repr=False)
- session_key: str = field(repr=False)
- captured_at: float
- complete: bool
- records: tuple[ReservationRecord, ...] = field(repr=False)
- # Reuse the actual slot readback JS in the same synchronous browser turn as the
- # native final click, so a Python/browser round trip cannot select another slot.
- # Never reconstruct the POST payload: the website handler remains its owner.
- NATIVE_FINAL_SCRIPT = r"""
- /* coordinate:ita-native-final-once */
- const [serviceId, day, dailyId, timeLabel, capacity] = arguments;
- const state = (function () {
- """ + SLOT_SELECTION_SCRIPT + r"""
- }).apply(null, [serviceId, day, dailyId, timeLabel, capacity, false]);
- const positive = ['runtimeMatches', 'finalGuarded', 'firstSelectedMatches',
- 'dayPositive', 'candidateReady', 'activeIsCandidate', 'activeIdMatches',
- 'activeDayMatches', 'activeTimeMatches', 'activeCapacityMatches'];
- const negative = ['dayDisabled', 'dayNegative', 'activeUnavailable', 'activeRedDot', 'clicked'];
- const ready = positive.every(k => state[k] === true) && negative.every(k => state[k] === false) &&
- ['matchingDateCount', 'candidateCount', 'activeCount', 'activeInputCount'].every(k => state[k] === 1) &&
- JSON.stringify(state.timelineDays) === JSON.stringify([day]) &&
- JSON.stringify(state.contentDays) === JSON.stringify([day]);
- const buttons = Array.from(document.querySelectorAll('#btnPrenotaNoOtp'));
- if (!ready || buttons.length !== 1 || !buttons[0].isConnected ||
- buttons[0].dataset.coordinateFinalAttemptConsumed) return {clicked: false};
- const button = buttons[0];
- button.dataset.coordinateFinalAttemptConsumed = 'true';
- try {
- button.disabled = false;
- button.removeAttribute('aria-disabled');
- button.click();
- return {clicked: true};
- } finally {
- button.disabled = true;
- button.setAttribute('aria-disabled', 'true');
- button.dataset.coordinateFinalGuard = 'enabled';
- }
- """
- def _unique_object(pairs):
- result = {}
- for key, value in pairs:
- if key in result:
- raise ValueError("duplicate field")
- result[key] = value
- return result
- def inspect_final_packet(packet: object, target: FinalTarget) -> tuple[SubmissionSignal, VerifiedSubmission | None, str]:
- """Validate the observed request before interpreting a response as a hint.
- Invalid metadata/HTTP/schema is UNKNOWN after a write, not a retryable
- authentication/no-slot error. Never expose the raw server errorMessage.
- """
- evidence = None
- reason = "request_metadata"
- try:
- path, parsed = same_origin_path(packet.url)
- if (path != FINAL_PATH or parsed.query or parsed.fragment or packet.method != "POST"
- or packet.tab_id != target.tab_id or getattr(packet, "is_failed", False)):
- return SubmissionSignal.UNKNOWN, None, reason
- reason = "request_fields"
- body = packet.request.postData
- if isinstance(body, str) and len(body) <= MAX_PROTOCOL_PAYLOAD_CHARS:
- body = _unique_object(parse_qsl(body, keep_blank_values=True, strict_parsing=True))
- if not isinstance(body, dict) or set(body) != {
- "idCalendarioGiornaliero", "selectedDay", "selectedHour",
- } or any(not isinstance(value, str) for value in body.values()):
- return SubmissionSignal.UNKNOWN, None, reason
- reason = "request_selection"
- slot = target.approval.candidate
- if body["idCalendarioGiornaliero"] != slot.daily_calendar_id or body["selectedDay"] != slot.day.isoformat():
- return SubmissionSignal.UNKNOWN, None, reason
- compact = lambda value: re.sub(r"\s+", "", value)
- if compact(body["selectedHour"]) != compact(f"{slot.time_label}({slot.slots_free})"):
- return SubmissionSignal.UNKNOWN, None, reason
- evidence = VerifiedSubmission(target)
- reason = "response_metadata"
- response = packet.response
- if type(response.status) is not int or response.status != 200:
- return SubmissionSignal.UNKNOWN, evidence, reason
- response_url = getattr(response, "url", None)
- if response_url:
- response_path, response_parsed = same_origin_path(response_url)
- if response_path != FINAL_PATH or response_parsed.query or response_parsed.fragment:
- return SubmissionSignal.UNKNOWN, evidence, reason
- reason = "response_body"
- raw = response.raw_body
- if not isinstance(raw, str) or not 0 < len(raw) <= MAX_PROTOCOL_PAYLOAD_CHARS:
- return SubmissionSignal.UNKNOWN, evidence, reason
- data = json.loads(raw, object_pairs_hook=_unique_object)
- reason = "response_fields"
- if not isinstance(data, dict) or not {"errorMessage", "url"} <= set(data):
- return SubmissionSignal.UNKNOWN, evidence, reason
- error, destination = data["errorMessage"], data["url"]
- if not isinstance(error, str) or not _final_text(destination):
- return SubmissionSignal.UNKNOWN, evidence, reason
- reason = "response_destination"
- same_origin_path(urljoin(packet.url, destination))
- return (SubmissionSignal.REJECTED if error.strip() else SubmissionSignal.ACCEPTED), evidence, "recognized"
- except Exception:
- return SubmissionSignal.UNKNOWN, evidence, reason
- def classify_final_packet(packet: object, target: FinalTarget) -> SubmissionSignal:
- return inspect_final_packet(packet, target)[0]
- class NativeFinalSubmitter:
- """One native click with the existing listener; no navigation/retry/OTP.
- A process-local latch is not a durable task fence. Production reaches this
- adapter only with explicit final-submit configuration; default pre-final
- CLIs never call it. The opt-in local evidence gate has its own persistent fence.
- """
- def __init__(self, page: object, target: FinalTarget, session_is_current: Callable[[], bool]):
- self.page, self.target, self.session_is_current = page, target, session_is_current
- self._lock = threading.Lock()
- self._consumed = False
- self.submitted_selection: VerifiedSubmission | None = None
- self.diagnostic = {"requestMatched": False, "reason": "not_observed"}
- def __call__(self) -> SubmissionSignal:
- with self._lock:
- if self._consumed:
- raise FinalBookingError("Italy native final attempt is already consumed")
- self._consumed = True
- target = self.target
- def require_context():
- if (self.session_is_current() is not True or self.page.tab_id != target.tab_id
- or same_origin_path(self.page.url)[0] != CALENDAR_PATH):
- raise FinalBookingError("Italy native final context changed")
- def action():
- require_context()
- slot = target.approval.candidate
- raw = self.page.run_js(
- NATIVE_FINAL_SCRIPT, target.runtime_service, slot.day.isoformat(),
- slot.daily_calendar_id, slot.time_label, slot.slots_free,
- )
- if raw != {"clicked": True} or type(raw.get("clicked")) is not bool:
- raise FinalBookingError("Italy native final click was not acknowledged")
- try:
- require_context()
- verify_precommit_selection(self.page, runtime_service=target.runtime_service, approval=target.approval)
- packet = listen_once(self.page, target=FINAL_PATH, method="POST", action=action, timeout=30)
- signal, self.submitted_selection, reason = inspect_final_packet(packet, target)
- self.diagnostic = {"requestMatched": self.submitted_selection is not None, "reason": reason}
- return signal
- except Exception:
- # A lost browser acknowledgement can follow a committed write.
- self.diagnostic = {"requestMatched": False, "reason": "native_or_listener_error"}
- return SubmissionSignal.UNKNOWN
- class FinalBookingAttempt:
- """Single-use orchestration; reconciliation only after a possible write.
- read_reservations must perform a fresh, complete, read-only site read bound
- to this applicant/session. The real read port accepts only empty/cancelled
- baselines, then binds new confirmed receipts to a verified native request. submit_native
- is an injected NativeFinalSubmitter (or an offline test double), not an HTTP
- replay function. Context checks must work after a same-session redirect.
- """
- def __init__(
- self, target: FinalTarget, *, read_reservations: Callable[[], ReservationSnapshot],
- submit_native: Callable[[], SubmissionSignal], session_is_current: Callable[[], bool],
- ):
- if not isinstance(target, FinalTarget) or not all(callable(item) for item in (
- read_reservations, submit_native, session_is_current,
- )):
- raise FinalBookingError("Italy final adapters are required")
- self.target = target
- self._read_reservations = read_reservations
- self._submit_native = submit_native
- self._session_is_current = session_is_current
- self._lock = threading.Lock()
- self._state = "ready"
- self._signal = SubmissionSignal.UNKNOWN
- self._before: ReservationSnapshot | None = None
- @property
- def state(self) -> str:
- return self._state
- def _require_context(self):
- if self._session_is_current() is not True:
- raise FinalBookingError("Italy final applicant or Session changed")
- def _read(self) -> ReservationSnapshot:
- self._require_context()
- started = time.monotonic()
- snapshot = self._read_reservations()
- self._require_context()
- now = time.monotonic()
- if (not isinstance(snapshot, ReservationSnapshot) or snapshot.complete is not True
- or snapshot.applicant != self.target.applicant or snapshot.session_key != self.target.session_key
- or type(snapshot.captured_at) not in (int, float) or not started <= snapshot.captured_at <= now
- or not isinstance(snapshot.records, tuple) or len(snapshot.records) > 512):
- raise FinalBookingError("Italy reservation snapshot is incomplete or not current")
- seen = set()
- for record in snapshot.records:
- if (not isinstance(record, ReservationRecord) or not _final_text(record.reference)
- or record.reference in seen or type(record.day) is not date
- or not _valid_receipt_time(record)
- or not isinstance(record.state, ReservationState) or record.state is ReservationState.UNKNOWN):
- raise FinalBookingError("Italy reservation records require verified identity and status")
- fingerprint = record.receipt_fingerprint
- if fingerprint is not None and (not isinstance(fingerprint, str) or
- re.fullmatch(r"[0-9a-f]{64}", fingerprint) is None):
- raise FinalBookingError("Italy receipt fingerprint is invalid")
- if record.submission is not None and not self._submitted_binding(record):
- raise FinalBookingError("Italy receipt submission evidence does not match this attempt")
- if not _final_text(record.service_id) and not (
- record.service_id is None and fingerprint is not None and
- (record.state is ReservationState.CANCELLED or self._submitted_binding(record))):
- raise FinalBookingError("Italy live reservation service binding is unverified")
- seen.add(record.reference)
- return snapshot
- def _submitted_binding(self, record: ReservationRecord) -> bool:
- slot = self.target.approval.candidate
- return (self._state in {"submitted", "unknown"} and
- isinstance(record.submission, VerifiedSubmission) and
- record.submission.target == self.target and _final_text(self.target.service_name) and
- record.state is ReservationState.ACTIVE and record.service_id is None and
- record.time_label is None and record.receipt_fingerprint is not None and
- record.day == slot.day and isinstance(record.appointment_time, str) and
- slot.time_label[:5] <= record.appointment_time <= slot.time_label[-5:])
- def _live(self, snapshot: ReservationSnapshot) -> list[ReservationRecord]:
- return [record for record in snapshot.records if (record.service_id == self.target.service_id or
- self._submitted_binding(record))
- and record.state in {ReservationState.ACTIVE, ReservationState.WAITLIST}]
- def execute(self, *, enabled: bool = False) -> VSBookResult:
- if enabled is not True:
- raise FinalBookingError("Italy final submission is disabled")
- if not self._lock.acquire(blocking=False):
- raise FinalBookingError("Italy final attempt is already running")
- try:
- if self._state != "ready":
- raise FinalBookingError("Italy final attempt is already consumed")
- self._state = "checking"
- try:
- self._before = self._read()
- self._require_context()
- except Exception:
- self._state = "blocked"
- raise FinalBookingError("Italy final preflight blocked; no submission attempted") from None
- if self._live(self._before):
- self._state = "blocked"
- raise FinalBookingError("Italy service already has an active reservation or waitlist")
- self._state = "submitted"
- try:
- signal = self._submit_native()
- self._signal = signal if isinstance(signal, SubmissionSignal) else SubmissionSignal.UNKNOWN
- except Exception:
- self._signal = SubmissionSignal.UNKNOWN
- return self._reconcile()
- finally:
- # Ctrl-C/SystemExit must not make a possibly dispatched write look
- # unattempted, nor make read-only reconciliation impossible.
- if self._state == "submitted":
- self._state = "unknown"
- elif self._state == "checking":
- self._state = "blocked"
- self._lock.release()
- def reconcile(self) -> VSBookResult:
- """One read-only check. Never enters the native submit path."""
- if not self._lock.acquire(blocking=False):
- raise FinalBookingError("Italy final attempt is already running")
- try:
- if self._state != "unknown":
- raise FinalBookingError("Italy final attempt does not need reconciliation")
- return self._reconcile()
- finally:
- self._lock.release()
- def _reconcile(self) -> VSBookResult:
- self._state = "unknown"
- try:
- after = self._read()
- live = self._live(after)
- before = {record.reference: record for record in self._before.records}
- after_by_id = {record.reference: record for record in after.records}
- # Missing/modified history and unrelated new rows make attribution
- # ambiguous. Do not equate a count increment with this appointment.
- if any(after_by_id.get(key) != value for key, value in before.items()):
- raise FinalOutcomeUnknown()
- new = [record for record in after.records if record.reference not in before]
- slot = self.target.approval.candidate
- if (len(new) == 1 and len(live) == 1 and new[0] == live[0]
- and live[0].state is ReservationState.ACTIVE and live[0].day == slot.day
- and (live[0].time_label == slot.time_label or self._submitted_binding(live[0]))
- and self._signal is not SubmissionSignal.REJECTED):
- self._state = "confirmed"
- return VSBookResult(
- success=True, account=self.target.applicant, urn=live[0].reference,
- book_date=slot.day.isoformat(), book_time=live[0].appointment_time or slot.time_label,
- )
- if not new and not live and self._signal is SubmissionSignal.REJECTED:
- self._state = "rejected"
- return VSBookResult(success=False, label="italy-final-rejected")
- except Exception:
- pass
- self._state = "unknown"
- raise FinalOutcomeUnknown() from None
- # ============================================================================
- # RESERVATION (from plugins/ita_reservation.py)
- # ============================================================================
- """Read-only Prenot@Mi receipt adapter, not a final-submit read port.
- These objects contain observed display facts, not an inferred service/account
- binding or proof linking an assigned appointment time to a selected slot.
- Only observed Italian cancelled/confirmed states are classified; others stay UNKNOWN.
- No navigation, credentials, OTP, form writes or final actions live here.
- """
- import math
- import re
- import time
- from dataclasses import dataclass, field
- from datetime import date
- LIST_PATH = "/Reservation"
- DETAIL_PREFIX = "/ReservationDetail/Index/"
- HEADERS = ("Codice Prenotazione", "Ufficio", "Servizio", "Data", "Ora", "Stato", "Dati Richiedente")
- DETAIL_LABELS = ("Servizio Consolare", "Servizio Erogato", "Codice Prenotazione",
- "Tipo Prenotazione", "Data", "Ora", "Stato")
- MONTHS_IT = ("gennaio", "febbraio", "marzo", "aprile", "maggio", "giugno", "luglio",
- "agosto", "settembre", "ottobre", "novembre", "dicembre")
- class ReservationReadError(ValueError):
- """Only adapter-owned reason codes; never include DOM text or browser errors."""
- def __init__(self, reason: str):
- self.reason = reason
- super().__init__(f"Italy reservation read rejected: {reason}")
- @dataclass(frozen=True, slots=True, repr=False)
- class ReservationDetail:
- reference: str
- office: str
- service_name: str
- booking_type: str
- day: date
- appointment_time: str
- status_text: str
- status_code: str
- state: ReservationState
- @dataclass(frozen=True, slots=True, repr=False)
- class ReservationListRow:
- reference: str
- detail_url: str
- office: str
- service_name: str
- day: date
- appointment_time: str
- status_text: str
- state: ReservationState
- @dataclass(frozen=True, slots=True)
- class ReservationListing:
- """Coverage of the loaded client data, NOT a fresh account-bound snapshot."""
- rows: tuple[ReservationListRow, ...] = field(repr=False)
- page_count: int
- waitlist_count: int = 0
- _CONTEXT_JS = r"""
- const clean = s => String(s || '').replace(/\s+/g, ' ').trim();
- const fail = reason => ({error: reason});
- if (window.location.origin !== 'https://prenotami.esteri.it') return fail('wrong_page');
- if (document.readyState !== 'complete') return fail('not_ready');
- if (!document.querySelector('.app-menu')) return fail('authentication_missing');
- """
- DETAIL_READ_SCRIPT = _CONTEXT_JS + r"""
- /* coordinate:ita-reservation-detail-readonly */
- if (!/^\/ReservationDetail\/Index\/[^/]+$/.test(window.location.pathname)) return fail('wrong_page');
- const headings = Array.from(document.querySelectorAll('h4'));
- const booking = headings.filter(e => clean(e.textContent) === 'Dati Prenotazione');
- const applicant = headings.filter(e => clean(e.textContent) === 'Dati Richiedente');
- if (booking.length !== 1 || applicant.length !== 1) return fail('section_ambiguous');
- const root = booking[0].parentElement;
- if (!root || !root.classList.contains('my-col-6') || root.contains(applicant[0])) return fail('unsafe_scope');
- const nameOf = e => clean(e.textContent).match(
- /^\*?\s*(Servizio Consolare|Servizio Erogato|Codice Prenotazione|Tipo Prenotazione|Data|Ora|Stato)\s*:\s*$/)?.[1];
- const labels = Array.from(root.querySelectorAll('label')).filter(nameOf);
- if (labels.length !== 7 || new Set(labels.map(nameOf)).size !== 7) return fail('fields_ambiguous');
- const fields = {};
- for (const label of labels) {
- const row = label.parentElement;
- if (labels.filter(e => row.contains(e)).length !== 1) return fail('row_ambiguous');
- const values = [];
- for (const node of row.childNodes) {
- if (node === label || node.nodeType === 8) continue;
- // The observed values are text siblings or one b. Do not read nested
- // forms, print payloads, applicant sections or arbitrary HTML as values.
- if (node.nodeType !== 3 && !(node.nodeType === 1 && node.tagName === 'B' && node.children.length === 0))
- return fail('value_structure_changed');
- const value = clean(node.textContent);
- if (value) values.push(value);
- }
- if (values.length !== 1 || values[0].length > 256) return fail('value_ambiguous');
- fields[nameOf(label)] = values[0];
- }
- const codes = document.querySelectorAll('input#IDTipoStatoPrenotazione');
- if (codes.length !== 1 || codes[0].type !== 'hidden' || codes[0].name !== 'IDTipoStatoPrenotazione')
- return fail('status_control_ambiguous');
- return {path: window.location.pathname, fields, statusCode: clean(codes[0].value)};
- """
- LIST_READ_SCRIPT = _CONTEXT_JS + r"""
- /* coordinate:ita-reservation-list-readonly */
- if (window.location.pathname !== '/Reservation') return fail('wrong_page');
- const readDateCell = cell => {
- // Observed shape: optional hidden element(s), one non-empty text sibling.
- // Do not use the whole cell's textContent (includes hidden metadata), nor
- // innerText (unrendered DataTables pages can fall back to textContent).
- const nodes = Array.from(cell.childNodes), values = [];
- if (nodes.length > 16) return null;
- for (const node of nodes) {
- if (node.nodeType === 8) continue;
- if (node.nodeType === 3) {
- const value = clean(node.textContent);
- if (value) values.push(value);
- continue;
- }
- if (node.nodeType !== 1) return null;
- const style = window.getComputedStyle(node);
- // Own inline/hidden markers remain checkable for detached client rows.
- // visibility:hidden only proves a leaf hidden: descendants can override it.
- const hidden = node.hidden === true || node.style.display === 'none' || style.display === 'none';
- const hiddenLeaf = node.children.length === 0 &&
- (node.style.visibility === 'hidden' || style.visibility === 'hidden');
- if (!hidden && !hiddenLeaf) return null;
- // Hidden metadata is excluded structurally; never parse or log its value.
- }
- return values.length === 1 ? values[0] : null;
- };
- const $ = window.jQuery;
- const ids = ['dataTableReservations', 'dataTableReservationsWL'];
- const tables = [];
- for (const id of ids) {
- const matches = document.querySelectorAll('#' + id);
- if (matches.length !== 1) return fail('table_ambiguous');
- const table = matches[0];
- const headers = Array.from(table.querySelectorAll('thead th')).map(e => clean(e.textContent));
- if (!$?.fn?.dataTable?.isDataTable(table)) {
- const empty = table.querySelectorAll('tbody tr').length === 0 && headers.length === 0 &&
- !table.classList.contains('dataTable') && !table.closest('.dataTables_wrapper');
- if (id !== ids[1] || !empty) return fail('not_ready');
- tables.push({id, structuralEmpty: true});
- continue;
- }
- // This getter is only used after isDataTable: it must never initialize a table.
- const api = $(table).DataTable(), pageInfo = api.page.info();
- const info = Object.fromEntries(['page', 'pages', 'start', 'end', 'length',
- 'recordsTotal', 'recordsDisplay', 'serverSide'].map(k => [k, pageInfo[k]]));
- const count = api.rows().count();
- if (!Number.isInteger(count) || count < 0 || count > 512) return fail('row_limit');
- if (info.serverSide !== false || api.search() || api.columns().search().toArray().some(Boolean) ||
- count !== info.recordsTotal || count !== info.recordsDisplay || api.rows({search: 'applied'}).count() !== count)
- return fail('coverage_incomplete');
- if (id === ids[1]) {
- if (count !== 0) return fail('waitlist_schema_unverified');
- tables.push({id, structuralEmpty: false, count, info});
- continue;
- }
- const expected = ['Codice Prenotazione', 'Ufficio', 'Servizio', 'Data', 'Ora', 'Stato', 'Dati Richiedente'];
- if (![7, 8].includes(headers.length) || expected.some((h, i) => headers[i] !== h) ||
- (headers.length === 8 && headers[7] !== '')) return fail('headers_changed');
- const nodes = api.rows().nodes().toArray();
- if (nodes.length !== count) return fail('row_nodes_incomplete');
- const rows = [];
- for (const node of nodes) {
- const cells = Array.from(node.children);
- if (cells.length !== headers.length || cells.some(c => c.tagName !== 'TD')) return fail('cells_changed');
- const links = cells[0].querySelectorAll('a[href]');
- if (links.length !== 1) return fail('detail_link_ambiguous');
- const date = readDateCell(cells[3]);
- if (date === null) return fail('date_cell_structure_changed');
- const row = {reference: clean(cells[0].textContent), detailUrl: links[0].href,
- office: clean(cells[1].textContent), service: clean(cells[2].textContent),
- date, time: clean(cells[4].textContent), status: clean(cells[5].textContent)};
- if (Object.values(row).some(v => typeof v !== 'string' || !v || v.length > 256)) return fail('field_invalid');
- rows.push(row);
- // Do not access applicant cell 6 or unnamed cell 7.
- }
- tables.push({id, structuralEmpty: false, headers, count, info, rows});
- }
- return {path: window.location.pathname, tables};
- """
- DATE_DIAGNOSTIC_SCRIPT = _CONTEXT_JS + r"""
- /* coordinate:ita-reservation-date-diagnostic-readonly */
- if (window.location.pathname !== '/Reservation') return fail('wrong_page');
- const tables = document.querySelectorAll('#dataTableReservations');
- if (tables.length !== 1) return fail('table_ambiguous');
- const table = tables[0], $ = window.jQuery;
- const headers = Array.from(table.querySelectorAll('thead th')).map(e => clean(e.textContent));
- const expected = ['Codice Prenotazione', 'Ufficio', 'Servizio', 'Data', 'Ora', 'Stato', 'Dati Richiedente'];
- if (![7,8].includes(headers.length) || expected.some((v,i) => headers[i] !== v) ||
- (headers.length === 8 && headers[7] !== '') || !$?.fn?.dataTable?.isDataTable(table))
- return fail('headers_changed');
- const nodes = $(table).DataTable().rows().nodes().toArray();
- if (nodes.length > 512) return fail('row_limit');
- const samples = [];
- for (const row of nodes.slice(0,3)) {
- const cells = Array.from(row.children);
- if (cells.length !== headers.length || cells.some(c => c.tagName !== 'TD')) return fail('cells_changed');
- // Only the verified Data column. No reference, account, applicant, HTML or attributes.
- const cell = cells[3], children = Array.from(cell.childNodes);
- const text = clean(cell.textContent), rendered = clean(cell.innerText);
- if (text.length > 256 || rendered.length > 256) return fail('field_invalid');
- const parts = children.slice(0,6).map(n => {
- const style = n.nodeType === 1 ? window.getComputedStyle(n) : null;
- return {kind: n.nodeType === 3 ? 'text' : (n.nodeType === 1 &&
- ['SPAN','B','I','BR'].includes(n.tagName) ? n.tagName.toLowerCase() : 'other'),
- text: clean(n.textContent), hidden: !!style && (style.display === 'none' || style.visibility === 'hidden')};
- });
- samples.push({text, rendered, parts, partsTruncated: children.length > 6});
- }
- return {path: window.location.pathname, samples, rowsTruncated: nodes.length > 3};
- """
- def _date_shape(value: object) -> dict:
- """Only structural symbols and known month indexes; never emit raw field text."""
- if not isinstance(value, str) or len(value) > 256:
- raise ValueError()
- normalized = " ".join(value.split())
- shape = "".join("D" if c.isdecimal() else "L" if c.isalpha() else c if c in " /:.,-" else "?"
- for c in normalized[:96])
- months = [i for i, month in enumerate(MONTHS_IT, 1)
- if re.search(r"(?<![A-Za-z])" + month + r"(?![A-Za-z])", normalized, re.IGNORECASE)]
- try:
- _day(normalized)
- accepted = True
- except ReservationReadError:
- accepted = False
- return {"shape": shape, "length": len(normalized), "truncated": len(normalized) > 96,
- "italianMonths": months, "acceptedByCurrentParser": accepted}
- def read_reservation_date_diagnostic(page: object) -> dict:
- """One bounded extra read on a failed list parse, not an alternate parser.
- The raw verified date-cell strings stay local; only allowlisted shapes leave
- this function. A malformed diagnostic cannot leak arbitrary browser output.
- """
- try:
- raw = _read_current(page, DATE_DIAGNOSTIC_SCRIPT, detail=False)
- if (set(raw) != {"path", "samples", "rowsTruncated"} or
- type(raw["rowsTruncated"]) is not bool or not isinstance(raw["samples"], list) or
- len(raw["samples"]) > 3):
- raise ValueError()
- samples = []
- for item in raw["samples"]:
- if (not isinstance(item, dict) or set(item) != {"text", "rendered", "parts", "partsTruncated"} or
- type(item["partsTruncated"]) is not bool or not isinstance(item["parts"], list) or
- len(item["parts"]) > 6):
- raise ValueError()
- parts = []
- for part in item["parts"]:
- if (not isinstance(part, dict) or set(part) != {"kind", "text", "hidden"} or
- part["kind"] not in ("text", "span", "b", "i", "br", "other") or
- type(part["hidden"]) is not bool):
- raise ValueError()
- parts.append({"kind": part["kind"], "hidden": part["hidden"], **_date_shape(part["text"])})
- samples.append({"text": _date_shape(item["text"]), "rendered": _date_shape(item["rendered"]),
- "textEqualsRendered": item["text"] == item["rendered"],
- "parts": parts, "partsTruncated": item["partsTruncated"]})
- return {"available": True, "samples": samples, "rowsTruncated": raw["rowsTruncated"]}
- except Exception:
- return {"available": False}
- def _reservation_text(value: object) -> str:
- if (not isinstance(value, str) or not 0 < len(value) <= 256 or value != value.strip()
- or any(ord(c) < 32 or ord(c) == 127 for c in value)):
- raise ReservationReadError("field_invalid")
- return value
- def _day(value: object) -> date:
- value = _reservation_text(value)
- match = re.fullmatch(r"([0-9]{1,2}) ([A-Za-z]+) ([0-9]{4})", value)
- if match:
- try:
- return date(int(match[3]), MONTHS_IT.index(match[2].casefold()) + 1, int(match[1]))
- except ValueError:
- pass
- raise ReservationReadError("date_unrecognized") from None
- def _appointment_time(value: object) -> str:
- value = _reservation_text(value)
- if re.fullmatch(r"(?:[01][0-9]|2[0-3]):[0-5][0-9]", value) is None:
- raise ReservationReadError("time_unrecognized")
- return value
- def _state(text: str, code: str | None = None) -> ReservationState:
- # A list label is a candidate; a detail must also have its observed code.
- # Never infer ACTIVE from "not cancelled" or from the numeric code alone.
- if text.casefold() == "annullata" and code in (None, "3"):
- return ReservationState.CANCELLED
- if text.casefold() == "confermata" and code in (None, "2"):
- return ReservationState.ACTIVE
- return ReservationState.UNKNOWN
- def _detail_path(url: object) -> str:
- try:
- path, parsed = same_origin_path(url)
- suffix = path.removeprefix(DETAIL_PREFIX)
- if (not path.startswith(DETAIL_PREFIX) or not suffix or len(suffix) > 256
- or any(c in suffix for c in "/\\%") or suffix in {".", ".."}
- or parsed.query or parsed.fragment):
- raise ValueError()
- return path
- except Exception:
- raise ReservationReadError("detail_url_invalid") from None
- def parse_reservation_detail(raw: object) -> ReservationDetail:
- if not isinstance(raw, dict) or set(raw) != {"path", "fields", "statusCode"}:
- raise ReservationReadError("detail_schema_changed")
- _detail_path("https://prenotami.esteri.it" + raw["path"] if isinstance(raw["path"], str) else None)
- fields = raw["fields"]
- if not isinstance(fields, dict) or set(fields) != set(DETAIL_LABELS):
- raise ReservationReadError("fields_ambiguous")
- values = {key: _reservation_text(value) for key, value in fields.items()}
- code = raw["statusCode"]
- if not isinstance(code, str) or not re.fullmatch(r"[0-9]{1,4}", code):
- raise ReservationReadError("status_code_invalid")
- return ReservationDetail(
- values["Codice Prenotazione"], values["Servizio Consolare"], values["Servizio Erogato"],
- values["Tipo Prenotazione"], _day(values["Data"]), _appointment_time(values["Ora"]),
- values["Stato"], code, _state(values["Stato"], code),
- )
- def _coverage(table: dict) -> tuple[int, int]:
- info, count = table.get("info"), table.get("count")
- if not isinstance(info, dict) or type(count) is not int or not 0 <= count <= MAX_PROTOCOL_ITEMS:
- raise ReservationReadError("coverage_invalid")
- keys = ("recordsTotal", "recordsDisplay", "page", "pages", "start", "end", "length")
- if any(type(info.get(k)) is not int for k in keys) or info.get("serverSide") is not False:
- raise ReservationReadError("coverage_invalid")
- total, displayed, page, pages, start, end, length = (info[k] for k in keys)
- if total != count or displayed != count or not 0 <= start <= end <= count:
- raise ReservationReadError("coverage_incomplete")
- expected_pages = (math.ceil(count / length) if length > 0 else 1) if count else 0
- if (length not in (-1,) and length <= 0) or pages != expected_pages or not 0 <= page < max(1, pages):
- raise ReservationReadError("pagination_invalid")
- if start != (page * length if length > 0 else 0) or end != (min(start + length, count) if length > 0 else count):
- raise ReservationReadError("pagination_invalid")
- return count, pages
- def parse_reservation_listing(raw: object) -> ReservationListing:
- if not isinstance(raw, dict) or set(raw) != {"path", "tables"} or raw["path"] != LIST_PATH:
- raise ReservationReadError("list_schema_changed")
- tables = raw["tables"]
- if not isinstance(tables, list) or len(tables) != 2 or not all(isinstance(t, dict) for t in tables):
- raise ReservationReadError("table_ambiguous")
- main, waitlist = tables
- if main.get("id") != "dataTableReservations" or waitlist.get("id") != "dataTableReservationsWL":
- raise ReservationReadError("table_ambiguous")
- if main.get("structuralEmpty") is not False or main.get("headers") not in (list(HEADERS), [*HEADERS, ""]):
- raise ReservationReadError("headers_changed")
- count, pages = _coverage(main)
- if waitlist.get("structuralEmpty") is True:
- if set(waitlist) != {"id", "structuralEmpty"}:
- raise ReservationReadError("waitlist_ambiguous")
- elif waitlist.get("structuralEmpty") is not False or _coverage(waitlist)[0] != 0:
- raise ReservationReadError("waitlist_schema_unverified")
- rows = main.get("rows")
- if not isinstance(rows, list) or len(rows) != count:
- raise ReservationReadError("row_nodes_incomplete")
- result, references, destinations = [], set(), set()
- for row in rows:
- if not isinstance(row, dict) or set(row) != {"reference", "detailUrl", "office", "service", "date", "time", "status"}:
- raise ReservationReadError("row_schema_changed")
- values = {key: _reservation_text(value) for key, value in row.items()}
- path = _detail_path(values["detailUrl"])
- if values["reference"] in references or path in destinations:
- raise ReservationReadError("duplicate_record")
- references.add(values["reference"])
- destinations.add(path)
- result.append(ReservationListRow(values["reference"], values["detailUrl"], values["office"],
- values["service"], _day(values["date"]), _appointment_time(values["time"]),
- values["status"], _state(values["status"])))
- return ReservationListing(tuple(result), pages)
- def _read_current(page: object, script: str, *, detail: bool) -> object:
- try:
- before_url, before_tab = page.url, page.tab_id
- path, parsed = same_origin_path(before_url)
- if parsed.query or parsed.fragment or (not detail and path != LIST_PATH):
- raise ReservationReadError("wrong_page")
- if detail:
- _detail_path(before_url)
- if not isinstance(before_tab, str) or not before_tab:
- raise ReservationReadError("context_changed")
- raw = page.run_js(script)
- if page.url != before_url or page.tab_id != before_tab:
- raise ReservationReadError("context_changed")
- if not isinstance(raw, dict) or raw.get("path") != path:
- reason = "not_ready" if isinstance(raw, dict) and raw == {"error": "not_ready"} else "page_read_rejected"
- raise ReservationReadError(reason)
- return raw
- except ReservationReadError:
- raise
- except Exception:
- raise ReservationReadError("browser_read_failed") from None
- def read_reservation_detail(page: object) -> ReservationDetail:
- """Read the current detail page once. No URL, reference or PII is logged."""
- return parse_reservation_detail(_read_current(page, DETAIL_READ_SCRIPT, detail=True))
- def read_reservation_listing(page: object, *, timeout: float = 5, poll_interval: float = 0.25) -> ReservationListing:
- """Two stable reads within a bound, reusing the existing count tool pattern.
- Only not-ready states are polled; unsupported schemas/coverage fail closed.
- This checks the current page and never navigates, draws or clears filters.
- """
- if (any(type(v) not in (int, float) or not math.isfinite(v) or v <= 0 for v in (timeout, poll_interval))
- or poll_interval > timeout or timeout > 60):
- raise ReservationReadError("wait_config_invalid")
- try:
- binding = (page.url, page.tab_id)
- except Exception:
- raise ReservationReadError("browser_read_failed") from None
- deadline, previous = time.monotonic() + timeout, None
- while time.monotonic() < deadline:
- try:
- try:
- context_matches = (page.url, page.tab_id) == binding
- except Exception:
- raise ReservationReadError("browser_read_failed") from None
- if not context_matches:
- raise ReservationReadError("context_changed")
- current = parse_reservation_listing(_read_current(page, LIST_READ_SCRIPT, detail=False))
- except ReservationReadError as error:
- if error.reason != "not_ready":
- raise
- previous = None
- else:
- if current == previous:
- return current
- previous = current
- time.sleep(min(poll_interval, max(0, deadline - time.monotonic())))
- raise ReservationReadError("stability_timeout")
- # ============================================================================
- # FINAL_READ_PORT (from plugins/ita_final_read_port.py)
- # ============================================================================
- """Read-port adapter shared by production Book and local final validation.
- Preserves the applicant Calendar in its original tab. Reads existing receipts in
- an owned background tab of the SAME browser/context. Baselines allow only empty
- or cancelled history. A new confirmed receipt may bind to a verified native POST;
- observed receipt fields remain distinct from submission evidence.
- """
- import hashlib
- import json
- import threading
- import time
- from dataclasses import dataclass, field
- from uuid import uuid4
- from urllib.parse import parse_qsl
- LIST_URL = "https://prenotami.esteri.it/Reservation"
- MAX_DETAIL_READS = 20
- @dataclass(frozen=True, repr=False)
- class ReceiptObservation:
- """Bound display evidence only; UNKNOWN is never promoted to success."""
- records: tuple = field(repr=False) # (verified list row, matching detail)
- def _require(condition, reason):
- if condition is not True:
- raise FinalBookingError(reason)
- def _cancelled_record(row, detail) -> ReservationRecord:
- _require(row.state is ReservationState.CANCELLED and detail.state is ReservationState.CANCELLED and
- detail.status_code == "3" and all(getattr(row, field) == getattr(detail, field) for field in (
- "reference", "office", "service_name", "day", "appointment_time", "status_text")),
- "Italy cancelled receipt is not verified")
- # Equality of fingerprints preserves changes to fields absent from the final
- # model (office, displayed service, booking type). It is NOT identity proof.
- facts = [detail.reference, row.detail_url, detail.office, detail.service_name, detail.booking_type,
- detail.day.isoformat(), detail.appointment_time, detail.status_text, detail.status_code]
- digest = hashlib.sha256(json.dumps(facts, ensure_ascii=True, separators=(",", ":")).encode()).hexdigest()
- return ReservationRecord(detail.reference, None, detail.day, None, ReservationState.CANCELLED,
- appointment_time=detail.appointment_time, receipt_fingerprint=digest)
- def _confirmed_record(row, detail, submission: VerifiedSubmission) -> ReservationRecord:
- target, slot = submission.target, submission.target.approval.candidate
- _require(row.state is ReservationState.ACTIVE and detail.state is ReservationState.ACTIVE and
- detail.status_code == "2" and detail.booking_type == "Prenotazione Singola" and
- isinstance(target.service_name, str) and detail.service_name == target.service_name and
- detail.day == slot.day and slot.time_label[:5] <= detail.appointment_time <= slot.time_label[-5:] and
- all(getattr(row, key) == getattr(detail, key) for key in (
- "reference", "office", "service_name", "day", "appointment_time", "status_text")),
- "Italy confirmed receipt does not match the submitted selection")
- facts = [detail.reference, row.detail_url, detail.office, detail.service_name, detail.booking_type,
- detail.day.isoformat(), detail.appointment_time, detail.status_text, detail.status_code]
- digest = hashlib.sha256(json.dumps(facts, ensure_ascii=True, separators=(",", ":")).encode()).hexdigest()
- # The website receipt supplies neither service_id nor the selected interval.
- # Keep them None; the separate evidence explicitly identifies the native POST.
- return ReservationRecord(detail.reference, None, detail.day, None, ReservationState.ACTIVE,
- appointment_time=detail.appointment_time, receipt_fingerprint=digest,
- submission=submission)
- class FinalReceiptReadPort:
- """Capture an existing applicant Book precommit, then read fresh snapshots.
- Uses the plugin's established session/route checks, not a caller-supplied
- username assertion. Constructor does no navigation. Calling the port reads
- only; it never touches final buttons, rebuilds calendars or generates OTP.
- The owning Book workflow must serialize this with other browser work.
- """
- def __init__(self, plugin, route: ItaRouteConfig, *, observe_tab=None):
- try:
- _require(isinstance(route, ItaRouteConfig) and
- route.capability is ItaCapability.SINGLE_SCHENGEN_TOURISM,
- "Italy final read route is invalid")
- self._plugin, self._route = plugin, route
- _require(observe_tab is None or callable(observe_tab), "Italy receipt observer is invalid")
- self._observe_tab = observe_tab
- self._page = plugin.page
- self._browser = self._page.browser
- self._browser_id = self._browser.id
- self._generation = plugin.session_create_time
- self._prepared = plugin._calendar_book_prepared_context
- self._approval = plugin.last_booking_precommit
- self._username = plugin.config.account.username.strip().casefold()
- _require(isinstance(self._approval, PrecommitApproval) and
- isinstance(self._prepared, tuple) and len(self._prepared) == 7 and
- isinstance(self._browser_id, str) and bool(self._browser_id) and
- same_origin_path(self._page.url)[0] == CALENDAR_PATH,
- "Italy final read requires the current Book precommit")
- _, calendar_url = same_origin_path(self._page.url)
- names = [value for key, value in parse_qsl(calendar_url.query, keep_blank_values=True)
- if key == "selectedService"]
- service_name = names[0] if len(names) == 1 and names[0] else None
- self._target = FinalTarget(self._username, uuid4().hex, self._page.tab_id,
- route.routing_key, str(route.service_id), self._prepared[5], self._approval,
- service_name=service_name)
- self._lock = threading.Lock()
- self._unusable = False
- self._baseline = None
- self._submission = None
- _require(self.session_is_current(), "Italy final read Session is not current")
- except Exception:
- raise FinalBookingError("Italy final read context could not be captured") from None
- @property
- def target(self):
- return self._target
- def session_is_current(self) -> bool:
- try:
- p = self._plugin
- same_origin_path(self._page.url)
- return (not self._unusable and p.page is self._page and self._page.browser is self._browser and
- self._browser.id == self._browser_id and self._page.tab_id == self._target.tab_id and
- p.session_create_time == self._generation and p.is_healthy is True and
- p.last_booking_precommit is self._approval and
- p._calendar_book_prepared_context == self._prepared and
- p.config.account.username.strip().casefold() == self._username and
- p._calendar_book_context_matches(self._route, self._username) is True)
- except Exception:
- return False
- def __call__(self) -> ReservationSnapshot:
- snapshot = self._read(observation=False)
- if self._submission is None:
- self._baseline = snapshot
- return snapshot
- def record_submission(self, submission: VerifiedSubmission) -> None:
- """Called only after a matched native POST and one-request audit."""
- _require(self.session_is_current() and self._baseline is not None and self._submission is None and
- isinstance(submission, VerifiedSubmission) and submission.target == self.target and
- self.target.service_name is not None, "Italy submission binding is not current")
- self._submission = submission
- def observe_receipts(self) -> ReceiptObservation:
- """Read unknown status text for controlled discovery, NOT reconciliation."""
- return self._read(observation=True)
- def _read(self, *, observation: bool):
- if not self._lock.acquire(blocking=False):
- raise FinalBookingError("Italy receipt read is already running")
- receipt_page = None
- finish_observation = None
- close_failed = False
- cleanup_interrupt = None
- try:
- _require(self.session_is_current(), "Italy final read Session changed")
- origin = (self._page.url, self._page.tab_id)
- candidate = self._browser.new_tab(background=True, new_context=False)
- # Only close a separately identified tab created by our own browser.
- # A broken factory returning the original/foreign page is not owned.
- _require(candidate is not self._page and candidate.browser is self._browser and
- isinstance(candidate.tab_id, str) and bool(candidate.tab_id) and
- candidate.tab_id != self._target.tab_id, "Italy receipt tab ownership is unverified")
- receipt_page, receipt_tab = candidate, candidate.tab_id
- if self._observe_tab is not None:
- finish_observation = self._observe_tab(receipt_page)
- _require(callable(finish_observation), "Italy receipt observer did not start")
- def context():
- _require(self.session_is_current() and (self._page.url, self._page.tab_id) == origin and
- receipt_page.browser is self._browser and receipt_page.tab_id == receipt_tab,
- "Italy receipt read context changed")
- def navigate(url):
- context()
- _require(receipt_page.get(url, retry=0, timeout=30) is not False,
- "Italy receipt navigation failed")
- context()
- same_origin_path(receipt_page.url)
- _require(receipt_page.url == url, "Italy receipt navigation was redirected")
- navigate(LIST_URL)
- before = read_reservation_listing(receipt_page)
- context()
- _require(before.waitlist_count == 0 and len(before.rows) <= MAX_DETAIL_READS,
- "Italy receipt coverage exceeds supported verification")
- if not observation and self._submission is None:
- _require(all(row.state is ReservationState.CANCELLED for row in before.rows),
- "Italy live receipt attribution is not verified")
- records = []
- for row in before.rows:
- # Only actual links accepted by the established listing parser.
- navigate(row.detail_url)
- detail = read_reservation_detail(receipt_page)
- context()
- _require(all(getattr(row, key) == getattr(detail, key) for key in (
- "reference", "office", "service_name", "day", "appointment_time", "status_text")),
- "Italy observed receipt does not match its list row")
- if observation:
- records.append((row, detail))
- elif row.state is ReservationState.CANCELLED:
- records.append(_cancelled_record(row, detail))
- else:
- _require(self._submission is not None and self._baseline is not None and
- row.reference not in {r.reference for r in self._baseline.records},
- "Italy receipt is not new to this submission")
- records.append(_confirmed_record(row, detail, self._submission))
- navigate(LIST_URL)
- after = read_reservation_listing(receipt_page)
- context()
- _require({r.reference: r for r in before.rows} == {r.reference: r for r in after.rows} and
- before.waitlist_count == after.waitlist_count, "Italy receipt history changed during read")
- snapshot = (ReceiptObservation(tuple(records)) if observation else
- ReservationSnapshot(self._target.applicant, self._target.session_key,
- time.monotonic(), True, tuple(records)))
- except Exception:
- raise FinalBookingError("Italy bound receipt read could not be verified") from None
- finally:
- if callable(finish_observation):
- try:
- finish_observation()
- except BaseException as exc:
- self._unusable = True
- if isinstance(exc, Exception):
- close_failed = True
- else:
- cleanup_interrupt = exc
- if receipt_page is not None:
- try:
- receipt_page.close()
- except BaseException as exc:
- # Do not trust a later read after losing control of an owned tab.
- self._unusable = True
- if isinstance(exc, Exception):
- close_failed = True
- else:
- cleanup_interrupt = exc
- self._lock.release()
- if cleanup_interrupt is not None:
- raise cleanup_interrupt
- if close_failed:
- raise FinalBookingError("Italy owned receipt tab cleanup failed") from None
- _require(self.session_is_current() and (self._page.url, self._page.tab_id) == origin,
- "Italy final read context changed during cleanup")
- return snapshot
- # ============================================================================
- # CALENDAR_SESSION (from plugins/ita_calendar_session.py)
- # ============================================================================
- """Shared Italy form preparation and passive request audit.
- Extracted from the real-tested Calendar gate. Production and diagnostic tools
- use the same protocol; no tool imports, credentials, or network calls on import.
- """
- import json
- import time
- from enum import Enum
- from threading import Lock
- from urllib.parse import parse_qs, urljoin, urlparse
- _header = header_value; _same_origin_path = same_origin_path
- OTP_PATH = "/BookingCalendar/GenerateOTP"
- def booking_preflight_state(raw: object) -> str:
- """Classify observed readiness, not the unknown cause of a widget failure."""
- if not isinstance(raw, dict):
- return "snapshot_unavailable"
- token, disabled = raw.get("turnstileTokenPresent"), raw.get("avantiDisabled")
- if type(token) is not bool or type(disabled) is not bool:
- return "invalid_snapshot"
- if not token:
- return "turnstile_and_avanti_pending" if disabled else "turnstile_token_pending"
- return "avanti_disabled" if disabled else "ready"
- def safe_booking_preflight_diagnostic(raw: object, *, stage, outcome: str) -> dict:
- """Only bounded booleans/counts and fixed categories; never token/value/HTML."""
- snapshot = raw if isinstance(raw, dict) else {}
- result = {
- "contract": "ita-book-preflight-v2",
- "stage": stage.value if isinstance(stage, BookingPreflightStage) else "invalid",
- "outcome": outcome if outcome in {"ready", "waiting", "rejected", "timeout", "read_failed"} else "invalid",
- "state": booking_preflight_state(raw),
- }
- for key in ("pathMatches", "formPresent", "privacyChecked", "otpDisabled", "otpValuePresent",
- "turnstileTokenPresent", "avantiDisabled", "turnstileApiPresent",
- "turnstileScriptPresent", "documentVisible"):
- value = snapshot.get(key)
- result[key] = value if type(value) is bool else None
- for key in ("turnstileCount", "avantiButtonCount", "unknownRequiredCount"):
- value = snapshot.get(key)
- result[key] = value if type(value) is int and 0 <= value <= 1000 else None
- return result
- def _print_booking_preflight_diagnostic(raw: object, *, stage, outcome: str) -> None:
- print("ITA_BOOK_PREFLIGHT_DIAGNOSTIC=" + json.dumps(
- safe_booking_preflight_diagnostic(raw, stage=stage, outcome=outcome), sort_keys=True,
- ), flush=True)
- def wait_for_booking_preflight(
- page: object,
- *,
- script: str,
- stage: BookingPreflightStage = None,
- timeout: float = 120,
- diagnostic=None,
- wait_action=None,
- check_current=None,
- ) -> dict[str, object]:
- """Wait without relaxing structure; optional bounded form interaction.
- An interaction return value is never evidence of readiness: only the next
- validated site snapshot can permit OTP/AVANTI. No recovery is enabled by
- default; callers must explicitly supply their preparation recovery.
- """
- stage = stage if stage is not None else BookingPreflightStage.BEFORE_OTP_SEND
- report = diagnostic or _print_booking_preflight_diagnostic
- started = time.monotonic()
- deadline = started + timeout
- announced = False
- raw = None
- last_state = None
- next_report = started
- while (now := time.monotonic()) < deadline:
- if check_current is not None:
- check_current()
- try:
- raw = page.run_js(script)
- except Exception:
- report(None, stage=stage, outcome="read_failed")
- raise CalendarGateError("Italy booking preflight read_failed") from None
- if check_current is not None:
- check_current()
- try:
- _validate_preflight_except_dynamic_token(raw, stage=stage)
- except CalendarGateError:
- report(
- raw,
- stage=stage,
- outcome="rejected",
- )
- raise
- if raw.get("turnstileTokenPresent") and not raw.get("avantiDisabled"):
- try:
- validate_booking_preflight(raw, stage=stage)
- except CalendarGateError:
- report(
- raw,
- stage=stage,
- outcome="rejected",
- )
- raise
- report(
- raw,
- stage=stage,
- outcome="ready",
- )
- return raw
- if not announced:
- print("ITA_BOOK_WAITING_FOR_FORM: watch the opened browser; complete any human verification. "
- "Do not click OTP, AVANTI, or final Prenota.", flush=True)
- announced = True
- state = booking_preflight_state(raw)
- if state != last_state or now >= next_report:
- report(raw, stage=stage, outcome="waiting")
- last_state, next_report = state, now + 15
- if wait_action is not None:
- wait_action(raw, stage=stage, elapsed=now - started, remaining=deadline - now)
- time.sleep(0.5)
- report(raw, stage=stage, outcome="timeout")
- raise CalendarGateError(f"Italy booking preflight timed out: {booking_preflight_state(raw)}")
- def guarded_preflight_script(route: ItaRouteConfig, booking_path: str) -> str:
- """Check scope before the reused script changes any visible form control."""
- prefix = """
- /* coordinate:ita-book-gate-form-boundary */
- const bookGateForms = document.querySelectorAll('#bookingForm');
- const bookGateForm = bookGateForms.length === 1 ? bookGateForms[0] : null;
- let bookGateAction = null;
- try { bookGateAction = bookGateForm ? new URL(bookGateForm.action, location.href) : null; }
- catch (_) {}
- if (location.origin !== 'https://prenotami.esteri.it' ||
- location.pathname !== BOOK_GATE_PATH || !bookGateForm ||
- bookGateForm.method.toUpperCase() !== 'POST' ||
- bookGateForm.enctype !== 'multipart/form-data' ||
- !bookGateAction || bookGateAction.origin !== location.origin ||
- bookGateAction.pathname !== BOOK_GATE_PATH || bookGateAction.search || bookGateAction.hash ||
- bookGateForm.querySelectorAll('input[type="file"]').length !== 0) {
- return {pathMatches: false, formPresent: false};
- }
- """.replace("BOOK_GATE_PATH", json.dumps(booking_path))
- return prefix + _booking_preflight_script(route, booking_path)
- class BookingPreflightStage(Enum):
- BEFORE_OTP_SEND = "before_otp_send"
- AFTER_OTP_SEND = "after_otp_send"
- class CalendarRequestAudit:
- """Passively count business requests across refreshes; never retain bodies.
- The production page.listen owns a separate CDP connection. This diagnostic
- callback uses the page driver and refuses to replace an existing handler.
- It never enables Fetch interception or changes any browser request.
- """
- EVENT = "Network.requestWillBeSent"
- def __init__(self, page: object, *, include_time_slots: bool = False) -> None:
- self.page = page
- self.driver = page.driver
- self._callback = self._on_request
- self._lock = Lock()
- self._started = False
- self._invalid_event = False
- self._counts = {
- "otpRequests": 0,
- "avantiPosts": 0,
- "availabilityRequests": 0,
- "finalRequests": 0,
- }
- if include_time_slots:
- self._counts["timeSlotRequests"] = 0
- def enable_time_slot_counting(self) -> None:
- """Opt in for the soak; existing gate counter shapes stay unchanged."""
- with self._lock:
- self._counts.setdefault("timeSlotRequests", 0)
- def start(self) -> None:
- if self._started:
- raise CalendarGateError("Passive request audit was already started")
- for name in ("event_handlers", "immediate_event_handlers"):
- handlers = getattr(self.driver, name, None)
- if not isinstance(handlers, dict) or self.EVENT in handlers:
- raise CalendarGateError(
- "Passive request audit cannot replace an existing callback"
- )
- self.driver.set_callback(self.EVENT, self._callback, immediate=True)
- self._started = True
- try:
- self.page.run_cdp("Network.enable")
- except Exception:
- self.stop()
- raise
- def stop(self) -> None:
- if not self._started:
- return
- if self.driver.immediate_event_handlers.get(self.EVENT) is not self._callback:
- raise CalendarGateError("Passive request audit callback changed")
- self.driver.set_callback(self.EVENT, None, immediate=True)
- self._started = False
- def _on_request(self, **event: object) -> None:
- request = event.get("request")
- if (
- not isinstance(request, dict)
- or not isinstance(request.get("url"), str)
- or not isinstance(request.get("method"), str)
- ):
- with self._lock:
- self._invalid_event = True
- return
- try:
- path, _ = _same_origin_path(request["url"])
- except CalendarGateError:
- return
- method = request["method"].upper()
- key = None
- if path == OTP_PATH:
- key = "otpRequests"
- elif path == "/BookingCalendar/InsertNewBooking":
- key = "finalRequests"
- elif method == "POST" and path.startswith("/Services/Booking/"):
- key = "avantiPosts"
- elif path == AVAILABILITY_PATH:
- key = "availabilityRequests"
- elif path == "/BookingCalendar/RetrieveTimeSlots" and "timeSlotRequests" in self._counts:
- key = "timeSlotRequests"
- if key is not None:
- with self._lock:
- self._counts[key] += 1
- def require_active_on(self, page: object) -> None:
- """Validate a borrowed audit without registering or removing callbacks."""
- if self.page is not page or self.driver is not getattr(page, "driver", None):
- raise CalendarGateError("Passive request audit belongs to another page or driver")
- if not self._started or self.driver.is_running is not True:
- raise CalendarGateError("Passive request audit is not connected")
- immediate = getattr(self.driver, "immediate_event_handlers", None)
- regular = getattr(self.driver, "event_handlers", None)
- if (not isinstance(immediate, dict) or immediate.get(self.EVENT) is not self._callback
- or not isinstance(regular, dict) or self.EVENT in regular):
- raise CalendarGateError("Passive request audit callback changed")
- def snapshot(self) -> dict[str, int]:
- self.require_active_on(self.page)
- with self._lock:
- if self._invalid_event:
- raise CalendarGateError("Passive request audit received an invalid event")
- return dict(self._counts)
- def retained_snapshot(self) -> dict[str, int]:
- """Best-effort last observed counters, not proof after a disconnect."""
- with self._lock:
- if self._invalid_event:
- raise CalendarGateError("Passive request audit received an invalid event")
- return dict(self._counts)
- def settled_snapshot(self, *, timeout: float = 3) -> dict[str, int]:
- # A read-only CDP round trip plus a bounded stable-count window lets
- # already-arriving callbacks catch up before a per-query comparison.
- self.page.run_cdp("Page.getFrameTree")
- deadline = time.monotonic() + timeout
- previous = self.snapshot()
- stable_since = time.monotonic()
- while time.monotonic() < deadline:
- time.sleep(0.1)
- current = self.snapshot()
- if current != previous:
- previous = current
- stable_since = time.monotonic()
- elif time.monotonic() - stable_since >= 0.3:
- return current
- raise CalendarGateError("Passive business-request counts did not settle")
- def validate_otp_packet(packet: object, *, service_id: int) -> None:
- path, parsed = _same_origin_path(packet.url)
- if str(packet.method).upper() != "GET" or path != OTP_PATH:
- raise CalendarGateError("OTP request method or path changed")
- if parse_qs(parsed.query) != {"ServiceID": [str(service_id)]}:
- raise CalendarGateError("OTP request service id changed")
- if packet.response.status != 200:
- raise CalendarGateError("OTP response status was not 200")
- raw_body = packet.response.raw_body
- if not isinstance(raw_body, str):
- raise CalendarGateError("OTP response body type changed")
- try:
- decoded = json.loads(raw_body)
- except json.JSONDecodeError as exc:
- raise CalendarGateError("OTP response was not the observed JSON string") from exc
- if decoded != "SENT":
- raise CalendarGateError("OTP response did not confirm SENT")
- def validate_avanti_packet(
- packet: object,
- *,
- booking_path: str,
- final_page_url: str,
- ) -> str:
- path, request_url = _same_origin_path(packet.url)
- if (
- str(packet.method).upper() != "POST"
- or path != booking_path
- or request_url.query
- or request_url.fragment
- ):
- raise CalendarGateError("AVANTI request method or path changed")
- status = packet.response.status
- if status == 302:
- raw_location = _header(packet.response.headers, "location")
- redirect_path, _ = _same_origin_path(
- urljoin("https://prenotami.esteri.it", raw_location)
- )
- if redirect_path != CALENDAR_PATH:
- raise CalendarGateError("AVANTI redirect did not target Calendar")
- transition_mode = "direct_302"
- elif status == 200:
- response_path, _ = _same_origin_path(
- getattr(packet.response, "url", "")
- )
- if response_path != CALENDAR_PATH:
- raise CalendarGateError(
- "AVANTI followed response did not target Calendar"
- )
- transition_mode = "followed_redirect_200"
- else:
- raise CalendarGateError(
- "AVANTI response status was not an allowed redirect representation"
- )
- final_path, _ = _same_origin_path(final_page_url)
- if final_path != CALENDAR_PATH:
- raise CalendarGateError("AVANTI browser did not finish on Calendar")
- return transition_mode
- def validate_booking_preflight(
- raw: object,
- *,
- stage: BookingPreflightStage = BookingPreflightStage.BEFORE_OTP_SEND,
- ) -> None:
- """Validate shared form shape and the stage-sensitive OTP-send control."""
- if not isinstance(raw, dict):
- raise CalendarGateError("Booking preflight did not return an object")
- if not isinstance(stage, BookingPreflightStage):
- raise CalendarGateError("Booking preflight stage is invalid")
- true_fields = (
- "pathMatches",
- "formPresent",
- "bookingTypeOptionMatched",
- "purposeOptionMatched",
- "bookingVisibleMatches",
- "bookingHiddenMatches",
- "companionsHiddenIsZero",
- "purposeVisibleMatches",
- "purposeHiddenIsPreSubmit",
- "privacyChecked",
- "turnstileTokenPresent",
- )
- for field_name in true_fields:
- if raw.get(field_name) is not True:
- raise CalendarGateError(
- f"Booking preflight rejected {field_name}"
- )
- for field_name in (
- "otpInputCount",
- "otpButtonCount",
- "avantiButtonCount",
- "turnstileCount",
- ):
- if raw.get(field_name) != 1:
- raise CalendarGateError(
- f"Booking preflight rejected {field_name}"
- )
- otp_disabled = raw.get("otpDisabled")
- if not isinstance(otp_disabled, bool) or (
- stage is BookingPreflightStage.BEFORE_OTP_SEND
- and otp_disabled
- ):
- raise CalendarGateError(
- "Booking preflight rejected otpDisabled"
- )
- if raw.get("avantiDisabled") is not False:
- raise CalendarGateError(
- "Booking preflight rejected avantiDisabled"
- )
- otp_value_present = raw.get("otpValuePresent")
- expected_otp_value_present = (
- stage is BookingPreflightStage.AFTER_OTP_SEND
- )
- if (
- not isinstance(otp_value_present, bool)
- or otp_value_present is not expected_otp_value_present
- ):
- raise CalendarGateError(
- "Booking preflight rejected otpValuePresent"
- )
- if raw.get("unknownRequiredCount") != 0:
- raise CalendarGateError(
- "Booking preflight rejected unknownRequiredCount"
- )
- def _booking_preflight_script(
- route: ItaRouteConfig,
- booking_path: str,
- ) -> str:
- if route.booking_type is None or route.purpose is None:
- raise CalendarGateError("Q-CAL route is missing form controls")
- config = {
- "bookingPath": booking_path,
- "bookingTypeId": route.booking_type.control_id,
- "bookingTypeValue": route.booking_type.value,
- "bookingTypeLabels": list(route.booking_type.labels),
- "purposeId": route.purpose.control_id,
- "purposeValue": route.purpose.value,
- "purposeLabels": list(route.purpose.labels),
- }
- config_json = json.dumps(config, ensure_ascii=False)
- return f"""
- /* coordinate:ita-qcal-booking-preflight */
- const cfg = {config_json};
- const normalize = (value) => String(value || '')
- .replace(/\\s+/g, ' ').trim().toLocaleLowerCase();
- const form = document.querySelector('#bookingForm');
- const booking = document.getElementById(cfg.bookingTypeId);
- const purpose = document.getElementById(cfg.purposeId);
- const bookingOption = booking
- ? Array.from(booking.options).find(
- (option) => option.value === cfg.bookingTypeValue
- )
- : null;
- const purposeOption = purpose
- ? Array.from(purpose.options).find(
- (option) => option.value === cfg.purposeValue
- )
- : null;
- const bookingLabels = cfg.bookingTypeLabels.map(normalize);
- const purposeLabels = cfg.purposeLabels.map(normalize);
- const bookingTypeOptionMatched = Boolean(
- bookingOption && bookingLabels.includes(normalize(bookingOption.textContent))
- );
- const purposeOptionMatched = Boolean(
- purposeOption && purposeLabels.includes(normalize(purposeOption.textContent))
- );
- if (bookingTypeOptionMatched && booking.value !== cfg.bookingTypeValue) {{
- booking.value = cfg.bookingTypeValue;
- booking.dispatchEvent(new Event('change', {{bubbles: true}}));
- }}
- if (purposeOptionMatched && purpose.value !== cfg.purposeValue) {{
- purpose.value = cfg.purposeValue;
- purpose.dispatchEvent(new Event('change', {{bubbles: true}}));
- }}
- const privacy = document.getElementById('PrivacyCheck');
- if (privacy && !privacy.checked) privacy.click();
- const allowedRequiredIds = new Set([
- cfg.bookingTypeId,
- cfg.purposeId,
- 'otp-input',
- 'PrivacyCheck',
- 'hiddenTipoPrenotazione',
- 'numAccSelected',
- 'hiddenSelezionato_0',
- ]);
- const allowedRequiredNames = new Set([
- 'otp-input',
- 'PrivacyCheck',
- 'cf-turnstile-response',
- '__RequestVerificationToken',
- ]);
- const unknownRequired = form
- ? Array.from(form.querySelectorAll('[required]')).filter((element) =>
- !allowedRequiredIds.has(element.id) &&
- !allowedRequiredNames.has(element.name)
- )
- : [];
- const bookingHidden = document.getElementById('hiddenTipoPrenotazione');
- const companionsHidden = document.getElementById('numAccSelected');
- const purposeHidden = document.getElementById('hiddenSelezionato_0');
- const otpInputs = document.querySelectorAll('#otp-input');
- const otpButtons = document.querySelectorAll('#otp-send');
- const avantiButtons = document.querySelectorAll('#btnAvanti');
- const turnstile = document.querySelectorAll(
- 'input[name="cf-turnstile-response"]'
- );
- return {{
- pathMatches: window.location.pathname === cfg.bookingPath,
- formPresent: Boolean(form),
- bookingTypeOptionMatched,
- purposeOptionMatched,
- bookingVisibleMatches: Boolean(
- booking && booking.value === cfg.bookingTypeValue
- ),
- bookingHiddenMatches: Boolean(
- bookingHidden && bookingHidden.value === cfg.bookingTypeValue
- ),
- companionsHiddenIsZero: Boolean(
- companionsHidden && companionsHidden.value === '0'
- ),
- purposeVisibleMatches: Boolean(
- purpose && purpose.value === cfg.purposeValue
- ),
- purposeHiddenIsPreSubmit: Boolean(
- purposeHidden && ['0', cfg.purposeValue].includes(purposeHidden.value)
- ),
- privacyChecked: Boolean(privacy && privacy.checked),
- otpInputCount: otpInputs.length,
- otpValuePresent: Boolean(
- otpInputs.length === 1 && String(otpInputs[0].value || '').trim()
- ),
- otpButtonCount: otpButtons.length,
- otpDisabled: otpButtons.length === 1 ? otpButtons[0].disabled : null,
- avantiButtonCount: avantiButtons.length,
- avantiDisabled:
- avantiButtons.length === 1 ? avantiButtons[0].disabled : null,
- turnstileCount: turnstile.length,
- turnstileTokenPresent: Boolean(
- turnstile.length === 1 && turnstile[0].value
- ),
- turnstileApiPresent: Boolean(window.turnstile),
- turnstileScriptPresent: Boolean(document.querySelector(
- 'script[src^="https://challenges.cloudflare.com/turnstile/"]'
- )),
- documentVisible: document.visibilityState === 'visible',
- unknownRequiredCount: unknownRequired.length,
- }};
- """
- def _validate_preflight_except_dynamic_token(
- raw: object,
- *,
- stage: BookingPreflightStage,
- ) -> None:
- if not isinstance(raw, dict):
- raise CalendarGateError("Booking preflight did not return an object")
- for key in ("turnstileTokenPresent", "avantiDisabled"):
- if type(raw.get(key)) is not bool:
- raise CalendarGateError(f"Booking preflight rejected {key}")
- candidate = dict(raw)
- candidate["turnstileTokenPresent"] = True
- candidate["avantiDisabled"] = False
- validate_booking_preflight(candidate, stage=stage)
- def _wait_for_calendar(page: object, timeout: float = 30) -> None:
- deadline = time.monotonic() + timeout
- while time.monotonic() < deadline:
- if (urlparse(str(page.url or "")).path.rstrip("/") or "/") == CALENDAR_PATH:
- page.wait.doc_loaded()
- return
- time.sleep(0.25)
- raise CalendarGateError("AVANTI did not reach Calendar before timeout")
- def _element_or_fail(page: object, selector: str) -> object:
- element = page.ele(selector, timeout=5)
- if not element:
- raise CalendarGateError(f"Required element is missing: {selector}")
- return element
- def _read_manual_otp() -> str:
- otp = input(
- "Italy booking OTP "
- "(visible; terminal scrollback may retain it): "
- ).strip()
- if not otp.isdigit() or not 4 <= len(otp) <= 12:
- raise CalendarGateError("OTP must be 4-12 digits")
- return otp
- def _enter_otp(plugin: object, otp: str) -> None:
- """Focus, type, and compare in-page without returning the OTP value."""
- otp_input = _element_or_fail(plugin.page, "#otp-input")
- plugin.mouse.human_click_ele(otp_input)
- otp_input.input(otp, clear=True)
- value_matches = otp_input.run_js(
- "return this.value === arguments[0];",
- otp,
- )
- if value_matches is not True:
- raise CalendarGateError("OTP DOM write verification failed")
- print("ITA_QCAL_OTP_DOM_WRITE_VERIFIED matched=true")
- # ============================================================================
- # OTP (from plugins/ita_otp.py)
- # ============================================================================
- """Italy-only OTP adapter.
- The adapter deliberately reuses ``VSCloudApi.fetch_mail_content`` instead of
- creating another mail provider. It adds the Italy contract around that call:
- one sent-time window, a fixed Prenot@Mi sender filter, deterministic body
- parsing, and fail-closed errors that never carry the raw mail body.
- The provider returns body only: its header/time filtering is a dependency, not
- independent sender authentication or freshness proof by this adapter.
- """
- import logging
- import re
- from datetime import datetime, timezone
- import vs_log_macros
- from toolkit.vs_cloud_api import VSCloudApi
- from vs_types import (
- BizLogicError,
- PermissionDeniedError,
- RateLimiteddError,
- SessionExpiredOrInvalidError,
- )
- _OTP_EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
- _SENT_AT_FORMAT = "%Y-%m-%d %H:%M:%S"
- def utc_sent_at() -> str:
- """Return the exact UTC format required by the existing cloud endpoint."""
- return datetime.now(timezone.utc).strftime(_SENT_AT_FORMAT)
- def validate_cloud_otp_logging() -> None:
- """Validate before any shared SDK call; never change logging state.
- Existing SDK DEBUG output includes raw mail. Automatic Italy OTP therefore
- requires a stable INFO-or-higher logger throughout the call. Runtime log
- reconfiguration and backend logging are outside this local guarantee.
- """
- logger = getattr(vs_log_macros, "_active_logger", None)
- if not isinstance(logger, logging.Logger) or logger.isEnabledFor(logging.DEBUG):
- raise CalendarGateError("Italy automatic OTP requires DEBUG payload logging to be disabled")
- def validate_cloud_otp_environment(mail_config: OtpMailConfig, recipient: str) -> None:
- """Validate the configured mailbox policy and actual account before OTP."""
- if not isinstance(mail_config, OtpMailConfig):
- raise CalendarGateError("Italy OTP mail configuration is missing")
- recipient_value = _validate_recipient(recipient)
- mail_config.mailbox_for(recipient_value)
- validate_cloud_otp_logging()
- def _validate_recipient(recipient: str) -> str:
- if not isinstance(recipient, str):
- raise CalendarGateError("Italy OTP recipient must be an email address")
- value = recipient.strip()
- if not _OTP_EMAIL_PATTERN.fullmatch(value):
- raise CalendarGateError("Italy OTP recipient must be an email address")
- return value
- def _validate_sent_at(sent_at: str) -> str:
- if not isinstance(sent_at, str):
- raise CalendarGateError("Italy OTP sent time is invalid")
- value = sent_at.strip()
- try:
- datetime.strptime(value, _SENT_AT_FORMAT)
- except ValueError:
- raise CalendarGateError("Italy OTP sent time is invalid") from None
- return value
- def fetch_otp_from_cloud(
- mail_config: OtpMailConfig,
- *,
- recipient: str,
- sent_at: str,
- api: VSCloudApi | None = None,
- ) -> str:
- """Read and parse one new Italy OTP through the existing cloud API.
- The call is intentionally one-shot. ``fetch-top`` is not a fallback and
- no retry or second OTP request is issued after a read/parse failure.
- """
- validate_cloud_otp_environment(mail_config, recipient)
- recipient_value = _validate_recipient(recipient)
- sent_at_value = _validate_sent_at(sent_at)
- try:
- client = api if api is not None else VSCloudApi.Instance()
- # Keep the body inside this scope; callers receive only the parsed
- # digits and must not log either the body or the code.
- body = client.fetch_mail_content(
- email=mail_config.mailbox_for(recipient_value),
- sender=PRENOTAMI_OTP_SENDER,
- recipient=recipient_value,
- subject_keywords=mail_config.subject_keywords,
- body_keywords=mail_config.body_keywords,
- sent_date=sent_at_value,
- expiry=mail_config.expiry_seconds,
- only_text=True,
- )
- except SessionExpiredOrInvalidError:
- # Mail API authentication is NOT the appointment site's Session.
- raise CalendarGateError("Italy OTP mailbox API authentication failed") from None
- except PermissionDeniedError:
- raise CalendarGateError(
- "Italy OTP mailbox authorization is not permitted"
- ) from None
- except RateLimiteddError:
- raise CalendarGateError("Italy OTP mailbox read was rate limited") from None
- except BizLogicError:
- # The shared SDK may include a provider response body in this error.
- raise CalendarGateError("Italy OTP mailbox read failed") from None
- except Exception:
- # Suppress provider exception context in standard traceback rendering.
- raise CalendarGateError("Italy OTP mailbox read failed") from None
- try:
- return parse_otp_body(body)
- except ItaProtocolError as exc:
- raise CalendarGateError(
- f"Italy OTP mail rejected ({exc.code})"
- ) from None
- # ============================================================================
- # TURNSTILE (from plugins/ita_turnstile.py)
- # ============================================================================
- """Bounded Calendar-preparation interaction, composing the existing VFS helper.
- This adapter never declares success: Italy's next preflight must observe the
- actual response field AND an enabled AVANTI. No refresh, reset, token injection,
- OTP action, blanket DFS search, or final submission lives here.
- """
- import json
- from utils.cloudflare_bypass_for_scraping import CloudflareBypasser
- class ItalyTurnstileRecovery:
- """One instance per Query/Book preparation; three attempts across stages."""
- MAX_ATTEMPTS = 3
- INITIAL_DELAY = 5
- RETRY_INTERVAL = 10
- def __init__(self, page, *, check_current):
- self.page = page
- self.check_current = check_current
- self.attempts = 0
- self._stage = None
- self._next_attempt = self.INITIAL_DELAY
- self._helper = None
- def __call__(self, raw, *, stage, elapsed, remaining):
- if not isinstance(stage, BookingPreflightStage):
- raise CalendarGateError("Italy Turnstile interaction stage invalid")
- if (not isinstance(raw, dict) or raw.get("pathMatches") is not True
- or raw.get("formPresent") is not True or type(raw.get("turnstileCount")) is not int
- or raw.get("turnstileCount") != 1):
- raise CalendarGateError("Italy Turnstile interaction requires the verified booking form")
- if raw.get("turnstileTokenPresent") is not False:
- return # Never touch a verified widget to fix an unrelated button.
- if self._stage is not stage:
- self._stage = stage
- self._next_attempt = self.INITIAL_DELAY
- if self.attempts >= self.MAX_ATTEMPTS or elapsed < self._next_attempt or remaining < 2:
- return
- self.check_current()
- self.attempts += 1
- self._next_attempt = elapsed + self.RETRY_INTERVAL
- clicked = False
- failed = False
- try:
- if self._helper is None:
- # Reuse the exact helper used by VFS. Suppress its free-form
- # browser exceptions; emit only fixed Italy metadata below.
- self._helper = CloudflareBypasser(self.page, log=False)
- # Do NOT use bypass(): its page-title success check would accept
- # "Booking - Prenot@Mi" while the embedded widget is still pending.
- clicked = self._helper.click_verification_button(is_dfs=False) is True
- except Exception:
- failed = True
- self.check_current()
- print("ITA_BOOK_TURNSTILE_INTERACTION=" + json.dumps({
- "contract": "ita-book-preflight-v2", "stage": stage.value,
- "attempt": self.attempts, "maxAttempts": self.MAX_ATTEMPTS,
- "clicked": clicked, "helperFailed": failed,
- }, sort_keys=True), flush=True)
- # ============================================================================
- # WORKFLOW (from plugins/ita_workflow.py)
- # ============================================================================
- """Compose Italy's verified site adapters behind the normal plugin interface.
- No scheduler, queue, or local test-gate dependency. Calendar preparation uses
- one explicit manual/cloud OTP provider for either role. Only applicant Book
- may enter the separately enabled final submission and receipt reconciliation.
- """
- import re
- import sys
- from time import monotonic
- from threading import Lock
- from vs_types import BizLogicError, PermissionDeniedError
- # Reuse the existing preparation lock, including cloud reads: no competing OTP
- # requests inside this process. This does not coordinate other worker processes.
- # The existing factory executes this file separately for each instance.
- # Keep only the primitive process-wide lock on the shared host module; never
- # cache plugin functions/classes there. setdefault preserves concurrent loads
- # and hot reloads without requiring another Italy file or a host code change.
- import vs_plg as _ita_host
- _OTP_INPUT_LOCK = vars(_ita_host).setdefault("_coordinate_ita_otp_input_lock", Lock())
- def prepare_calendar(plugin, route, *, role):
- """One native OTP + AVANTI, using the same functions as the tested gate."""
- if (role not in {"query", "book"} or route.capability is not ItaCapability.SINGLE_SCHENGEN_TOURISM
- or route.calendar_scan is None):
- raise BizLogicError("Italy Calendar preparation requires a single-tourism route")
- cloud = plugin.free_config.get("otp_mode") == "cloud"
- if cloud:
- query_config = plugin.free_config.get("query_mode", "services_probe") == "calendar"
- if ((role == "query") != query_config
- or plugin._book_final_configuration_valid() is not True):
- raise PermissionDeniedError("Italy automatic OTP requires a matching Query/Book role and valid final configuration")
- validate_cloud_otp_environment(route.mail, plugin.config.account.username)
- elif plugin.free_config.get("otp_mode") != "manual" or not sys.stdin.isatty():
- raise PermissionDeniedError("Italy Calendar needs an attached terminal for manual OTP (ITA-OTP-01)")
- page, generation = plugin.page, plugin.session_create_time
- username = plugin.config.account.username.strip().casefold()
- tab_id = page.tab_id
- booking_path = plugin._booking_path(route)
- def current(path):
- if (plugin.page is not page or page.tab_id != tab_id or plugin.session_create_time != generation
- or plugin.config.account.username.strip().casefold() != username
- or same_origin_path(page.url)[0] != path):
- raise CalendarGateError("Italy preparation Session or page changed")
- def packet_current(packet):
- if getattr(packet, "tab_id", None) != tab_id or getattr(packet, "is_failed", None) is not False:
- raise CalendarGateError("Italy preparation response came from another tab or failed")
- def click(selector):
- current(booking_path)
- plugin.mouse.human_click_ele(_element_or_fail(page, selector))
- # A failed partial preparation cannot resend OTP on every Query signal.
- # A fresh login/session permits another operator-assisted attempt.
- preparation_key = (generation, tab_id, route.routing_key)
- with _OTP_INPUT_LOCK:
- if getattr(plugin, "_manual_preparation_attempt", None) == preparation_key:
- raise PermissionDeniedError("Italy preparation failed; restore the session before retrying")
- current(booking_path)
- script = guarded_preflight_script(route, booking_path)
- check_form = lambda: current(booking_path)
- # Both roles must pass the same form before entering Calendar. Reuse
- # one bounded recovery across both stages; prepared scans skip this path.
- recovery = ItalyTurnstileRecovery(page, check_current=check_form)
- plugin._log(f"Italy {role} Calendar preparation: reusing bounded Turnstile recovery.")
- wait_for_booking_preflight(page, script=script,
- check_current=check_form, wait_action=recovery)
- plugin._manual_preparation_attempt = preparation_key
- sent_at, sent_monotonic = None, None
- def send_otp():
- nonlocal sent_at, sent_monotonic
- if cloud:
- validate_cloud_otp_environment(route.mail, username)
- sent_at, sent_monotonic = utc_sent_at(), monotonic()
- click("#otp-send")
- def check_cloud_window():
- if cloud and (sent_monotonic is None or
- not 0 <= monotonic() - sent_monotonic < route.mail.expiry_seconds):
- raise CalendarGateError("Italy OTP local read window expired; no automatic resend")
- packet = listen_once(page, target=OTP_PATH, method="GET", timeout=30,
- action=send_otp)
- packet_current(packet)
- validate_otp_packet(packet, service_id=route.service_id)
- current(booking_path)
- if cloud:
- check_cloud_window()
- plugin._log(f"Italy {role} OTP sent; waiting for the authorized mailbox (one read attempt).")
- otp = fetch_otp_from_cloud(route.mail, recipient=username, sent_at=sent_at)
- else:
- plugin._log(f"Italy {role} OTP sent; enter the code in this terminal.")
- otp = _read_manual_otp()
- try:
- pattern = r"[0-9]{6}" if cloud else r"[0-9]{4,12}"
- if not isinstance(otp, str) or re.fullmatch(pattern, otp) is None:
- raise CalendarGateError("Italy OTP format rejected")
- current(booking_path)
- check_cloud_window()
- try:
- _enter_otp(plugin, otp)
- except Exception:
- if cloud:
- # Browser transport exceptions may contain typed values.
- raise CalendarGateError("Italy automatic OTP DOM write verification failed") from None
- raise
- if cloud:
- plugin._log("Italy automatic OTP DOM write verified; continuing to Calendar.")
- finally:
- del otp
- wait_for_booking_preflight(
- page, script=script, stage=BookingPreflightStage.AFTER_OTP_SEND,
- check_current=check_form, wait_action=recovery,
- )
- check_cloud_window()
- try:
- page.set.auto_handle_alert(accept=True)
- packet = listen_once(page, target=booking_path, method="POST", timeout=30,
- action=lambda: click("#btnAvanti"))
- packet_current(packet)
- _wait_for_calendar(page)
- current(CALENDAR_PATH)
- validate_avanti_packet(packet, booking_path=booking_path, final_page_url=page.url)
- finally:
- page.set.auto_handle_alert(on_off=False)
- guard_calendar(page)
- wait_for_calendar_service(page, session_is_current=lambda: current(CALENDAR_PATH) is None)
- if role == "query":
- plugin._record_calendar_query_prepared_route(route)
- else:
- plugin._record_calendar_book_prepared_route(route)
- plugin._manual_preparation_attempt = None
- def prepare_query_if_needed(plugin, apt_type):
- """Return a negative entry result, or prepare and let Query scan real dates."""
- if same_origin_path(plugin.page.url)[0] == CALENDAR_PATH:
- return None # Existing Query continuity checks remain authoritative.
- route = plugin._resolve_route(apt_type)
- entry = plugin._query_once(apt_type, query_mode="services_probe")
- if not entry.success:
- return entry
- plugin._clear_calendar_query_state()
- prepare_calendar(plugin, route, role="query")
- return None
- def book(plugin, slot_info, user_inputs):
- """Applicant-owned Calendar → existing pre-final adapter → standard result."""
- if plugin._book_final_configuration_valid() is not True:
- raise PermissionDeniedError("Italy final submission configuration is invalid")
- if not isinstance(user_inputs, dict) or not isinstance(user_inputs.get("username"), str):
- raise BizLogicError("Italy Book requires the applicant username")
- username = user_inputs["username"].strip().casefold()
- if (not username or username != plugin.config.account.username.strip().casefold()
- or plugin.free_config.get("query_mode", "services_probe") == "calendar"
- or getattr(plugin, "_calendar_query_route_key", None) is not None):
- raise BizLogicError("Italy Book requires a separate applicant Session, not a Query Session")
- route = plugin._resolve_route(slot_info.apt_type)
- attempt = getattr(plugin, "_production_final_attempt", None)
- if attempt is not None and attempt.state not in {"blocked", "rejected"}:
- # The same task may retry success reporting, but must never submit twice.
- result = getattr(plugin, "_production_book_result", None)
- if (attempt.state == "confirmed" and result is not None
- and attempt.target.applicant == username and attempt.target.routing_key == route.routing_key):
- return result
- raise FinalOutcomeUnknown()
- if same_origin_path(plugin.page.url)[0] != CALENDAR_PATH:
- entry = plugin._book_discovery_or_prepared(slot_info, user_inputs)
- if entry.label != "booking-form-ready-before-avanti":
- return entry
- prepare_calendar(plugin, route, role="book")
- elif plugin._calendar_book_context_matches(route, username):
- # Refresh inventory on the next signal after a definite negative result.
- plugin._calendar_book_attempted = False
- result = plugin._book_discovery_or_prepared(slot_info, user_inputs)
- if plugin.last_booking_precommit is None or plugin.free_config.get("final_submit_enabled") is not True:
- return result
- return submit_final(plugin, route)
- def submit_final(plugin, route, *, request_audit: CalendarRequestAudit | None = None):
- """Reuse native submission and attribution with one audit per page.
- A caller observing the whole workflow may lend its live audit. Ownership
- stays with that caller; standalone production calls own their audit as
- before. Neither path replaces callbacks or interrupts request coverage.
- """
- port = FinalReceiptReadPort(plugin, route)
- owns_audit = request_audit is None
- audit = CalendarRequestAudit(plugin.page, include_time_slots=True) if owns_audit else request_audit
- if owns_audit:
- audit.start()
- else:
- audit.require_active_on(plugin.page)
- if "timeSlotRequests" not in audit.snapshot():
- raise CalendarGateError("Final request audit must include time slots")
- try:
- before = audit.settled_snapshot()
- def submit():
- native = NativeFinalSubmitter(plugin.page, port.target, port.session_is_current)
- signal = native()
- after = audit.settled_snapshot()
- if (after["finalRequests"] - before["finalRequests"] == 1
- and all(after[key] == before[key] for key in before if key != "finalRequests")
- and isinstance(native.submitted_selection, VerifiedSubmission)):
- port.record_submission(native.submitted_selection)
- return signal
- attempt = FinalBookingAttempt(port.target, read_reservations=port, submit_native=submit,
- session_is_current=port.session_is_current)
- plugin._production_final_attempt = attempt
- result = attempt.execute(enabled=True)
- plugin._production_book_result = result if result.success else None
- return result
- finally:
- # A diagnostic teardown failure must not turn a verified success into a
- # generic booking failure (and a second real booking on the next signal).
- if owns_audit:
- try:
- audit.stop()
- except Exception:
- plugin._log("Italy passive request audit cleanup failed; session needs cleanup.")
- # ============================================================================
- # PLUGIN (from plugins/ita_plugin.py)
- # ============================================================================
- import time
- import json
- import random
- import socket
- import uuid
- import shutil
- import re
- import os
- import stat
- from dataclasses import dataclass
- from datetime import datetime
- from pathlib import Path
- from typing import Dict, Optional, Any, Callable
- from urllib.parse import parse_qs, urlparse
- try:
- import fcntl
- except ImportError: # pragma: no cover - persistent local profiles require POSIX.
- fcntl = None
- from DrissionPage import ChromiumPage, ChromiumOptions
- from DrissionPage.errors import PageDisconnectedError
- import configure
- from vs_plg import IVSPlg
- from vs_types import VSPlgConfig, AppointmentType, VSQueryResult, VSBookResult, DateAvailability, AvailabilityStatus, SessionExpiredOrInvalidError, RateLimiteddError, PermissionDeniedError, BizLogicError, PluginStatus, utc_now_str
- from toolkit.mihomo_tunnel import MihomoTunnel
- from utils.mouse import HumanMouse
- from utils.keyboard import HumanKeyboard
- from utils.fingerprint_utils import FingerprintGenerator
- BOOKING_FORM_DISCOVERY_STOP_LABEL = "booking-form-ready-before-avanti"
- BOOKING_RECHECK_NONE_AVAILABLE_LABEL = "no-availability-after-user-recheck"
- BOOKING_CALENDAR_PREFINAL_STOP_LABEL = "calendar-ready-before-final"
- PERSISTENT_BROWSER_PROFILE_KEY = "persistent_browser_profile_path"
- RADWARE_VALIDATION_HOSTS = frozenset({"validate.perfdrive.com"})
- SERVICE_LINK_WAIT_SECONDS = 15
- SERVICES_PROBE_QUERY_MODE = "services_probe"
- CALENDAR_QUERY_MODE = "calendar"
- SERVICE_LIST_DIAGNOSTIC_SCRIPT = r"""
- /* coordinate:ita-service-list-structure */
- const targetPath = '__TARGET_PATH__';
- const tables = Array.from(document.querySelectorAll('table'));
- const bookingLinks = Array.from(
- document.querySelectorAll('a[href^="/Services/Booking/"]')
- );
- // Page-level diagnostic only: a row without its booking link exposes no
- // verified service-id binding. Never turn this count into a booking result.
- const normalizeNotice = (value) => String(value || '').replace(/\s+/g, ' ')
- .trim().toLowerCase().replace(/[.。!!]+$/, '');
- const alreadyBookedNotice = 'prenotazione già effettuata per questo servizio';
- const alreadyBookedRows = tables.flatMap((table) =>
- Array.from(table.querySelectorAll('tbody tr')),
- ).filter((row) => Array.from(row.cells).some((cell) => {
- const style = window.getComputedStyle(cell);
- return cell.getClientRects().length > 0 && style.visibility === 'visible'
- && normalizeNotice(cell.innerText) === alreadyBookedNotice;
- }));
- return {
- path: window.location.pathname,
- ready_state: document.readyState,
- table_count: tables.length,
- row_count: tables.reduce(
- (count, table) => count + table.querySelectorAll('tbody tr').length,
- 0,
- ),
- booking_link_count: bookingLinks.length,
- target_link_count: bookingLinks.filter(
- (link) => link.getAttribute('href') === targetPath,
- ).length,
- already_booked_notice_row_count: alreadyBookedRows.length,
- };
- """
- class ItaAuthenticationChallengeError(BizLogicError):
- """Raised when website authentication requires an external security challenge."""
- class ItaTargetServiceLinkMissingError(BizLogicError):
- """Raised when the authenticated Services page lacks the configured link."""
- class ItaCalendarPreparationRequiredError(BizLogicError):
- """Read-only recovery cannot restore Calendar; ITA-OTP-01 remains pending."""
- class ItaCalendarTransientError(BizLogicError):
- """A bounded read-only retry is possible without repeating preparation."""
- @dataclass(frozen=True, slots=True, repr=False)
- class CalendarQueryCheckpoint:
- """In-memory comparison reference, never authentication proof or a signal.
- Kept only by the owner of the prepared Query session. It must not be
- serialized, sent to Book, or used for a different account/profile/route.
- """
- route: ItaRouteConfig
- username: str
- profile_path: str
- calendar_url: str
- runtime_service: str
- BOOKING_FORM_DISCOVERY_SCRIPT = r"""
- const form = document.querySelector('#bookingForm');
- if (!form) {
- return null;
- }
- const toPath = (rawUrl) => {
- try {
- return new URL(rawUrl, window.location.origin).pathname;
- } catch (_error) {
- return null;
- }
- };
- const allFields = Array.from(
- form.querySelectorAll('input, select, textarea')
- );
- const allButtons = Array.from(
- form.querySelectorAll('button, input[type="submit"], input[type="button"]')
- );
- return {
- path: window.location.pathname,
- form: {
- method: (form.getAttribute('method') || 'GET').toUpperCase(),
- action_path: toPath(form.getAttribute('action') || window.location.href),
- },
- field_count: allFields.length,
- fields_truncated: allFields.length > 100,
- fields: allFields.slice(0, 100).map((element) => ({
- tag: element.tagName.toLowerCase(),
- type: element.tagName === 'INPUT'
- ? (element.getAttribute('type') || 'text').toLowerCase()
- : null,
- id: element.getAttribute('id'),
- name: element.getAttribute('name'),
- required: Boolean(element.required),
- })),
- button_count: allButtons.length,
- buttons_truncated: allButtons.length > 50,
- buttons: allButtons.slice(0, 50).map((element) => ({
- tag: element.tagName.toLowerCase(),
- type: (element.getAttribute('type') || 'button').toLowerCase(),
- id: element.getAttribute('id'),
- name: element.getAttribute('name'),
- text: element.tagName === 'BUTTON'
- ? (element.textContent || '').trim()
- : (element.getAttribute('aria-label') || '').trim(),
- })),
- };
- """
- # ==========================================
- # 2. ItaPlugin 核心逻辑
- # ==========================================
- class ItaPlugin(IVSPlg):
- name = "ita_plugin"
- version = "1.0.1"
- description = "意大利Prenot@Mi领事预约插件 (支持拟人化交互与多领区调度)"
- _KNOWN_NO_AVAILABILITY_NOTICES = frozenset(
- {
- "stante l'elevata richiesta i posti disponibili per il servizio "
- "scelto sono esauriti",
- }
- )
- def __init__(self, group_id: str):
- self.group_id = group_id
- self.config: Optional[VSPlgConfig] = None
- self.free_config: Dict[str, Any] = {}
- self.is_healthy = True
- self._cleanup_attempted = False
- self.logger = None
- self.page: Optional[ChromiumPage] = None
- # Prenotami 特有配置
- self.ita_url = 'https://prenotami.esteri.it'
- self.instance_id = uuid.uuid4().hex[:8]
- self.root_workspace = os.path.abspath(os.path.join("data/temp_browser_data", f"{self.group_id}.{self.instance_id}"))
- self._transient_user_data_path = os.path.join(self.root_workspace, "user_data")
- self.user_data_path = self._transient_user_data_path
- self._persistent_profile_path: Optional[Path] = None
- self._profile_lock_handle = None
- if not os.path.exists(self.root_workspace):
- os.makedirs(self.root_workspace)
- self.tunnel = None
- self.session_create_time: float = 0
- self.last_booking_form_structure: Optional[Dict[str, Any]] = None
- self.last_service_list_structure: Optional[Dict[str, Any]] = None
- self.last_calendar_query_scan: Optional[CalendarQueryScanResult] = None
- self._calendar_query_route_key: Optional[str] = None
- self._calendar_query_checkpoint: Optional[CalendarQueryCheckpoint] = None
- self._calendar_query_page = None
- self._calendar_query_generation = None
- self._calendar_query_tab_id = None
- self._query_stop_reason = None
- self._reset_calendar_book_state()
- def set_log(self, logger: Callable[[str], None]) -> None:
- self.logger = logger
- def _log(self, message):
- if self.logger:
- self.logger(f'[ItaPlugin] [{self.group_id}] {message}')
- else:
- print(f'[ItaPlugin] [{self.group_id}] {message}')
- @staticmethod
- def _url_for_log(raw_url: str) -> str:
- parsed = urlparse(str(raw_url or ""))
- path = parsed.path or "/"
- if path.startswith("/signin/") and path != "/signin/":
- path = "/signin/<redacted>"
- if (parsed.hostname or "").lower() in RADWARE_VALIDATION_HOSTS:
- path = "/<redacted-challenge>"
- if parsed.scheme and parsed.netloc:
- return f"{parsed.scheme}://{parsed.netloc}{path}"
- return path
- @staticmethod
- def _normalize_service_notice(message: str) -> str:
- normalized = str(message or "").replace("’", "'").replace("‘", "'")
- normalized = re.sub(r"\s+", " ", normalized).strip().casefold()
- return normalized.rstrip(".。!!")
- @classmethod
- def _classify_service_notice(
- cls,
- message: str,
- ) -> Optional[AvailabilityStatus]:
- """Classify only service notices backed by current website evidence."""
- normalized = cls._normalize_service_notice(message)
- if normalized in cls._KNOWN_NO_AVAILABILITY_NOTICES:
- return AvailabilityStatus.NoneAvailable
- return None
- def _random_sleep(self, min_sec=30, max_sec=60):
- sleep_time = random.uniform(min_sec, max_sec)
- self._log(f"Anti-Rate-Limit: Sleeping for {sleep_time:.2f} seconds...")
- time.sleep(sleep_time)
- def set_config(self, config: VSPlgConfig):
- self.config = config
- self.free_config = config.free_config or {}
- query_mode = self.free_config.get(
- "query_mode",
- SERVICES_PROBE_QUERY_MODE,
- )
- if query_mode not in {
- SERVICES_PROBE_QUERY_MODE,
- CALENDAR_QUERY_MODE,
- }:
- raise BizLogicError(
- "Italy query_mode must be services_probe or calendar"
- )
- otp_mode = self.free_config.get("otp_mode")
- if otp_mode not in (None, "manual", "cloud"):
- raise BizLogicError("Italy otp_mode must be manual, cloud, or omitted")
- if not self._book_final_configuration_valid():
- raise BizLogicError(
- "Italy final submission requires explicit OTP mode on an applicant Book configuration"
- )
- self.user_data_path = self._transient_user_data_path
- self._persistent_profile_path = None
- self._clear_calendar_query_state()
- self._reset_calendar_book_state()
- configured_profile = self.free_config.get(PERSISTENT_BROWSER_PROFILE_KEY)
- if configured_profile is not None:
- if not isinstance(configured_profile, str) or not configured_profile.strip():
- raise BizLogicError(
- "Italy persistent browser profile path must be a non-empty string"
- )
- candidate = Path(configured_profile).expanduser()
- if candidate.is_symlink():
- raise BizLogicError(
- "Italy persistent browser profile path must not be a symlink"
- )
- try:
- resolved_profile = candidate.resolve(strict=True)
- except OSError as exc:
- raise BizLogicError(
- "Italy persistent browser profile directory does not exist"
- ) from exc
- if not resolved_profile.is_dir():
- raise BizLogicError(
- "Italy persistent browser profile path must be a directory"
- )
- if os.name == "posix":
- profile_mode = stat.S_IMODE(resolved_profile.stat().st_mode)
- if profile_mode != 0o700:
- raise BizLogicError(
- "Italy persistent browser profile permissions must be 700"
- )
- transient_root = Path(self.root_workspace).resolve()
- if (
- resolved_profile == transient_root
- or resolved_profile.is_relative_to(transient_root)
- ):
- raise BizLogicError(
- "Italy persistent browser profile must stay outside the temporary workspace"
- )
- self._persistent_profile_path = resolved_profile
- self.user_data_path = str(resolved_profile)
- def _resolve_route(self, apt_type: AppointmentType) -> ItaRouteConfig:
- """Resolve the current route through the shared pure protocol core."""
- if not isinstance(apt_type, AppointmentType):
- raise BizLogicError("Italy route requires an AppointmentType")
- try:
- return resolve_route_config(
- self.free_config.get("apt_configs", {}),
- apt_type.routing_key,
- )
- except ItaProtocolError as exc:
- raise BizLogicError(
- f"Italy route configuration rejected ({exc.code})"
- ) from exc
- @staticmethod
- def _booking_path(route: ItaRouteConfig) -> str:
- return f"/Services/Booking/{route.service_id}"
- def _record_calendar_query_prepared_route(
- self,
- route: ItaRouteConfig,
- ) -> None:
- """Record route continuity only after a validated AVANTI transition."""
- if not isinstance(route, ItaRouteConfig):
- raise BizLogicError(
- "Italy Calendar preparation requires an ItaRouteConfig"
- )
- current_path, _ = same_origin_path(self.page.url)
- if current_path != CALENDAR_PATH:
- raise BizLogicError(
- "Italy Calendar route cannot be recorded outside Calendar"
- )
- self._calendar_query_route_key = route.routing_key
- def _clear_calendar_query_state(self) -> None:
- self._calendar_query_route_key = None
- self.last_calendar_query_scan = None
- self._calendar_query_checkpoint = None
- self._calendar_query_page = None
- self._calendar_query_generation = None
- self._calendar_query_tab_id = None
- def _invalidate_query_session(self, reason: str) -> None:
- # Same health -> cleanup -> creator contract as VFS/BLS. The caller
- # owns the retry budget; Query itself never logs in or sends an OTP.
- self.is_healthy = False
- self._query_stop_reason = reason
- self._clear_calendar_query_state()
- def _check_query_checkpoint_owner(
- self, apt_type: AppointmentType, checkpoint: CalendarQueryCheckpoint,
- ) -> None:
- account = self.config.account if self.config else None
- username = account.username.strip().casefold() if account else ""
- if (
- not isinstance(checkpoint, CalendarQueryCheckpoint)
- or not username
- or username != checkpoint.username
- or getattr(self, "_persistent_profile_path", None) is None
- or str(self._persistent_profile_path) != checkpoint.profile_path
- or self.user_data_path != checkpoint.profile_path
- or self._resolve_route(apt_type) != checkpoint.route
- or self.free_config.get("query_mode") != CALENDAR_QUERY_MODE
- or self.free_config.get("final_submit_enabled", False) is not False
- or getattr(self, "_calendar_book_prepared_context", None) is not None
- ):
- raise BizLogicError("Italy Query recovery account, profile, or route does not match")
- def capture_calendar_query_checkpoint(
- self, apt_type: AppointmentType,
- ) -> CalendarQueryCheckpoint:
- """Read a recovery reference only from this already-prepared Calendar."""
- route = self._resolve_route(apt_type)
- if (
- not self.page or not self.is_healthy or self.session_create_time <= 0
- or getattr(self, "_calendar_query_route_key", None) != route.routing_key
- or route.capability is not ItaCapability.SINGLE_SCHENGEN_TOURISM
- or route.calendar_scan is None
- ):
- raise BizLogicError("Italy Query recovery requires a prepared current Session")
- self._validate_calendar_query_url(self.page.url)
- guard_calendar(self.page)
- checkpoint = CalendarQueryCheckpoint(
- route=route,
- username=self.config.account.username.strip().casefold(),
- profile_path=str(getattr(self, "_persistent_profile_path", "")),
- calendar_url=str(self.page.url),
- runtime_service=read_calendar_service(self.page),
- )
- self._check_query_checkpoint_owner(apt_type, checkpoint)
- tab_id = self.page.tab_id
- if not isinstance(tab_id, str) or not tab_id:
- raise BizLogicError("Italy Query recovery requires a current browser tab")
- self._calendar_query_checkpoint = checkpoint
- self._calendar_query_page = self.page
- self._calendar_query_generation = self.session_create_time
- self._calendar_query_tab_id = tab_id
- return checkpoint
- @staticmethod
- def _validate_calendar_query_url(raw_url: str) -> None:
- path, parsed = same_origin_path(raw_url)
- query = parse_qs(parsed.query, keep_blank_values=True)
- if (
- path != CALENDAR_PATH or parsed.fragment
- or set(query) - {"selectedService"}
- or any(len(values) != 1 or not values[0] for values in query.values())
- ):
- raise BizLogicError("Italy Query recovery requires the observed Calendar URL shape")
- def _check_current_query_checkpoint(self, apt_type: AppointmentType) -> None:
- checkpoint = getattr(self, "_calendar_query_checkpoint", None)
- if checkpoint is None:
- return # Existing CS3A callers attest the same-instance route.
- self._check_query_checkpoint_owner(apt_type, checkpoint)
- if (
- self.page is not self._calendar_query_page
- or self.session_create_time != self._calendar_query_generation
- or self.page.tab_id != self._calendar_query_tab_id
- or read_calendar_service(self.page) != checkpoint.runtime_service
- ):
- raise BizLogicError("Italy Query current Calendar identity changed")
- def _check_calendar_access(self, booking_path: str) -> None:
- parsed = urlparse(str(self.page.url or ""))
- if parsed.hostname == "iam.esteri.it":
- raise SessionExpiredOrInvalidError("Italy session is no longer authenticated")
- if parsed.hostname in RADWARE_VALIDATION_HOSTS:
- raise PermissionDeniedError("Italy Calendar requires browser verification")
- path, _ = same_origin_path(self.page.url)
- if self.page.ele("#pingid-button", timeout=0.5):
- raise SessionExpiredOrInvalidError("Italy session is no longer authenticated")
- if path != CALENDAR_PATH:
- if path in {"/UserArea", "/Services", booking_path}:
- raise ItaCalendarPreparationRequiredError(
- "Italy Calendar requires preparation; automatic OTP is pending (ITA-OTP-01)"
- )
- raise CalendarGateError("Italy Calendar reached an unexpected page")
- def restore_calendar_query(
- self, apt_type: AppointmentType, checkpoint: CalendarQueryCheckpoint,
- ) -> None:
- """Try one observed read-only navigation after same-account login.
- A checkpoint only supplies comparison values. New page/route/service
- evidence is required before the new instance may query again.
- """
- self._clear_calendar_query_state()
- self._check_query_checkpoint_owner(apt_type, checkpoint)
- if not self.page or not self.is_healthy or self.session_create_time <= 0:
- raise SessionExpiredOrInvalidError("Italy Query recovery requires a new authenticated Session")
- self._validate_calendar_query_url(checkpoint.calendar_url)
- try:
- self.page.get(checkpoint.calendar_url)
- self.page.wait.doc_loaded()
- self._check_calendar_access(self._booking_path(checkpoint.route))
- guard_calendar(self.page)
- if read_calendar_service(self.page) != checkpoint.runtime_service:
- raise BizLogicError("Italy Query restored Calendar service does not match")
- self._record_calendar_query_prepared_route(checkpoint.route)
- self.capture_calendar_query_checkpoint(apt_type)
- self._query_stop_reason = None
- except SessionExpiredOrInvalidError:
- self._invalidate_query_session("session_expired")
- raise
- except PageDisconnectedError:
- self._invalidate_query_session("browser_disconnected")
- raise
- except Exception:
- self._clear_calendar_query_state()
- self._query_stop_reason = "needs_manual"
- raise
- def _reset_calendar_book_state(self) -> None:
- self._calendar_book_prepared_context = None
- self._calendar_book_attempted = False
- self.last_booking_precommit = None
- def _record_calendar_book_prepared_route(self, route: ItaRouteConfig) -> None:
- """Attest Book preparation after the caller validates this route's AVANTI.
- This private hook does not perform or infer preparation. It must not be
- called merely because a persisted browser happens to show Calendar.
- """
- self._calendar_book_prepared_context = None
- self.last_booking_precommit = None
- if (not isinstance(route, ItaRouteConfig)
- or route.capability is not ItaCapability.SINGLE_SCHENGEN_TOURISM
- or route.calendar_scan is None):
- raise BizLogicError("Italy Book preparation requires a single-tourism Calendar route")
- configured = self._resolve_route(AppointmentType(routing_key=route.routing_key))
- if route != configured or getattr(self, "_calendar_query_route_key", None) is not None:
- raise BizLogicError("Italy Book cannot reuse a Query preparation or another route")
- username = self.config.account.username.strip().casefold() if self.config else ""
- if (not username or not self.page or self.session_create_time <= 0
- or not self._book_final_configuration_valid()):
- raise BizLogicError("Italy Book preparation requires an authenticated user Session and final disabled")
- try:
- runtime_service = read_calendar_service(self.page)
- tab_id = self.page.tab_id
- if not isinstance(tab_id, str) or not tab_id:
- raise CalendarBookError("Book Calendar tab identity was unavailable")
- except Exception:
- raise BizLogicError("Italy Book preparation did not identify the current Calendar service") from None
- self._calendar_book_prepared_context = (
- id(self), self.page, username, self.session_create_time, route, runtime_service, tab_id,
- )
- self._calendar_book_attempted = False
- def _calendar_book_context_matches(self, route: ItaRouteConfig, username: str) -> bool:
- context = getattr(self, "_calendar_book_prepared_context", None)
- try:
- return (
- context is not None
- and len(context) == 7
- and context[1] is self.page
- and context[6] == self.page.tab_id
- and context[:5] == (id(self), self.page, username, self.session_create_time, route)
- and self.config.account.username.strip().casefold() == username
- and getattr(self, "_calendar_query_route_key", None) is None
- and self._book_final_configuration_valid()
- and self._resolve_route(AppointmentType(routing_key=route.routing_key)) == route
- )
- except Exception:
- return False
- def _book_prepared_calendar(
- self, slot_info: VSQueryResult, route: ItaRouteConfig, user_inputs: Dict,
- ) -> VSBookResult:
- """Recheck only the prepared applicant Session; stop before final."""
- if getattr(self, "_calendar_book_attempted", False):
- raise BizLogicError("Italy Book Calendar was already attempted; fresh preparation is required")
- if not isinstance(user_inputs, dict) or not isinstance(user_inputs.get("username"), str):
- raise BizLogicError("Italy Calendar Book requires user_inputs.username for applicant binding")
- username = user_inputs["username"].strip().casefold()
- if not username or not self._calendar_book_context_matches(route, username):
- raise BizLogicError("Italy Book Calendar preparation does not match the current applicant and route")
- try:
- start_day, end_day = book_date_preferences(user_inputs)
- if read_calendar_service(self.page) != self._calendar_book_prepared_context[5]:
- raise CalendarBookError("Book Calendar no longer matches the prepared service")
- self._calendar_book_attempted = True
- approval = recheck_calendar_before_final(
- self.page,
- lookahead_months=route.calendar_scan.lookahead_months,
- start_day=start_day, end_day=end_day,
- preferred_day=slot_info.earliest_date.date() if slot_info.earliest_date else None,
- session_is_current=lambda: self._calendar_book_context_matches(route, username),
- log=self._log,
- )
- if not self._calendar_book_context_matches(route, username):
- raise CalendarBookError("Book Session changed before publishing the pre-final checkpoint")
- except CalendarGateError as exc:
- self._calendar_book_prepared_context = None
- self.last_booking_precommit = None
- if getattr(exc, "http_status", None) == 401 or urlparse(str(self.page.url or "")).hostname == "iam.esteri.it":
- raise SessionExpiredOrInvalidError("Italy Book Session is no longer authenticated") from None
- if getattr(exc, "http_status", None) == 429:
- raise RateLimiteddError("Italy Book Calendar is rate limited") from None
- raise BizLogicError(str(exc)) from None
- except Exception:
- self._calendar_book_prepared_context = None
- self.last_booking_precommit = None
- raise BizLogicError("Italy Book Calendar failed before final confirmation") from None
- self.last_booking_precommit = approval
- result = VSBookResult(success=False)
- if approval is None:
- result.label = BOOKING_RECHECK_NONE_AVAILABLE_LABEL
- else:
- result.label = BOOKING_CALENDAR_PREFINAL_STOP_LABEL
- self._log(
- "Italy Book selected current user Calendar slot "
- f"date={approval.candidate.day.isoformat()} time={approval.candidate.time_label}; "
- "stopped before final confirmation."
- )
- return result
- def _acquire_persistent_profile_lock(self) -> None:
- profile_path = self._persistent_profile_path
- if profile_path is None or self._profile_lock_handle is not None:
- return
- if fcntl is None:
- raise BizLogicError(
- "Italy persistent browser profiles require POSIX file locking"
- )
- lock_path = profile_path / ".coordinate-profile.lock"
- try:
- lock_handle = lock_path.open("a+", encoding="utf-8")
- lock_path.chmod(0o600)
- fcntl.flock(lock_handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
- except BlockingIOError as exc:
- try:
- lock_handle.close()
- except UnboundLocalError:
- pass
- raise BizLogicError(
- "Italy persistent browser profile is already in use"
- ) from exc
- except OSError as exc:
- try:
- lock_handle.close()
- except UnboundLocalError:
- pass
- raise BizLogicError(
- f"Cannot lock Italy persistent browser profile ({type(exc).__name__})"
- ) from exc
- self._profile_lock_handle = lock_handle
- def _release_persistent_profile_lock(self) -> None:
- lock_handle = getattr(self, "_profile_lock_handle", None)
- if lock_handle is None:
- return
- try:
- if fcntl is not None:
- fcntl.flock(lock_handle.fileno(), fcntl.LOCK_UN)
- finally:
- lock_handle.close()
- self._profile_lock_handle = None
- def keep_alive(self):
- pass
- def health_check(self) -> bool:
- if not self.is_healthy:
- return False
- if not self.page:
- self._invalidate_query_session("browser_disconnected")
- return False
- try:
- if not self.page.run_js("return 1;"):
- self._invalidate_query_session("browser_disconnected")
- return False
- except Exception:
- self._invalidate_query_session("browser_disconnected")
- return False
- if self.config.session_max_life > 0:
- if time.time() - self.session_create_time > self.config.session_max_life:
- self._log("Session expired.")
- self._invalidate_query_session("configured_lifetime_reached")
- return False
- return True
- def create_session(self):
- """
- 创建认证浏览器会话,并在登录后的 /UserArea 停止。
- """
- self._log(f"Initializing Session (ID: {self.instance_id})...")
- self._cleanup_attempted = False
- self.is_healthy = False
- self._query_stop_reason = None
- self._clear_calendar_query_state()
- self._reset_calendar_book_state()
- co = ChromiumOptions()
- def get_free_port():
- with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
- s.bind(('', 0))
- return s.getsockname()[1]
- debug_port = get_free_port()
- self._log(f"Assigned Debug Port: {debug_port}")
- self._log(f"Account id={self.config.account.id}, proxy id={self.config.proxy.id}")
- self._acquire_persistent_profile_lock()
- if self._persistent_profile_path is not None:
- self._log(
- "Browser profile mode=persistent "
- f"id={self._persistent_profile_path.name}"
- )
- else:
- self._log("Browser profile mode=transient")
- co.set_local_port(debug_port)
- co.set_user_data_path(self.user_data_path)
- chrome_path = configure.CHROME_PATH
- if not chrome_path:
- chrome_path = os.getenv("CHROME_BIN")
- if chrome_path and os.path.exists(chrome_path):
- co.set_paths(browser_path=chrome_path)
- if self.config.proxy and self.config.proxy.ip:
- p = self.config.proxy
- if p.username and p.password:
- self._log(f"Starting Proxy Tunnel for {p.ip}...")
- exit_node = {
- "name": "ExitNode",
- "type": p.proto,
- "server": p.ip,
- "port": p.port,
- "username": p.username,
- "password": p.password
- }
- relay_node = None
- if configure.MIHOMO_RELAY_NODES:
- relay_node = random.choice(configure.MIHOMO_RELAY_NODES)
- mihomo_path = configure.MIHOMO_BIN_PATH
- if not mihomo_path:
- mihomo_path = os.getenv("MIHOMO_BIN")
- if not mihomo_path:
- raise BizLogicError(message='Mihomo path is null, You need set mihomo bin path in configure or os env')
- self.tunnel = MihomoTunnel(mihomo_path, exit_node=exit_node, relay_node=relay_node)
- local_proxy = self.tunnel.start()
- self._log(f"Tunnel started at {local_proxy}")
- co.set_argument(f'--proxy-server={local_proxy}')
- else:
- proxy_str = f"{p.proto}://{p.ip}:{p.port}"
- co.set_argument(f'--proxy-server={proxy_str}')
- else:
- self._log("[WARN] No proxy configured!")
- specific_fp = FingerprintGenerator().generate(self.config.account.username)
- fp_seed = specific_fp.get("seed")
- fp_platform = specific_fp.get("platform")
- fp_brand = specific_fp.get("brand")
- self._log(f'browser fingerprint seed={fp_seed}')
- co.headless(False)
- co.set_argument('--no-sandbox')
- co.set_argument('--disable-dev-shm-usage')
- co.set_argument('--window-size=1920,1080')
- co.set_argument('--disable-blink-features=AutomationControlled')
- co.set_argument(f"--fingerprint={fp_seed}")
- co.set_argument(f"--fingerprint-platform={fp_platform}")
- co.set_argument(f"--fingerprint-brand={fp_brand}")
- self.page = ChromiumPage(co)
- if self.config.debug:
- self.page.get('https://example.com')
- js_script = """
- function getFingerprint() {
- let webglVendor = 'Unknown';
- let webglRenderer = 'Unknown';
- try {
- let canvas = document.createElement('canvas');
- let gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl');
- if (gl) {
- let debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
- if (debugInfo) {
- webglVendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);
- webglRenderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
- }
- }
- } catch(e) {}
- return {
- "User-Agent": navigator.userAgent,
- "Platform": navigator.userAgentData ? navigator.userAgentData.platform : navigator.platform,
- "Brands": navigator.userAgentData ? navigator.userAgentData.brands.map(b => b.brand).join(', ') : 'Not Supported',
- "CPU Cores": navigator.hardwareConcurrency,
- "Language": navigator.language,
- "Timezone": Intl.DateTimeFormat().resolvedOptions().timeZone,
- "WebGL Vendor": webglVendor,
- "WebGL Renderer": webglRenderer
- };
- }
- return getFingerprint();
- """
- fp_data = self.page.run_js(js_script)
- self._log("================ 预检浏览器指纹数据 ================")
- self._log(json.dumps(fp_data, indent=4, ensure_ascii=False))
- self._log("====================================================")
- self.page = ChromiumPage(co)
- ita_url = self.ita_url
- self._log(f"Navigating to {ita_url}")
- self.page.get(ita_url)
- self._log("Init humanize tools...")
- self.mouse = HumanMouse(self.page, debug=True)
- self.keyboard = HumanKeyboard(self.page)
- self._log("Random mouse start position...")
- viewport_width = self.page.rect.viewport_size[0]
- viewport_height = self.page.rect.viewport_size[1]
- init_x = random.randint(10, viewport_width - 10)
- init_y = random.randint(10, viewport_height - 10)
- self.mouse.move(init_x, init_y)
- max_steps = 15
- stuck_counter = 0
- last_url = ""
- session_created = False
- has_clicked_login = False
- has_submitted_login = False
- username = self.config.account.username
- password = self.config.account.password
- for step in range(max_steps):
- self.page.wait.doc_loaded()
- time.sleep(1)
- current_url = self.page.url
- current_parsed_url = urlparse(current_url)
- current_host = (current_parsed_url.hostname or "").lower()
- current_path = urlparse(current_url).path.rstrip("/") or "/"
- current_title = self.page.title.lower()
- current_html_content = self.page.html
- self._log(
- f"--- [Router Step {step+1}] Current URL: "
- f"{self._url_for_log(current_url)} ---"
- )
- if current_host in RADWARE_VALIDATION_HOSTS:
- raise ItaAuthenticationChallengeError(
- "Italy authentication requires Radware browser validation; "
- "automatic retry is disabled"
- )
- # --- [异常处理与反爬对抗层] ---
- if current_url == last_url:
- stuck_counter += 1
- else:
- last_url = current_url
- stuck_counter = 0
- if stuck_counter >= 3:
- if current_path == "/UserArea":
- # The URL can stay stable while authenticated DOM finishes
- # rendering; let the success predicate below inspect it.
- pass
- elif has_clicked_login or has_submitted_login:
- self._log(
- "[WARN] Authentication flow is still on the same page; "
- "waiting without refresh or repeated submission."
- )
- time.sleep(2)
- continue
- self._log("[WARN] Page stucked before authentication, try to refresh...")
- self.page.refresh()
- self._random_sleep(5, 8)
- stuck_counter = 0
- continue
- server_error_indicators = ["502 Bad Gateway", "503 Service Temporarily Unavailable", "error 1020"]
- if any(err in current_html_content for err in server_error_indicators):
- if has_clicked_login or has_submitted_login:
- raise BizLogicError(
- "Italy authentication reached a server error; "
- "refusing to refresh or repeat the login attempt"
- )
- self._log(f"[WARN] Server network error, try to refresh (Step: {step})...")
- self.page.refresh()
- self._random_sleep(10, 15)
- continue
- # Cloudflare 拦截
- cloudflare_blocked_indicators = [
- "Sorry, you have been blocked",
- "You are being rate limited",
- "Cloudflare Ray ID"
- ]
- if any(indicator in current_html_content for indicator in cloudflare_blocked_indicators):
- raise BizLogicError(message="Blocked by Cloudflare WAF. Need to change IP or browser fingerprint.")
- # 遇到五秒盾先绕盾 (保留你原有的逻辑)
- if "just a moment" in current_title or "cloudflare" in current_title:
- # 假设你有 cf_bypasser 实例
- # if not cf_bypasser.bypass(max_retry=3): continue
- self._log("[State] CF 5-second shield detected. Waiting...")
- time.sleep(5)
- continue
- # 状态 0: 登录成功后的用户控制台。
- if (
- current_path == "/UserArea"
- and self.page.ele('.app-menu', timeout=1)
- and self.page.ele('@href=/Services', timeout=1)
- ):
- self._log("Successfully reached authenticated /UserArea.")
- self.session_create_time = time.time()
- self.is_healthy = True
- session_created = True
- break
- # 状态 1: 登录前的初始首页
- elif self.page.ele('#pingid-button', timeout=1):
- if has_clicked_login:
- self._log(
- "[State] Login entry was already clicked; "
- "waiting without clicking it again."
- )
- time.sleep(2)
- continue
- self._log("[State] Initial Landing Page detected. Clicking login button...")
- login_btn = self.page.ele('#pingid-button')
- self.mouse.human_click_ele(login_btn)
- has_clicked_login = True
- self._log("Redirecting to PingID...")
- self._random_sleep(3, 5)
- continue
- # 状态 2: 真正的表单登录页 (PingID)
- elif self.page.ele('@name=callback_1', timeout=1):
- if has_submitted_login:
- self._log(
- "[State] Login form is still present after submission; "
- "waiting without resubmitting credentials."
- )
- time.sleep(2)
- continue
- self._log("[State] PingID Login Form detected. Submitting credentials...")
- user_input = self.page.ele('@name=callback_1')
- pwd_input = self.page.ele('@name=callback_2')
- submit_btn = self.page.ele('tag:button@type=submit')
- if not user_input or not pwd_input or not submit_btn:
- raise BizLogicError(
- "Italy IAM login form is missing callback_1, "
- "callback_2, or the submit button"
- )
- self._log("Entering username...")
- self.mouse.human_click_ele(user_input)
- user_input.input(username, clear=True)
- time.sleep(1)
- self._log("Entering password...")
- self.mouse.human_click_ele(pwd_input)
- pwd_input.input(password, clear=True)
- time.sleep(1)
- self._log("Clicking submit login button...")
- self.mouse.human_click_ele(submit_btn)
- has_submitted_login = True
- self._log("Login form submitted. Waiting for dashboard to load...")
- self._random_sleep(5, 7)
- continue
- # /UserArea 只有在认证 DOM 同时就绪时才能成功。
- elif current_path == "/UserArea":
- self._log(
- "[State] /UserArea loaded without complete authentication "
- "markers; waiting."
- )
- time.sleep(2)
- continue
- else:
- self._log("[State] In unknown or transitional state. Waiting for next polling cycle...")
- time.sleep(2)
- if not session_created:
- raise BizLogicError(
- f"Failed to create authenticated /UserArea session after "
- f"{max_steps} navigation steps. Stuck at: "
- f"{self._url_for_log(self.page.url)}"
- )
- # -------------------------------------------------------------
- # 2. Query Availability
- # -------------------------------------------------------------
- def _inspect_service_list_structure(
- self,
- booking_path: str,
- ) -> Optional[Dict[str, Any]]:
- """Return counts, including known notices; never export row text or IDs."""
- if not self.page:
- return None
- script = SERVICE_LIST_DIAGNOSTIC_SCRIPT.replace(
- "__TARGET_PATH__",
- booking_path,
- )
- raw = self.page.run_js(script)
- if not isinstance(raw, dict):
- self.last_service_list_structure = None
- return None
- def bounded_count(value: object) -> int:
- try:
- parsed = int(value)
- except (TypeError, ValueError):
- parsed = 0
- return max(0, min(parsed, 10000))
- path = str(raw.get("path") or "").strip()[:120] or None
- ready_state = str(raw.get("ready_state") or "").strip().lower()
- if ready_state not in {"loading", "interactive", "complete"}:
- ready_state = "unknown"
- structure = {
- "path": path,
- "ready_state": ready_state,
- "table_count": bounded_count(raw.get("table_count")),
- "row_count": bounded_count(raw.get("row_count")),
- "booking_link_count": bounded_count(
- raw.get("booking_link_count")
- ),
- "target_link_count": bounded_count(raw.get("target_link_count")),
- "already_booked_notice_row_count": (
- bounded_count(raw["already_booked_notice_row_count"])
- if type(raw.get("already_booked_notice_row_count")) is int else 0
- ),
- }
- self.last_service_list_structure = structure
- return structure
- def query(self, apt_type: AppointmentType) -> VSQueryResult:
- """Preserve the framework's typed failures and unhealthy handoff."""
- self.last_calendar_query_scan = None
- if getattr(self, "is_healthy", True) is False:
- raise SessionExpiredOrInvalidError("Italy Query cannot reuse an unhealthy Session")
- try:
- if (self.page and self.free_config.get("otp_mode") in {"manual", "cloud"}
- and self.free_config.get("query_mode") == CALENDAR_QUERY_MODE
- and urlparse(self.page.url or "").hostname == "prenotami.esteri.it"):
- entry = prepare_query_if_needed(self, apt_type)
- if entry is not None:
- return entry
- return self._query_once(apt_type)
- except SessionExpiredOrInvalidError:
- self._invalidate_query_session("session_expired")
- raise
- except PageDisconnectedError:
- self._invalidate_query_session("browser_disconnected")
- raise
- except RateLimiteddError:
- self._invalidate_query_session("rate_limited")
- raise
- except PermissionDeniedError:
- self._invalidate_query_session("needs_manual")
- raise
- except ItaCalendarPreparationRequiredError:
- self._clear_calendar_query_state()
- self._query_stop_reason = "needs_manual"
- raise
- def _query_once(self, apt_type: AppointmentType, *, query_mode=None) -> VSQueryResult:
- # Diagnostic evidence is per call, never a reusable availability cache.
- self.last_calendar_query_scan = None
- if not self.page:
- raise BizLogicError("Italy query requires an initialized browser session")
- route = self._resolve_route(apt_type)
- query_mode = query_mode or self.free_config.get(
- "query_mode",
- SERVICES_PROBE_QUERY_MODE,
- )
- current_url = self.page.url or ""
- current_parsed_url = urlparse(current_url)
- current_path = current_parsed_url.path.rstrip("/") or "/"
- if query_mode == CALENDAR_QUERY_MODE:
- if route.capability is not ItaCapability.SINGLE_SCHENGEN_TOURISM:
- raise BizLogicError(
- "Italy calendar query requires the "
- "single_schengen_tourism capability"
- )
- if (
- current_parsed_url.netloc.lower() == "iam.esteri.it"
- or self.page.ele("#pingid-button", timeout=0.5)
- ):
- raise SessionExpiredOrInvalidError(
- "Italy session is no longer authenticated"
- )
- same_origin_path(current_url)
- if current_path != CALENDAR_PATH:
- raise ItaCalendarPreparationRequiredError(
- "Italy calendar query requires a route-confirmed "
- "Calendar Session; preparation is not complete (ITA-OTP-01)"
- )
- if getattr(self, "_calendar_query_route_key", None) != route.routing_key:
- raise BizLogicError(
- "Italy calendar query route continuity is not confirmed"
- )
- self._check_current_query_checkpoint(apt_type)
- return self._query_calendar(apt_type, route)
- service_id = route.service_id
- result = VSQueryResult(
- success=False,
- apt_type=apt_type,
- availability_status=AvailabilityStatus.NoneAvailable,
- )
- self.last_service_list_structure = None
- services_path = "/Services"
- services_url = f"{self.ita_url}{services_path}"
- booking_path = self._booking_path(route)
- if current_path not in {"/UserArea", services_path, booking_path}:
- if (
- current_parsed_url.netloc.lower() == "iam.esteri.it"
- or self.page.ele("#pingid-button", timeout=0.5)
- ):
- raise SessionExpiredOrInvalidError(
- "Italy session is no longer authenticated"
- )
- raise BizLogicError(
- "Italy query expected /UserArea or /Services, "
- f"got {current_path}"
- )
- # Always reload Services before probing. The no-slot response leaves a
- # modal over the service list, so reusing the old DOM can block the next
- # Sentinel iteration even though the URL is still /Services.
- self.page.get(services_url)
- self.page.wait.doc_loaded()
- current_url = self.page.url or ""
- current_parsed_url = urlparse(current_url)
- current_path = current_parsed_url.path.rstrip("/") or "/"
- if (
- current_parsed_url.netloc.lower() == "iam.esteri.it"
- or self.page.ele("#pingid-button", timeout=0.5)
- ):
- raise SessionExpiredOrInvalidError(
- "Italy session expired while loading the service list"
- )
- if current_path != services_path:
- raise BizLogicError(
- f"Italy service-list navigation reached {current_path}"
- )
- self._log(f"Checking configured Italy service id={service_id}...")
- booking_link = self.page.ele(
- f"tag:a@@href={booking_path}",
- timeout=SERVICE_LINK_WAIT_SECONDS,
- )
- if not booking_link:
- structure = self._inspect_service_list_structure(booking_path)
- if structure is not None:
- self._log(
- "Italy service-list structure after missing target link: "
- + json.dumps(structure, sort_keys=True)
- )
- message = (
- "Italy target service link is missing after the bounded wait: "
- f"{booking_path}"
- )
- if structure and structure["already_booked_notice_row_count"] > 0:
- message += (
- "; Services contains an already-booked notice "
- "(Prenotazione già effettuata per questo servizio). "
- "Check the target service row and existing reservations; "
- "the notice is not bound to the configured service ID."
- )
- raise ItaTargetServiceLinkMissingError(message)
- self.mouse.human_click_ele(booking_link)
- self.page.wait.load_start()
- self.page.wait.doc_loaded()
- current_url = self.page.url or ""
- current_parsed_url = urlparse(current_url)
- current_path = current_parsed_url.path.rstrip("/") or "/"
- if (
- current_parsed_url.netloc.lower() == "iam.esteri.it"
- or self.page.ele("#pingid-button", timeout=0.5)
- ):
- raise SessionExpiredOrInvalidError(
- "Italy session expired while checking the target service"
- )
- not_available = self.page.ele("#WNotAvailable", timeout=2)
- not_available_message = ""
- if not_available:
- not_available_message = (
- not_available.attr("value")
- or getattr(not_available, "value", "")
- or ""
- ).strip()
- visible_notice = self.page.ele(".jconfirm-content", timeout=2)
- visible_notice_message = ""
- if visible_notice:
- visible_notice_message = (visible_notice.text or "").strip()
- visible_notice_status = self._classify_service_notice(
- visible_notice_message
- )
- if current_path == services_path and not_available_message:
- self._log("Target Italy service explicitly reported no availability.")
- return result
- if (
- current_path == services_path
- and visible_notice_status == AvailabilityStatus.NoneAvailable
- ):
- self._log(
- "Target Italy service showed the verified no-availability notice."
- )
- return result
- if current_path == services_path:
- if visible_notice_message:
- raise BizLogicError(
- "Italy service returned to /Services with an unrecognized "
- "visible service notice"
- )
- raise BizLogicError(
- "Italy service returned to /Services without a non-empty "
- "#WNotAvailable marker or a recognized no-availability notice"
- )
- booking_form = self.page.ele("#bookingForm", timeout=1)
- if current_path == booking_path and booking_form:
- self._log(
- "Target Italy service accepted entry; returning a weak signal "
- "without form, calendar, or OTP actions."
- )
- result.success = True
- return result
- if current_path == booking_path:
- raise BizLogicError(
- "Italy target service reached the booking path without #bookingForm"
- )
- if booking_form:
- raise BizLogicError(
- "Italy #bookingForm appeared on an unexpected path"
- )
- raise BizLogicError(
- f"Italy query reached an unrecognized path: {current_path}"
- )
- def _query_calendar(
- self,
- apt_type: AppointmentType,
- route: ItaRouteConfig,
- ) -> VSQueryResult:
- """Publish only the earliest day from the first positive month."""
- if route.calendar_scan is None:
- raise BizLogicError(
- "Italy calendar query route is missing calendar_scan"
- )
- try:
- scan = scan_until_first_available_month(
- self.page,
- lookahead_months=route.calendar_scan.lookahead_months,
- log=self._log,
- )
- except CalendarAuthenticationExpiredError:
- raise SessionExpiredOrInvalidError("Italy Calendar authentication expired") from None
- except CalendarRateLimitedError:
- raise RateLimiteddError("Italy Calendar request was rate limited") from None
- except CalendarAccessDeniedError:
- raise PermissionDeniedError("Italy Calendar access requires operator attention") from None
- except (CalendarTransientError, TimeoutError):
- # A refresh may have returned to IAM without producing the XHR
- # being listened for. Inspect current page before calling it a
- # transient network error; never repeat preparation here.
- self._check_calendar_access(self._booking_path(route))
- raise ItaCalendarTransientError("Italy Calendar read temporarily failed") from None
- except CalendarGateError as exc:
- raise BizLogicError(
- "Italy Calendar query failed closed"
- ) from exc
- self._check_current_query_checkpoint(apt_type)
- self.last_calendar_query_scan = scan
- result = VSQueryResult(
- success=False,
- apt_type=apt_type,
- availability_status=AvailabilityStatus.NoneAvailable,
- )
- earliest = scan.earliest_available_date
- if earliest is None:
- self._log(
- "Italy Calendar scan completed without a positive month."
- )
- return result
- earliest_dt = datetime.combine(earliest, datetime.min.time())
- result.success = True
- result.availability_status = AvailabilityStatus.Available
- result.earliest_date = earliest_dt
- result.availability = [
- DateAvailability(date=earliest_dt, times=[])
- ]
- self._log(
- "Italy Calendar found the first positive month; "
- f"earliest_date={earliest.isoformat()}."
- )
- return result
- # -------------------------------------------------------------
- # 3. Book
- # -------------------------------------------------------------
- def _inspect_booking_form_structure(
- self,
- booking_path: str,
- ) -> Dict[str, Any]:
- """Read structural metadata only; never read values or submit the form."""
- if not self.page:
- raise BizLogicError(
- "Italy booking-form inspection requires an initialized browser session"
- )
- raw = self.page.run_js(BOOKING_FORM_DISCOVERY_SCRIPT)
- if not isinstance(raw, dict):
- raise BizLogicError(
- "Italy booking form disappeared before structural inspection"
- )
- raw_form = raw.get("form") if isinstance(raw.get("form"), dict) else {}
- raw_fields = raw.get("fields") if isinstance(raw.get("fields"), list) else []
- raw_buttons = (
- raw.get("buttons") if isinstance(raw.get("buttons"), list) else []
- )
- def metadata_text(value: object) -> Optional[str]:
- if value is None:
- return None
- text = re.sub(r"\s+", " ", str(value)).strip()
- return text[:120] or None
- def bounded_count(value: object, fallback: int, maximum: int) -> int:
- try:
- parsed = int(value)
- except (TypeError, ValueError):
- parsed = fallback
- return max(0, min(parsed, maximum))
- structure = {
- "path": metadata_text(raw.get("path")),
- "form": {
- "method": metadata_text(raw_form.get("method")),
- "action_path": metadata_text(raw_form.get("action_path")),
- },
- "field_count": bounded_count(
- raw.get("field_count"), len(raw_fields), 10000
- ),
- "fields_truncated": bool(
- raw.get("fields_truncated") or len(raw_fields) > 100
- ),
- "fields": [
- {
- "tag": metadata_text(item.get("tag")),
- "type": metadata_text(item.get("type")),
- "id": metadata_text(item.get("id")),
- "name": metadata_text(item.get("name")),
- "required": bool(item.get("required")),
- }
- for item in raw_fields[:100]
- if isinstance(item, dict)
- ],
- "button_count": bounded_count(
- raw.get("button_count"), len(raw_buttons), 10000
- ),
- "buttons_truncated": bool(
- raw.get("buttons_truncated") or len(raw_buttons) > 50
- ),
- "buttons": [
- {
- "tag": metadata_text(item.get("tag")),
- "type": metadata_text(item.get("type")),
- "id": metadata_text(item.get("id")),
- "name": metadata_text(item.get("name")),
- "text": metadata_text(item.get("text")),
- }
- for item in raw_buttons[:50]
- if isinstance(item, dict)
- ],
- }
- self.last_booking_form_structure = structure
- if structure["path"] != booking_path:
- raise BizLogicError(
- "Italy booking form appeared on an unexpected path during Book recheck"
- )
- if not structure["form"]["method"] or not structure["form"]["action_path"]:
- raise BizLogicError(
- "Italy booking form is missing method or action metadata"
- )
- return structure
- def book(self, slot_info: VSQueryResult, user_inputs: Dict = None) -> VSBookResult:
- if self.free_config.get("otp_mode") in {"manual", "cloud"}:
- if not self.page or not isinstance(slot_info, VSQueryResult):
- raise BizLogicError("Italy Book requires a browser Session and Query trigger")
- return book(self, slot_info, user_inputs)
- return self._book_discovery_or_prepared(slot_info, user_inputs)
- def _book_final_configuration_valid(self) -> bool:
- value = self.free_config.get("final_submit_enabled", False)
- return value is False or (
- value is True and self.free_config.get("otp_mode") in ("manual", "cloud")
- and self.free_config.get("query_mode", SERVICES_PROBE_QUERY_MODE) == SERVICES_PROBE_QUERY_MODE
- )
- def _book_discovery_or_prepared(self, slot_info: VSQueryResult, user_inputs: Dict = None) -> VSBookResult:
- """Recheck the user's Session; prepared Calendar stops before final."""
- res = VSBookResult()
- res.success = False
- self.last_booking_form_structure = None
- self.last_booking_precommit = None
- if not self.page:
- raise BizLogicError("Italy Book requires an initialized browser session")
- if not isinstance(slot_info, VSQueryResult):
- raise BizLogicError("Italy Book requires a VSQueryResult trigger")
- self._log(
- "Rechecking the target Italy service in the user's authenticated Session..."
- )
- route = self._resolve_route(slot_info.apt_type)
- current_path = urlparse(str(self.page.url or "")).path.rstrip("/") or "/"
- if (current_path == CALENDAR_PATH
- or getattr(self, "_calendar_book_prepared_context", None) is not None):
- return self._book_prepared_calendar(slot_info, route, user_inputs)
- recheck = self.query(slot_info.apt_type)
- if not recheck.success:
- self._log("Target Italy service is no longer available for this user Session.")
- res.label = BOOKING_RECHECK_NONE_AVAILABLE_LABEL
- return res
- self._inspect_booking_form_structure(self._booking_path(route))
- res.label = BOOKING_FORM_DISCOVERY_STOP_LABEL
- self._log(
- "Italy booking form reached; stopped before AVANTI for field verification."
- )
- return res
- # --- 资源清理核心方法 ---
- def cleanup(self):
- """
- 销毁浏览器并彻底删除临时文件
- """
- self._cleanup_attempted = True
- cleanup_failed = False
- # 1. 关闭浏览器
- if self.page:
- try:
- self.page.quit() # 这会关闭 Chrome 进程
- except Exception:
- # DrissionPage already handles an ordinary disconnection in
- # quit(). An additional failure must not silently permit a
- # second browser to take ownership of this persistent profile.
- cleanup_failed = True
- self.page = None
- self.is_healthy = False
- self._clear_calendar_query_state()
- self._reset_calendar_book_state()
- # 2. 删除文件
- # 注意:Chrome 关闭后可能需要几百毫秒释放文件锁,稍微等待
- if os.path.exists(self.root_workspace):
- for _ in range(3):
- try:
- time.sleep(0.2)
- shutil.rmtree(self.root_workspace, ignore_errors=True)
- break
- except Exception as e:
- # 如果删除失败(通常是Windows文件占用),重试
- self._log(f"Cleanup retry: {e}")
- time.sleep(0.5)
- # 如果依然存在,打印警告(虽然 ignore_errors=True 会掩盖报错,但可以 check exists)
- if os.path.exists(self.root_workspace):
- self._log(f"[WARN] Failed to fully remove workspace: {self.root_workspace}")
- cleanup_failed = True
- # 3. [新增] 关闭代理隧道
- if self.tunnel:
- try: self.tunnel.stop()
- except Exception: cleanup_failed = True
- self.tunnel = None
- self._release_persistent_profile_lock()
- if cleanup_failed:
- raise BizLogicError("Italy cleanup did not complete; automatic recreation is unsafe")
- def get_plugin_status(self) -> PluginStatus:
- account_name = self.config.account.username if self.config and self.config.account else ""
- proxy_info = f"{self.config.proxy.ip}:{self.config.proxy.port}" if self.config and self.config.proxy and self.config.proxy.ip else ""
- current_url = ""
- if self.page:
- try:
- current_url = self.page.url
- except Exception:
- pass
- state = getattr(self, "_query_stop_reason", None) or ("running" if self.is_healthy else "unhealthy")
- return PluginStatus(
- instance_id=self.instance_id,
- is_healthy=self.is_healthy,
- state=state,
- current_url=self._url_for_log(current_url) if current_url else "",
- account=account_name,
- proxy=proxy_info,
- session_age_sec=0,
- last_active_at=utc_now_str(),
- )
- def __del__(self):
- """
- 析构函数:当对象被垃圾回收时自动调用
- """
- try:
- if not getattr(self, "_cleanup_attempted", False):
- self.cleanup()
- except Exception:
- # Explicit lifecycle owners report cleanup errors. A finalizer
- # must not retry business actions or emit unraisable tracebacks.
- pass
|