ita_calendar_query.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607
  1. """Shared browser adapter for read-only Prenot@Mi Calendar queries.
  2. The pure wire-format rules live in :mod:`plugins.ita_protocol`. This module
  3. owns only the browser-facing mechanics that production Query and the Q-CAL
  4. diagnostic tool must share: one-shot listeners, strict packet metadata,
  5. native month navigation, the final-button guard, and bounded scanning.
  6. """
  7. from __future__ import annotations
  8. import json
  9. import time
  10. from dataclasses import dataclass
  11. from datetime import date, datetime
  12. from typing import Any, Callable
  13. from urllib.parse import urljoin, urlparse
  14. from plugins.ita_protocol import (
  15. CalendarDay,
  16. ItaProtocolError,
  17. available_calendar_days,
  18. parse_calendar_availability,
  19. )
  20. CALENDAR_PATH = "/BookingCalendar"
  21. AVAILABILITY_PATH = "/BookingCalendar/RetrieveCalendarAvailability"
  22. MAX_QUERY_LOOKAHEAD_MONTHS = 120
  23. DEFAULT_MONTH_CLICK_INTERVAL_SECONDS = 1.5
  24. CALENDAR_GUARD_SCRIPT = r"""
  25. /* coordinate:ita-calendar-query-final-guard */
  26. const finalButtons = Array.from(
  27. document.querySelectorAll('#btnPrenotaNoOtp')
  28. );
  29. finalButtons.forEach((button) => {
  30. button.disabled = true;
  31. button.setAttribute('aria-disabled', 'true');
  32. button.dataset.coordinateFinalGuard = 'enabled';
  33. });
  34. const resources = performance.getEntriesByType('resource');
  35. return {
  36. path: window.location.pathname,
  37. calendarFunctionPresent:
  38. typeof window.CaricaTimelineOrizzontale === 'function',
  39. finalButtonCount: finalButtons.length,
  40. allFinalButtonsGuarded: finalButtons.every(
  41. (button) => button.disabled &&
  42. button.dataset.coordinateFinalGuard === 'enabled'
  43. ),
  44. finalRequestCount: resources.filter(
  45. (entry) => entry.name.includes(
  46. '/BookingCalendar/InsertNewBooking'
  47. )
  48. ).length,
  49. timeSlotRequestCount: resources.filter(
  50. (entry) => entry.name.includes(
  51. '/BookingCalendar/RetrieveTimeSlots'
  52. )
  53. ).length,
  54. };
  55. """
  56. NEXT_MONTH_CONTROL_SCRIPT = r"""
  57. /* coordinate:ita-calendar-query-next-month */
  58. const shouldClick = arguments[0] === true;
  59. const selector = '#datetimepicker th.dtpicker-next';
  60. const candidates = Array.from(document.querySelectorAll(selector));
  61. const isActionable = (element) => {
  62. if (
  63. !element.isConnected ||
  64. element.hasAttribute('disabled') ||
  65. element.getAttribute('aria-disabled') === 'true'
  66. ) {
  67. return false;
  68. }
  69. const style = window.getComputedStyle(element);
  70. if (
  71. style.display === 'none' ||
  72. style.visibility === 'hidden' ||
  73. style.pointerEvents === 'none' ||
  74. Number.parseFloat(style.opacity || '1') <= 0
  75. ) {
  76. return false;
  77. }
  78. const rect = element.getBoundingClientRect();
  79. const left = Math.max(0, rect.left);
  80. const right = Math.min(window.innerWidth, rect.right);
  81. const top = Math.max(0, rect.top);
  82. const bottom = Math.min(window.innerHeight, rect.bottom);
  83. if (right <= left || bottom <= top) return false;
  84. const topNode = document.elementFromPoint(
  85. (left + right) / 2,
  86. (top + bottom) / 2
  87. );
  88. return Boolean(topNode && (
  89. topNode === element || element.contains(topNode)
  90. ));
  91. };
  92. const actionable = candidates.filter(isActionable);
  93. let clicked = false;
  94. if (shouldClick && actionable.length === 1) {
  95. clicked = true;
  96. actionable[0].click();
  97. }
  98. return {
  99. pathMatches: window.location.pathname === '/BookingCalendar',
  100. candidateCount: candidates.length,
  101. actionableCount: actionable.length,
  102. clicked,
  103. };
  104. """
  105. class CalendarGateError(RuntimeError):
  106. """Fail-closed Calendar adapter error without sensitive response data."""
  107. class CalendarAuthenticationExpiredError(CalendarGateError):
  108. """An observed response explicitly rejected the authenticated session."""
  109. class CalendarRateLimitedError(CalendarGateError):
  110. """The server explicitly limited requests; callers must not rotate accounts."""
  111. class CalendarAccessDeniedError(CalendarGateError):
  112. """Permission or browser verification requires operator attention."""
  113. class CalendarTransientError(CalendarGateError):
  114. """A read failed without evidence that authentication or schema changed."""
  115. class CalendarNextMonthUnavailableError(CalendarGateError):
  116. """Raised when the native next-month control cannot be used safely."""
  117. def require_plain_nonnegative_int(value: object, name: str) -> int:
  118. if isinstance(value, bool) or not isinstance(value, int) or value < 0:
  119. raise CalendarGateError(f"{name} must be a nonnegative integer")
  120. return value
  121. def same_origin_path(raw_url: object) -> tuple[str, object]:
  122. parsed = urlparse(str(raw_url or ""))
  123. try:
  124. port = parsed.port
  125. except ValueError as exc:
  126. raise CalendarGateError(
  127. "Observed request used an unexpected origin"
  128. ) from exc
  129. if (
  130. parsed.scheme != "https"
  131. or parsed.hostname != "prenotami.esteri.it"
  132. or port not in (None, 443)
  133. or parsed.username is not None
  134. or parsed.password is not None
  135. ):
  136. raise CalendarGateError("Observed request used an unexpected origin")
  137. return parsed.path, parsed
  138. def header_value(headers: object, name: str) -> str:
  139. if not hasattr(headers, "items"):
  140. return ""
  141. for key, value in headers.items():
  142. if str(key).casefold() == name.casefold():
  143. return str(value)
  144. return ""
  145. @dataclass(frozen=True, slots=True)
  146. class CalendarProbeResult:
  147. days: tuple[CalendarDay, ...]
  148. selected_day: str
  149. def __post_init__(self) -> None:
  150. if not isinstance(self.selected_day, str) or not self.selected_day.strip():
  151. raise CalendarGateError("selected_day must be a non-empty string")
  152. if any(not isinstance(item, CalendarDay) for item in self.days):
  153. raise CalendarGateError("days must contain CalendarDay values")
  154. selected_month = self.selected_month
  155. if any(
  156. (item.day.year, item.day.month) != selected_month
  157. for item in self.days
  158. ):
  159. raise CalendarGateError(
  160. "Availability response escaped the requested month"
  161. )
  162. @property
  163. def item_count(self) -> int:
  164. return len(self.days)
  165. @property
  166. def available_days(self) -> tuple[CalendarDay, ...]:
  167. return available_calendar_days(self.days)
  168. @property
  169. def available_count(self) -> int:
  170. return len(self.available_days)
  171. @property
  172. def selected_month(self) -> tuple[int, int]:
  173. value = self.selected_day.strip()[:10]
  174. for date_format in ("%Y-%m-%d", "%d/%m/%Y"):
  175. try:
  176. parsed = datetime.strptime(value, date_format)
  177. except ValueError:
  178. continue
  179. return parsed.year, parsed.month
  180. raise CalendarGateError(
  181. "Availability selectedDay used an unknown date format"
  182. )
  183. def next_month_value(value: tuple[int, int]) -> tuple[int, int]:
  184. year, month = value
  185. return (year + 1, 1) if month == 12 else (year, month + 1)
  186. def month_text(value: tuple[int, int]) -> str:
  187. return f"{value[0]:04d}-{value[1]:02d}"
  188. @dataclass(frozen=True, slots=True)
  189. class CalendarQueryScanResult:
  190. """Result of scanning until the first positive month or the horizon end."""
  191. probes: tuple[CalendarProbeResult, ...]
  192. lookahead_months: int
  193. stop_reason: str
  194. def __post_init__(self) -> None:
  195. _validate_lookahead_months(self.lookahead_months)
  196. if not self.probes or any(
  197. not isinstance(probe, CalendarProbeResult)
  198. for probe in self.probes
  199. ):
  200. raise CalendarGateError(
  201. "Calendar query scan requires parsed probe results"
  202. )
  203. if len(self.probes) > self.lookahead_months:
  204. raise CalendarGateError(
  205. "Calendar query scan exceeded the configured horizon"
  206. )
  207. for previous, current in zip(self.probes, self.probes[1:]):
  208. if current.selected_month != next_month_value(
  209. previous.selected_month
  210. ):
  211. raise CalendarGateError(
  212. "Calendar request did not advance exactly one month"
  213. )
  214. if self.stop_reason == "first_available_month":
  215. if self.probes[-1].available_count == 0:
  216. raise CalendarGateError(
  217. "first-available stop requires a positive final probe"
  218. )
  219. if any(probe.available_count for probe in self.probes[:-1]):
  220. raise CalendarGateError(
  221. "Calendar query scanned beyond the first positive month"
  222. )
  223. elif self.stop_reason == "horizon_exhausted":
  224. if len(self.probes) != self.lookahead_months:
  225. raise CalendarGateError(
  226. "Calendar query ended before the configured horizon"
  227. )
  228. if any(probe.available_count for probe in self.probes):
  229. raise CalendarGateError(
  230. "Calendar query ignored a positive month"
  231. )
  232. else:
  233. raise CalendarGateError(
  234. "Calendar query scan used an unknown stop reason"
  235. )
  236. @property
  237. def scanned_months(self) -> int:
  238. return len(self.probes)
  239. @property
  240. def available_days(self) -> tuple[CalendarDay, ...]:
  241. if self.stop_reason != "first_available_month":
  242. return ()
  243. return self.probes[-1].available_days
  244. @property
  245. def earliest_available_date(self) -> date | None:
  246. return (
  247. self.available_days[0].day
  248. if self.available_days
  249. else None
  250. )
  251. def _validate_lookahead_months(value: object) -> int:
  252. if (
  253. isinstance(value, bool)
  254. or not isinstance(value, int)
  255. or not 1 <= value <= MAX_QUERY_LOOKAHEAD_MONTHS
  256. ):
  257. raise CalendarGateError(
  258. "lookahead_months must be between 1 and 120"
  259. )
  260. return value
  261. def listen_once(
  262. page: object,
  263. *,
  264. target: str,
  265. method: str,
  266. action: Callable[[], Any],
  267. timeout: float,
  268. ) -> object:
  269. """Listen around one native action and always stop the listener."""
  270. page.listen.start(target, method=method)
  271. try:
  272. action()
  273. packet = page.listen.wait(timeout=timeout)
  274. if not packet:
  275. raise CalendarTransientError(
  276. f"Expected {method} {target} was not observed"
  277. )
  278. return packet
  279. finally:
  280. page.listen.stop()
  281. def parse_availability_packet(packet: object) -> CalendarProbeResult:
  282. path, _ = same_origin_path(packet.url)
  283. if str(packet.method).upper() != "POST" or path != AVAILABILITY_PATH:
  284. raise CalendarGateError("Availability request method or path changed")
  285. response = packet.response
  286. status = response.status
  287. if type(status) is not int:
  288. raise CalendarGateError("Availability HTTP status was not an integer")
  289. if status in {301, 302, 303, 307, 308}:
  290. location = header_value(getattr(response, "headers", None), "Location")
  291. destination = urlparse(urljoin(packet.url, location))
  292. if location and destination.scheme == "https" and destination.hostname == "iam.esteri.it":
  293. raise CalendarAuthenticationExpiredError("Calendar response redirected to IAM")
  294. response_url = getattr(response, "url", None)
  295. if isinstance(response_url, str) and response_url:
  296. destination = urlparse(response_url)
  297. if destination.scheme == "https" and destination.hostname == "iam.esteri.it":
  298. raise CalendarAuthenticationExpiredError("Calendar response returned to IAM")
  299. response_path, _ = same_origin_path(response_url)
  300. if response_path != AVAILABILITY_PATH:
  301. raise CalendarGateError("Availability response reached an unexpected path")
  302. if status == 401:
  303. raise CalendarAuthenticationExpiredError("Calendar authentication expired")
  304. if status == 429:
  305. raise CalendarRateLimitedError("Calendar request was rate limited")
  306. if status == 403:
  307. raise CalendarAccessDeniedError("Calendar access requires operator attention")
  308. if status in {0, 408, 502, 503, 504}:
  309. raise CalendarTransientError("Calendar request temporarily failed")
  310. if status != 200:
  311. raise CalendarGateError("Availability response status was not 200")
  312. post_data = packet.request.postData
  313. if isinstance(post_data, str):
  314. try:
  315. post_data = json.loads(post_data)
  316. except json.JSONDecodeError as exc:
  317. raise CalendarGateError(
  318. "Availability request body was not JSON"
  319. ) from exc
  320. if not isinstance(post_data, dict) or set(post_data) != {
  321. "_Servizio",
  322. "selectedDay",
  323. }:
  324. raise CalendarGateError("Availability request keys changed")
  325. if isinstance(post_data["_Servizio"], bool) or not str(
  326. post_data["_Servizio"]
  327. ).strip():
  328. raise CalendarGateError("Availability runtime service id was empty")
  329. if (
  330. not isinstance(post_data["selectedDay"], str)
  331. or not post_data["selectedDay"].strip()
  332. ):
  333. raise CalendarGateError("Availability selectedDay was empty")
  334. try:
  335. days = parse_calendar_availability(packet.response.raw_body)
  336. except ItaProtocolError as exc:
  337. raise CalendarGateError(
  338. f"Availability response rejected ({exc.code})"
  339. ) from exc
  340. return CalendarProbeResult(
  341. days=days,
  342. selected_day=post_data["selectedDay"],
  343. )
  344. def validate_next_month_snapshot(
  345. raw: object,
  346. *,
  347. expected_clicked: bool,
  348. allow_unready: bool = False,
  349. ) -> dict[str, object]:
  350. """Require the exact, non-sensitive Calendar month-control shape."""
  351. if not isinstance(raw, dict):
  352. raise CalendarGateError(
  353. "Calendar next-month control did not return an object"
  354. )
  355. expected_keys = {
  356. "pathMatches",
  357. "candidateCount",
  358. "actionableCount",
  359. "clicked",
  360. }
  361. if set(raw) != expected_keys:
  362. raise CalendarGateError(
  363. "Calendar next-month control returned unexpected fields"
  364. )
  365. if raw["pathMatches"] is not True:
  366. raise CalendarGateError(
  367. "Calendar next-month control was evaluated outside Calendar"
  368. )
  369. candidate_count = require_plain_nonnegative_int(
  370. raw["candidateCount"],
  371. "candidateCount",
  372. )
  373. actionable_count = require_plain_nonnegative_int(
  374. raw["actionableCount"],
  375. "actionableCount",
  376. )
  377. if actionable_count > candidate_count:
  378. raise CalendarGateError(
  379. "Calendar next-month actionable count exceeded candidates"
  380. )
  381. if not isinstance(expected_clicked, bool):
  382. raise CalendarGateError("expected_clicked must be a boolean")
  383. if raw["clicked"] is not expected_clicked:
  384. raise CalendarGateError(
  385. "Calendar next-month click acknowledgement changed"
  386. )
  387. if actionable_count != 1 and not (
  388. allow_unready and actionable_count == 0
  389. ):
  390. raise CalendarGateError(
  391. "Calendar next-month control was not uniquely actionable"
  392. )
  393. return raw
  394. def click_next_month(
  395. page: object,
  396. *,
  397. timeout: float = 10,
  398. diagnostic: Callable[[object], None] | None = None,
  399. ) -> None:
  400. """Click only the unique visible Bootstrap day-view month control."""
  401. deadline = time.monotonic() + timeout
  402. last_raw: object = None
  403. while time.monotonic() < deadline:
  404. last_raw = page.run_js(NEXT_MONTH_CONTROL_SCRIPT, False)
  405. try:
  406. snapshot = validate_next_month_snapshot(
  407. last_raw,
  408. expected_clicked=False,
  409. allow_unready=True,
  410. )
  411. except CalendarGateError:
  412. if diagnostic:
  413. diagnostic(last_raw)
  414. raise
  415. if snapshot["actionableCount"] == 1:
  416. break
  417. time.sleep(0.25)
  418. else:
  419. if diagnostic:
  420. diagnostic(last_raw)
  421. raise CalendarNextMonthUnavailableError(
  422. "Calendar next-month control was not actionable before timeout"
  423. )
  424. clicked = page.run_js(NEXT_MONTH_CONTROL_SCRIPT, True)
  425. if diagnostic:
  426. diagnostic(clicked)
  427. validate_next_month_snapshot(clicked, expected_clicked=True)
  428. def refresh_calendar(page: object) -> None:
  429. page.refresh()
  430. page.wait.doc_loaded()
  431. def guard_calendar(page: object) -> dict[str, object]:
  432. """Disable the final button and reject any observed final request."""
  433. raw = page.run_js(CALENDAR_GUARD_SCRIPT)
  434. if not isinstance(raw, dict):
  435. raise CalendarGateError("Calendar guard did not return an object")
  436. expected = {
  437. "path": CALENDAR_PATH,
  438. "calendarFunctionPresent": True,
  439. "finalButtonCount": 1,
  440. "allFinalButtonsGuarded": True,
  441. "finalRequestCount": 0,
  442. }
  443. for key, expected_value in expected.items():
  444. if raw.get(key) != expected_value:
  445. raise CalendarGateError(f"Calendar guard rejected {key}")
  446. return raw
  447. def capture_initial_probe(page: object) -> CalendarProbeResult:
  448. packet = listen_once(
  449. page,
  450. target=AVAILABILITY_PATH,
  451. method="POST",
  452. action=lambda: refresh_calendar(page),
  453. timeout=30,
  454. )
  455. probe = parse_availability_packet(packet)
  456. guard_calendar(page)
  457. return probe
  458. def capture_next_probe(page: object) -> CalendarProbeResult:
  459. packet = listen_once(
  460. page,
  461. target=AVAILABILITY_PATH,
  462. method="POST",
  463. action=lambda: click_next_month(page),
  464. timeout=30,
  465. )
  466. probe = parse_availability_packet(packet)
  467. guard_calendar(page)
  468. return probe
  469. def scan_until_first_available_month(
  470. page: object,
  471. *,
  472. lookahead_months: int,
  473. log: Callable[[str], None] | None = None,
  474. month_click_interval_seconds: float = DEFAULT_MONTH_CLICK_INTERVAL_SECONDS,
  475. ) -> CalendarQueryScanResult:
  476. """Scan sequential months and stop immediately at the first positive one."""
  477. months = _validate_lookahead_months(lookahead_months)
  478. if (
  479. isinstance(month_click_interval_seconds, bool)
  480. or not isinstance(month_click_interval_seconds, (int, float))
  481. or month_click_interval_seconds < 0
  482. ):
  483. raise CalendarGateError(
  484. "month_click_interval_seconds must be nonnegative"
  485. )
  486. probes = [capture_initial_probe(page)]
  487. if log:
  488. log(
  489. "Italy Calendar probe "
  490. f"index=0 available={probes[0].available_count}"
  491. )
  492. if probes[0].available_count:
  493. return CalendarQueryScanResult(
  494. probes=tuple(probes),
  495. lookahead_months=months,
  496. stop_reason="first_available_month",
  497. )
  498. for index in range(1, months):
  499. if month_click_interval_seconds:
  500. time.sleep(month_click_interval_seconds)
  501. try:
  502. probe = capture_next_probe(page)
  503. except CalendarNextMonthUnavailableError as exc:
  504. raise CalendarGateError(
  505. "Calendar scan ended before the configured horizon"
  506. ) from exc
  507. if probe.selected_month != next_month_value(
  508. probes[-1].selected_month
  509. ):
  510. raise CalendarGateError(
  511. "Calendar request did not advance exactly one month"
  512. )
  513. probes.append(probe)
  514. if log:
  515. log(
  516. "Italy Calendar probe "
  517. f"index={index} available={probe.available_count}"
  518. )
  519. if probe.available_count:
  520. return CalendarQueryScanResult(
  521. probes=tuple(probes),
  522. lookahead_months=months,
  523. stop_reason="first_available_month",
  524. )
  525. return CalendarQueryScanResult(
  526. probes=tuple(probes),
  527. lookahead_months=months,
  528. stop_reason="horizon_exhausted",
  529. )