Skip to content

feat!: finalize typed CDP semantics and transport performance - #7

Merged
mathisarends merged 7 commits into
mainfrom
feat/finalize-protocol-api
Nov 7, 2026
Merged

mathisarends merged 7 commits into
mainfrom
feat/finalize-protocol-api

Conversation

@mathisarends

Copy link
Copy Markdown
Owner

CDP values such as CallArgument(value=None) currently become JavaScript undefined, command deadlines exclude sending and custom transports, and the default WebSocket path adds avoidable compression and UTF-8 work. This change fixes those semantics and finalizes the generated API while keeping its scope to typed CDP commands, models, events and transport.

Changes:

  • Distinguish omitted optional Any values with UNSET, preserve explicit JSON null, and raise structured CDPDecodeError for missing required fields. Explicit strict=False decoding remains available.
  • Enforce one client-owned deadline across sending and receiving for root/session/custom-transport calls. Generated methods retain only CDP parameters; callers use asyncio.timeout() for individual budgets.
  • Disable WebSocket compression by default, expose connection options, and send orjson bytes as text frames while receiving bytes directly.
  • Generate wire dictionaries directly without intermediate Params instances; retain public Params models and keyword-only signatures.
  • Make bounded-stream overflow explicit with overflow="error", retain opt-in drop_oldest, and add root/session/global raw event subscriptions.
  • Preserve spec parameter/attribute documentation and experimental/deprecated markers in generated code.
  • Add reproducible benchmarks, offline regeneration/drift checking, public API type assertions, and a headless Chrome CI job.

Breaking changes and migration examples are documented in CHANGELOG.md and README.md: optional Any defaults, strict required-field decoding, timeout ownership and None semantics, standalone transport timeout configuration, compression defaults, and bounded-buffer overflow behavior.

The bundled specs are unchanged. Most of the generated diff is attribute/method documentation and direct parameter serialization. The implementation is split into seven commits.

Validation on Windows:

  • 298 unit tests passed on Python 3.12, 3.13 and 3.14.
  • 7 integration tests passed against real headless Chrome, covering null/undefined, event registration and routing, cancellation cleanup and connection reuse, both JSON backends, compression, and large Unicode payloads.
  • Pyright: zero errors or warnings for the complete library and the public API sample.
  • Ruff lint/format, bundled-spec generated-code drift check, benchmark smoke run, and wheel build passed.

Reproduce:

uv sync --all-extras --locked
uv run --all-extras pytest
uv run --all-extras pytest -m integration
uv run pyright
uv run python scripts/check_generated.py
uv run python benchmarks/runtime.py

@mathisarends
mathisarends merged commit 00b91fc into main Nov 7, 2026
11 checks passed
@mathisarends
mathisarends deleted the feat/finalize-protocol-api branch November 7, 2026 09:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant