| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374 |
- #!/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())
|