cadrumo.adapters.outbound.aeat.browser.site_health_records module

Strict records for AEAT site-health detection.

The site-health layer classifies AEAT Sede Electrónica responses into a closed SiteHealthState catalogue. A planned mantenimiento page, WAF challenge, HTTP 429/503 rate-limit answer, or transport failure becomes a typed SiteHealthStatus instead of collapsing into a generic browser or workflow exception.

Every record in this module is frozen, strict, extra="forbid" pydantic v2. The closed state catalogue is an enum.StrEnum. Collections are tuple[str, ...] so evidence remains immutable after classification.

See also

adapters.outbound.aeat.browser._site_health_parsers.evaluate_response()

Pure parser entry point that creates SiteHealthStatus records from HTTP status, headers, and body text.

adapters.outbound.aeat.browser.session.BrowserSession.navigate()

Browser navigation hook that raises core.errors.hierarchy.SiteHealthError when a non-OK status is classified.

core.errors.hierarchy.SiteHealthStatusLike

Core-layer structural view that lets application workflow and diagnostics consume these adapter records without importing them.

class SiteHealthEvidence(**data)[source]

Bases: _SiteHealthRecord

Bounded evidence block captured alongside a classification.

Evidence is diagnostic, not a full response archive. The HTML fragment is redacted and bounded before it is stored, while detected_markers keeps the exact marker keys that caused the parser to choose a SiteHealthState.

Variables:

  • url – The probe URL whose response was classified.

  • http_status – HTTP status observed on the response. Bounded to [100, 599]; transport-level failures use 599 as a sentinel and annotate detected_markers accordingly.

  • html_fragment – At most 4096 characters of redacted response body, captured for diagnostic logs. The bound keeps error logs sane and avoids leaking full response bodies.

  • detected_markers – Frozen tuple of the substrings (or structured keys such as retry-after:30) that led the parser to its verdict. Each marker is bounded between 1 and 128 characters.

Parameters:

data (Any)

url: AnyHttpUrl
http_status: int
html_fragment: str
detected_markers: tuple[str, ...]
class SiteHealthStatus(**data)[source]

Bases: _SiteHealthRecord

Full classification record for a single probe.

Produced by the parser suite and by adapters.outbound.aeat.browser.session.BrowserSession.navigate() for transport failures. Non-OK records are carried by core.errors.hierarchy.SiteHealthError; diagnostics and workflow code then inspect this record instead of re-parsing response bodies.

Variables:

  • state – The detected SiteHealthState.

  • evidence – Bounded SiteHealthEvidence describing the response that was classified.

  • observed_at – Timezone-aware timestamp when the classification was produced.

  • retry_after_seconds – Optional positive integer derived from a Retry-After header or the rate-limit default when the state is SiteHealthState.RATE_LIMITED.

Parameters:

data (Any)

state: SiteHealthState
evidence: SiteHealthEvidence
observed_at: AwareDatetime
retry_after_seconds: int | None
parse_site_health_url(value)[source]

Validate one URL for a concrete site-health evidence record.

Return type:

AnyHttpUrl

Parameters:

value (str)