ddp_utils.browser.facade.proxy

import ddp_utils.browser.facade.proxy

Backend-neutral proxy state, verification, and rotation service.

class ddp_utils.browser.facade.proxy.BrowserProxy(browser: Browser)

Bases: object

Expose safe proxy status and delegate provider-owned runtime changes.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Note

Standard Selenium and Playwright cannot replace a process-level proxy reliably after launch. Runtime rotation is therefore delegated to an injected controller that must keep endpoint, browser, and identity in sync or return an explicit failure.

Examples

Verify a Windscribe allocation after browser startup:

verification = browser.proxy.verify(timeout=15)

Bind proxy state to one browser session.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Browser creates this service once:

proxy = BrowserProxy(browser)

property configured: bool

Return whether launch configuration contains a proxy endpoint.

Returns

True when a proxy server can be identified.

Examples

Skip verification for direct sessions:

if browser.proxy.configured:
    browser.proxy.verify()

property settings: BrowserProxySettings

Return redacted effective proxy settings.

Returns

Safe proxy metadata with passwords removed.

Examples

Display only safe connection metadata:

print(browser.proxy.settings)

property verification: ProxyVerification | None

Return the latest verification without starting network traffic.

Returns

Cached verification result or None.

Examples

Reuse already collected evidence:

previous = browser.proxy.verification

verify(*, timeout: float | None = None) → ProxyVerification

Verify the browser-visible proxy through the injected controller.

Parameters

Name	Type	Description
timeout	float | None	Optional verifier deadline in seconds.

Returns

Type	Description
ProxyVerification	Normalized proxy verification. No public-IP service is contacted unless the explicitly supplied controller chooses to do so.

Raises

Exception	Description
BrowserError	Controller execution fails or returns invalid data.

Examples

Verify after a browser launch checkpoint:

result = browser.proxy.verify(timeout=10)

rotate(location: str | None = None, *, restart: str | bool = 'auto') → CapabilityResult[Any]

Rotate through a controller that owns browser/proxy coherence.

Parameters

Name	Type	Description
location	str | None	Optional provider location selector.
restart	str | bool	auto, True, or False restart policy.

Returns

Type	Description
CapabilityResult[Any]	Controller result wrapped in a structured capability result.

Raises

Exception	Description
BrowserError	Controller rotation fails.
UnsupportedCapabilityError	Rotation is required but unavailable.

Examples

Rotate Windscribe and allow the controller to restart if needed:

browser.proxy.rotate("US Central", restart="auto")

release() → None

Release the controller-owned proxy allocation idempotently.

Raises

Exception	Description
BrowserError	If the proxy cannot be released.

Examples

Release an explicitly leased proxy before shutdown:

browser.proxy.release()

class ddp_utils.browser.facade.proxy.BrowserProxyController(*args, **kwargs)

Bases: Protocol

Define the injectable runtime controller used by NKL/Windscribe.

Examples

Pass a project controller through BrowserConfig.proxy_controller:

config = config.with_overrides(proxy_controller=windscribe)

verify(*, browser: Browser, timeout: float | None = None) → Any

Verify the active browser-visible proxy identity.

Parameters

Name	Type	Description
browser	Browser	Active facade whose browser-visible connection must be verified.
timeout	float | None	Optional controller deadline in seconds. None delegates deadline selection to the controller.

Returns

Type	Description
Any	Provider verification data. BrowserProxy accepts a ProxyVerification, a compatible mapping, or a boolean.

Examples

Return structured identity evidence:

controller.verify(browser=browser, timeout=10)

rotate(*, browser: Browser, location: str | None = None, restart: str | bool = 'auto') → Any

Rotate and apply the proxy coherently to the active browser.

Parameters

Name	Type	Description
browser	Browser	Active facade whose proxy allocation must change.
location	str | None	Optional provider-specific location selector. None lets the controller choose a location.
restart	str | bool	Browser restart policy: auto, True, or False.

Returns

Type	Description
Any	Provider-specific rotation result wrapped by BrowserProxy in a capability result.

Examples

Rotate to a provider location:

controller.rotate(browser=browser, location="US Central")

release(*, browser: Browser) → Any

Release resources owned by this browser allocation.

Parameters

Name	Type	Description
browser	Browser	Facade whose controller-owned allocation must be released.

Returns

Type	Description
Any	Provider-specific release acknowledgement. The facade discards this value after a successful call.

Examples

Release one explicit lease:

controller.release(browser=browser)

class ddp_utils.browser.facade.proxy.BrowserProxySettings(configured: bool, server: str | None = None, scheme: str | None = None, host: str | None = None, port: int | None = None, username_present: bool = False, source: str = 'browser_config')

Bases: object

Expose safe effective proxy metadata without returning credentials.

Parameters

Name	Type	Description
configured	bool	Whether a proxy endpoint was supplied before startup.
server	str | None	Redacted server URL or endpoint text.
scheme	str | None	Proxy scheme when known.
host	str | None	Proxy host when known.
port	int | None	Proxy port when known.
username_present	bool	Whether authentication contains a username.
source	str	Configuration source label.

Examples

Record proxy topology without leaking secrets:

print(browser.proxy.settings.host)

class ddp_utils.browser.facade.proxy.ProxyVerification(success: bool, observed_ip: str | None = None, country: str | None = None, region: str | None = None, city: str | None = None, reason: str | None = None, details: dict[str, ~typing.Any]=<factory>)

Bases: object

Represent observed proxy identity and coherence evidence.

Parameters

Name	Type	Description
success	bool	Whether verification proved the expected proxy state.
observed_ip	str | None	Public IP observed by the configured verifier.
country	str | None	Observed country code or name.
region	str | None	Observed region.
city	str | None	Observed city.
reason	str | None	Failure or uncertainty explanation.
details	dict[str, Any]	Additional non-secret verifier evidence.

Examples

Stop when the proxy does not match its intended location:

result = browser.proxy.verify()
if not result.success:
    raise RuntimeError(result.reason)