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