aeat.adapters.outbound.aeat.browser.session module

Playwright browser-session manager for AEAT outbound adapters.

BrowserSession is the concrete browser runtime behind the application auth providers and live Sede readers. It creates one Playwright BrowserContext at a time from a Profile, optional persisted storage state, and an optional adapters.outbound.aeat.auth.BrowserContextProvisioner. Certificate auth passes a adapters.outbound.aeat.auth.CertificateContextProvisioner so the AEAT origin receives the configured PKCS#12 certificate at context construction time.

The session also applies the configured EvasionStrategy and exposes BrowserSession.navigate(), the health-probed navigation path that turns AEAT maintenance, WAF, rate-limit, and transport failures into typed SiteHealthStatus or BrowserError outcomes.

class BrowserSession(playwright, settings, profile, evasion_strategy=None)[source]

Bases: object

Factory and lifecycle manager for one Playwright browser context.

A session owns at most one live browser until close() runs. Auth providers use create_context() to combine Profile defaults, encrypted-session storage state, and provider-owned browser context kwargs such as client-certificate provisioning.

Parameters:
async create_context(*, provisioner=None, storage_state_path=None, storage_state=None)[source]

Create and configure a new Playwright BrowserContext.

When provisioner is supplied, it can inject auth-provider- specific browser.new_context(...) kwargs and tag the resulting context after construction. Certificate auth uses this hook through adapters.outbound.aeat.auth.CertificateContextProvisioner; Cl@ve Móvil usually passes only persisted in-memory storage state.

Parameters:

  • provisioner (BrowserContextProvisioner | None) – Optional BrowserContextProvisioner used to decorate the new context call and annotate the returned context.

  • storage_state_path (Path | None) – Optional path to a Playwright storage-state JSON file; passed directly to browser.new_context.

  • storage_state (Mapping[str, object] | None) – Optional in-memory storage state mapping passed directly to browser.new_context; takes precedence over storage_state_path when both are supplied.

Return type:

BrowserContext

Returns:

A configured BrowserContext with evasion strategies applied and — when provisioner is supplied — the provider-specific context kwargs wired through at construction time.

Raises:

BrowserError – If the browser cannot be launched, the context cannot be created, evasion setup fails, annotation fails, or this session already owns a live browser.

async close()[source]

Close the retained Playwright browser, if any.

Safe to call multiple times. The caller still owns any previously returned BrowserContext objects and should close them before closing the session.

Return type:

None

async navigate(page, url)[source]

Navigate page to url and probe the response health.

This is an additive helper; direct page.goto calls remain legal but bypass the health probe. Stages that have migrated to navigate() gain automatic classification of AEAT mantenimiento banners, WAF challenges, and rate-limit responses as typed SiteHealthError instances.

Parameters:

  • page (Page) – The Playwright Page to navigate.

  • url (str) – The target URL.

Return type:

Response | None

Returns:

The Response Playwright yielded for the navigation (may be None when Playwright skipped the response — e.g. cached navigations).

Raises:

  • SiteHealthError – When the parser suite classifies the response as non-OK, or when page.goto fails with a transport-level error (DNS / TCP / TLS / Playwright timeout).

  • BrowserError – When reading the page content after navigation fails.