debug_ita_book_gate.py 42 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782
  1. #!/usr/bin/env python3
  2. """Prepare an applicant Calendar; default stops before final booking.
  3. Default/preflight is local-only. --run permits one manual OTP and one AVANTI
  4. in a new temporary browser. --use-local-query-account explicitly reuses the
  5. saved credentials only; Query browser profiles are never loaded.
  6. Q-CAL supplies preparation/audit helpers; CS4B owns all Calendar decisions.
  7. --submit-once adds a separately confirmed REAL submission for local discovery,
  8. with a persistent local fence and manual receipt review, never production final.
  9. """
  10. from __future__ import annotations
  11. import argparse
  12. import hashlib
  13. import json
  14. import math
  15. import os
  16. import re
  17. import sys
  18. from dataclasses import dataclass, field
  19. from pathlib import Path
  20. from typing import Callable, Mapping
  21. REPO_ROOT = Path(__file__).resolve().parents[1]
  22. if str(REPO_ROOT) not in sys.path:
  23. sys.path.insert(0, str(REPO_ROOT))
  24. from plugins import ita_plugin as calendar_book
  25. from plugins.ita_plugin import FinalReceiptReadPort
  26. from plugins.ita_plugin import CALENDAR_PATH, guard_calendar, same_origin_path
  27. from plugins.ita_plugin import (
  28. BOOKING_CALENDAR_PREFINAL_STOP_LABEL,
  29. BOOKING_FORM_DISCOVERY_STOP_LABEL,
  30. BOOKING_RECHECK_NONE_AVAILABLE_LABEL,
  31. PERSISTENT_BROWSER_PROFILE_KEY,
  32. SERVICES_PROBE_QUERY_MODE,
  33. ItaPlugin,
  34. )
  35. from plugins.ita_plugin import ItaRouteConfig, PrecommitApproval, resolve_route_config
  36. from tools import debug_ita_calendar_gate as preparation
  37. from tools import ita_final_evidence as final_evidence
  38. from tools.debug_ita_query import DEBUG_ROUTE_ENV_NAMES, _popup_text_for_log, resolve_debug_route
  39. from tools.debug_ita_session import _get_credentials, resolve_chrome_path
  40. from utils.ita_local_profile import ITA_QUERY_ACCOUNT_FILE
  41. from utils.local_account import LocalAccountConfigurationError, load_local_account
  42. from vs_types import AppointmentType, AvailabilityStatus, BizLogicError, VSBookResult, VSQueryResult
  43. BOOK_GATE_CONTRACT = "book-final-attribution-v9"
  44. CALENDAR_READY_TIMEOUT_SECONDS = 5
  45. BOOK_GATE_SOURCE_PATHS = (
  46. Path(__file__), Path(preparation.__file__),
  47. REPO_ROOT / "plugins" / "ita_plugin.py",
  48. REPO_ROOT / "plugins" / "ita_plugin.py",
  49. REPO_ROOT / "plugins" / "ita_plugin.py",
  50. REPO_ROOT / "plugins" / "ita_plugin.py",
  51. REPO_ROOT / "plugins" / "ita_plugin.py",
  52. REPO_ROOT / "plugins" / "ita_plugin.py",
  53. REPO_ROOT / "plugins" / "ita_plugin.py",
  54. REPO_ROOT / "plugins" / "ita_plugin.py",
  55. REPO_ROOT / "tools" / "debug_ita_query.py",
  56. REPO_ROOT / "tools" / "debug_ita_session.py",
  57. REPO_ROOT / "tools" / "ita_final_evidence.py",
  58. REPO_ROOT / "tools" / "ita_local_handoff.py",
  59. REPO_ROOT / "utils" / "local_account.py",
  60. REPO_ROOT / "utils" / "ita_local_profile.py",
  61. )
  62. BOOK_GATE_FINGERPRINT = hashlib.sha256(
  63. b"".join(path.read_bytes() for path in BOOK_GATE_SOURCE_PATHS)
  64. ).hexdigest()[:12]
  65. _COUNT_KEYS = {"otpRequests", "avantiPosts", "availabilityRequests", "finalRequests"}
  66. class BookGateError(ValueError):
  67. """Tool-owned safe message, with no provider data or credential values."""
  68. @dataclass(frozen=True)
  69. class _ApplicantBinding:
  70. plugin_id: int
  71. page: object = field(repr=False)
  72. tab_id: str = field(repr=False)
  73. username: str = field(repr=False)
  74. login_generation: float
  75. route: ItaRouteConfig
  76. @classmethod
  77. def capture(cls, plugin: ItaPlugin, username: str, route: ItaRouteConfig):
  78. page = plugin.page
  79. generation = plugin.session_create_time
  80. if (not page or not isinstance(page.tab_id, str) or not page.tab_id
  81. or type(generation) not in (int, float)
  82. or not math.isfinite(generation) or generation <= 0):
  83. raise BookGateError("Applicant Session identity is unavailable")
  84. binding = cls(id(plugin), page, page.tab_id, username.strip().casefold(), generation, route)
  85. binding.require_current(plugin, expected_path="/UserArea")
  86. return binding
  87. def require_current(self, plugin: ItaPlugin, *, expected_path: str | None = None) -> None:
  88. if (id(plugin) != self.plugin_id or plugin.page is not self.page
  89. or self.page.tab_id != self.tab_id
  90. or not self.username
  91. or plugin.config.account.username.strip().casefold() != self.username
  92. or plugin.session_create_time != self.login_generation
  93. or plugin.free_config.get(PERSISTENT_BROWSER_PROFILE_KEY) is not None
  94. or getattr(plugin, "_persistent_profile_path", None) is not None
  95. or plugin.free_config.get("final_submit_enabled") is not False
  96. or plugin.free_config.get("query_mode") != SERVICES_PROBE_QUERY_MODE
  97. or getattr(plugin, "_calendar_query_route_key", None) is not None
  98. or plugin._resolve_route(
  99. AppointmentType(routing_key=self.route.routing_key)
  100. ) != self.route):
  101. raise BookGateError("Applicant, browser, route or preparation identity changed")
  102. path, _ = same_origin_path(self.page.url)
  103. if expected_path is not None and path != expected_path:
  104. raise BookGateError("Applicant browser is not on the expected stage")
  105. def _counts(audit: preparation.CalendarRequestAudit) -> dict[str, int]:
  106. raw = audit.settled_snapshot()
  107. if (not isinstance(raw, dict) or set(raw) != _COUNT_KEYS
  108. or any(type(value) is not int or value < 0 for value in raw.values())):
  109. raise BookGateError("Business-request audit shape changed")
  110. return raw
  111. def _budget(counts: dict[str, int], *, otp: int, avanti: int, before_calendar: bool = False) -> None:
  112. if (counts["otpRequests"] != otp or counts["avantiPosts"] != avanti
  113. or counts["finalRequests"] != 0
  114. or (before_calendar and counts["availabilityRequests"] != 0)):
  115. raise BookGateError("Business requests exceeded the current one-shot budget")
  116. def _current_packet(packet: object, binding: _ApplicantBinding) -> None:
  117. if (getattr(packet, "tab_id", None) != binding.tab_id
  118. or getattr(packet, "is_failed", None) is not False
  119. or type(packet.response.status) is not int):
  120. raise BookGateError("Preparation response is not a completed request from this applicant tab")
  121. def _guarded_preflight_script(route: ItaRouteConfig, booking_path: str) -> str:
  122. return preparation.calendar_session.guarded_preflight_script(route, booking_path)
  123. def _wait_preflight(plugin: ItaPlugin, binding: _ApplicantBinding, stage) -> None:
  124. booking_path = f"/Services/Booking/{binding.route.service_id}"
  125. binding.require_current(plugin, expected_path=booking_path)
  126. preparation.wait_for_booking_preflight(
  127. binding.page, script=_guarded_preflight_script(binding.route, booking_path), stage=stage,
  128. )
  129. binding.require_current(plugin, expected_path=booking_path)
  130. def _native_click(plugin: ItaPlugin, binding: _ApplicantBinding, selector: str) -> None:
  131. binding.require_current(plugin, expected_path=f"/Services/Booking/{binding.route.service_id}")
  132. plugin.mouse.human_click_ele(preparation._element_or_fail(binding.page, selector))
  133. def _require_stop_result(result: object) -> VSBookResult:
  134. if (not isinstance(result, VSBookResult) or result.success is not False
  135. or any(getattr(result, key) for key in
  136. ("session_id", "urn", "account", "book_date", "book_time", "payment_link"))):
  137. raise BookGateError("Book returned appointment-success data during a pre-final gate")
  138. return result
  139. def _selection_readback(
  140. plugin: ItaPlugin, binding: _ApplicantBinding, user_inputs: dict, result: VSBookResult,
  141. ) -> dict:
  142. binding.require_current(plugin, expected_path=CALENDAR_PATH)
  143. guard_calendar(binding.page)
  144. if not plugin._calendar_book_context_matches(binding.route, binding.username):
  145. raise BookGateError("Book-specific Calendar preparation is no longer current")
  146. approval = plugin.last_booking_precommit
  147. if result.label == BOOKING_RECHECK_NONE_AVAILABLE_LABEL and approval is None:
  148. return {"selectionVerified": False, "selectedDate": None, "selectedTime": None,
  149. "remaining": None, "bookResultSuccess": False}
  150. if result.label != BOOKING_CALENDAR_PREFINAL_STOP_LABEL or not isinstance(approval, PrecommitApproval):
  151. raise BookGateError("Book did not return the expected pre-final checkpoint")
  152. candidate = approval.candidate
  153. start, end = calendar_book.book_date_preferences(user_inputs)
  154. if (not start <= candidate.day <= end or not approval.calendar_day.is_available
  155. or not candidate.is_available or candidate.day != approval.calendar_day.day):
  156. raise BookGateError("Book checkpoint does not match positive inventory and date preferences")
  157. service = calendar_book.read_calendar_service(binding.page)
  158. raw = calendar_book._snapshot(binding.page, service, candidate.day, candidate, click=False)
  159. calendar_book._require_ready(raw, candidate.day)
  160. if (raw["clicked"] or raw["activeCount"] != 1 or raw["activeInputCount"] != 1
  161. or raw["activeUnavailable"] or raw["activeRedDot"]
  162. or not all(raw[key] for key in (
  163. "activeIsCandidate", "activeIdMatches", "activeDayMatches",
  164. "activeTimeMatches", "activeCapacityMatches",
  165. ))):
  166. raise BookGateError("Selected slot changed before the read-only gate readback")
  167. return {"selectionVerified": True, "selectedDate": candidate.day.isoformat(),
  168. "selectedTime": candidate.time_label, "remaining": candidate.slots_free,
  169. "bookResultSuccess": False}
  170. def _book_credentials(
  171. env: Mapping[str, str], *, use_local_query_account: bool = False,
  172. ) -> tuple[str, str]:
  173. if use_local_query_account:
  174. try:
  175. account = load_local_account(ITA_QUERY_ACCOUNT_FILE)
  176. except LocalAccountConfigurationError:
  177. raise BookGateError(
  178. "Local Query account is invalid; check config/ita_query_account.local.json "
  179. "and its private file permissions"
  180. ) from None
  181. print("ITA_BOOK_GATE_CREDENTIALS role=applicant profile=temporary source=local_query_file", flush=True)
  182. return account.username, account.password
  183. # A projection rather than dict(env): Query/general credentials cannot leak
  184. # into the fallback helper even when inherited from the user's terminal.
  185. print("ITA_BOOK_GATE_CREDENTIALS role=applicant profile=temporary source=book_environment_or_prompt", flush=True)
  186. return _get_credentials({
  187. "ITA_USERNAME": env.get("ITA_BOOK_USERNAME", ""),
  188. "ITA_PASSWORD": env.get("ITA_BOOK_PASSWORD", ""),
  189. }, non_interactive=False)
  190. def _resolve_inputs(env: Mapping[str, str], user_inputs: Mapping[str, str] | None):
  191. if any(not str(env.get(name, "")).strip() for name in DEBUG_ROUTE_ENV_NAMES):
  192. raise BookGateError("Book gate requires all four explicit ITA route fields")
  193. preferences = dict(user_inputs or {})
  194. if not set(preferences) <= {"expected_start_date", "expected_end_date"}:
  195. raise BookGateError("Gate inputs may only contain the two date preferences")
  196. calendar_book.book_date_preferences(preferences)
  197. debug_route = resolve_debug_route(env)
  198. chrome_path = resolve_chrome_path(env)
  199. # Synthetic values only validate the existing config builder. Nothing leaves
  200. # this process, and no account file or real credential is read in preflight.
  201. config = preparation.build_calendar_gate_config(
  202. env, username="preflight@example.test", password="local-only", route=debug_route,
  203. )
  204. route = resolve_route_config(config.free_config["apt_configs"], debug_route.routing_key)
  205. return debug_route, route, chrome_path, preferences
  206. _PREPARATION_FAILURES = {
  207. "Italy Book preparation requires a single-tourism Calendar route": "route_not_supported",
  208. "Italy Book cannot reuse a Query preparation or another route": "query_or_route_mismatch",
  209. "Italy Book preparation requires an authenticated user Session and final disabled": "applicant_session_not_ready",
  210. "Italy Book preparation did not identify the current Calendar service": "calendar_service_unidentified",
  211. "Italy Book Calendar service did not initialize before timeout": "calendar_service_not_ready",
  212. }
  213. _PRODUCTION_BOOK_FAILURES = {
  214. "Book date control structure changed": "date_snapshot_structure_changed",
  215. "Book date control types changed": "date_snapshot_types_changed",
  216. "Book date control context was not unique and guarded": "date_context_not_ready",
  217. "Book date readback unexpectedly clicked": "date_readback_clicked",
  218. "Book date is already selected without a fresh captured response": "date_selected_without_fresh_response",
  219. "Book date control was not ready before timeout": "date_control_timeout",
  220. "Book date click was not acknowledged": "date_click_not_acknowledged",
  221. "Book selected date did not match the response before timeout": "selected_date_timeout",
  222. "Book TimeSlots request date format changed": "timeslot_request_date_format_changed",
  223. "Book TimeSlots request method or path changed": "timeslot_request_route_changed",
  224. "Book TimeSlots response status was not 200": "timeslot_response_status_rejected",
  225. "Book TimeSlots request fields changed": "timeslot_request_fields_changed",
  226. "Book TimeSlots request does not match the current service": "timeslot_service_mismatch",
  227. "Book TimeSlots request does not match the target day": "timeslot_request_day_mismatch",
  228. "Book TimeSlots response contains another day": "timeslot_response_day_mismatch",
  229. "Book TimeSlots packet could not be validated": "timeslot_packet_invalid",
  230. "Book slot snapshot fields changed": "slot_snapshot_fields_changed",
  231. "Book slot snapshot boolean types changed": "slot_snapshot_types_changed",
  232. "Book selected-date snapshot types changed": "selected_date_snapshot_types_changed",
  233. "Book slot DOM changed its context or uniqueness": "slot_context_changed",
  234. "Book slot DOM did not match the response before timeout": "slot_dom_timeout",
  235. "Book candidate is not safely selectable": "candidate_not_selectable",
  236. "Book selected day is marked unavailable": "selected_day_unavailable",
  237. "Book date or slot is not unique": "date_or_slot_not_unique",
  238. "Book timeline and content dates do not match the target": "selected_dates_mismatch",
  239. "Book Availability and TimeSlots disagree": "inventory_disagreement",
  240. "Book read-only snapshot unexpectedly clicked": "slot_snapshot_clicked",
  241. "Book slot click was not acknowledged": "slot_click_not_acknowledged",
  242. "Book readback unexpectedly clicked": "slot_readback_clicked",
  243. "Book precommit rejected (precommit_rejected)": "precommit_readback_rejected",
  244. "Book Calendar selection or final guard failed": "selection_or_guard_failed",
  245. "Book applicant, route or browser Session changed": "applicant_context_changed",
  246. "Book Calendar runtime service changed": "calendar_service_changed",
  247. "Book response did not belong to the current browser tab": "response_tab_mismatch",
  248. "Book browser request failed": "browser_request_failed",
  249. "Book Calendar recheck failed; no further action was attempted": "calendar_recheck_failed",
  250. "Italy Book Calendar failed before final confirmation": "calendar_internal_failure",
  251. "Book final-button guard could not be verified": "final_guard_failed",
  252. }
  253. BOOK_FAILURE_STATE_SCRIPT = r"""
  254. /* coordinate:ita-book-failure-state-readonly */
  255. const service = Array.from(document.querySelectorAll('#idServizio'));
  256. const timeline = Array.from(document.querySelectorAll('.events a.selected'));
  257. const content = Array.from(document.querySelectorAll('.events-content li.selected'));
  258. const slots = content.length === 1 ? Array.from(content[0].querySelectorAll('.fascia')) : [];
  259. const finalButtons = Array.from(document.querySelectorAll('#btnPrenotaNoOtp'));
  260. const states = slots.slice(0, 12).map(slot => {
  261. const style = window.getComputedStyle(slot), rect = slot.getBoundingClientRect();
  262. const left = Math.max(0, rect.left), right = Math.min(window.innerWidth, rect.right);
  263. const top = Math.max(0, rect.top), bottom = Math.min(window.innerHeight, rect.bottom);
  264. const inViewport = right > left && bottom > top;
  265. const hit = inViewport ? document.elementFromPoint((left + right)/2, (top + bottom)/2) : null;
  266. return {
  267. active: slot.classList.contains('act'),
  268. markedUnavailable: slot.classList.contains('notAvailableFascia'),
  269. redDot: Boolean(slot.querySelector('.dotRed')),
  270. cssVisible: style.display !== 'none' && style.visibility !== 'hidden' &&
  271. style.pointerEvents !== 'none' && Number.parseFloat(style.opacity || '1') > 0,
  272. hasSize: rect.width > 0 && rect.height > 0,
  273. inViewport,
  274. centerHit: Boolean(hit && (hit === slot || slot.contains(hit))),
  275. hiddenInputCount: slot.querySelectorAll('input[type="hidden"]').length,
  276. };
  277. });
  278. return {
  279. pathMatches: location.origin === 'https://prenotami.esteri.it' && location.pathname === '/BookingCalendar',
  280. serviceControlCount: service.length,
  281. serviceValuePresent: service.length === 1 && typeof service[0].value === 'string' && Boolean(service[0].value),
  282. timelineSelectedCount: timeline.length, contentSelectedCount: content.length,
  283. firstSelectedIsTimeline: timeline.length === 1 && document.querySelector('.selected') === timeline[0],
  284. selectedDatesMatch: timeline.length === 1 && content.length === 1 && Boolean(timeline[0].dataset.date) &&
  285. timeline[0].dataset.date === content[0].dataset.date,
  286. slotCount: slots.length, activeSlotCount: document.querySelectorAll('.fascia.act').length,
  287. finalButtonCount: finalButtons.length,
  288. finalGuarded: finalButtons.length === 1 && finalButtons[0].disabled === true &&
  289. finalButtons[0].dataset.coordinateFinalGuard === 'enabled',
  290. timeSlotResourceEntries: performance.getEntriesByType('resource').filter(entry => {
  291. try { const url = new URL(entry.name); return url.origin === location.origin &&
  292. url.pathname === '/BookingCalendar/RetrieveTimeSlots'; } catch (_) { return false; }
  293. }).length,
  294. slotStatesTruncated: slots.length > states.length, slotStates: states,
  295. };
  296. """
  297. _BOOK_STATE_BOOLS = {"pathMatches", "serviceValuePresent", "selectedDatesMatch", "firstSelectedIsTimeline",
  298. "finalGuarded", "slotStatesTruncated"}
  299. _BOOK_STATE_COUNTS = {"serviceControlCount", "timelineSelectedCount", "contentSelectedCount", "slotCount",
  300. "activeSlotCount", "finalButtonCount", "timeSlotResourceEntries"}
  301. _BOOK_SLOT_BOOLS = {"active", "markedUnavailable", "redDot", "cssVisible", "hasSize", "inViewport", "centerHit"}
  302. def _print_production_book_diagnostic(page: object) -> None:
  303. """After-failure shape/visibility only; never emit browser text or field values."""
  304. result = {"contract": BOOK_GATE_CONTRACT, "afterFailure": True, "readSucceeded": False}
  305. try:
  306. if same_origin_path(page.url)[0] != CALENDAR_PATH:
  307. raise ValueError("Not Calendar")
  308. raw = page.run_js(BOOK_FAILURE_STATE_SCRIPT)
  309. if (not isinstance(raw, dict) or set(raw) != _BOOK_STATE_BOOLS | _BOOK_STATE_COUNTS | {"slotStates"}
  310. or any(type(raw[key]) is not bool for key in _BOOK_STATE_BOOLS)
  311. or any(type(raw[key]) is not int or not 0 <= raw[key] <= 100000 for key in _BOOK_STATE_COUNTS)
  312. or not isinstance(raw["slotStates"], list) or len(raw["slotStates"]) > 12):
  313. raise ValueError("Unrecognized state shape")
  314. for slot in raw["slotStates"]:
  315. if (not isinstance(slot, dict) or set(slot) != _BOOK_SLOT_BOOLS | {"hiddenInputCount"}
  316. or any(type(slot[key]) is not bool for key in _BOOK_SLOT_BOOLS)
  317. or type(slot["hiddenInputCount"]) is not int or not 0 <= slot["hiddenInputCount"] <= 100000):
  318. raise ValueError("Unrecognized slot shape")
  319. result.update(readSucceeded=True, state=raw)
  320. except Exception:
  321. pass # Diagnostics must neither expose raw data nor replace the original failure.
  322. print("ITA_BOOK_GATE_SELECTION_DIAGNOSTIC=" + json.dumps(result, sort_keys=True), flush=True)
  323. def _print_calendar_preparation_diagnostic(page: object) -> None:
  324. """Read structural metadata after failure; never log the runtime ID itself."""
  325. diagnostic = {"contract": BOOK_GATE_CONTRACT, "afterFailure": True, "readSucceeded": False}
  326. try:
  327. diagnostic["pathMatches"] = same_origin_path(page.url)[0] == CALENDAR_PATH
  328. if diagnostic["pathMatches"]:
  329. tab_id = getattr(page, "tab_id", None)
  330. diagnostic["tabIdPresent"] = isinstance(tab_id, str) and bool(tab_id)
  331. raw = page.run_js(calendar_book.RUNTIME_SERVICE_SCRIPT)
  332. diagnostic["readSucceeded"] = True
  333. diagnostic["snapshotIsObject"] = isinstance(raw, dict)
  334. if isinstance(raw, dict):
  335. count, value = raw.get("count"), raw.get("value")
  336. diagnostic.update(
  337. snapshotKeysMatch=set(raw) == {"path", "count", "value"},
  338. snapshotPathMatches=raw.get("path") == CALENDAR_PATH,
  339. controlCountType=(type(count).__name__ if type(count) in (int, float, bool, str, type(None)) else "other"),
  340. controlCount=(count if type(count) is int and 0 <= count <= 10000 else None),
  341. valueType=(type(value).__name__ if type(value) in (str, int, float, bool, type(None)) else "other"),
  342. valueLength=len(value) if isinstance(value, str) else None,
  343. valuePresent=bool(value) if isinstance(value, str) else None,
  344. valueTrimmed=value == value.strip() if isinstance(value, str) else None,
  345. valueAccepted=False,
  346. )
  347. if isinstance(value, str):
  348. try:
  349. calendar_book._runtime_id(value)
  350. diagnostic["valueAccepted"] = True
  351. except calendar_book.CalendarBookError:
  352. pass
  353. except Exception:
  354. # The original failure must survive a failed best-effort readback.
  355. diagnostic["readSucceeded"] = False
  356. print("ITA_BOOK_GATE_CALENDAR_DIAGNOSTIC=" + json.dumps(diagnostic, sort_keys=True), flush=True)
  357. def _stop_listener_if_active(page: object) -> None:
  358. # listen_once already stops it; the installed SDK's stop is not idempotent.
  359. listener = page.listen
  360. if listener.listening:
  361. listener.stop()
  362. def _failure(stage: str, exc: BaseException) -> None:
  363. # Provider exception strings may contain bodies, URLs, credentials or OTP.
  364. message = str(exc) if type(exc) is BookGateError else "Stage failed; use the allowlisted diagnostic"
  365. failure = {
  366. "stage": stage, "type": type(exc).__name__, "message": message,
  367. }
  368. if stage == "calendar_preparation" and type(exc) is BizLogicError and isinstance(exc.message, str):
  369. reason = _PREPARATION_FAILURES.get(exc.message)
  370. if reason:
  371. failure["reason"] = reason
  372. elif stage == "production_book" and type(exc) is BizLogicError and isinstance(exc.message, str):
  373. failure["reason"] = _PRODUCTION_BOOK_FAILURES.get(exc.message, "unclassified_book_failure")
  374. if failure["reason"] == "unclassified_book_failure":
  375. # Dynamic protocol codes never enter output; emit only a fixed category.
  376. protocol = re.fullmatch(
  377. r"Book (TimeSlots protocol|Calendar protocol|precommit) rejected \([a-z_]{1,64}\)",
  378. exc.message,
  379. )
  380. if protocol:
  381. failure["reason"] = {
  382. "TimeSlots protocol": "timeslot_protocol_rejected",
  383. "Calendar protocol": "calendar_protocol_rejected",
  384. "precommit": "precommit_readback_rejected",
  385. }[protocol[1]]
  386. print("ITA_BOOK_GATE_FAILED=" + json.dumps(failure, sort_keys=True), flush=True)
  387. def _receipt_observer(observed):
  388. def observe(page):
  389. audit = preparation.CalendarRequestAudit(page, include_time_slots=True)
  390. audit.start()
  391. def finish():
  392. try:
  393. counts = audit.settled_snapshot()
  394. expected = _COUNT_KEYS | {"timeSlotRequests"}
  395. if (not isinstance(counts, dict) or set(counts) != expected or
  396. any(type(value) is not int or value != 0 for value in counts.values())):
  397. raise BookGateError("Receipt tab emitted unexpected business requests")
  398. observed.append(counts)
  399. finally:
  400. audit.stop()
  401. return finish
  402. return observe
  403. def _single_submission_verified(audit, before):
  404. after = _counts(audit)
  405. return (before["finalRequests"] == 0 and after["finalRequests"] == 1 and
  406. all(after[k] == before[k] for k in _COUNT_KEYS - {"finalRequests"}))
  407. def _verify_receipt_baseline(plugin, route) -> dict:
  408. """Optional background-tab acceptance; no final submission is reachable."""
  409. observed = []
  410. port = FinalReceiptReadPort(plugin, route, observe_tab=_receipt_observer(observed))
  411. snapshot = port()
  412. if not port.session_is_current() or len(observed) != 1:
  413. raise BookGateError("Receipt read acceptance did not finish")
  414. calendar_book.verify_precommit_selection(plugin.page, runtime_service=port.target.runtime_service,
  415. approval=port.target.approval)
  416. return {"verified": True, "recordCount": len(snapshot.records), "calendarSelectionPreserved": True,
  417. "businessRequests": observed[0], "finalSubmissionEnabled": False}
  418. def run_book_gate(
  419. env: Mapping[str, str], *, execute: bool = False,
  420. use_local_query_account: bool = False,
  421. user_inputs: Mapping[str, str] | None = None,
  422. otp_reader: Callable[[], str] = preparation._read_manual_otp,
  423. verify_receipts: bool = False,
  424. submit_once: bool = False,
  425. final_confirm: Callable[[str], str] = input,
  426. review_reader: Callable[[str], str] = input,
  427. ) -> int:
  428. print(f"ITA_BOOK_GATE_TOOL_CONTRACT version={BOOK_GATE_CONTRACT} source_sha256={BOOK_GATE_FINGERPRINT}", flush=True)
  429. plugin = binding = audit = None
  430. before = after = observed = None
  431. preparation_counts = book_counts = None
  432. selection: dict = {}
  433. receipt_baseline = None
  434. final_run = None
  435. audit_verified = False
  436. entry_calls = calendar_calls = 0
  437. stage, outcome, exit_code = "configuration", "failed", 1
  438. try:
  439. if type(verify_receipts) is not bool:
  440. raise BookGateError("Receipt verification flag must be boolean")
  441. if type(submit_once) is not bool or (submit_once and not verify_receipts):
  442. raise BookGateError("One-shot final requires explicit receipt verification")
  443. if submit_once:
  444. final_evidence.require_unused_claim()
  445. debug_route, route, chrome_path, preferences = _resolve_inputs(env, user_inputs)
  446. if not execute:
  447. print("ITA_BOOK_GATE_PREFLIGHT_OK external_requests=0 credentials_read=false browser_created=false", flush=True)
  448. return 0
  449. if execute is not True:
  450. raise BookGateError("Book gate execute must be an explicit boolean")
  451. stage = "applicant_credentials"
  452. username, password = _book_credentials(env, use_local_query_account=use_local_query_account)
  453. config = preparation.build_calendar_gate_config(
  454. env, username=username, password=password, route=debug_route,
  455. )
  456. os.environ["CHROME_BIN"] = str(chrome_path)
  457. plugin = ItaPlugin(group_id="ita-book-prefinal-gate")
  458. plugin.set_log(lambda message: print(
  459. _popup_text_for_log(str(message).replace(username, "<applicant>").replace(password, "<password>")),
  460. flush=True,
  461. ))
  462. plugin.set_config(config)
  463. stage = "applicant_login"
  464. plugin.create_session()
  465. binding = _ApplicantBinding.capture(plugin, username, route)
  466. stage = "reservation_before"
  467. audit = preparation.CalendarRequestAudit(binding.page)
  468. audit.start()
  469. before = preparation.read_reservation_snapshot(binding.page)
  470. _budget(_counts(audit), otp=0, avanti=0, before_calendar=True)
  471. print(f"ITA_BOOK_GATE_RESERVATION_BEFORE reservations={before.reservations} waitlist={before.waitlist}", flush=True)
  472. inputs = {**preferences, "username": username}
  473. trigger = VSQueryResult(
  474. success=True, apt_type=debug_route.appointment_type(),
  475. availability_status=AvailabilityStatus.NoneAvailable,
  476. )
  477. stage = "booking_form_entry"
  478. binding.require_current(plugin)
  479. entry_calls += 1
  480. entry = _require_stop_result(plugin.book(trigger, user_inputs=inputs))
  481. binding.require_current(plugin)
  482. _budget(_counts(audit), otp=0, avanti=0, before_calendar=True)
  483. if entry.label == BOOKING_RECHECK_NONE_AVAILABLE_LABEL:
  484. outcome, exit_code = "entry_unavailable", 2
  485. elif entry.label != BOOKING_FORM_DISCOVERY_STOP_LABEL:
  486. raise BookGateError("Entry did not stop at the configured booking form")
  487. else:
  488. stage = "before_otp_send"
  489. _wait_preflight(plugin, binding, preparation.BookingPreflightStage.BEFORE_OTP_SEND)
  490. _budget(_counts(audit), otp=0, avanti=0, before_calendar=True)
  491. otp_guard = preparation.OneShotAction("Book OTP")
  492. stage = "otp_send"
  493. otp_packet = otp_guard.run(lambda: preparation.listen_once(
  494. binding.page, target=preparation.OTP_PATH, method="GET", timeout=30,
  495. action=lambda: _native_click(plugin, binding, "#otp-send"),
  496. ))
  497. _current_packet(otp_packet, binding)
  498. preparation.validate_otp_packet(otp_packet, service_id=route.service_id)
  499. del otp_packet
  500. _budget(_counts(audit), otp=1, avanti=0, before_calendar=True)
  501. print("ITA_BOOK_GATE_OTP_SENT requests=1", flush=True)
  502. stage = "manual_otp_input"
  503. otp = otp_reader()
  504. try:
  505. if not isinstance(otp, str) or re.fullmatch(r"[0-9]{4,12}", otp) is None:
  506. raise BookGateError("Manual OTP must contain 4-12 ASCII digits")
  507. binding.require_current(plugin, expected_path=debug_route.booking_path)
  508. preparation._enter_otp(plugin, otp)
  509. finally:
  510. del otp
  511. stage = "after_otp_send"
  512. _wait_preflight(plugin, binding, preparation.BookingPreflightStage.AFTER_OTP_SEND)
  513. _budget(_counts(audit), otp=1, avanti=0, before_calendar=True)
  514. stage = "avanti_transition"
  515. avanti_guard = preparation.OneShotAction("Book AVANTI")
  516. avanti_packet = None
  517. try:
  518. binding.page.set.auto_handle_alert(accept=True)
  519. avanti_packet = avanti_guard.run(lambda: preparation.listen_once(
  520. binding.page, target=debug_route.booking_path, method="POST", timeout=30,
  521. action=lambda: _native_click(plugin, binding, "#btnAvanti"),
  522. ))
  523. _current_packet(avanti_packet, binding)
  524. preparation._wait_for_calendar(binding.page)
  525. binding.require_current(plugin, expected_path=CALENDAR_PATH)
  526. transition = preparation.validate_avanti_packet(
  527. avanti_packet, booking_path=debug_route.booking_path, final_page_url=binding.page.url,
  528. )
  529. except Exception:
  530. preparation._print_avanti_failure_diagnostic(
  531. binding.page, avanti_packet, booking_path=debug_route.booking_path,
  532. )
  533. raise
  534. finally:
  535. binding.page.set.auto_handle_alert(on_off=False)
  536. avanti_packet = None
  537. stage = "calendar_preparation"
  538. try:
  539. guard_calendar(binding.page)
  540. preparation_counts = _counts(audit)
  541. _budget(preparation_counts, otp=1, avanti=1)
  542. binding.require_current(plugin, expected_path=CALENDAR_PATH)
  543. try:
  544. calendar_book.wait_for_calendar_service(
  545. binding.page,
  546. session_is_current=lambda: binding.require_current(
  547. plugin, expected_path=CALENDAR_PATH,
  548. ) is None,
  549. timeout=CALENDAR_READY_TIMEOUT_SECONDS,
  550. )
  551. except calendar_book.CalendarServiceNotReadyError:
  552. raise BizLogicError("Italy Book Calendar service did not initialize before timeout") from None
  553. except BookGateError:
  554. raise
  555. except Exception:
  556. raise BizLogicError("Italy Book preparation did not identify the current Calendar service") from None
  557. plugin._record_calendar_book_prepared_route(route)
  558. preparation_counts = _counts(audit)
  559. _budget(preparation_counts, otp=1, avanti=1)
  560. except Exception:
  561. _print_calendar_preparation_diagnostic(binding.page)
  562. raise
  563. print(f"ITA_BOOK_GATE_CALENDAR_READY transition={transition} final_requests=0", flush=True)
  564. stage = "production_book"
  565. calendar_calls += 1
  566. result = _require_stop_result(plugin.book(trigger, user_inputs=inputs))
  567. stage = "selection_readback"
  568. selection = _selection_readback(plugin, binding, inputs, result)
  569. book_counts = _counts(audit)
  570. _budget(book_counts, otp=1, avanti=1)
  571. if book_counts["availabilityRequests"] <= preparation_counts["availabilityRequests"]:
  572. raise BookGateError("Book did not observe fresh Calendar availability requests")
  573. print("ITA_BOOK_GATE_SELECTION=" + json.dumps(selection, sort_keys=True), flush=True)
  574. if verify_receipts and selection["selectionVerified"]:
  575. stage = "receipt_baseline"
  576. receipt_baseline = _verify_receipt_baseline(plugin, route)
  577. if receipt_baseline["recordCount"] != before.reservations:
  578. raise BookGateError("Receipt baseline count differs from the pre-run inventory")
  579. binding.require_current(plugin, expected_path=CALENDAR_PATH)
  580. print("ITA_BOOK_GATE_RECEIPT_BASELINE=" + json.dumps(receipt_baseline, sort_keys=True), flush=True)
  581. outcome = "pre_final" if selection["selectionVerified"] else "no_candidate_in_scan_range"
  582. exit_code = 0 if selection["selectionVerified"] else 2
  583. if submit_once and selection["selectionVerified"]:
  584. stage = "final_evidence"
  585. binding.require_current(plugin, expected_path=CALENDAR_PATH)
  586. _budget(_counts(audit), otp=1, avanti=1)
  587. final_run = final_evidence.FinalEvidenceRun(
  588. plugin, route, observe_tab=_receipt_observer([]),
  589. verify_submission=lambda: _single_submission_verified(audit, book_counts),
  590. )
  591. final_run.execute(confirm=final_confirm)
  592. outcome = final_run.report["outcome"]
  593. exit_code = 4 if final_run.possibly_submitted else 2
  594. except (KeyboardInterrupt, EOFError):
  595. print(f"ITA_BOOK_GATE_CANCELLED stage={stage} retries=0", flush=True)
  596. outcome, exit_code = "cancelled", 130
  597. except Exception as exc:
  598. if stage == "production_book" and binding is not None:
  599. _print_production_book_diagnostic(binding.page)
  600. _failure(stage, exc)
  601. exit_code = 1
  602. finally:
  603. if final_run is not None and final_run.possibly_submitted:
  604. # Never report an interrupted/lost acknowledgement as safely retryable.
  605. outcome = final_run.report["outcome"]
  606. exit_code = 0 if final_run.report["bookingConfirmed"] is True else 4
  607. print("ITA_BOOK_GATE_FINAL_EVIDENCE=" + json.dumps(final_run.report, sort_keys=True), flush=True)
  608. try:
  609. final_evidence.wait_for_receipt_review(reader=review_reader)
  610. except (KeyboardInterrupt, EOFError):
  611. print("ITA_FINAL_REVIEW_INTERRUPTED do_not_retry=true", flush=True)
  612. except Exception:
  613. print("ITA_FINAL_REVIEW_UNAVAILABLE do_not_retry=true", flush=True)
  614. # Best-effort read-only reconciliation, including failures after a write.
  615. # No OTP, form action, or Calendar retry is performed during cleanup.
  616. if binding is not None:
  617. try:
  618. binding.require_current(plugin)
  619. # NativeFinalSubmitter re-guards its button. The pre-final guard
  620. # asserts ZERO historical final requests, so it must not run
  621. # after an authorized submission; the final audit checks <=1.
  622. if (same_origin_path(binding.page.url)[0] == CALENDAR_PATH and
  623. not (final_run is not None and final_run.possibly_submitted)):
  624. guard_calendar(binding.page)
  625. if before is not None:
  626. after = preparation.read_reservation_snapshot(binding.page)
  627. binding.require_current(plugin)
  628. print(f"ITA_BOOK_GATE_RESERVATION_AFTER reservations={after.reservations} waitlist={after.waitlist}", flush=True)
  629. if before != after and not (final_run is not None and final_run.possibly_submitted):
  630. raise BookGateError("Reservation or waitlist counts changed; do not retry")
  631. except Exception as exc:
  632. _failure("read_only_reconciliation", exc)
  633. if exit_code in (0, 2):
  634. exit_code = 1
  635. if audit is not None:
  636. try:
  637. observed = _counts(audit)
  638. final_limit = 1 if final_run is not None and final_run.possibly_submitted else 0
  639. if (observed["finalRequests"] > final_limit or observed["otpRequests"] > 1
  640. or observed["avantiPosts"] > 1):
  641. raise BookGateError("Final audit exceeded the one-shot side-effect budget")
  642. if final_run is not None and final_run.report["bookingConfirmed"] is True:
  643. if (observed["finalRequests"] != 1 or before is None or after is None or
  644. after.reservations != before.reservations + 1 or after.waitlist != before.waitlist):
  645. raise BookGateError("Confirmed booking did not retain its final audit evidence")
  646. if book_counts is not None and any(observed[k] != book_counts[k] for k in _COUNT_KEYS
  647. if k != "finalRequests" or final_limit == 0):
  648. raise BookGateError("Business requests changed after the Book readback")
  649. audit_verified = True
  650. except Exception as exc:
  651. _failure("final_request_audit", exc)
  652. if exit_code in (0, 2):
  653. exit_code = 1
  654. cleanup_failed = False
  655. for name, action in (
  656. ("listener", (lambda: _stop_listener_if_active(binding.page)) if binding is not None else None),
  657. ("audit", audit.stop if audit is not None else None),
  658. ("browser", plugin.cleanup if plugin is not None else None),
  659. ):
  660. if action is not None:
  661. try:
  662. action()
  663. except Exception as exc:
  664. cleanup_failed = True
  665. _failure(f"cleanup_{name}", exc)
  666. if cleanup_failed:
  667. exit_code = 3
  668. elif plugin is not None:
  669. print("ITA_BOOK_GATE_CLEANUP_OK", flush=True)
  670. report = {
  671. "contract": BOOK_GATE_CONTRACT, "outcome": outcome, "passed": exit_code == 0,
  672. "receiptBaseline": receipt_baseline,
  673. "finalEvidence": final_run.report if final_run is not None else None,
  674. "requestAuditVerified": audit_verified,
  675. "exitCode": exit_code, "entryBookCalls": entry_calls, "calendarBookCalls": calendar_calls,
  676. "requests": observed,
  677. "bookRequestDelta": (
  678. {key: book_counts[key] - preparation_counts[key] for key in _COUNT_KEYS}
  679. if book_counts is not None and preparation_counts is not None else None
  680. ),
  681. "reservationCountBefore": before.reservations if before is not None else None,
  682. "reservationCountAfter": after.reservations if after is not None else None,
  683. "waitlistCountBefore": before.waitlist if before is not None else None,
  684. "waitlistCountAfter": after.waitlist if after is not None else None,
  685. **selection,
  686. }
  687. if final_run is not None:
  688. report["bookResultSuccess"] = (exit_code == 0 and final_run.result is not None and
  689. final_run.result.success is True)
  690. print("ITA_BOOK_GATE_RESULT=" + json.dumps(report, sort_keys=True), flush=True)
  691. return exit_code
  692. def main(argv: list[str] | None = None) -> int:
  693. parser = argparse.ArgumentParser(description=__doc__)
  694. mode = parser.add_mutually_exclusive_group()
  695. mode.add_argument("--preflight", action="store_true", help="Local config check only (default).")
  696. mode.add_argument("--run", action="store_true", help="Allow one OTP, one AVANTI and pre-final selection; never final booking.")
  697. parser.add_argument(
  698. "--use-local-query-account", action="store_true",
  699. help="Use saved local Query credentials for this Book run, in a separate temporary browser.",
  700. )
  701. parser.add_argument("--expected-start-date", help="Inclusive applicant date preference, YYYY-MM-DD.")
  702. parser.add_argument("--expected-end-date", help="Inclusive applicant date preference, YYYY-MM-DD.")
  703. parser.add_argument("--verify-receipts", action="store_true", help="After selection, verify receipts in an owned background tab; never final booking.")
  704. parser.add_argument("--submit-once", action="store_true",
  705. help="With --run --verify-receipts: confirm a REAL appointment once, then inspect receipts. Exit 4 means do NOT retry.")
  706. args = parser.parse_args(argv)
  707. preferences = {key: value for key in ("expected_start_date", "expected_end_date")
  708. if (value := getattr(args, key)) is not None}
  709. return run_book_gate(
  710. os.environ, execute=args.run, user_inputs=preferences,
  711. use_local_query_account=args.use_local_query_account,
  712. verify_receipts=args.verify_receipts,
  713. submit_once=args.submit_once,
  714. )
  715. if __name__ == "__main__":
  716. raise SystemExit(main())