#!/usr/bin/env python3 """Run a bounded Italy Calendar discovery or production-Query safety gate. This tool is intentionally interactive. It uses an authorized team Query account, sends exactly one booking OTP, submits the pre-calendar form exactly once, then either probes the discovery horizon or calls the real production Query twice in the same prepared session. Both modes compare non-sensitive Reservation counts before and after. This tool never explicitly selects a date or time slot and never clicks the final booking button. The site's own Calendar initialization may automatically select a date when it renders. """ from __future__ import annotations import hashlib import json import os import sys import time from dataclasses import dataclass from datetime import date, datetime from enum import Enum from pathlib import Path from threading import Lock from typing import Any, Callable, Mapping from urllib.parse import parse_qs, urljoin, urlparse REPO_ROOT = Path(__file__).resolve().parents[1] if str(REPO_ROOT) not in sys.path: sys.path.insert(0, str(REPO_ROOT)) from plugins.ita_plugin import ( CALENDAR_QUERY_MODE, SERVICES_PROBE_QUERY_MODE, ItaPlugin, ) from plugins import ita_calendar_session as calendar_session from plugins.ita_calendar_query import ( AVAILABILITY_PATH, CALENDAR_PATH, NEXT_MONTH_CONTROL_SCRIPT, CalendarGateError, CalendarNextMonthUnavailableError, CalendarProbeResult, CalendarQueryScanResult, click_next_month, guard_calendar, header_value as _header, listen_once, month_text as _month_text, next_month_value as _next_month_value, parse_availability_packet, refresh_calendar, require_plain_nonnegative_int as _require_plain_nonnegative_int, same_origin_path as _same_origin_path, validate_next_month_snapshot, ) from plugins.ita_protocol import ( ItaProtocolError, ItaRouteConfig, resolve_route_config, ) from tools.debug_ita_query import ( ItaDebugRoute, _get_query_credentials, _prepare_query_profile, build_query_config, resolve_debug_route, ) from tools.debug_ita_session import ( DebugConfigurationError, _env_text, _text_for_log, resolve_chrome_path, ) from vs_types import AppointmentType, AvailabilityStatus, VSPlgConfig, VSQueryResult RESERVATION_URL = "https://prenotami.esteri.it/Reservation" OTP_PATH = "/BookingCalendar/GenerateOTP" QCAL_TOOL_CONTRACT_VERSION = "qcal1-calendar-soak-v11" QCAL_TOOL_SOURCE_PATHS = ( Path(__file__), REPO_ROOT / "plugins" / "ita_calendar_session.py", REPO_ROOT / "plugins" / "ita_calendar_query.py", REPO_ROOT / "plugins" / "ita_plugin.py", REPO_ROOT / "plugins" / "ita_protocol.py", REPO_ROOT / "plugins" / "ita_calendar_book.py", REPO_ROOT / "tools" / "debug_ita_soak.py", REPO_ROOT / "toolkit" / "backoff.py", ) QCAL_TOOL_SOURCE_FINGERPRINT = hashlib.sha256( b"".join(path.read_bytes() for path in QCAL_TOOL_SOURCE_PATHS) ).hexdigest()[:12] QCAL_MODE_ENV = "ITA_QCAL_MODE" QCAL_PRODUCTION_QUERY_ATTEMPTS = 2 QCAL_QUERY_INTERVAL_SECONDS = 3 QCAL_FORWARD_MONTHS_ENV = "ITA_QCAL_FORWARD_MONTHS" QCAL_FORWARD_MONTHS_DEFAULT = 1 QCAL_FORWARD_MONTHS_MAX = 12 QCAL_MONTH_CLICK_INTERVAL_SECONDS = 1.5 SAFE_PREFLIGHT_DIAGNOSTIC_OUTCOMES = frozenset({"ready", "waiting", "rejected", "timeout", "read_failed"}) FORM_REQUIRED_ENV_NAMES = ( "ITA_CALENDAR_LOOKAHEAD_MONTHS", "ITA_BOOKING_TYPE_CONTROL_ID", "ITA_BOOKING_TYPE_VALUE", "ITA_BOOKING_TYPE_LABELS", "ITA_PURPOSE_CONTROL_ID", "ITA_PURPOSE_VALUE", "ITA_PURPOSE_LABELS", ) RESERVATION_SNAPSHOT_SCRIPT = r""" /* coordinate:ita-qcal-reservation-counts */ const ids = ['dataTableReservations', 'dataTableReservationsWL']; const hasJQuery = Boolean(window.jQuery); const hasDataTables = Boolean( hasJQuery && jQuery.fn && jQuery.fn.dataTable ); const tableState = (id) => { const table = document.getElementById(id); if (!table) return {ready: false, count: null}; const initialized = hasDataTables && jQuery.fn.dataTable.isDataTable(table); if (initialized) { return { ready: true, count: jQuery('#' + id).DataTable().rows().count(), }; } const structurallyEmpty = table.querySelectorAll('tbody tr').length === 0 && table.querySelectorAll('thead th').length === 0 && !table.classList.contains('dataTable') && !table.closest('.dataTables_wrapper'); return { ready: structurallyEmpty, count: structurallyEmpty ? 0 : null, }; }; const reservations = tableState(ids[0]); const waitlist = tableState(ids[1]); return { path: window.location.pathname, authenticated: Boolean(document.querySelector('.app-menu')), tableCount: ids.filter((id) => document.getElementById(id)).length, ready: reservations.ready && waitlist.ready, reservations: reservations.count, waitlist: waitlist.count, }; """ AVANTI_FAILURE_DIAGNOSTIC_SCRIPT = r""" /* coordinate:ita-qcal-avanti-failure-diagnostic */ const isVisible = (element) => Boolean( element && element.getClientRects().length > 0 && window.getComputedStyle(element).visibility !== 'hidden' ); const otpInputs = document.querySelectorAll('#otp-input'); const otpInvalid = document.getElementById('IdOtpInvalid'); const bookingForm = document.getElementById('bookingForm'); const avantiButtons = document.querySelectorAll('#btnAvanti'); const turnstile = document.querySelectorAll( 'input[name="cf-turnstile-response"]' ); const validationNodes = new Set([ ...document.querySelectorAll('.field-validation-error'), ...document.querySelectorAll('.validation-summary-errors li'), ...document.querySelectorAll('[aria-invalid="true"]'), ]); const visibleValidationCount = Array.from(validationNodes).filter( isVisible ).length; const visibleConfirmCount = Array.from( document.querySelectorAll('.jconfirm-content') ).filter(isVisible).length; const resources = performance.getEntriesByType('resource'); return { path: window.location.pathname, bookingFormPresent: Boolean(bookingForm), otpInputCount: otpInputs.length, otpValuePresent: Boolean( otpInputs.length === 1 && String(otpInputs[0].value || '').trim() ), otpInvalidVisible: isVisible(otpInvalid), avantiButtonCount: avantiButtons.length, avantiDisabled: avantiButtons.length === 1 ? avantiButtons[0].disabled : null, turnstileCount: turnstile.length, turnstileTokenPresent: Boolean( turnstile.length === 1 && turnstile[0].value ), visibleValidationCount, visibleConfirmCount, finalRequestCount: resources.filter( (entry) => entry.name.includes( '/BookingCalendar/InsertNewBooking' ) ).length, }; """ from plugins.ita_calendar_session import ( BookingPreflightStage, CalendarRequestAudit, validate_otp_packet, validate_avanti_packet, validate_booking_preflight, _booking_preflight_script, _validate_preflight_except_dynamic_token, _wait_for_calendar, _element_or_fail, _read_manual_otp, _enter_otp, ) class CalendarGateMode(str, Enum): DISCOVERY_HORIZON = "discovery_horizon" PRODUCTION_QUERY = "production_query" CALENDAR_SOAK = "calendar_soak" class PositiveQueryEvidenceUnavailable(CalendarGateError): """Natural inventory did not provide evidence for the positive gate.""" def resolve_qcal_mode(env: Mapping[str, str]) -> CalendarGateMode: raw = _env_text(env, QCAL_MODE_ENV) or CalendarGateMode.DISCOVERY_HORIZON.value try: return CalendarGateMode(raw) except ValueError as exc: raise CalendarGateError( "ITA_QCAL_MODE must be discovery_horizon, production_query, or calendar_soak" ) from exc def _safe_boolean_shape(value: object) -> dict[str, object]: """Describe one boolean without serializing an unexpected value.""" is_boolean = isinstance(value, bool) return { "type": type(value).__name__, "value": value if is_boolean else None, } def _safe_nonnegative_int_shape(value: object) -> dict[str, object]: """Describe a count without serializing an unexpected value.""" is_count = ( isinstance(value, int) and not isinstance(value, bool) and value >= 0 ) return { "type": type(value).__name__, "value": value if is_count else None, } def _safe_http_status_shape(value: object) -> dict[str, object]: """Describe a conventional HTTP status without leaking response data.""" is_status = ( isinstance(value, int) and not isinstance(value, bool) and 100 <= value <= 599 ) return { "type": type(value).__name__, "value": value if is_status else None, } def _safe_path_category( raw_url: object, *, booking_path: str, ) -> str: """Map a URL to one fixed category without returning its raw value.""" if not str(raw_url or "").strip(): return "missing" normalized = urljoin("https://prenotami.esteri.it", str(raw_url)) try: path, _ = _same_origin_path(normalized) except CalendarGateError: return "unexpected_origin" if path == booking_path: return "booking" if path == CALENDAR_PATH: return "calendar" if path == "/Services": return "services" if path == "/UserArea": return "user_area" return "other_same_origin" def safe_avanti_failure_diagnostic( packet: object, raw: object, *, booking_path: str, ) -> dict[str, object]: """Return allowlisted AVANTI evidence without body, query, or form values.""" snapshot = raw if isinstance(raw, dict) else {} response = getattr(packet, "response", None) packet_url = getattr(packet, "url", "") request_matches = False try: request_path, parsed_request = _same_origin_path(packet_url) request_matches = ( str(getattr(packet, "method", "")).upper() == "POST" and request_path == booking_path and not parsed_request.query and not parsed_request.fragment ) except CalendarGateError: pass response_path = _safe_path_category( getattr(response, "url", ""), booking_path=booking_path, ) location_path = _safe_path_category( _header(getattr(response, "headers", {}), "location"), booking_path=booking_path, ) browser_path = _safe_path_category( snapshot.get("path"), booking_path=booking_path, ) diagnostic = { "contract": QCAL_TOOL_CONTRACT_VERSION, "sourceFingerprint": QCAL_TOOL_SOURCE_FINGERPRINT, "snapshotType": type(raw).__name__, "bookingPostObserved": packet is not None, "requestMatches": request_matches, "responseStatus": _safe_http_status_shape( getattr(response, "status", None) ), "responsePath": response_path, "locationPath": location_path, "browserPath": browser_path, "bookingFormPresent": _safe_boolean_shape( snapshot.get("bookingFormPresent") ), "otpValuePresent": _safe_boolean_shape( snapshot.get("otpValuePresent") ), "otpInvalidVisible": _safe_boolean_shape( snapshot.get("otpInvalidVisible") ), "avantiDisabled": _safe_boolean_shape( snapshot.get("avantiDisabled") ), "turnstileReady": _safe_boolean_shape( snapshot.get("turnstileTokenPresent") ), "visibleValidationCount": _safe_nonnegative_int_shape( snapshot.get("visibleValidationCount") ), "visibleConfirmCount": _safe_nonnegative_int_shape( snapshot.get("visibleConfirmCount") ), "finalRequestCount": _safe_nonnegative_int_shape( snapshot.get("finalRequestCount") ), } if packet is None: outcome = "booking_post_not_observed" elif browser_path == "booking": outcome = "booking_form_returned" elif response_path == "calendar" and browser_path != "calendar": outcome = "calendar_response_not_rendered" else: outcome = "unexpected_transition" return {"outcome": outcome, **diagnostic} def safe_preflight_diagnostic( raw: object, *, stage: BookingPreflightStage, outcome: str, ) -> dict[str, object]: """Return an allowlisted diagnostic with no token or form values.""" snapshot = raw if isinstance(raw, dict) else {} return { "contract": QCAL_TOOL_CONTRACT_VERSION, "sourceFingerprint": QCAL_TOOL_SOURCE_FINGERPRINT, "outcome": ( outcome if outcome in SAFE_PREFLIGHT_DIAGNOSTIC_OUTCOMES else "invalid" ), "stage": ( stage.value if isinstance(stage, BookingPreflightStage) else "invalid" ), "snapshotType": type(raw).__name__, "otpDisabled": _safe_boolean_shape( snapshot.get("otpDisabled") ), "otpValuePresent": _safe_boolean_shape( snapshot.get("otpValuePresent") ), "avantiDisabled": _safe_boolean_shape( snapshot.get("avantiDisabled") ), "turnstileReady": _safe_boolean_shape( snapshot.get("turnstileTokenPresent") ), } def safe_next_month_diagnostic(raw: object) -> dict[str, object]: """Return only fixed-shape evidence for the Calendar month control.""" snapshot = raw if isinstance(raw, dict) else {} return { "contract": QCAL_TOOL_CONTRACT_VERSION, "sourceFingerprint": QCAL_TOOL_SOURCE_FINGERPRINT, "snapshotType": type(raw).__name__, "pathMatches": _safe_boolean_shape( snapshot.get("pathMatches") ), "candidateCount": _safe_nonnegative_int_shape( snapshot.get("candidateCount") ), "actionableCount": _safe_nonnegative_int_shape( snapshot.get("actionableCount") ), "clicked": _safe_boolean_shape(snapshot.get("clicked")), } def _print_preflight_diagnostic( raw: object, *, stage: BookingPreflightStage, outcome: str, ) -> None: print( "ITA_QCAL_PREFLIGHT_DIAGNOSTIC=" + json.dumps( safe_preflight_diagnostic( raw, stage=stage, outcome=outcome, ), sort_keys=True, ), flush=True, ) def _print_next_month_diagnostic(raw: object) -> None: print( "ITA_QCAL_NEXT_MONTH_DIAGNOSTIC=" + json.dumps( safe_next_month_diagnostic(raw), sort_keys=True, ), flush=True, ) def _print_avanti_failure_diagnostic( page: object, packet: object, *, booking_path: str, ) -> dict[str, object]: """Print one bounded allowlist even when the page snapshot itself fails.""" try: raw = page.run_js(AVANTI_FAILURE_DIAGNOSTIC_SCRIPT) except Exception: raw = None diagnostic = safe_avanti_failure_diagnostic( packet, raw, booking_path=booking_path, ) print( "ITA_QCAL_AVANTI_FAILURE_DIAGNOSTIC=" + json.dumps(diagnostic, sort_keys=True), flush=True, ) return diagnostic @dataclass(frozen=True, slots=True) class ReservationSnapshot: reservations: int waitlist: int def __post_init__(self) -> None: _require_plain_nonnegative_int(self.reservations, "reservations") _require_plain_nonnegative_int(self.waitlist, "waitlist") @property def total(self) -> int: return self.reservations + self.waitlist @dataclass(frozen=True, slots=True) class CalendarMonthScanResult: probes: tuple[CalendarProbeResult, ...] requested_forward_months: int stop_reason: str def __post_init__(self) -> None: if ( isinstance(self.requested_forward_months, bool) or not isinstance(self.requested_forward_months, int) or not 1 <= self.requested_forward_months <= QCAL_FORWARD_MONTHS_MAX ): raise CalendarGateError( "requested_forward_months must be between 1 and 12" ) if not self.probes or any( not isinstance(probe, CalendarProbeResult) for probe in self.probes ): raise CalendarGateError( "Calendar month scan requires parsed probe results" ) if len(self.probes) > self.requested_forward_months + 1: raise CalendarGateError( "Calendar month scan exceeded its forward-month limit" ) 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" ) allowed_stop_reasons = { "forward_limit_reached", "next_control_unavailable", } if self.stop_reason not in allowed_stop_reasons: raise CalendarGateError( "Calendar month scan used an unknown stop reason" ) if ( self.stop_reason == "forward_limit_reached" and len(self.probes) != self.requested_forward_months + 1 ): raise CalendarGateError( "Calendar month scan ended before its forward limit" ) @property def availability_requests(self) -> int: return len(self.probes) @property def forward_clicks(self) -> int: return len(self.probes) - 1 @property def earliest_available_date(self) -> date | None: return min( ( day.day for probe in self.probes for day in probe.days if day.is_available ), default=None, ) def safe_dict(self) -> dict[str, object]: earliest = self.earliest_available_date return { "requestedForwardMonths": self.requested_forward_months, "forwardClicks": self.forward_clicks, "availabilityRequests": self.availability_requests, "startMonth": _month_text(self.probes[0].selected_month), "furthestMonth": _month_text(self.probes[-1].selected_month), "monthsWithAvailability": sum( probe.available_count > 0 for probe in self.probes ), "earliestAvailableDate": ( earliest.isoformat() if earliest is not None else None ), "stopReason": self.stop_reason, "nextControlUnavailable": ( self.stop_reason == "next_control_unavailable" ), } @dataclass(frozen=True, slots=True) class CalendarGateEvidence: before: ReservationSnapshot after: ReservationSnapshot otp_requests: int avanti_posts: int availability_requests: int final_requests: int calendar_ready: bool def __post_init__(self) -> None: for field_name in ( "otp_requests", "avanti_posts", "availability_requests", "final_requests", ): _require_plain_nonnegative_int( getattr(self, field_name), field_name, ) if not isinstance(self.calendar_ready, bool): raise CalendarGateError("calendar_ready must be a boolean") @property def passed(self) -> bool: return ( self.before == self.after and self.otp_requests == 1 and self.avanti_posts == 1 and self.availability_requests >= 2 and self.final_requests == 0 and self.calendar_ready ) def safe_dict(self) -> dict[str, object]: return { "reservationCountBefore": self.before.reservations, "waitlistCountBefore": self.before.waitlist, "reservationCountAfter": self.after.reservations, "waitlistCountAfter": self.after.waitlist, "otpRequests": self.otp_requests, "avantiPosts": self.avanti_posts, "availabilityRequests": self.availability_requests, "finalRequests": self.final_requests, "calendarReady": self.calendar_ready, "passed": self.passed, } class OneShotAction: """An in-memory at-most-once guard that burns before the action starts.""" def __init__(self, name: str) -> None: self.name = name self.attempted = False def run(self, action: Callable[[], Any]) -> Any: if self.attempted: raise CalendarGateError(f"{self.name} was already attempted") self.attempted = True return action() def _required_env_text(env: Mapping[str, str], name: str) -> str: value = _env_text(env, name) if not value: raise CalendarGateError(f"{name} is required for Q-CAL-1") return value def resolve_qcal_forward_months(env: Mapping[str, str]) -> int: """Resolve the debug-only bound without changing route semantics.""" raw = _env_text(env, QCAL_FORWARD_MONTHS_ENV) if not raw: return QCAL_FORWARD_MONTHS_DEFAULT try: value = int(raw) except ValueError as exc: raise CalendarGateError( f"{QCAL_FORWARD_MONTHS_ENV} must be an integer between 1 and 12" ) from exc if not 1 <= value <= QCAL_FORWARD_MONTHS_MAX: raise CalendarGateError( f"{QCAL_FORWARD_MONTHS_ENV} must be between 1 and 12" ) return value def _split_labels(raw: str, name: str) -> list[str]: labels = [label.strip() for label in raw.split("|") if label.strip()] if not labels: raise CalendarGateError(f"{name} must contain at least one label") return labels def build_calendar_gate_config( env: Mapping[str, str], *, username: str, password: str, persistent_profile_path: Path | None = None, route: ItaDebugRoute | None = None, ) -> VSPlgConfig: """Build one explicit live-route config while keeping production mode off.""" resolved_debug_route = route or resolve_debug_route(env) values = { name: _required_env_text(env, name) for name in FORM_REQUIRED_ENV_NAMES } try: lookahead_months = int(values["ITA_CALENDAR_LOOKAHEAD_MONTHS"]) except ValueError as exc: raise CalendarGateError( "ITA_CALENDAR_LOOKAHEAD_MONTHS must be a positive integer" ) from exc config = build_query_config( env, username=username, password=password, persistent_profile_path=persistent_profile_path, route=resolved_debug_route, ) live_route = { "service_id": resolved_debug_route.service_id, "capability": "single_schengen_tourism", "calendar_scan": {"lookahead_months": lookahead_months}, "form": { "booking_type_control_id": values[ "ITA_BOOKING_TYPE_CONTROL_ID" ], "booking_type_value": values["ITA_BOOKING_TYPE_VALUE"], "booking_type_labels": _split_labels( values["ITA_BOOKING_TYPE_LABELS"], "ITA_BOOKING_TYPE_LABELS", ), "purpose_control_id": values["ITA_PURPOSE_CONTROL_ID"], "purpose_value": values["ITA_PURPOSE_VALUE"], "purpose_labels": _split_labels( values["ITA_PURPOSE_LABELS"], "ITA_PURPOSE_LABELS", ), }, } config.free_config["apt_configs"] = { resolved_debug_route.routing_key: live_route, } try: resolve_route_config( config.free_config["apt_configs"], resolved_debug_route.routing_key, ) except ItaProtocolError as exc: raise CalendarGateError( f"Italy Q-CAL route configuration rejected ({exc.code})" ) from exc return config def wait_for_booking_preflight(page, *, script, stage=BookingPreflightStage.BEFORE_OTP_SEND, timeout=120): return calendar_session.wait_for_booking_preflight( page, script=script, stage=stage, timeout=timeout, diagnostic=_print_preflight_diagnostic, ) def read_reservation_snapshot( page: object, *, timeout: float = 20, settle_seconds: float = 5, ) -> ReservationSnapshot: """Read both row counts after the page has had time to initialize tables.""" tab = page.new_tab(RESERVATION_URL) try: tab.wait.doc_loaded() deadline = time.monotonic() + timeout settle_deadline = time.monotonic() + settle_seconds last_raw: object = None last_snapshot: ReservationSnapshot | None = None stable_samples = 0 while time.monotonic() < deadline: last_raw = tab.run_js(RESERVATION_SNAPSHOT_SCRIPT) if ( isinstance(last_raw, dict) and last_raw.get("path") == "/Reservation" and last_raw.get("authenticated") is True and last_raw.get("tableCount") == 2 and last_raw.get("ready") is True and time.monotonic() >= settle_deadline ): snapshot = ReservationSnapshot( reservations=last_raw.get("reservations"), waitlist=last_raw.get("waitlist"), ) if snapshot == last_snapshot: stable_samples += 1 else: last_snapshot = snapshot stable_samples = 1 if stable_samples >= 2: return snapshot time.sleep(0.25) raise CalendarGateError( "Reservation DataTables did not become ready before timeout" ) finally: tab.close() def _calendar_guard(page: object) -> dict[str, object]: return guard_calendar(page) def _click_next_month(page: object, *, timeout: float = 10) -> None: click_next_month( page, timeout=timeout, diagnostic=_print_next_month_diagnostic, ) def scan_calendar_horizon( page: object, *, forward_months: int, ) -> CalendarMonthScanResult: """Probe the initial month and a bounded number of native next-month pages.""" if ( isinstance(forward_months, bool) or not isinstance(forward_months, int) or not 1 <= forward_months <= QCAL_FORWARD_MONTHS_MAX ): raise CalendarGateError("forward_months must be between 1 and 12") initial_packet = listen_once( page, target=AVAILABILITY_PATH, method="POST", action=lambda: _refresh_calendar(page), timeout=30, ) probes = [parse_availability_packet(initial_packet)] _calendar_guard(page) print( "ITA_QCAL_PROBE index=0 " f"items={probes[0].item_count} " f"available={probes[0].available_count}" ) stop_reason = "forward_limit_reached" for index in range(1, forward_months + 1): time.sleep(QCAL_MONTH_CLICK_INTERVAL_SECONDS) try: packet = listen_once( page, target=AVAILABILITY_PATH, method="POST", action=lambda: _click_next_month(page), timeout=30, ) except CalendarNextMonthUnavailableError: stop_reason = "next_control_unavailable" break probe = parse_availability_packet(packet) if probe.selected_month != _next_month_value( probes[-1].selected_month ): raise CalendarGateError( "Calendar request did not advance exactly one month" ) probes.append(probe) _calendar_guard(page) print( f"ITA_QCAL_PROBE index={index} " f"items={probe.item_count} available={probe.available_count}" ) result = CalendarMonthScanResult( probes=tuple(probes), requested_forward_months=forward_months, stop_reason=stop_reason, ) print( "ITA_QCAL_MONTH_SCAN_RESULT=" + json.dumps(result.safe_dict(), sort_keys=True) ) return result def _refresh_calendar(page: object) -> None: refresh_calendar(page) def validate_production_query_result( result: object, scan: object, *, apt_type: AppointmentType, lookahead_months: int, ) -> dict[str, object]: """Compare the public VFS-style result with this call's real scan evidence.""" if not isinstance(result, VSQueryResult): raise CalendarGateError("Production Query did not return VSQueryResult") if not isinstance(scan, CalendarQueryScanResult): raise CalendarGateError("Production Query did not expose fresh scan evidence") if scan.lookahead_months != lookahead_months: raise CalendarGateError("Production Query used a different scan horizon") if result.apt_type != apt_type: raise CalendarGateError("Production Query returned a different route") earliest = scan.earliest_available_date positive = earliest is not None expected_date = ( datetime.combine(earliest, datetime.min.time()) if positive else None ) expected_status = ( AvailabilityStatus.Available if positive else AvailabilityStatus.NoneAvailable ) if ( result.success is not positive or result.availability_status is not expected_status or result.earliest_date != expected_date or len(result.availability) != int(positive) ): raise CalendarGateError("Production Query result disagrees with scan evidence") if positive and ( result.availability[0].date != expected_date or result.availability[0].times != [] ): raise CalendarGateError("Production Query must publish one earliest date without times") # Exercise the existing Sentinel serialization, without publishing to Redis. snapshot = result.to_snapshot_payload() expected_snapshot = { "routing_key": apt_type.routing_key, "country": apt_type.country, "city": apt_type.city, "visa_type": apt_type.visa_type, "availability_status": expected_status.value, "earliest_date": earliest.isoformat() if positive else None, "availability": [{"date": earliest.isoformat()}] if positive else [], "snapshot_source": "worker", } if ( set(snapshot) != set(expected_snapshot) | {"snapshot_at"} or any(snapshot.get(key) != value for key, value in expected_snapshot.items()) or not isinstance(snapshot.get("snapshot_at"), str) ): raise CalendarGateError("Production Query snapshot contract changed") return { "lookaheadMonths": lookahead_months, "scannedMonths": scan.scanned_months, "months": [ {"month": _month_text(probe.selected_month), "positiveDays": probe.available_count} for probe in scan.probes ], "stopReason": scan.stop_reason, "success": result.success, "availabilityStatus": result.availability_status.value, "earliestDate": earliest.isoformat() if positive else None, "availabilityCount": len(result.availability), "timesCount": 0, "snapshotVerified": True, } def _query_request_delta( before: Mapping[str, int], after: Mapping[str, int], *, expected_availability: int, ) -> dict[str, int]: keys = {"otpRequests", "avantiPosts", "availabilityRequests", "finalRequests"} if set(before) != keys or set(after) != keys: raise CalendarGateError("Production Query request counters changed shape") delta = {} for key in keys: previous = _require_plain_nonnegative_int(before[key], key) current = _require_plain_nonnegative_int(after[key], key) delta[key] = _require_plain_nonnegative_int(current - previous, key) if ( delta["otpRequests"] != 0 or delta["avantiPosts"] != 0 or delta["finalRequests"] != 0 or delta["availabilityRequests"] != expected_availability ): raise CalendarGateError("Production Query exceeded its read-only request contract") return delta def run_production_query_acceptance( plugin: ItaPlugin, route: ItaDebugRoute, request_audit: CalendarRequestAudit, ) -> tuple[dict[str, object], ...]: """Call the real Query twice; never replace its scanner or recreate Session.""" free_config = plugin.free_config if ( free_config.get("query_mode") != SERVICES_PROBE_QUERY_MODE or free_config.get("final_submit_enabled") is not False ): raise CalendarGateError("Production Query acceptance requires the safe debug config") protocol_route = resolve_route_config(free_config["apt_configs"], route.routing_key) if protocol_route.calendar_scan is None: raise CalendarGateError("Production Query acceptance requires a Calendar route") page = plugin.page reports = [] start_month = None free_config["query_mode"] = CALENDAR_QUERY_MODE try: for attempt in range(1, QCAL_PRODUCTION_QUERY_ATTEMPTS + 1): if attempt > 1: time.sleep(QCAL_QUERY_INTERVAL_SECONDS) print( "ITA_QCAL_PRODUCTION_QUERY_START " f"attempt={attempt} total={QCAL_PRODUCTION_QUERY_ATTEMPTS}", flush=True, ) before = request_audit.settled_snapshot() previous_scan = getattr(plugin, "last_calendar_query_scan", None) apt_type = route.appointment_type() result = plugin.query(apt_type) scan = getattr(plugin, "last_calendar_query_scan", None) if scan is previous_scan: raise CalendarGateError("Production Query reused stale scan evidence") if plugin.page is not page or plugin.free_config is not free_config: raise CalendarGateError("Production Query changed its prepared Session") report = validate_production_query_result( result, scan, apt_type=apt_type, lookahead_months=protocol_route.calendar_scan.lookahead_months, ) current_start = scan.probes[0].selected_month if start_month is not None and current_start != start_month: raise CalendarGateError("Repeated Query did not restart from the same initial month") start_month = current_start after = request_audit.settled_snapshot() report["queryRequestDelta"] = _query_request_delta( before, after, expected_availability=scan.scanned_months, ) _calendar_guard(page) report["attempt"] = attempt reports.append(report) print( "ITA_QCAL_PRODUCTION_QUERY_RESULT=" + json.dumps(report, sort_keys=True), flush=True, ) finally: # Do not call set_config(): it would erase the prepared-route proof. # This is an in-memory mode switch, never a production config write. free_config["query_mode"] = SERVICES_PROBE_QUERY_MODE return tuple(reports) def run_calendar_gate( env: Mapping[str, str], *, otp_reader: Callable[[], str] = _read_manual_otp, ) -> int: print( "ITA_QCAL_TOOL_CONTRACT " f"version={QCAL_TOOL_CONTRACT_VERSION} " f"source_sha256={QCAL_TOOL_SOURCE_FINGERPRINT}", flush=True, ) mode = resolve_qcal_mode(env) if mode is CalendarGateMode.CALENDAR_SOAK: # Validate limits before any credentials, browser, OTP, or form action. from tools.debug_ita_soak import calendar_soak_limits calendar_soak_limits(env) forward_months = ( resolve_qcal_forward_months(env) if mode is CalendarGateMode.DISCOVERY_HORIZON else None ) route = resolve_debug_route(env) chrome_path = resolve_chrome_path(env) os.environ["CHROME_BIN"] = str(chrome_path) username, password = _get_query_credentials(env, non_interactive=False) profile_path = _prepare_query_profile(username) config = build_calendar_gate_config( env, username=username, password=password, persistent_profile_path=profile_path, route=route, ) protocol_route = resolve_route_config( config.free_config["apt_configs"], route.routing_key, ) booking_path = f"/Services/Booking/{protocol_route.service_id}" print( f"ITA_QCAL_MODE mode={mode.value} " f"lookahead_months={protocol_route.calendar_scan.lookahead_months} " f"query_attempts={QCAL_PRODUCTION_QUERY_ATTEMPTS if mode is CalendarGateMode.PRODUCTION_QUERY else 0}", flush=True, ) plugin = ItaPlugin(group_id="ita-qcal-gate") plugin.set_log(lambda message: print(message, flush=True)) plugin.set_config(config) otp_guard = OneShotAction("OTP") avanti_guard = OneShotAction("AVANTI") cleanup_error: Exception | None = None request_audit: CalendarRequestAudit | None = None exit_code = 0 try: plugin.create_session() if mode in {CalendarGateMode.PRODUCTION_QUERY, CalendarGateMode.CALENDAR_SOAK}: request_audit = CalendarRequestAudit( plugin.page, include_time_slots=mode is CalendarGateMode.CALENDAR_SOAK, ) request_audit.start() before = read_reservation_snapshot(plugin.page) print( "ITA_QCAL_RESERVATION_BEFORE " f"reservations={before.reservations} waitlist={before.waitlist}" ) entry = plugin.query(route.appointment_type()) if not entry.success: if mode is CalendarGateMode.PRODUCTION_QUERY: raise PositiveQueryEvidenceUnavailable( "Service currently has no entry; positive Query gate was not exercised" ) raise CalendarGateError( "Configured service did not reach the booking form" ) preflight_script = _booking_preflight_script( protocol_route, booking_path, ) wait_for_booking_preflight( plugin.page, script=preflight_script, stage=BookingPreflightStage.BEFORE_OTP_SEND, ) otp_packet = otp_guard.run( lambda: listen_once( plugin.page, target=OTP_PATH, method="GET", action=lambda: plugin.mouse.human_click_ele( _element_or_fail(plugin.page, "#otp-send") ), timeout=30, ) ) validate_otp_packet( otp_packet, service_id=protocol_route.service_id, ) print("ITA_QCAL_OTP_SENT requests=1") otp = otp_reader() _enter_otp(plugin, otp) del otp wait_for_booking_preflight( plugin.page, script=preflight_script, stage=BookingPreflightStage.AFTER_OTP_SEND, ) plugin.page.set.auto_handle_alert(accept=True) avanti_packet = None try: avanti_packet = avanti_guard.run( lambda: listen_once( plugin.page, target=booking_path, method="POST", action=lambda: plugin.mouse.human_click_ele( _element_or_fail(plugin.page, "#btnAvanti") ), timeout=30, ) ) print("ITA_QCAL_AVANTI_POST_OBSERVED requests=1") _wait_for_calendar(plugin.page) transition_mode = validate_avanti_packet( avanti_packet, booking_path=booking_path, final_page_url=str(plugin.page.url or ""), ) plugin._record_calendar_query_prepared_route(protocol_route) except Exception: _print_avanti_failure_diagnostic( plugin.page, avanti_packet, booking_path=booking_path, ) raise finally: if mode is CalendarGateMode.CALENDAR_SOAK: plugin.page.set.auto_handle_alert(accept=False) print(f"ITA_QCAL_AVANTI_TRANSITION mode={transition_mode}") first_guard = _calendar_guard(plugin.page) print("ITA_QCAL_CALENDAR_READY avanti_posts=1 final_requests=0") if mode is CalendarGateMode.CALENDAR_SOAK: # Transfer ownership, including cleanup, to the existing soak loop. # Never leave alert auto-accept enabled during monitoring/recovery. from tools.debug_ita_soak import run_prepared_calendar_soak owned_plugin, owned_audit = plugin, request_audit plugin, request_audit = None, None return run_prepared_calendar_soak( env, plugin=owned_plugin, route=route, request_audit=owned_audit, before=before, ) production_reports = () if mode is CalendarGateMode.PRODUCTION_QUERY: preparation_counts = request_audit.settled_snapshot() if ( preparation_counts["otpRequests"] != 1 or preparation_counts["avantiPosts"] != 1 or preparation_counts["finalRequests"] != 0 ): raise CalendarGateError("Calendar preparation exceeded its one-shot request contract") production_reports = run_production_query_acceptance(plugin, route, request_audit) availability_requests = sum( report["queryRequestDelta"]["availabilityRequests"] for report in production_reports ) else: scan_result = scan_calendar_horizon( plugin.page, forward_months=forward_months, ) availability_requests = scan_result.availability_requests print( "ITA_QCAL_MONTH_NAVIGATION_VERIFIED " f"forward_clicks={scan_result.forward_clicks}" ) last_guard = _calendar_guard(plugin.page) after = read_reservation_snapshot(plugin.page) print( "ITA_QCAL_RESERVATION_AFTER " f"reservations={after.reservations} waitlist={after.waitlist}" ) final_requests = max( first_guard["finalRequestCount"], last_guard["finalRequestCount"], ) observed_counts = request_audit.settled_snapshot() if request_audit is not None else None if observed_counts is not None: final_requests = max(final_requests, observed_counts["finalRequests"]) evidence = CalendarGateEvidence( before=before, after=after, otp_requests=observed_counts["otpRequests"] if observed_counts is not None else 1, avanti_posts=observed_counts["avantiPosts"] if observed_counts is not None else 1, availability_requests=availability_requests, final_requests=final_requests, calendar_ready=True, ) gate_result = evidence.safe_dict() prefix = "ITA_QCAL_GATE_RESULT=" if mode is CalendarGateMode.PRODUCTION_QUERY: positive_queries = sum(report["success"] for report in production_reports) gate_result.update({ "mode": mode.value, "queryAttempts": len(production_reports), "positiveQueries": positive_queries, "passed": ( evidence.passed and len(production_reports) == QCAL_PRODUCTION_QUERY_ATTEMPTS and positive_queries > 0 ), }) prefix = "ITA_QCAL_PRODUCTION_QUERY_GATE_RESULT=" print(prefix + json.dumps(gate_result, sort_keys=True), flush=True) if ( mode is CalendarGateMode.PRODUCTION_QUERY and len(production_reports) != QCAL_PRODUCTION_QUERY_ATTEMPTS ): raise CalendarGateError("Production gate requires exactly two Query calls") if not evidence.passed: raise CalendarGateError("Q-CAL-1 evidence did not pass") if mode is CalendarGateMode.PRODUCTION_QUERY and not positive_queries: raise PositiveQueryEvidenceUnavailable( "Both Query calls completed without positive inventory; positive gate remains open" ) except PositiveQueryEvidenceUnavailable as exc: print(f"ITA_QCAL_PRODUCTION_QUERY_NOT_READY message={_text_for_log(exc)}", flush=True) exit_code = 2 except (CalendarGateError, DebugConfigurationError) as exc: print( f"ITA_QCAL_GATE_FAILED type={type(exc).__name__} " f"message={_text_for_log(exc)}" ) exit_code = 1 except Exception as exc: print( f"ITA_QCAL_GATE_FAILED type={type(exc).__name__} " f"message={_text_for_log(exc)}" ) exit_code = 1 finally: if request_audit is not None: try: request_audit.stop() except Exception as exc: cleanup_error = exc print( "ITA_QCAL_AUDIT_CLEANUP_FAILED " f"type={type(exc).__name__} message={_text_for_log(exc)}", file=sys.stderr, ) try: if plugin is not None: plugin.cleanup() print("ITA_QCAL_GATE_CLEANUP_OK") except Exception as exc: cleanup_error = exc print( f"ITA_QCAL_GATE_CLEANUP_FAILED type={type(exc).__name__} " f"message={_text_for_log(exc)}", file=sys.stderr, ) return 3 if cleanup_error is not None else exit_code def main() -> int: return run_calendar_gate(os.environ) if __name__ == "__main__": raise SystemExit(main())