Connection (astra.connection)

Overview

Connection components manage the browser process and Playwright context. They are responsible for session locking, crash detection and page state monitoring.

BrowserController

class BrowserController(session_path, headless=True)

Controller for the Playwright browser engine.

This class ensures that only one instance of Astra uses a specific session directory and provides a stable interface for page interactions.

Parameters:

• session_path (str)

• headless (bool)

__init__(session_path, headless=True)

Initialize the controller.

Parameters:

• session_path (str) – Path to the browser profile directory.

• headless (bool) – Whether to run the browser without a UI.

async start()

Launches the browser and navigates to WhatsApp Web.

Returns:

The primary Playwright Page object.

Raises:

BrowserLimitError – If another instance is using the same session.

Return type:

playwright.async_api.Page

async stop()

Gracefully shuts down the browser and releases files.

set_crash_handler(handler)

Registers a callback for when the browser crashes.

Parameters:

handler (Callable[[], Awaitable[None]])

async get_state()

Detects the current state of WhatsApp Web (QR, Loading, Connected).

Return type:

str

async inject_local_storage(storage)

Directly injects localStorage data into the active page.

Parameters:

storage (dict)

property context: playwright.async_api.BrowserContext

Provides direct access to the Playwright BrowserContext.

property page: playwright.async_api.Page

Provides direct access to the Playwright Page object.

Page monitor & retry

class PageMonitor(page)

Monitors the browser page to detect authentication status and QR codes.

Parameters:

page (playwright.async_api.Page)

on_qr(callback)

Registers a callback for when a new QR code is displayed.

Parameters:

callback (Callable[[str], None])

async wait_until_ready(timeout=60.0)

Polls the page until the user is authenticated or the timeout expires.

Parameters:

timeout (float) – Maximum time to wait in seconds.

Raises:

LoginFailedError – If the user fails to authenticate in time.

class RetryStrategy(base_delay=2.0, max_delay=60.0, max_attempts=10)

A resilient retry manager for connection recovery.

Implements exponential backoff with random jitter to ensure reconnections happen in a nature-friendly way.

Parameters:

• base_delay (float)

• max_delay (float)

• max_attempts (int)

reset()

Resets the attempt counter (usually called on successful connection).

next_delay()

Calculates the wait time for the next reconnection attempt.

Returns:

The delay in seconds, or None if the retry limit is reached.

Return type:

float | None

Usage example

controller = BrowserController(session_path="./.sessions/default", headless=True)
page = await controller.start()
state = await controller.get_state()

Async notes

• Browser start/stop operations are async and must be awaited.

• Page interactions use Playwright’s async API (await page.evaluate(...)).