diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 28784749c4..ac3943ef57 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,6 +1,6 @@ version: 2 updates: - - package-ecosystem: "pip" + - package-ecosystem: "uv" directory: "/docs" schedule: interval: "daily" diff --git a/.github/workflows/build-pre-release.yml b/.github/workflows/build-pre-release.yml index e1326b6aa5..f6473c1cc3 100644 --- a/.github/workflows/build-pre-release.yml +++ b/.github/workflows/build-pre-release.yml @@ -15,7 +15,7 @@ on: jobs: build-and-publish: - uses: ./.github/workflows/lib-build-and-push.yml + uses: ./.github/workflows/lib-build.yml with: python-version: ${{ inputs.python-version }} target: ${{ inputs.target }} diff --git a/.github/workflows/build-push.yml b/.github/workflows/build-push.yml index 15c77f3861..60f0983fd4 100644 --- a/.github/workflows/build-push.yml +++ b/.github/workflows/build-push.yml @@ -10,11 +10,12 @@ on: jobs: build-and-publish: name: "Build wheels" - uses: ./.github/workflows/lib-build-and-push.yml - with: - upload: false + uses: ./.github/workflows/lib-build.yml - # TODO: Remove when https://github.com/pypa/gh-action-pypi-publish/issues/166 is fixed and update build-and-publish.with.upload to ${{ endsWith(github.event.ref, 'scylla') }} + # Publishing is a separate job (not inside the reusable workflow) because PyPI Trusted Publishing + # requires the *caller* workflow path in the OIDC token. A reusable workflow would embed its own + # path instead, causing an `invalid-publisher` error on the PyPI side. + # See: https://github.com/pypa/gh-action-pypi-publish/issues/166 publish: name: "Publish wheels to PyPi" if: ${{ endsWith(github.event.ref, 'scylla') }} @@ -23,11 +24,11 @@ jobs: permissions: id-token: write steps: - - uses: actions/download-artifact@v7 + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: path: dist merge-multiple: true - - uses: pypa/gh-action-pypi-publish@release/v1 + - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0 with: skip-existing: true diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml index 3e1f1067d7..ebfe383047 100644 --- a/.github/workflows/build-test.yml +++ b/.github/workflows/build-test.yml @@ -18,6 +18,4 @@ jobs: test-wheels-build: name: "Test wheels building" if: "!contains(github.event.pull_request.labels.*.name, 'disable-test-build')" - uses: ./.github/workflows/lib-build-and-push.yml - with: - upload: false \ No newline at end of file + uses: ./.github/workflows/lib-build.yml \ No newline at end of file diff --git a/.github/workflows/call_jira_sync.yml b/.github/workflows/call_jira_sync.yml new file mode 100644 index 0000000000..7397f10cdc --- /dev/null +++ b/.github/workflows/call_jira_sync.yml @@ -0,0 +1,18 @@ +name: Sync Jira Based on PR Events + +on: + pull_request_target: + types: [opened, edited, ready_for_review, review_requested, labeled, unlabeled, closed] + +permissions: + contents: read + pull-requests: write + issues: write + +jobs: + jira-sync: + uses: scylladb/github-automation/.github/workflows/main_pr_events_jira_sync.yml@47138e9130250ee1a35166cff7dd0e94c8897196 # main 2026-06-01 + with: + caller_action: ${{ github.event.action }} + secrets: + caller_jira_auth: ${{ secrets.USER_AND_KEY_FOR_JIRA_AUTOMATION }} diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml index 0da86fef34..a413e3317e 100644 --- a/.github/workflows/docs-pages.yml +++ b/.github/workflows/docs-pages.yml @@ -24,14 +24,14 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: ref: ${{ github.event.repository.default_branch }} persist-credentials: false fetch-depth: 0 - name: Install uv - uses: astral-sh/setup-uv@v7 + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 with: working-directory: docs enable-cache: true diff --git a/.github/workflows/docs-pr.yml b/.github/workflows/docs-pr.yml index b5651c8159..1881c227ed 100644 --- a/.github/workflows/docs-pr.yml +++ b/.github/workflows/docs-pr.yml @@ -2,6 +2,9 @@ name: "Docs / Build PR" # For more information, # see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows +permissions: + contents: read + on: push: branches: @@ -28,13 +31,13 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v6 + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: persist-credentials: false fetch-depth: 0 - name: Install uv - uses: astral-sh/setup-uv@v7 + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 with: working-directory: docs enable-cache: true diff --git a/.github/workflows/integration-tests.yml b/.github/workflows/integration-tests.yml index 048dbd1352..acebb1d617 100644 --- a/.github/workflows/integration-tests.yml +++ b/.github/workflows/integration-tests.yml @@ -38,7 +38,7 @@ jobs: if: "!contains(github.event.pull_request.labels.*.name, 'disable-integration-tests')" runs-on: ubuntu-24.04 env: - SCYLLA_VERSION: release:2025.2 + SCYLLA_VERSION: release:2026.1 strategy: fail-fast: false matrix: @@ -56,10 +56,10 @@ jobs: event_loop_manager: "asyncore" steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - name: Set up JDK ${{ matrix.java-version }} - uses: actions/setup-java@v5 + uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0 with: java-version: ${{ matrix.java-version }} distribution: 'adopt' @@ -68,7 +68,7 @@ jobs: run: sudo apt-get install libev4 libev-dev - name: Install uv - uses: astral-sh/setup-uv@v7 + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 with: python-version: ${{ matrix.python-version }} @@ -77,6 +77,12 @@ jobs: - name: Build driver run: uv sync + - name: Cache Scylla download + uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5 + with: + path: ~/.ccm/repository + key: scylla-${{ env.SCYLLA_VERSION }}-${{ runner.os }} + # This is to get honest accounting of test time vs download time vs build time. # Not strictly necessary for running tests. - name: Download Scylla @@ -92,4 +98,4 @@ jobs: if [[ "${{ matrix.python-version }}" =~ t$ ]]; then export PYTHON_GIL=0 fi - uv run pytest tests/integration/standard/ tests/integration/cqlengine/ + uv run pytest -v tests/integration/standard/ tests/integration/cqlengine/ diff --git a/.github/workflows/lib-build-and-push.yml b/.github/workflows/lib-build.yml similarity index 81% rename from .github/workflows/lib-build-and-push.yml rename to .github/workflows/lib-build.yml index 735a4638f4..f6959ddfec 100644 --- a/.github/workflows/lib-build-and-push.yml +++ b/.github/workflows/lib-build.yml @@ -1,14 +1,8 @@ -name: Build and upload to PyPi +name: Build wheels on: workflow_call: inputs: - upload: - description: 'Upload to PyPI' - type: boolean - required: false - default: false - python-version: description: 'Python version to run on' type: string @@ -83,11 +77,11 @@ jobs: include: ${{ fromJson(needs.prepare-matrix.outputs.matrix) }} steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - name: Checkout tag ${{ inputs.target_tag }} if: inputs.target_tag != '' - uses: actions/checkout@v6 + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: ref: ${{ inputs.target_tag }} @@ -102,7 +96,7 @@ jobs: echo "CIBW_BEFORE_TEST_WINDOWS=(exit 0)" >> $GITHUB_ENV; - name: Install uv - uses: astral-sh/setup-uv@v7 + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 with: python-version: ${{ inputs.python-version }} @@ -117,7 +111,7 @@ jobs: - name: Install Conan if: runner.os == 'Windows' - uses: turtlebrowser/get-conan@main + uses: turtlebrowser/get-conan@c171f295f3f507360ee018736a6608731aa2109d # v1.2 - name: Configure libev for Windows if: runner.os == 'Windows' @@ -146,14 +140,14 @@ jobs: if: matrix.target != 'linux-aarch64' shell: bash run: | - GITHUB_WORKFLOW_REF="scylladb/python-driver/.github/workflows/lib-build-and-push.yml@refs/heads/master" cibuildwheel --output-dir wheelhouse + cibuildwheel --output-dir wheelhouse - name: Build wheels for linux aarch64 if: matrix.target == 'linux-aarch64' run: | - GITHUB_WORKFLOW_REF="scylladb/python-driver/.github/workflows/lib-build-and-push.yml@refs/heads/master" CIBW_BUILD="cp3*" cibuildwheel --archs aarch64 --output-dir wheelhouse + CIBW_BUILD="cp3*" cibuildwheel --archs aarch64 --output-dir wheelhouse - - uses: actions/upload-artifact@v6 + - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: wheels-${{ matrix.target }}-${{ matrix.os }} path: ./wheelhouse/*.whl @@ -162,34 +156,17 @@ jobs: name: Build source distribution runs-on: ubuntu-24.04 steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - name: Install uv - uses: astral-sh/setup-uv@v7 + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 with: python-version: ${{ inputs.python-version }} - name: Build sdist run: uv build --sdist - - uses: actions/upload-artifact@v6 + - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: source-dist path: dist/*.tar.gz - - upload_pypi: - if: inputs.upload - needs: [build-wheels, build-sdist] - runs-on: ubuntu-24.04 - permissions: - id-token: write - - steps: - - uses: actions/download-artifact@v7 - with: - path: dist - merge-multiple: true - - - uses: pypa/gh-action-pypi-publish@release/v1 - with: - skip-existing: true diff --git a/.github/workflows/publish-manually.yml b/.github/workflows/publish-manually.yml index 09b9779117..e38de5b0c4 100644 --- a/.github/workflows/publish-manually.yml +++ b/.github/workflows/publish-manually.yml @@ -39,15 +39,17 @@ on: jobs: build-and-publish: name: "Build wheels" - uses: ./.github/workflows/lib-build-and-push.yml + uses: ./.github/workflows/lib-build.yml with: - upload: false python-version: ${{ inputs.python-version }} ignore_tests: ${{ inputs.ignore_tests }} target_tag: ${{ inputs.target_tag }} target: ${{ inputs.target }} - # TODO: Remove when https://github.com/pypa/gh-action-pypi-publish/issues/166 is fixed and update build-and-publish.with.upload to ${{ inputs.upload }} + # Publishing is a separate job (not inside the reusable workflow) because PyPI Trusted Publishing + # requires the *caller* workflow path in the OIDC token. A reusable workflow would embed its own + # path instead, causing an `invalid-publisher` error on the PyPI side. + # See: https://github.com/pypa/gh-action-pypi-publish/issues/166 publish: name: "Publish wheels to PyPi" needs: build-and-publish @@ -56,11 +58,11 @@ jobs: permissions: id-token: write steps: - - uses: actions/download-artifact@v7 + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: path: dist merge-multiple: true - - uses: pypa/gh-action-pypi-publish@release/v1 + - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0 with: skip-existing: true diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 0c4aa63669..2a02f1ac54 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,3 +1,98 @@ +Unreleased +========== + +Features +-------- +* Negotiate and implement the ``SCYLLA_USE_METADATA_ID`` protocol extension: prepared + statements skip re-sending result metadata on EXECUTE, and the driver automatically + refreshes cached metadata when the server detects a schema change (DRIVER-153) + +Others +------ +* ``PreparedStatement.result_metadata`` and ``PreparedStatement.result_metadata_id`` are + now read-only. They are replaced together by + ``PreparedStatement.update_result_metadata()``, so a request can never observe a metadata + id paired with result metadata from a different schema version. Code that assigned either + attribute directly must call ``update_result_metadata()`` instead. +* Message serialization now receives the connection's negotiated ``ProtocolFeatures``: + ``Connection.send_msg`` passes ``protocol_features`` to the encoder, and + ``_ProtocolHandler.encode_message`` forwards it to each message's ``send_body``. + This changes the contracted signature of ``encode_message`` (and of ``send_body``). + Custom protocol handlers that override ``encode_message`` must accept a required + ``protocol_features`` keyword argument (adding ``**kwargs`` is recommended for + future-proofing), and custom encoders that delegate to ``msg.send_body`` should + forward it. There is deliberately no compatibility fallback: protocol extensions + are negotiated per connection at STARTUP, so an encoder unaware of + ``protocol_features`` could silently omit fields a negotiated extension requires. + This release emits no new bytes on the wire; the parameter is groundwork for + upcoming protocol extensions (``SCYLLA_USE_METADATA_ID``, ``TABLETS_ROUTING_V2``). + +3.29.11 +======= +Jun 15, 2026 + +Features +-------- +* asyncio backend now supports TLS + +Bug Fixes +--------- +* Race conditions in libev backend resulting in EBADF error have been fixed + +Testing / CI +------------ +* Integration tests now use ``NetworkTopologyStrategy`` instead of ``SimpleStrategy`` +* All actions used in CI are now hash-pinned to decrease risk of supply-chain attacks +* Various fixes to make CI tests work with various versions of Scylla - mostly related to tablets and LWT +* Bumped Scylla version used in CI to 2026.1 + +3.29.10 +======= +May 10, 2026 + +Features +-------- +* Fast-path ``lookup_casstype()`` for simple type names +* Add ``Session.wait_for_schema_agreement`` + +Bug Fixes +--------- +* Fix CQL injection in ``Connection.set_keyspace_blocking`` and ``Connection.set_keyspace_async`` +* Fix libev shutdown crashes by correcting atexit registration +* Handle ``None`` ``control_connection_timeout`` in ``wait_for_schema_agreement`` +* Clean up failed heartbeat sends +* Fix ``ExponentialBackoffRetryPolicy.__init__`` super() call +* Correct ``clustering_key`` to ``clustering`` in column kind filter +* Fix inverted cooldown check in ``_get_shard_aware_endpoint`` + +Others +------ +* Deprecate ``ControlConnection.wait_for_schema_agreement`` +* Add timeout and in-flight observability to ``OperationTimedOut`` +* Drop per-query connection log + +3.29.9 +====== +March 18, 2026 + +Features +-------- +* Add Private Link support via client routes handler +* Add optional query_params parameter to QueryMessage + +Bug Fixes +--------- +* Fix segmentation fault in libev prepare_callback during shutdown +* Add null checks to io_callback and timer_callback in libev wrapper +* Fix RecursionError in execute_concurrent on synchronous errbacks +* Fix floating-point precision loss for timestamps far from epoch + +Others +------ +* Cache parsed tablet routing type in ResponseFuture +* Remove deprecated setup_requires in favor of PEP 517 build-system.requires +* Update dependency hatchling to v1.29.0 + 3.29.8 ====== February 09, 2026 diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8b8fc0e791..e8d0e66ddd 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -40,6 +40,19 @@ When modifying driver files, rebuilding Cython modules is often necessary. Without caching, each such rebuild may take over a minute. Caching usually brings it down to about 2-3 seconds. +**Important:** After modifying any ``.py`` file under ``cassandra/`` that is +Cython-compiled (such as ``query.py``, ``protocol.py``, ``cluster.py``, etc.), +extensions must be rebuilt before running tests. If you always use ``uv run`` +(e.g. ``uv run pytest``), this is handled automatically via the ``cache-keys`` +configuration in ``pyproject.toml``. If you invoke ``pytest`` directly, you can +rebuild with:: + + uv sync --reinstall-package scylla-driver + +Without rebuilding, Python will load the stale compiled extension (``.so`` / ``.pyd``) +instead of your modified ``.py`` source, and your changes will not actually be tested. +The test suite will emit a warning if it detects this situation. + Building the Docs ================= @@ -80,12 +93,6 @@ Or you can specify a scylla/cassandra directory (to test unreleased versions):: SCYLLA_VERSION=/path/to/scylla uv run pytest tests/integration/standard/ -Specifying the usage of an already running Scylla cluster ------------------------------------------------------------- -The test will start the appropriate Scylla clusters when necessary but if you don't want this to happen because a Scylla cluster is already running the flag ``USE_CASS_EXTERNAL`` can be used, for example:: - - USE_CASS_EXTERNAL=1 SCYLLA_VERSION='release:5.1' uv run pytest tests/integration/standard - Specify a Protocol Version for Tests ------------------------------------ The protocol version defaults to: diff --git a/benchmarks/base.py b/benchmarks/base.py index d9cd004474..3922eefad5 100644 --- a/benchmarks/base.py +++ b/benchmarks/base.py @@ -97,7 +97,7 @@ def setup(options): try: session.execute(""" CREATE KEYSPACE %s - WITH replication = { 'class': 'SimpleStrategy', 'replication_factor': '2' } + WITH replication = { 'class': 'NetworkTopologyStrategy', 'replication_factor': '2' } """ % options.keyspace) log.debug("Setting keyspace...") diff --git a/cassandra/__init__.py b/cassandra/__init__.py index 5567c0b9bd..cb3703d40a 100644 --- a/cassandra/__init__.py +++ b/cassandra/__init__.py @@ -23,7 +23,7 @@ def emit(self, record): logging.getLogger('cassandra').addHandler(NullHandler()) -__version_info__ = (3, 29, 8) +__version_info__ = (3, 29, 11) __version__ = '.'.join(map(str, __version_info__)) @@ -687,10 +687,29 @@ class OperationTimedOut(DriverException): The last :class:`~.Host` this operation was attempted against. """ - def __init__(self, errors=None, last_host=None): + timeout = None + """ + The timeout value (in seconds) that was in effect when the operation + timed out, or ``None`` if not applicable. + """ + + in_flight = None + """ + The number of in-flight requests on the connection at the time of + the timeout (includes orphaned requests), or ``None`` if not applicable. + """ + + def __init__(self, errors=None, last_host=None, timeout=None, in_flight=None): self.errors = errors self.last_host = last_host + self.timeout = timeout + self.in_flight = in_flight message = "errors=%s, last_host=%s" % (self.errors, self.last_host) + if self.timeout is not None: + message += " (timeout=%ss" % self.timeout + if self.in_flight is not None: + message += ", in_flight=%d" % self.in_flight + message += ")" Exception.__init__(self, message) diff --git a/cassandra/client_routes.py b/cassandra/client_routes.py new file mode 100644 index 0000000000..80b2477a6d --- /dev/null +++ b/cassandra/client_routes.py @@ -0,0 +1,451 @@ +# Copyright 2026 ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Client Routes support for Private Link and similar network configurations. + +This module implements support for dynamic address translation via the +system.client_routes table and CLIENT_ROUTES_CHANGE events. +""" + +from __future__ import absolute_import + +from dataclasses import dataclass +import enum +import logging +import socket +import threading +import uuid +from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Set, Tuple + +from cassandra import ConsistencyLevel +from cassandra.protocol import QueryMessage +from cassandra.query import dict_factory + +if TYPE_CHECKING: + from cassandra.connection import Connection + +log = logging.getLogger(__name__) + + +class ClientRoutesChangeType(enum.Enum): + """ + Types of CLIENT_ROUTES_CHANGE events. + + Currently the protocol defines only UPDATE_NODES. + New variants will be added here if the protocol is extended. + """ + UPDATE_NODES = "UPDATE_NODES" + + +@dataclass +class ClientRouteProxy: + """ + :param connection_id: String identifying the connection (required) + :param connection_addr_override:: Optional string address for initial connection + """ + + connection_id: str + connection_addr_override: Optional[str] = None + + def __post_init__(self): + if self.connection_id is None: + raise ValueError("connection_id is required") + +class ClientRoutesConfig: + """ + Configuration for client routes (Private Link support). + + :param proxies: List of :class:`ClientRouteProxy` objects + (REQUIRED, at least one) + :param advanced_shard_awareness: Whether to enable advanced shard awareness + (default: ``False``) + """ + + proxies: List[ClientRouteProxy] + advanced_shard_awareness: bool + + def __init__(self, proxies: List[ClientRouteProxy], advanced_shard_awareness: bool = False): + """ + :param proxies: List of ClientRouteProxy objects + :param advanced_shard_awareness: Enable advanced shard awareness (default False) + """ + if not proxies: + raise ValueError("At least one proxy must be specified") + + if not isinstance(proxies, (list, tuple)): + raise TypeError("proxies must be a list or tuple") + + for proxy in proxies: + if not isinstance(proxy, ClientRouteProxy): + raise TypeError("All proxies must be ClientRouteProxy instances") + + self.proxies = proxies + self.advanced_shard_awareness = advanced_shard_awareness + + def __repr__(self) -> str: + return (f"ClientRoutesConfig(proxies={self.proxies}, " + f"advanced_shard_awareness={self.advanced_shard_awareness})") + + +@dataclass(frozen=True) +class _Route: + connection_id: str + host_id: uuid.UUID + address: str # ipv4, ipv6 or DNS hostname from system.client_routes + port: int + +class _RouteStore: + """ + Thread-safe storage for routes. Reads are safe under CPython's GIL; + writes are serialized with a lock. + + This uses atomic pointer swaps for updates, allowing lock-free reads + while serializing writes. + """ + + _routes_by_host_id: Dict[uuid.UUID, _Route] + _lock: threading.Lock + + def __init__(self) -> None: + self._routes_by_host_id = {} + self._lock = threading.Lock() + + def get_by_host_id(self, host_id: uuid.UUID) -> Optional[_Route]: + """ + Get route for a host ID (lock-free read). + + :param host_id: UUID of the host + :return: _Route or None + """ + return self._routes_by_host_id.get(host_id) + + def get_all(self) -> List[_Route]: + """ + Get all routes as a list (lock-free read). + + :return: List of _Route + """ + return list(self._routes_by_host_id.values()) + + def _select_preferred_routes(self, new_routes: List[_Route]) -> List[_Route]: + """ + When multiple routes exist for the same host_id (different connection_ids), + prefer the connection_id already in use. Only migrate to a different + connection_id when the previously used one is no longer available. + + Must be called under self._lock. + """ + by_host: Dict[uuid.UUID, List[_Route]] = {} + for route in new_routes: + by_host.setdefault(route.host_id, []).append(route) + + selected = [] + for host_id, candidates in by_host.items(): + if len(candidates) == 1: + selected.append(candidates[0]) + continue + + existing = self._routes_by_host_id.get(host_id) + if existing: + preferred = [c for c in candidates if c.connection_id == existing.connection_id] + if preferred: + selected.append(preferred[0]) + continue + + selected.append(candidates[0]) + + return selected + + def update(self, routes: List[_Route]) -> None: + """ + Replace all routes atomically. + + :param routes: List of _Route objects + """ + with self._lock: + preferred = self._select_preferred_routes(routes) + self._routes_by_host_id = {route.host_id: route for route in preferred} + + def merge(self, new_routes: List[_Route], affected_host_ids: Set[uuid.UUID]) -> None: + """ + Merge new routes with existing ones atomically. + + Routes for affected_host_ids are replaced entirely: existing routes + for those hosts are dropped and replaced with whatever is in new_routes. + This handles deletions from system.client_routes (affected host present + but no new route for it). + + :param new_routes: List of _Route objects to merge + :param affected_host_ids: Set of host IDs affected by the change. + """ + with self._lock: + preferred = self._select_preferred_routes(new_routes) + new_by_host = {r.host_id: r for r in preferred} + + updated = {hid: r for hid, r in self._routes_by_host_id.items() + if hid not in affected_host_ids} + updated.update(new_by_host) + self._routes_by_host_id = updated + + +class _ClientRoutesHandler: + """ + Handles dynamic address translation for Private Link via system.client_routes. + + Lifecycle: + 1. Construction: Create with configuration + 2. Initialization: Read system.client_routes after control connection established + 3. Steady state: Listen for CLIENT_ROUTES_CHANGE events and update routes + 4. Translation: Translate addresses using Host ID lookup + """ + + config: 'ClientRoutesConfig' + ssl_enabled: bool + _routes: _RouteStore + _connection_ids: Set[str] + _proxy_addresses_override: Dict[str, str] + + def __init__(self, config: 'ClientRoutesConfig', ssl_enabled: bool = False): + """ + :param config: ClientRoutesConfig instance + :param ssl_enabled: Whether TLS is enabled (determines port selection) + """ + if not isinstance(config, ClientRoutesConfig): + raise TypeError("config must be a ClientRoutesConfig instance") + + self.config = config + self.ssl_enabled = ssl_enabled + self._routes = _RouteStore() + self._connection_ids = {dep.connection_id for dep in config.proxies} + # Precalculate proxy address mappings for efficient lookup + self._proxy_addresses_override = { + proxy.connection_id: proxy.connection_addr_override + for proxy in config.proxies + if proxy.connection_addr_override + } + + def initialize(self, connection: 'Connection', timeout: float) -> None: + """ + Load all routes from system.client_routes. + + Called once at startup and again whenever the control connection + is re-established. Reads all configured connection IDs and + replaces the in-memory route store atomically. + + Raises on failure so the caller can decide how to react (e.g. + abort startup or schedule a reconnect). + + :param connection: The Connection instance to execute queries on + :param timeout: Query timeout in seconds + """ + log.info("[client routes] Loading routes for %d proxies", len(self.config.proxies)) + + routes = self._query_all_routes_for_connections(connection, timeout, self._connection_ids) + self._routes.update(routes) + + def handle_client_routes_change(self, connection: 'Connection', timeout: float, + change_type: 'ClientRoutesChangeType', + connection_ids: Sequence[str], host_ids: Sequence[str]) -> None: + """ + Handle CLIENT_ROUTES_CHANGE event. + + Currently the protocol defines only :attr:`ClientRoutesChangeType.UPDATE_NODES`. + New variants will be added to the enum if the protocol is extended. + + :param connection: The Connection instance to execute queries on + :param timeout: Query timeout in seconds + :param change_type: A :class:`ClientRoutesChangeType` value + :param connection_ids: Affected connection ID strings; empty means all. + :param host_ids: Affected host ID strings; empty means all. + """ + + full_refresh = False + if not connection_ids or not host_ids: + log.warning( + "[client routes] CLIENT_ROUTES_CHANGE has no connection_ids or host_ids, doing full refresh") + full_refresh = True + elif len(connection_ids) != len(host_ids): + log.warning("[client routes] CLIENT_ROUTES_CHANGE has mismatched lengths (conn: %d, host: %d), doing full refresh", + len(connection_ids), len(host_ids)) + full_refresh = True + + if full_refresh: + routes = self._query_all_routes_for_connections(connection, timeout, self._connection_ids) + self._routes.update(routes) + return + + host_uuids = [uuid.UUID(hid) for hid in host_ids] + pairs = [(cid, hid) for cid, hid in zip(connection_ids, host_uuids) + if cid in self._connection_ids] + + if not pairs: + return + + routes = self._query_routes_for_change_event(connection, timeout, pairs) + self._routes.merge(routes, affected_host_ids=set(host_uuids)) + + def _query_all_routes_for_connections(self, connection: 'Connection', timeout: float, + connection_ids: Set[str]) -> List[_Route]: + """ + Query all routes for the given connection IDs (complete refresh). + + Used when control connection reconnects or as a fallback when + CLIENT_ROUTES_CHANGE event has malformed data. + + :param connection: Connection to execute query on + :param timeout: Query timeout in seconds + :param connection_ids: Set of connection ID strings + :return: List of _Route + """ + if not connection_ids: + return [] + + placeholders = ', '.join('?' for _ in connection_ids) + query = f"SELECT connection_id, host_id, address, port, tls_port FROM system.client_routes WHERE connection_id IN ({placeholders})" + params = [cid.encode('utf-8') for cid in connection_ids] + + log.debug("[client routes] Querying all routes for connection_ids=%s", connection_ids) + return self._execute_routes_query(connection, timeout, query, params) + + def _query_routes_for_change_event(self, connection: 'Connection', timeout: float, + route_pairs: List[Tuple[str, uuid.UUID]]) -> List[_Route]: + """ + Query specific routes affected by a CLIENT_ROUTES_CHANGE event. + + Takes a list of (connection_id, host_id) pairs that represent the exact + routes affected by an operation. This provides precise updates without + fetching unrelated routes. + + If the pairs list is empty or None, falls back to a complete refresh + of all routes for safety. + + :param connection: Connection to execute query on + :param timeout: Query timeout in seconds + :param route_pairs: List of (connection_id, host_id) tuples + :return: List of _Route + """ + unique_pairs = list(dict.fromkeys(route_pairs)) + + conn_ids = list(dict.fromkeys(cid for cid, _ in unique_pairs)) + host_ids = list(dict.fromkeys(hid for _, hid in unique_pairs)) + + log.debug("[client routes] Querying route pairs from CLIENT_ROUTES_CHANGE " + "(first 5 of %d): %s", len(unique_pairs), unique_pairs[:5]) + + conn_ph = ', '.join('?' for _ in conn_ids) + host_ph = ', '.join('?' for _ in host_ids) + query = ( + "SELECT connection_id, host_id, address, port, tls_port " + "FROM system.client_routes " + f"WHERE connection_id IN ({conn_ph}) AND host_id IN ({host_ph})" + ) + params: List = [cid.encode('utf-8') for cid in conn_ids] + params.extend(hid.bytes for hid in host_ids) + + return self._execute_routes_query(connection, timeout, query, params) + + def _execute_routes_query(self, connection: 'Connection', timeout: float, + query: str, params: List) -> List[_Route]: + """ + Execute a routes query and parse results. + + Common helper for both complete refresh and change event queries. + + :param connection: Connection to execute query on + :param timeout: Query timeout in seconds + :param query: CQL query string + :param params: Query parameters + :return: List of _Route + """ + log.debug("[client routes] Executing query: %s with %d parameters", query, len(params)) + + query_msg = QueryMessage(query=query, consistency_level=ConsistencyLevel.ONE, + query_params=params if params else None) + result = connection.wait_for_response( + query_msg, timeout=timeout + ) + + routes = [] + broken = 0 + rows = dict_factory(result.column_names, result.parsed_rows) + for row in rows: + try: + absent = [] + port = row['tls_port'] if self.ssl_enabled else row['port'] + connection_id = row['connection_id'] + host_id = row['host_id'] + address = row['address'] + + if not port: + absent.append("tls_port" if self.ssl_enabled else "port") + if not connection_id: + absent.append("connection_id") + if not host_id: + absent.append("host_id") + if not address: + absent.append("address") + + if absent: + log.error("[client routes] read a route %s, that has no values for the following fields: %s", row, ",".join(absent)) + broken += 1 + continue + + final_address = self._proxy_addresses_override.get(connection_id, address) + + routes.append(_Route( + connection_id=connection_id, + host_id=host_id, + address=final_address, + port=port, + )) + except Exception as e: + log.warning("[client routes] Failed to parse route row: %s", e) + broken += 1 + + if broken and not routes: + raise RuntimeError( + "[client routes] All %d route rows failed validation; " + "refusing to return empty result that would wipe the route store" % broken + ) + + return routes + + def resolve_host(self, host_id: uuid.UUID) -> Optional[Tuple[str, int]]: + """ + Resolve a host_id to an (address, port) pair. + + Looks up the current route and selects the appropriate port. + + :param host_id: Host UUID to resolve + :return: Tuple of (address, port) or None if no route mapping exists + """ + route = self._routes.get_by_host_id(host_id) + if route is None: + return None + + if not route.port: + raise ValueError("Mapping for host %s has no port" % host_id) + + try: + result = socket.getaddrinfo(route.address, route.port, + socket.AF_UNSPEC, socket.SOCK_STREAM) + if not result: + raise socket.gaierror("No addresses found for %s" % route.address) + resolved_ip = result[0][4][0] + return resolved_ip, route.port + except socket.gaierror as e: + log.warning('[client routes] Could not resolve hostname "%s" (host_id=%s): %s', + route.address, host_id, e) + raise diff --git a/cassandra/cluster.py b/cassandra/cluster.py index 51d0b2d88b..bcc7852c33 100644 --- a/cassandra/cluster.py +++ b/cassandra/cluster.py @@ -16,20 +16,21 @@ This module houses the main classes you will interact with, :class:`.Cluster` and :class:`.Session`. """ -from __future__ import absolute_import import atexit import datetime +from enum import Enum from binascii import hexlify from collections import defaultdict from collections.abc import Mapping -from concurrent.futures import ThreadPoolExecutor, FIRST_COMPLETED, wait as wait_futures +from concurrent.futures import Future, ThreadPoolExecutor, FIRST_COMPLETED, wait as wait_futures from copy import copy from functools import partial, reduce, wraps from itertools import groupby, count, chain +import enum import json import logging -from typing import Optional, Union +from typing import Any, Dict, Optional, Union, Tuple from warnings import warn from random import random import re @@ -43,12 +44,12 @@ import weakref from weakref import WeakValueDictionary -from cassandra import (ConsistencyLevel, AuthenticationFailed, InvalidRequest, - OperationTimedOut, UnsupportedOperation, +from cassandra import (ConsistencyLevel, AuthenticationFailed, OperationTimedOut, UnsupportedOperation, SchemaTargetType, DriverException, ProtocolVersion, UnresolvableContactPoints, DependencyException) from cassandra.auth import _proxy_execute_key, PlainTextAuthProvider -from cassandra.connection import (ConnectionException, ConnectionShutdown, +from cassandra.client_routes import ClientRoutesChangeType, ClientRoutesConfig, _ClientRoutesHandler +from cassandra.connection import (ClientRoutesEndPointFactory, ConnectionException, ConnectionShutdown, ConnectionHeartbeat, ProtocolVersionUnsupported, EndPoint, DefaultEndPoint, DefaultEndPointFactory, SniEndPointFactory, ConnectionBusy, locally_supported_compressions) @@ -68,7 +69,7 @@ RESULT_KIND_SET_KEYSPACE, RESULT_KIND_ROWS, RESULT_KIND_SCHEMA_CHANGE, ProtocolHandler, RESULT_KIND_VOID, ProtocolException) -from cassandra.metadata import Metadata, protect_name, murmur3, _NodeInfo +from cassandra.metadata import Metadata, Token, protect_name, murmur3, _NodeInfo from cassandra.policies import (TokenAwarePolicy, DCAwareRoundRobinPolicy, SimpleConvictionPolicy, ExponentialReconnectionPolicy, HostDistance, RetryPolicy, IdentityTranslator, NoSpeculativeExecutionPlan, @@ -82,7 +83,7 @@ named_tuple_factory, dict_factory, tuple_factory, FETCH_SIZE_UNSET, HostTargetingStatement) from cassandra.marshal import int64_pack -from cassandra.tablets import Tablet, Tablets +from cassandra.tablets import Tablet, choose_tablet_version_block, random_tablet_version_block from cassandra.timestamps import MonotonicTimestampGenerator from cassandra.util import _resolve_contact_points_to_string_map, Version, maybe_add_timeout_to_query @@ -190,7 +191,6 @@ def _connection_reduce_fn(val,import_fn): log = logging.getLogger(__name__) - _GRAPH_PAGING_MIN_DSE_VERSION = Version('6.8.0') _NOT_SET = object() @@ -214,6 +214,14 @@ def __init__(self, message, errors): self.errors = errors +class SchemaAgreementScope(str, Enum): + """Scope selectors for :meth:`.Session.wait_for_schema_agreement`.""" + + RACK = 'rack' + DC = 'dc' + CLUSTER = 'cluster' + + def _future_completed(future): """ Helper for run_in_executor() """ exc = future.exception() @@ -505,8 +513,9 @@ def __init__(self, load_balancing_policy=None, retry_policy=None, class ProfileManager(object): - def __init__(self): + def __init__(self, pools_allowed: bool=True): self.profiles = dict() + self.pools_allowed = pools_allowed def _profiles_without_explicit_lbps(self): names = (profile_name for @@ -518,6 +527,8 @@ def _profiles_without_explicit_lbps(self): ) def distance(self, host): + if not self.pools_allowed: + return HostDistance.IGNORED distances = set(p.load_balancing_policy.distance(host) for p in self.profiles.values()) return HostDistance.LOCAL_RACK if HostDistance.LOCAL_RACK in distances else \ HostDistance.LOCAL if HostDistance.LOCAL in distances else \ @@ -533,10 +544,14 @@ def check_supported(self): p.load_balancing_policy.check_supported() def on_up(self, host): + if not self.pools_allowed: + return for p in self.profiles.values(): p.load_balancing_policy.on_up(host) def on_down(self, host): + if not self.pools_allowed: + return for p in self.profiles.values(): p.load_balancing_policy.on_down(host) @@ -610,6 +625,31 @@ class _ConfigMode(object): PROFILES = 2 +class ControlConnectionQueryFallback(enum.Enum): + """ + Controls how application queries use the control connection when node pools + are unavailable. + + ``Disabled`` requires a usable node pool for application queries. If the + driver cannot establish one during session startup, it raises + :class:`NoHostAvailable`. + + ``Fallback`` still attempts to create node pools, but allows application + queries to fall back to the control connection when no usable node pool is + available. Session startup is allowed to proceed even if the initial pool + attempts all fail. + + ``SkipPoolCreation`` disables node-pool creation for the session and uses + the control-connection fallback path for application queries. + + The fallback path is not used for requests targeted to an explicit host. + """ + + Disabled = "Disabled" + Fallback = "Fallback" + SkipPoolCreation = "SkipPoolCreation" + + class Cluster(object): """ The main class to use when interacting with a Cassandra cluster. @@ -930,6 +970,16 @@ def default_retry_policy(self, policy): If set to :const:`None`, there will be no timeout for these queries. """ + allow_control_connection_query_fallback: ControlConnectionQueryFallback = ControlConnectionQueryFallback.Disabled + """ + Controls whether application queries may fall back to the control connection. + + ``Disabled`` keeps the old behavior. + ``Fallback`` enables control-connection fallback when no usable node pools exist. + ``SkipPoolCreation`` skips node-pool creation and uses the control connection fallback path. + This fallback is still not used for requests targeted to an explicit host. + """ + idle_heartbeat_interval = 30 """ Interval, in seconds, on which to heartbeat idle connections. This helps @@ -1215,7 +1265,9 @@ def __init__(self, shard_aware_options=None, metadata_request_timeout: Optional[float] = None, column_encryption_policy=None, - application_info:Optional[ApplicationInfoBase]=None + application_info:Optional[ApplicationInfoBase]=None, + client_routes_config:Optional[ClientRoutesConfig]=None, + allow_control_connection_query_fallback:Optional[ControlConnectionQueryFallback]=ControlConnectionQueryFallback.Disabled ): """ ``executor_threads`` defines the number of threads in a pool for handling asynchronous tasks such as @@ -1233,6 +1285,10 @@ def __init__(self, if port < 1 or port > 65535: raise ValueError("Invalid port number (%s) (1-65535)" % port) + if not isinstance(allow_control_connection_query_fallback, ControlConnectionQueryFallback): + raise TypeError( + "allow_control_connection_query_fallback must be a ControlConnectionQueryFallback value") + if connection_class is not None: self.connection_class = connection_class @@ -1280,6 +1336,45 @@ def __init__(self, if column_encryption_policy is not None: self.column_encryption_policy = column_encryption_policy + if client_routes_config is not None and endpoint_factory is not None: + raise ValueError("client_routes_config and endpoint_factory are mutually exclusive") + + self._client_routes_handler = None + if client_routes_config is not None: + if not isinstance(client_routes_config, ClientRoutesConfig): + raise TypeError("client_routes_config must be a ClientRoutesConfig instance") + + # SSL hostname verification is incompatible with client routes: + # connections go through NLB proxies whose addresses won't match + # server certificates. + _check_hostname_enabled = False + if ssl_context is not None and ssl_context.check_hostname: + _check_hostname_enabled = True + if ssl_options is not None and ssl_options.get('check_hostname', False): + _check_hostname_enabled = True + if _check_hostname_enabled: + raise ValueError( + "SSL hostname verification (check_hostname=True) is currently incompatible " + "with client_routes_config. When using client routes, connections " + "go through NLB proxies whose addresses won't match server " + "certificates. Disable hostname verification by setting " + "ssl_context.check_hostname = False." + ) + + ssl_enabled = ssl_context is not None or ssl_options is not None + self._client_routes_handler = _ClientRoutesHandler(client_routes_config, ssl_enabled=ssl_enabled) + + if contact_points is _NOT_SET or not self._contact_points_explicit: + seed_addrs = [dep.connection_addr_override for dep in client_routes_config.proxies + if dep.connection_addr_override] + if seed_addrs: + self.contact_points = seed_addrs + self._contact_points_explicit = True + log.info("[client routes] Using %d deployment connection addresses as contact points", + len(seed_addrs)) + + if self._client_routes_handler is not None: + endpoint_factory = ClientRoutesEndPointFactory(self._client_routes_handler, self.port) self.endpoint_factory = endpoint_factory or DefaultEndPointFactory(port=self.port) self.endpoint_factory.configure(self) @@ -1355,7 +1450,8 @@ def __init__(self, else: self.timestamp_generator = MonotonicTimestampGenerator() - self.profile_manager = ProfileManager() + self.profile_manager = ProfileManager( + pools_allowed=allow_control_connection_query_fallback != ControlConnectionQueryFallback.SkipPoolCreation) self.profile_manager.profiles[EXEC_PROFILE_DEFAULT] = ExecutionProfile( self.load_balancing_policy, self.default_retry_policy, @@ -1424,6 +1520,7 @@ def __init__(self, self.cql_version = cql_version self.max_schema_agreement_wait = max_schema_agreement_wait self.control_connection_timeout = control_connection_timeout + self.allow_control_connection_query_fallback = allow_control_connection_query_fallback self.metadata_request_timeout = self.control_connection_timeout if metadata_request_timeout is None else metadata_request_timeout self.idle_heartbeat_interval = idle_heartbeat_interval self.idle_heartbeat_timeout = idle_heartbeat_timeout @@ -1437,6 +1534,10 @@ def __init__(self, self.monitor_reporting_interval = monitor_reporting_interval self.shard_aware_options = ShardAwareOptions(opts=shard_aware_options) + if (client_routes_config is not None + and not client_routes_config.advanced_shard_awareness): + self.shard_aware_options.disable_shardaware_port = True + self._listeners = set() self._listener_lock = Lock() @@ -1638,7 +1739,8 @@ def add_execution_profile(self, name, profile, pool_wait_timeout=5): futures.update(session.update_created_pools()) _, not_done = wait_futures(futures, pool_wait_timeout) if not_done: - raise OperationTimedOut("Failed to create all new connection pools in the %ss timeout.") + raise OperationTimedOut("Failed to create all new connection pools in the %ss timeout." % pool_wait_timeout, + timeout=pool_wait_timeout) def connection_factory(self, endpoint, host_conn = None, *args, **kwargs): """ @@ -1761,7 +1863,8 @@ def get_all_pools(self): return pools def is_shard_aware(self): - return bool(self.get_all_pools()[0].host.sharding_info) + pools = self.get_all_pools() + return bool(pools and pools[0].host.sharding_info) def shard_aware_stats(self): if self.is_shard_aware(): @@ -1866,7 +1969,7 @@ def on_up(self, host): """ Intended for internal use only. """ - if self.is_shutdown: + if self.is_shutdown or self.allow_control_connection_query_fallback == ControlConnectionQueryFallback.SkipPoolCreation: return log.debug("Waiting to acquire lock for handling up status of node %s", host) @@ -1974,7 +2077,7 @@ def on_down(self, host, is_host_addition, expect_host_to_be_down=False): """ Intended for internal use only. """ - if self.is_shutdown: + if self.is_shutdown or self.allow_control_connection_query_fallback == ControlConnectionQueryFallback.SkipPoolCreation: return with host.lock: @@ -2579,20 +2682,24 @@ def __init__(self, cluster, hosts, keyspace=None): # create connection pools in parallel self._initial_connect_futures = set() - for host in hosts: - future = self.add_or_renew_pool(host, is_host_addition=False) - if future: - self._initial_connect_futures.add(future) - - futures = wait_futures(self._initial_connect_futures, return_when=FIRST_COMPLETED) - while futures.not_done and not any(f.result() for f in futures.done): - futures = wait_futures(futures.not_done, return_when=FIRST_COMPLETED) - - if not any(f.result() for f in self._initial_connect_futures): - msg = "Unable to connect to any servers" - if self.keyspace: - msg += " using keyspace '%s'" % self.keyspace - raise NoHostAvailable(msg, [h.address for h in hosts]) + fallback_mode = self.cluster.allow_control_connection_query_fallback + if fallback_mode is not ControlConnectionQueryFallback.SkipPoolCreation: + for host in hosts: + future = self.add_or_renew_pool(host, is_host_addition=False) + if future: + self._initial_connect_futures.add(future) + + futures = wait_futures(self._initial_connect_futures, return_when=FIRST_COMPLETED) + while futures.not_done and not any(f.result() for f in futures.done): + futures = wait_futures(futures.not_done, return_when=FIRST_COMPLETED) + + # Only Disabled requires an initial pool to come up. + if not any(f.result() for f in self._initial_connect_futures) and \ + fallback_mode is ControlConnectionQueryFallback.Disabled: + msg = "Unable to connect to any servers" + if self.keyspace: + msg += " using keyspace '%s'" % self.keyspace + raise NoHostAvailable(msg, [h.address for h in hosts]) self.session_id = uuid.uuid4() @@ -2939,6 +3046,31 @@ def _create_response_future(self, query, parameters, trace, custom_payload, else: timestamp = None + # Snapshot passed to the ResponseFuture for decoding skip_meta responses; only + # bound statements carry cached result metadata (set in the BoundStatement branch). + bound_result_metadata = _NOT_SET + + # Compute the ring token once, here on the request path, and pass it + # explicitly to the two consumers that run while sending: the + # tablet_version_block below and shard selection in the pool (via the + # ResponseFuture). The token is a pure function of the routing key and + # the cluster's partitioner, so computing it here keeps cluster-dependent + # state off the statement and avoids races when a statement is shared + # across concurrent requests. The load balancing policy computes its own + # token from the same routing key when ordering replicas. + # can_support_partitioner() is what makes this safe to do unconditionally: + # a Murmur3 cluster whose murmur3 helper is unavailable cannot hash a key + # at all (Murmur3Token.hash_fn raises NoMurmur3), and the default load + # balancing policy drops token awareness in that case. Without the check + # this path would raise on every prepared-statement execution instead. + routing_token = None + routing_key = query.routing_key + if routing_key is not None: + metadata = self.cluster.metadata + token_map = metadata.token_map + if token_map is not None and metadata.can_support_partitioner(): + routing_token = token_map.token_class.from_key(routing_key) + if isinstance(query, SimpleStatement): query_string = query.query_string statement_keyspace = query.keyspace if ProtocolVersion.uses_keyspace_flag(self._protocol_version) else None @@ -2950,12 +3082,33 @@ def _create_response_future(self, query, parameters, trace, custom_payload, continuous_paging_options, statement_keyspace) elif isinstance(query, BoundStatement): prepared_statement = query.prepared_statement + # Snapshot metadata and its id as one atomic pair so the message never + # carries the id of one schema version alongside a skip_meta decision + # made for another. skip_meta is requested only when there is both an + # id to validate it with and cached metadata to decode against: while + # a statement has no cached metadata there is nothing to decode a + # metadata-less response with, so the server must send it. + # Whether skip_meta and the id actually reach the wire is decided per + # connection at serialization time (see ExecuteMessage.send_body). + # Continuous paging sessions are excluded: Connection.process_msg hardcodes + # result_metadata=None for every page after the first (it isn't threaded + # through the paging session), so a skip_meta response has nothing to + # decode page 2+ against. + result_metadata, result_metadata_id = prepared_statement.result_metadata_and_id + bound_result_metadata = result_metadata + + # The tablet_version_block value is connection-independent, so compute + # it once here instead of copying the message per send attempt. The + # serializer emits it only when the serving connection negotiated + # TABLETS_ROUTING_V2 (see ExecuteMessage.send_body). message = ExecuteMessage( prepared_statement.query_id, query.values, cl, serial_cl, fetch_size, paging_state, timestamp, - skip_meta=bool(prepared_statement.result_metadata), + skip_meta=bool(result_metadata) and result_metadata_id is not None + and continuous_paging_options is None, continuous_paging_options=continuous_paging_options, - result_metadata_id=prepared_statement.result_metadata_id) + result_metadata_id=result_metadata_id, + tablet_version_block=self._compute_tablet_version_block(query, routing_key, routing_token)) elif isinstance(query, BatchStatement): if self._protocol_version < 2: raise UnsupportedOperation( @@ -2982,7 +3135,62 @@ def _create_response_future(self, query, parameters, trace, custom_payload, self, message, query, timeout, metrics=self._metrics, prepared_statement=prepared_statement, retry_policy=retry_policy, row_factory=row_factory, load_balancer=load_balancing_policy, start_time=start_time, speculative_execution_plan=spec_exec_plan, - continuous_paging_state=None, host=host) + continuous_paging_state=None, host=host, bound_result_metadata=bound_result_metadata, + routing_token=routing_token) + + def _compute_tablet_version_block(self, query, routing_key: Optional[bytes], + routing_token: Optional[Token]) -> int: + """ + Compute the tablet_version_block byte for a BoundStatement. + + Always returns an int in [0, 255]. A non-token-aware query (no routing + key) can never resolve to a tablet, so the server never version-checks + it; we send 0 and skip the work. Otherwise, when no cached tablet is + known for the routing key (unknown keyspace/table, vnode table, cold + cache, or a missing token map) a random block is returned; the server + treats that as a version miss and replies with fresh routing info. + + ``routing_key`` and ``routing_token`` are the statement's routing key and + the ring token derived from it, both resolved once per request by the + caller (see :meth:`_create_response_future`) and passed in so the send + path has a single source of truth for them. ``routing_token`` is ``None`` + both when there is no routing key and when no token map was available, so + telling those two cases apart needs the routing key as well -- taking it + as an argument rather than re-reading ``query.routing_key`` keeps the two + values here guaranteed to describe the same statement. + + This is computed once per request at message construction; the value is + connection-independent, and the serializer emits it only on connections + that negotiated TABLETS_ROUTING_V2 (see ExecuteMessage.send_body). + """ + if routing_key is None: + # Non-token-aware query: the server won't version-check it, so skip + # generating random bits and just send 0. + return 0 + + keyspace = query.keyspace or self.keyspace + table = query.table + if not keyspace or not table: + # We don't even know which table we're targeting. Don't waste + # CPU cycles on generating a random byte. + return 0 + + if routing_token is None: + # We're targeting a specific partition of some table, + # so the returned routing information can still be + # useful. Make it possible to obtain it. + return random_tablet_version_block() + + # A single lookup: get_tablet_for_key already reports a table with no + # cached tablets (a vnode table, or a tablet table on cold start) as + # None, and going through the mutable cache twice would leave a window + # for the tablet to disappear between the checks. + tablet = self.cluster.metadata._tablets.get_tablet_for_key(keyspace, table, routing_token) + if tablet is None or tablet.tablet_version is None: + # A version miss on the server, which replies with fresh routing info. + return random_tablet_version_block() + + return choose_tablet_version_block(tablet.tablet_version) def get_execution_profile(self, name): """ @@ -3191,6 +3399,9 @@ def add_or_renew_pool(self, host, is_host_addition): """ For internal use only. """ + if self.cluster.allow_control_connection_query_fallback is ControlConnectionQueryFallback.SkipPoolCreation: + return None + distance = self._profile_manager.distance(host) if distance == HostDistance.IGNORED: return None @@ -3261,6 +3472,9 @@ def update_created_pools(self): For internal use only. """ + if self.cluster.allow_control_connection_query_fallback is ControlConnectionQueryFallback.SkipPoolCreation: + return set() + futures = set() for host in self.cluster.metadata.all_hosts(): distance = self._profile_manager.distance(host) @@ -3324,11 +3538,195 @@ def pool_finished_setting_keyspace(pool, host_errors): errors[pool.host] = host_errors if not remaining_callbacks: - callback(host_errors) + callback(errors) for pool in tuple(self._pools.values()): pool._set_keyspace_for_all_conns(keyspace, pool_finished_setting_keyspace) + def wait_for_schema_agreement(self, wait_time: Optional[float] = None, + scope: SchemaAgreementScope = SchemaAgreementScope.CLUSTER) -> bool: + """ + Wait for connected hosts in the selected scope to report the same + schema version from ``system.local``. + + By default, the timeout for this operation is governed by + :attr:`~.Cluster.max_schema_agreement_wait` and + :attr:`~.Cluster.control_connection_timeout`. + + Passing ``wait_time`` here overrides + :attr:`~.Cluster.max_schema_agreement_wait`. If provided, ``wait_time`` + must be greater than 0. + + ``scope`` determines which connected hosts participate in the check. + Pass :attr:`SchemaAgreementScope.RACK`, :attr:`SchemaAgreementScope.DC`, + or :attr:`SchemaAgreementScope.CLUSTER`. + The default is :attr:`SchemaAgreementScope.CLUSTER`. ``RACK`` narrows + the check to connected hosts in the local rack only. ``DC`` checks + connected hosts in the local datacenter. ``CLUSTER`` queries every + connected host across all datacenters. + + :param wait_time: Override for + :attr:`~.Cluster.max_schema_agreement_wait`, should be positive + number. + :param scope: Restricts the check to connected hosts in the local rack, + local datacenter, or whole connected cluster. + :returns: ``True`` when the selected connected hosts agree on schema, + otherwise ``False``. + :raises ValueError: If ``wait_time`` is provided and is not greater + than 0. + :raises ValueError: If ``scope`` is not one of the schema agreement + scope values. + """ + + if wait_time is not None and wait_time <= 0: + raise ValueError("wait_time must be greater than 0") + + if scope not in (SchemaAgreementScope.RACK, SchemaAgreementScope.DC, SchemaAgreementScope.CLUSTER): + raise ValueError( + "scope must be SchemaAgreementScope.RACK, .DC, or .CLUSTER" + ) + + total_timeout = wait_time if wait_time is not None else self.cluster.max_schema_agreement_wait + if total_timeout <= 0: + raise ValueError("total_timeout must be greater than 0") + + deadline = time.time() + total_timeout + schema_mismatches = None + scope_label = 'local rack' if scope is SchemaAgreementScope.RACK else ( + 'local datacenter' if scope is SchemaAgreementScope.DC else 'cluster') + + while time.time() < deadline: + schema_mismatches = self._get_schema_mismatches_for_scope(deadline, scope) + if schema_mismatches is None: + return True + + log.debug("[session] Connected hosts in the %s still disagree on schema, trying again", scope_label) + remaining = deadline - time.time() + if remaining > 0: + time.sleep(min(0.2, remaining)) + + log.warning("[session] Connected hosts in the %s are reporting a schema disagreement: %s", + scope_label, schema_mismatches) + return False + + def _get_schema_mismatches_for_scope(self, deadline: float, + scope: SchemaAgreementScope) -> Optional[Dict[Any, Any]]: + hosts = self._get_schema_agreement_hosts(scope) + mismatches = defaultdict(list) + errors = {} + scope_label = 'local rack' if scope is SchemaAgreementScope.RACK else ( + 'local datacenter' if scope is SchemaAgreementScope.DC else 'cluster') + + if not hosts: + errors[scope.value] = ConnectionException( + "No connected hosts available in the %s" % (scope_label,) + ) + return {'unavailable': errors} + + metadata_request_timeout = self.cluster.control_connection._metadata_request_timeout + query = maybe_add_timeout_to_query(ControlConnection._SELECT_SCHEMA_LOCAL, metadata_request_timeout) + + schema_version_futures = [] + for host in hosts: + try: + schema_version_future = self._query_local_schema_version(host, query, deadline) + except Exception as exc: + errors[host.endpoint] = exc + continue + + schema_version_futures.append((host, schema_version_future)) + + if schema_version_futures: + # Start all host queries first, then wait for the whole batch. + remaining = max(0.0, deadline - time.time()) + if remaining > 0: + wait_futures([future for _, future in schema_version_futures], timeout=remaining) + + for host, future in schema_version_futures: + if future.done(): + try: + rows = future.result() + except Exception as exc: + errors[host.endpoint] = exc + continue + + row = rows.one() + schema_version = getattr(row, "schema_version", None) if row is not None else None + mismatches[schema_version].append(host.endpoint) + else: + errors[host.endpoint] = OperationTimedOut(last_host=host, timeout=max(0.0, deadline - time.time())) + + if len(mismatches) == 1 and None not in mismatches and not errors: + log.debug("[session] Connected hosts in the %s agree on schema", scope_label) + return None + + if errors: + mismatches['unavailable'] = errors + return dict(mismatches) + + def _get_schema_agreement_hosts(self, scope: SchemaAgreementScope) -> Tuple[Host, ...]: + if scope is SchemaAgreementScope.RACK: + allowed_distances = (HostDistance.LOCAL_RACK,) + elif scope is SchemaAgreementScope.DC: + allowed_distances = (HostDistance.LOCAL_RACK, HostDistance.LOCAL) + else: + allowed_distances = (HostDistance.LOCAL_RACK, HostDistance.LOCAL, HostDistance.REMOTE) + + return tuple( + host for host, pool in tuple(self._pools.items()) + if host.is_up + and not pool.is_shutdown + and self._profile_manager.distance(host) in allowed_distances) + + def _query_local_schema_version(self, host: Host, query: str, deadline: float) -> Future: + remaining = max(0.0, deadline - time.time()) + try: + response_future = self.execute_async( + query, + timeout=self._schema_agreement_query_timeout(remaining), + host=host, + ) + except OperationTimedOut as timeout: + log.debug("[session] Timed out waiting for schema version from %s: %s", host, timeout) + raise + except Exception as exc: + log.debug("[session] Error querying schema version from %s: %s", host, exc) + raise + + # execute_async returns cassandra.cluster.ResponseFuture, which does not have bulk waiting logic for it. + # That is why _query_local_schema_version returns concurrent.futures.Future + # so that schema agreement logic could use concurrent.futures.wait_futures to wait on them. + # schema_version_future is an adapter between cassandra.cluster.ResponseFuture and concurrent.futures.Future + # to make things work + schema_version_future = Future() + + def _set_result(result, result_future=schema_version_future, response_future=response_future): + if result_future.done(): + return + try: + result_future.set_result(ResultSet(response_future, result)) + except Exception as exc: + result_future.set_exception(exc) + + def _set_exception(exc, result_future=schema_version_future): + if result_future.done(): + return + result_future.set_exception(exc) + + try: + response_future.add_callbacks(_set_result, _set_exception) + except Exception as exc: + log.debug("[session] Error registering schema version callback from %s: %s", host, exc) + raise + + return schema_version_future + + def _schema_agreement_query_timeout(self, remaining: float) -> float: + control_timeout = self.cluster.control_connection._timeout + if control_timeout is None: + return max(0.0, remaining) + return max(0.0, min(control_timeout, remaining)) + def user_type_registered(self, keyspace, user_type, klass): """ Called by the parent Cluster instance when the user registers a new @@ -3470,7 +3868,6 @@ class PeersQueryType(object): _schema_meta_page_size = 1000 _uses_peers_v2 = True - _tablets_routing_v1 = False # for testing purposes _time = time @@ -3604,19 +4001,27 @@ def _try_connect(self, endpoint): self._metadata_request_timeout = None if connection.features.sharding_info is None or not self._cluster.metadata_request_timeout \ else datetime.timedelta(seconds=self._cluster.metadata_request_timeout) - self._tablets_routing_v1 = connection.features.tablets_routing_v1 - # use weak references in both directions # _clear_watcher will be called when this ControlConnection is about to be finalized # _watch_callback will get the actual callback from the Connection and relay it to # this object (after a dereferencing a weakref) self_weakref = weakref.ref(self, partial(_clear_watcher, weakref.proxy(connection))) try: - connection.register_watchers({ + watchers = { "TOPOLOGY_CHANGE": partial(_watch_callback, self_weakref, '_handle_topology_change'), "STATUS_CHANGE": partial(_watch_callback, self_weakref, '_handle_status_change'), "SCHEMA_CHANGE": partial(_watch_callback, self_weakref, '_handle_schema_change') - }, register_timeout=self._timeout) + } + + if self._cluster._client_routes_handler is not None: + watchers["CLIENT_ROUTES_CHANGE"] = partial(_watch_callback, self_weakref, '_handle_client_routes_change') + + connection.register_watchers(watchers, register_timeout=self._timeout) + + if self._cluster._client_routes_handler is not None: + self._cluster._client_routes_handler.initialize( + connection, + self._timeout) sel_peers = self._get_peers_query(self.PeersQueryType.PEERS, connection) sel_local = self._SELECT_LOCAL if self._token_meta_enabled else self._SELECT_LOCAL_NO_TOKENS @@ -3731,7 +4136,7 @@ def _refresh_schema(self, connection, preloaded_results=None, schema_agreement_w if self._cluster.is_shutdown: return False - agreed = self.wait_for_schema_agreement(connection, + agreed = self._wait_for_schema_agreement(connection=connection, preloaded_results=preloaded_results, wait_time=schema_agreement_wait) @@ -3979,6 +4384,44 @@ def _handle_status_change(self, event): # this will be run by the scheduler self._cluster.on_down(host, is_host_addition=False) + def _handle_client_routes_change(self, event: Dict[str, Any]) -> None: + """ + Handle CLIENT_ROUTES_CHANGE event from the server. + + This event indicates that the system.client_routes table has been updated + and we need to refresh our route mappings. + """ + if self._cluster._client_routes_handler is None: + log.warning("[control connection] Received CLIENT_ROUTES_CHANGE but no handler configured") + return + + raw_change_type = event.get("change_type") + try: + change_type = ClientRoutesChangeType(raw_change_type) + except ValueError: + log.warning("[control connection] Unknown CLIENT_ROUTES_CHANGE type: %s", raw_change_type) + return + + connection_ids = tuple(event.get("connection_ids", [])) + host_ids = tuple(event.get("host_ids", [])) + + self._cluster.scheduler.schedule_unique( + 0, + self._handle_client_routes_refresh, + self._connection, self._timeout, change_type, connection_ids, host_ids + ) + + def _handle_client_routes_refresh(self, connection, timeout, + change_type, connection_ids, host_ids): + try: + self._cluster._client_routes_handler.handle_client_routes_change( + connection, timeout, change_type, connection_ids, host_ids) + except ReferenceError: + pass # our weak reference to the Cluster is no good + except Exception: + log.debug("[control connection] Error handling CLIENT_ROUTES_CHANGE", exc_info=True) + self._signal_error() + def _handle_schema_change(self, event): if self._schema_event_refresh_window < 0: return @@ -3986,7 +4429,30 @@ def _handle_schema_change(self, event): self._cluster.scheduler.schedule_unique(delay, self.refresh_schema, **event) def wait_for_schema_agreement(self, connection=None, preloaded_results=None, wait_time=None): + """ + Wait for schema agreement from the control connection's metadata view. + This method is intended for internal metadata refresh flows. External + callers should use :meth:`.Session.wait_for_schema_agreement` instead. + + The control connection observes schema agreement from its own + perspective, which may include hosts the session is not using, and it + may fail when the control connection itself is transiently unhealthy. + That can produce false positives or failures that do not reflect + whether a session can safely proceed. + + .. deprecated:: 3.30.0 + Use :meth:`.Session.wait_for_schema_agreement` instead. + """ + warn("ControlConnection.wait_for_schema_agreement is deprecated and will be removed in 4.0. " + "Use Session.wait_for_schema_agreement instead. " + "This method is for internal metadata refresh use only.", + DeprecationWarning, stacklevel=2) + return self._wait_for_schema_agreement(connection=connection, + preloaded_results=preloaded_results, + wait_time=wait_time) + + def _wait_for_schema_agreement(self, connection=None, preloaded_results=None, wait_time=None): total_timeout = wait_time if wait_time is not None else self._cluster.max_schema_agreement_wait if total_timeout <= 0: return True @@ -4024,7 +4490,8 @@ def wait_for_schema_agreement(self, connection=None, preloaded_results=None, wai local_query = QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_SCHEMA_LOCAL, self._metadata_request_timeout), consistency_level=cl) try: - timeout = min(self._timeout, total_timeout - elapsed) + remaining = total_timeout - elapsed + timeout = min(self._timeout, remaining) if self._timeout is not None else remaining peers_result, local_result = connection.wait_for_responses( peers_query, local_query, timeout=timeout) except OperationTimedOut as timeout: @@ -4345,13 +4812,17 @@ class ResponseFuture(object): _spec_execution_plan = NoSpeculativeExecutionPlan() _continuous_paging_session = None _host = None + _control_connection_query_attempted = False _TABLET_ROUTING_CTYPE = None + _TABLET_ROUTING_V2_CTYPE = None + _bound_result_metadata = None _warned_timeout = False def __init__(self, session, message, query, timeout, metrics=None, prepared_statement=None, retry_policy=RetryPolicy(), row_factory=None, load_balancer=None, start_time=None, - speculative_execution_plan=None, continuous_paging_state=None, host=None): + speculative_execution_plan=None, continuous_paging_state=None, host=None, + bound_result_metadata=_NOT_SET, routing_token=None): self.session = session # TODO: normalize handling of retry policy and row factory self.row_factory = row_factory or session.row_factory @@ -4362,9 +4833,17 @@ def __init__(self, session, message, query, timeout, metrics=None, prepared_stat self._retry_policy = retry_policy self._metrics = metrics self.prepared_statement = prepared_statement + # Metadata snapshotted alongside the message's result_metadata_id at construction + # time (see Session._create_response_future). Decoding a skip_meta response uses + # this so the metadata decoded-with always pairs with the id the message sent, + # even if a concurrent METADATA_CHANGED replaces the prepared statement's cache in + # between. Defaults to [] for unprepared statements (no cached metadata). + self._bound_result_metadata = [] if bound_result_metadata is _NOT_SET else bound_result_metadata self._callback_lock = Lock() self._start_time = start_time or time.time() self._host = host + self._routing_token = routing_token + self._control_connection_query_attempted = False self._spec_execution_plan = speculative_execution_plan or self._spec_execution_plan self._make_query_plan() self._event = Event() @@ -4411,6 +4890,7 @@ def _on_timeout(self, _attempts=0): ) return + conn_in_flight = None if self._connection is not None: try: self._connection._requests.pop(self._req_id) @@ -4421,9 +4901,14 @@ def _on_timeout(self, _attempts=0): except KeyError: key = "Connection defunct by heartbeat" errors = {key: "Client request timeout. See Session.execute[_async](timeout)"} - self._set_final_exception(OperationTimedOut(errors, self._current_host)) + self._set_final_exception(OperationTimedOut(errors, self._current_host, + timeout=self.timeout, + in_flight=self._connection.in_flight)) return + # Capture connection stats before pool.return_connection() can alter state + conn_in_flight = self._connection.in_flight + pool = self.session._pools.get(self._current_host) if pool and not pool.is_shutdown: # Do not return the stream ID to the pool yet. We cannot reuse it @@ -4437,18 +4922,31 @@ def _on_timeout(self, _attempts=0): self._connection.orphaned_threshold_reached = True pool.return_connection(self._connection, stream_was_orphaned=True) + elif self._connection.is_control_connection: + with self._connection.lock: + self._connection.orphaned_request_ids.add(self._req_id) + if len(self._connection.orphaned_request_ids) >= self._connection.orphaned_threshold: + self._connection.orphaned_threshold_reached = True errors = self._errors if not errors: if self.is_schema_agreed: - key = str(self._current_host.endpoint) if self._current_host else 'no host queried before timeout' + if self._current_host is None: + key = 'no host queried before timeout' + elif self._connection is not None and self._connection.is_control_connection: + control_host = self.session.cluster.get_control_connection_host() + key = str(control_host.endpoint) if control_host is not None else str(self._connection.endpoint) + else: + key = str(self._current_host.endpoint) errors = {key: "Client request timeout. See Session.execute[_async](timeout)"} else: connection = self.session.cluster.control_connection._connection host = str(connection.endpoint) if connection else 'unknown' errors = {host: "Request timed out while waiting for schema agreement. See Session.execute[_async](timeout) and Cluster.max_schema_agreement_wait."} - self._set_final_exception(OperationTimedOut(errors, self._current_host)) + self._set_final_exception(OperationTimedOut(errors, self._current_host, + timeout=self.timeout, + in_flight=conn_in_flight)) def _on_speculative_execute(self): self._timer = None @@ -4497,14 +4995,110 @@ def send_request(self, error_no_hosts=True): self._on_timeout() return True if error_no_hosts: + if self._fallback_to_control_connection(): + req_id = self._query_control_connection() + if req_id is not None: + self._req_id = req_id + return True + self._set_final_exception(NoHostAvailable( "Unable to complete the operation against any hosts", self._errors)) return False + def _has_usable_node_pool(self): + try: + pools = tuple(self.session._pools.values()) + except (AttributeError, TypeError): + return False + + return any(pool and not pool.is_shutdown for pool in pools) + + def _fallback_to_control_connection(self): + fallback_mode = self.session.cluster.allow_control_connection_query_fallback + if fallback_mode is ControlConnectionQueryFallback.Disabled: + return False + if self._host or self._control_connection_query_attempted: + return False + if fallback_mode is ControlConnectionQueryFallback.SkipPoolCreation: + return True + return not self._has_usable_node_pool() + + def _borrow_control_connection(self, connection): + with connection.lock: + if connection.in_flight >= connection.max_request_id: + raise NoConnectionsAvailable("All request IDs are currently in use") + connection.in_flight += 1 + return connection.get_request_id() + + def _release_control_connection_request(self, connection, request_id): + with connection.lock: + connection.in_flight -= 1 + connection.request_ids.append(request_id) + connection._requests.pop(request_id, None) + + def _handle_control_connection_response(self, connection, cb, response): + with connection.lock: + connection.in_flight -= 1 + cb(response) + + def _query_control_connection(self, message=None, cb=None, connection=None, host=None): + self._control_connection_query_attempted = True + + if message is None: + message = self.message + + if connection is None: + control_connection = self.session.cluster.control_connection + connection = control_connection._connection if control_connection else None + if not connection: + self._errors['control connection'] = ConnectionException("Control connection is not connected") + return None + + if host is None: + host = self.session.cluster.get_control_connection_host() or connection.endpoint + self._current_host = host + + request_id = None + request_sent = False + try: + request_id = self._borrow_control_connection(connection) + self._connection = connection + result_meta = self._bound_result_metadata + if cb is None: + cb = partial(self._set_result, host, connection, None) + cb = partial(self._handle_control_connection_response, connection, cb) + + log.debug("No usable node pools; falling back to control connection for host %s", host) + self.request_encoded_size = connection.send_msg(message, request_id, cb=cb, + encoder=self._protocol_handler.encode_message, + decoder=self._protocol_handler.decode_message, + result_metadata=result_meta) + request_sent = True + self.attempted_hosts.append(host) + return request_id + except NoConnectionsAvailable as exc: + log.debug("Control connection is at capacity") + self._errors[host] = exc + except ConnectionBusy as exc: + log.debug("Control connection is busy") + self._errors[host] = exc + except Exception as exc: + log.debug("Error querying control connection", exc_info=True) + self._errors[host] = exc + if self._metrics is not None: + self._metrics.on_connection_error() + finally: + if request_id is not None and not request_sent: + self._release_control_connection_request(connection, request_id) + + return None + def _query(self, host, message=None, cb=None): if message is None: message = self.message + self._control_connection_query_attempted = False + pool = self.session._pools.get(host) if not pool: self._errors[host] = ConnectionException("Host has been marked down or removed") @@ -4519,11 +5113,16 @@ def _query(self, host, message=None, cb=None): try: # TODO get connectTimeout from cluster settings if self.query: - connection, request_id = pool.borrow_connection(timeout=2.0, routing_key=self.query.routing_key, keyspace=self.query.keyspace, table=self.query.table) + # Pass the ring token computed once for this request so the pool + # can select the shard without re-hashing the routing key. + connection, request_id = pool.borrow_connection( + timeout=2.0, routing_key=self.query.routing_key, + keyspace=self.query.keyspace, table=self.query.table, + routing_token=self._routing_token) else: connection, request_id = pool.borrow_connection(timeout=2.0) self._connection = connection - result_meta = self.prepared_statement.result_metadata if self.prepared_statement else [] + result_meta = self._bound_result_metadata if cb is None: cb = partial(self._set_result, host, connection, pool) @@ -4615,16 +5214,42 @@ def start_fetching_next_page(self): self._event.clear() self._final_result = _NOT_SET self._final_exception = None + self._control_connection_query_attempted = False self._start_timer() self.send_request() def _reprepare(self, prepare_message, host, connection, pool): cb = partial(self.session.submit, self._execute_after_prepare, host, connection, pool) - request_id = self._query(host, prepare_message, cb=cb) + if pool is None and connection is not None and connection.is_control_connection: + request_id = self._query_control_connection(prepare_message, cb=cb, + connection=connection, host=host) + else: + request_id = self._query(host, prepare_message, cb=cb) if request_id is None: # try to submit the original prepared statement on some other host self.send_request() + def _cache_tablet_from_payload(self, payload_key, ctype): + """ + Parse a tablets-routing ``custom_payload`` entry and cache the Tablet. + + ``ctype`` is the tuple type for the negotiated extension. The V1 and V2 + layouts differ only by a trailing ``tablet_version`` field, and + ``Tablet.from_row`` accepts that as an optional final argument, so + unpacking the decoded tuple positionally serves both. The tablet is + cached under the effective keyspace (the statement's, else the + session's) so a prepared statement executed in a session keyspace lands + under the same key ``_compute_tablet_version_block`` looks it up by; + otherwise that lookup always misses. + """ + info = self._custom_payload.get(payload_key) + protocol = self.session.cluster.protocol_version + tablet = Tablet.from_row(*ctype.from_binary(info, protocol)) + keyspace = self.query.keyspace or self.session.keyspace + table = self.query.table + if tablet and keyspace and table: + self.session.cluster.metadata._tablets.add_tablet(keyspace, table, tablet) + def _set_result(self, host, connection, pool, response): try: self.coordinator_host = host @@ -4640,25 +5265,29 @@ def _set_result(self, host, connection, pool, response): self._warnings = getattr(response, 'warnings', None) self._custom_payload = getattr(response, 'custom_payload', None) - if self._custom_payload and self.session.cluster.control_connection._tablets_routing_v1 and 'tablets-routing-v1' in self._custom_payload: - protocol = self.session.cluster.protocol_version - info = self._custom_payload.get('tablets-routing-v1') - ctype = ResponseFuture._TABLET_ROUTING_CTYPE - if ctype is None: - ctype = types.lookup_casstype('TupleType(LongType, LongType, ListType(TupleType(UUIDType, Int32Type)))') - ResponseFuture._TABLET_ROUTING_CTYPE = ctype - tablet_routing_info = ctype.from_binary(info, protocol) - first_token = tablet_routing_info[0] - last_token = tablet_routing_info[1] - tablet_replicas = tablet_routing_info[2] - tablet = Tablet.from_row(first_token, last_token, tablet_replicas) - keyspace = self.query.keyspace - table = self.query.table - self.session.cluster.metadata._tablets.add_tablet(keyspace, table, tablet) + if self._custom_payload and connection is not None: + # Parse the routing payload according to what the connection that + # *served this request* negotiated, not the control connection: + # different nodes may negotiate different extensions, and each + # payload key matches the extension its own connection negotiated. + if connection.features.tablets_routing_v2 and 'tablets-routing-v2' in self._custom_payload: + ctype = ResponseFuture._TABLET_ROUTING_V2_CTYPE + if ctype is None: + ctype = types.lookup_casstype('TupleType(LongType, LongType, ListType(TupleType(UUIDType, Int32Type)), LongType)') + ResponseFuture._TABLET_ROUTING_V2_CTYPE = ctype + self._cache_tablet_from_payload('tablets-routing-v2', ctype) + elif connection.features.tablets_routing_v1 and 'tablets-routing-v1' in self._custom_payload: + ctype = ResponseFuture._TABLET_ROUTING_CTYPE + if ctype is None: + ctype = types.lookup_casstype('TupleType(LongType, LongType, ListType(TupleType(UUIDType, Int32Type)))') + ResponseFuture._TABLET_ROUTING_CTYPE = ctype + self._cache_tablet_from_payload('tablets-routing-v1', ctype) if isinstance(response, ResultMessage): if response.kind == RESULT_KIND_SET_KEYSPACE: session = getattr(self, 'session', None) + if connection is not None: + connection.keyspace = response.new_keyspace # since we're running on the event loop thread, we need to # use a non-blocking method for setting the keyspace on # all connections in this session, otherwise the event @@ -4681,6 +5310,33 @@ def _set_result(self, host, connection, pool, response): self._paging_state = response.paging_state self._col_names = response.column_names self._col_types = response.column_types + new_result_metadata_id = getattr(response, 'result_metadata_id', None) + if self.prepared_statement and new_result_metadata_id is not None: + if response.column_metadata: + # METADATA_CHANGED: replace metadata and its id as one + # atomic pair so a concurrent reader can never pair the + # new id with the old metadata (the server would then + # skip sending metadata and rows would be decoded + # against stale columns, with no recovery). + # (this also re-arms the anomaly warning below) + self.prepared_statement.update_result_metadata( + response.column_metadata, new_result_metadata_id) + elif not self.prepared_statement._warned_missing_column_metadata: + # Anomalous response: a new id without the metadata it + # describes. Cache neither — adopting the id alone would + # create exactly the stale-metadata/fresh-id state + # described above. Keeping the old pair means the next + # EXECUTE sends the old id, the server detects the + # mismatch, and the driver recovers with full metadata. + # Log once per statement (not per execute) while the + # anomaly persists. + self.prepared_statement._warned_missing_column_metadata = True + log.warning( + "Server sent a new result_metadata_id but no column metadata " + "for prepared statement %r. Ignoring both; the cached metadata " + "and id are left unchanged.", + getattr(self.prepared_statement, 'query_id', None) + ) if getattr(self.message, 'continuous_paging_options', None): self._handle_continuous_paging_first_response(connection, response) else: @@ -4831,14 +5487,24 @@ def _execute_after_prepare(self, host, connection, pool, response): expected=hexlify(self.prepared_statement.query_id), got=hexlify(response.query_id) ) )) - self.prepared_statement.result_metadata = response.column_metadata - new_metadata_id = response.result_metadata_id - if new_metadata_id is not None: - self.prepared_statement.result_metadata_id = new_metadata_id - + # Update the metadata/id pair atomically from exactly what this + # reprepare response carries. Falling back to the previously + # cached id when this response has none would risk pairing it + # with metadata from a different schema version than the one the + # old id was computed for (e.g. schema changed and reverted + # between the two PREPAREs) - a stale-but-plausible id a later + # id-aware execute could send without the server detecting the + # mismatch. Dropping it instead triggers the same self-healing + # b'' sentinel path a never-prepared id would. + self.prepared_statement.update_result_metadata( + response.column_metadata, response.result_metadata_id) + # use self._query to re-use the same host and # at the same time properly borrow the connection - request_id = self._query(host) + if pool is None and connection is not None and connection.is_control_connection: + request_id = self._query_control_connection(connection=connection, host=host) + else: + request_id = self._query(host) if request_id is None: # this host errored out, move on to the next self.send_request() @@ -4940,7 +5606,17 @@ def _retry(self, reuse_connection, consistency_level, host, delay): if self._metrics is not None: self._metrics.on_retry() if consistency_level is not None: - self.message.consistency_level = consistency_level + # Never downgrade from serial to non-serial consistency, as that + # would break serial read (Paxos) guarantees. + original_cl = self.message.consistency_level + if ConsistencyLevel.is_serial(original_cl) and not ConsistencyLevel.is_serial(consistency_level): + log.debug( + "Retry policy attempted to downgrade serial consistency %s to %s; " + "keeping original consistency level.", + ConsistencyLevel.value_to_name.get(original_cl, original_cl), + ConsistencyLevel.value_to_name.get(consistency_level, consistency_level)) + else: + self.message.consistency_level = consistency_level # don't retry on the event loop thread self.session.cluster.scheduler.schedule(delay, self._retry_task, reuse_connection, host) @@ -4951,6 +5627,11 @@ def _retry_task(self, reuse_connection, host): # to retry the operation return + if self._control_connection_query_attempted: + self._control_connection_query_attempted = False + self.send_request() + return + if reuse_connection and self._query(host) is not None: return diff --git a/cassandra/concurrent.py b/cassandra/concurrent.py index b96d0b12d4..0e7bf794e0 100644 --- a/cassandra/concurrent.py +++ b/cassandra/concurrent.py @@ -17,7 +17,6 @@ from heapq import heappush, heappop from itertools import cycle from threading import Condition -import sys from cassandra.cluster import ResultSet, EXEC_PROFILE_DEFAULT diff --git a/cassandra/connection.py b/cassandra/connection.py index 87f860f32b..ac2578a16c 100644 --- a/cassandra/connection.py +++ b/cassandra/connection.py @@ -12,7 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import # to enable import io from stdlib from collections import defaultdict, deque import errno from functools import wraps, partial, total_ordering @@ -25,12 +24,14 @@ from threading import Thread, Event, RLock, Condition import time import ssl +import uuid import weakref import random import itertools -from typing import Optional, Union +from typing import Any, Dict, Optional, Tuple, Union from cassandra.application_info import ApplicationInfoBase +from cassandra.client_routes import _ClientRoutesHandler from cassandra.protocol_features import ProtocolFeatures if 'gevent.monkey' in sys.modules: @@ -49,7 +50,7 @@ RegisterMessage, ReviseRequestMessage) from cassandra.segment import SegmentCodec, CrcException from cassandra.util import OrderedDict -from cassandra.shard_info import ShardingInfo +from cassandra.shard_info import ShardingInfo # noqa: F401 # re-exported for cassandra.connection.ShardingInfo log = logging.getLogger(__name__) @@ -230,7 +231,7 @@ class DefaultEndPointFactory(EndPointFactory): port = None """ If no port is discovered in the row, this is the default port - used for endpoint creation. + used for endpoint creation. """ def __init__(self, port=None): @@ -328,6 +329,50 @@ def create_from_sni(self, sni): return SniEndPoint(self._proxy_address, sni, self._port) +class ClientRoutesEndPointFactory(EndPointFactory): + """ + EndPointFactory for Client Routes (Private Link) support. + + Creates ClientRoutesEndPoint instances that defer both address translation + (host_id -> hostname lookup) and DNS resolution until connection time. + This ensures immediate reaction to infrastructure changes. + """ + + client_routes_handler: _ClientRoutesHandler + default_port: int + + def __init__(self, client_routes_handler: _ClientRoutesHandler, default_port: int = None) -> None: + """ + :param client_routes_handler: _ClientRoutesHandler instance to lookup routes + :param default_port: Default port if none found in row + """ + self.client_routes_handler = client_routes_handler + self.default_port = default_port + + def create(self, row: Dict[str, Any]) -> 'ClientRoutesEndPoint': + """ + Create a ClientRoutesEndPoint from a system.peers row. + + Stores only the host_id and handler reference. Both translation + (route lookup) and DNS resolution happen later in resolve(). + """ + from cassandra.metadata import _NodeInfo + host_id = row.get("host_id") + + if host_id is None: + raise ValueError("No host_id to create ClientRoutesEndPoint") + + addr = _NodeInfo.get_broadcast_rpc_address(row) + port = _NodeInfo.get_broadcast_rpc_port(row) or _NodeInfo.get_broadcast_port(row) or self.default_port + + return ClientRoutesEndPoint( + host_id=host_id, + handler=self.client_routes_handler, + original_address=addr, + original_port=port, + ) + + @total_ordering class UnixSocketEndPoint(EndPoint): """ @@ -369,6 +414,76 @@ def __repr__(self): return "<%s: %s>" % (self.__class__.__name__, self._unix_socket_path) +@total_ordering +class ClientRoutesEndPoint(EndPoint): + """ + Client Routes (Private Link) EndPoint implementation. + + Defers both address translation (route lookup) and DNS resolution + until resolve() is called at connection time. This ensures immediate + reaction to infrastructure changes and CLIENT_ROUTES_CHANGE events. + """ + + _host_id: uuid.UUID + _handler: _ClientRoutesHandler + _original_address: str + _original_port: int + + def __init__(self, host_id: uuid.UUID, handler: _ClientRoutesHandler, original_address: str, original_port: int = None) -> None: + """ + :param host_id: Host UUID for route lookup + :param handler: _ClientRoutesHandler instance + :param original_address: Original address from system.peers (for identification) + :param original_port: Original port if route doesn't specify one + """ + self._host_id = host_id + self._handler = handler + self._original_address = original_address + self._original_port = original_port + + @property + def address(self) -> str: + """Returns the original address (updated by resolve()).""" + return self._original_address + + @property + def port(self) -> Optional[int]: + return self._original_port + + @property + def host_id(self) -> uuid.UUID: + return self._host_id + + def resolve(self) -> Tuple[str, int]: + """ + Resolve endpoint by delegating to the handler. + Falls back to original address/port if no route mapping is available. + """ + result = self._handler.resolve_host(self._host_id) + if result is None: + return self._original_address, self._original_port + return result + + def __eq__(self, other): + return (isinstance(other, ClientRoutesEndPoint) and + self._host_id == other._host_id and + self._original_address == other._original_address) + + def __hash__(self): + return hash((self._host_id, self._original_address)) + + def __lt__(self, other): + return ((self._host_id, self._original_address) < + (other._host_id, other._original_address)) + + def __str__(self): + return str("%s (host_id=%s)" % (self._original_address, self._host_id)) + + def __repr__(self): + return "<%s: host_id=%s, original_addr=%s>" % ( + self.__class__.__name__, self._host_id, self._original_address) + + class _Frame(object): def __init__(self, version, flags, stream, opcode, body_offset, end_pos): self.version = version @@ -868,7 +983,10 @@ def factory(cls, endpoint, timeout, host_conn = None, *args, **kwargs): raise conn.last_error elif not conn.connected_event.is_set(): conn.close() - raise OperationTimedOut("Timed out creating connection (%s seconds)" % timeout) + raise OperationTimedOut("Timed out creating connection (%s seconds)" % timeout, + timeout=timeout) + elif conn.is_closed: + raise ConnectionShutdown("Connection to %s was closed by server" % conn.endpoint) else: return conn @@ -1103,7 +1221,8 @@ def send_msg(self, msg, request_id, cb, encoder=ProtocolHandler.encode_message, # this allows us to inject custom functions per request to encode, decode messages self._requests[request_id] = (cb, decoder, result_metadata) msg = encoder(msg, request_id, self.protocol_version, compressor=self.compressor, - allow_beta_protocol_version=self.allow_beta_protocol_version) + allow_beta_protocol_version=self.allow_beta_protocol_version, + protocol_features=self.features) if self._is_checksumming_enabled: buffer = io.BytesIO() @@ -1131,6 +1250,7 @@ def wait_for_responses(self, *msgs, **kwargs): msg += ": %s" % (self.last_error,) raise ConnectionShutdown(msg) timeout = kwargs.get('timeout') + original_timeout = timeout # preserve for exception reporting fail_on_error = kwargs.get('fail_on_error', True) waiter = ResponseWaiter(self, len(msgs), fail_on_error) @@ -1155,7 +1275,8 @@ def wait_for_responses(self, *msgs, **kwargs): if timeout is not None: timeout -= 0.01 if timeout <= 0.0: - raise OperationTimedOut() + raise OperationTimedOut(timeout=original_timeout, + in_flight=self.in_flight) time.sleep(0.01) try: @@ -1542,7 +1663,8 @@ def set_keyspace_blocking(self, keyspace): if not keyspace or keyspace == self.keyspace: return - query = QueryMessage(query='USE "%s"' % (keyspace,), + from cassandra.metadata import escape_name + query = QueryMessage(query='USE %s' % (escape_name(keyspace),), consistency_level=ConsistencyLevel.ONE) try: result = self.wait_for_response(query) @@ -1596,7 +1718,8 @@ def set_keyspace_async(self, keyspace, callback): callback(self, None) return - query = QueryMessage(query='USE "%s"' % (keyspace,), + from cassandra.metadata import escape_name + query = QueryMessage(query='USE %s' % (escape_name(keyspace),), consistency_level=ConsistencyLevel.ONE) def process_result(result): @@ -1678,7 +1801,8 @@ def deliver(self, timeout=None): if self.error: raise self.error elif not self.event.is_set(): - raise OperationTimedOut() + raise OperationTimedOut(timeout=timeout, + in_flight=self.connection.in_flight) else: return self.responses @@ -1694,18 +1818,33 @@ def __init__(self, connection, owner): with connection.lock: if connection.in_flight < connection.max_request_id: connection.in_flight += 1 - connection.send_msg(OptionsMessage(), connection.get_request_id(), self._options_callback) + request_id = connection.get_request_id() + try: + connection.send_msg(OptionsMessage(), request_id, self._options_callback) + except Exception as exc: + if connection.is_control_connection: + connection.in_flight -= 1 + # send_msg() registers the callback before writing to the socket, + # so a write failure must unwind that registration here. + connection._requests.pop(request_id, None) + if request_id not in connection.request_ids: + connection.request_ids.append(request_id) + self._exception = exc + self._event.set() else: self._exception = Exception("Failed to send heartbeat because connection 'in_flight' exceeds threshold") self._event.set() - def wait(self, timeout): + def wait(self, timeout, original_timeout): self._event.wait(timeout) if self._event.is_set(): if self._exception: raise self._exception else: - raise OperationTimedOut("Connection heartbeat timeout after %s seconds" % (timeout,), self.connection.endpoint) + raise OperationTimedOut("Connection heartbeat timeout (total wait=%s seconds, this wait call=%s seconds)" % (original_timeout, timeout), + self.connection.endpoint, + timeout=original_timeout, + in_flight=self.connection.in_flight) def _options_callback(self, response): if isinstance(response, SupportedMessage): @@ -1763,13 +1902,13 @@ def run(self): self._raise_if_stopped() # Wait max `self._timeout` seconds for all HeartbeatFutures to complete - timeout = self._timeout + timeout_left = self._timeout start_time = time.time() for f in futures: self._raise_if_stopped() connection = f.connection try: - f.wait(timeout) + f.wait(timeout_left, self._timeout) # TODO: move this, along with connection locks in pool, down into Connection with connection.lock: connection.in_flight -= 1 @@ -1779,7 +1918,7 @@ def run(self): id(connection), connection.endpoint) failed_connections.append((f.connection, f.owner, e)) - timeout = self._timeout - (time.time() - start_time) + timeout_left = self._timeout - (time.time() - start_time) for connection, owner, exc in failed_connections: self._raise_if_stopped() diff --git a/cassandra/cqlengine/connection.py b/cassandra/cqlengine/connection.py index bf3e55a2e8..c48f8fef90 100644 --- a/cassandra/cqlengine/connection.py +++ b/cassandra/cqlengine/connection.py @@ -16,7 +16,7 @@ import logging import threading -from cassandra.cluster import Cluster, _ConfigMode, _NOT_SET, NoHostAvailable, UserTypeDoesNotExist, ConsistencyLevel +from cassandra.cluster import Cluster, _ConfigMode, _NOT_SET, NoHostAvailable, UserTypeDoesNotExist from cassandra.query import SimpleStatement, dict_factory from cassandra.cqlengine import CQLEngineException diff --git a/cassandra/cqlengine/management.py b/cassandra/cqlengine/management.py index d6dc44119a..aba79e4500 100644 --- a/cassandra/cqlengine/management.py +++ b/cassandra/cqlengine/management.py @@ -19,7 +19,7 @@ import warnings from itertools import product -from cassandra import metadata +from cassandra import DriverException, metadata from cassandra.cqlengine import CQLEngineException from cassandra.cqlengine import columns, query from cassandra.cqlengine.connection import execute, get_cluster, format_log_context @@ -56,7 +56,7 @@ def _get_context(keyspaces, connections): def create_keyspace_simple(name, replication_factor, durable_writes=True, connections=None): """ - Creates a keyspace with SimpleStrategy for replica placement + Creates a keyspace with NetworkTopologyStrategy for replica placement If the keyspace already exists, it will not be modified. @@ -66,11 +66,11 @@ def create_keyspace_simple(name, replication_factor, durable_writes=True, connec *There are plans to guard schema-modifying functions with an environment-driven conditional.* :param str name: name of keyspace to create - :param int replication_factor: keyspace replication factor, used with :attr:`~.SimpleStrategy` + :param int replication_factor: keyspace replication factor, used with :attr:`~.NetworkTopologyStrategy` :param bool durable_writes: Write log is bypassed if set to False :param list connections: List of connection names """ - _create_keyspace(name, durable_writes, 'SimpleStrategy', + _create_keyspace(name, durable_writes, 'NetworkTopologyStrategy', {'replication_factor': replication_factor}, connections=connections) @@ -270,7 +270,7 @@ def _sync_table(model, connection=None): _update_options(model, connection=connection) - table = cluster.metadata.keyspaces[ks_name].tables[raw_cf_name] + table = _get_table_metadata(model, connection) indexes = [c for n, c in model._columns.items() if c.index] @@ -431,9 +431,26 @@ def _get_table_metadata(model, connection=None): # returns the table as provided by the native driver for a given model cluster = get_cluster(connection) ks = model._get_keyspace() - table = model._raw_column_family_name() - table = cluster.metadata.keyspaces[ks].tables[table] - return table + raw_cf_name = model._raw_column_family_name() + try: + return cluster.metadata.keyspaces[ks].tables[raw_cf_name] + except KeyError: + # Metadata may be stale; force a targeted refresh and retry once. + try: + cluster.refresh_table_metadata(ks, raw_cf_name) + except DriverException as exc: + msg = format_log_context( + "Failed to refresh table metadata for '{0}'.'{1}': {2}", + keyspace=ks, connection=connection) + raise CQLEngineException(msg.format(ks, raw_cf_name, exc)) from exc + try: + return cluster.metadata.keyspaces[ks].tables[raw_cf_name] + except KeyError as exc: + msg = format_log_context( + "Table metadata for '{0}'.'{1}' is not available after refresh. " + "Check schema agreement and cluster health.", + keyspace=ks, connection=connection) + raise CQLEngineException(msg.format(ks, raw_cf_name)) from exc def _options_map_from_strings(option_strings): diff --git a/cassandra/cqlengine/query.py b/cassandra/cqlengine/query.py index afc7ceeef6..f99b953c16 100644 --- a/cassandra/cqlengine/query.py +++ b/cassandra/cqlengine/query.py @@ -18,7 +18,7 @@ import time from warnings import warn -from cassandra.query import SimpleStatement, BatchType as CBatchType, BatchStatement +from cassandra.query import SimpleStatement, BatchType as CBatchType from cassandra.cqlengine import columns, CQLEngineException, ValidationError, UnicodeMixin from cassandra.cqlengine import connection as conn from cassandra.cqlengine.functions import Token, BaseQueryFunction, QueryValue diff --git a/cassandra/cqltypes.py b/cassandra/cqltypes.py index d33e5fceb8..4d63ae5195 100644 --- a/cassandra/cqltypes.py +++ b/cassandra/cqltypes.py @@ -27,7 +27,6 @@ # for example), these classes would be a good place to tack on # .from_cql_literal() and .as_cql_literal() classmethods (or whatever). -from __future__ import absolute_import # to enable import io from stdlib import ast from binascii import unhexlify import calendar @@ -44,7 +43,7 @@ from uuid import UUID from cassandra.marshal import (int8_pack, int8_unpack, int16_pack, int16_unpack, - uint16_pack, uint16_unpack, uint32_pack, uint32_unpack, + uint16_unpack, uint32_pack, uint32_unpack, int32_pack, int32_unpack, int64_pack, int64_unpack, float_pack, float_unpack, double_pack, double_unpack, varint_pack, varint_unpack, point_be, point_le, @@ -249,6 +248,8 @@ def lookup_casstype(casstype): """ if isinstance(casstype, (CassandraType, CassandraTypeType)): return casstype + if '(' not in casstype: + return lookup_casstype_simple(casstype) try: return parse_casstype_args(casstype) except (ValueError, AssertionError, IndexError) as e: diff --git a/cassandra/datastax/cloud/__init__.py b/cassandra/datastax/cloud/__init__.py index 0f042ff1c8..be79d6db38 100644 --- a/cassandra/datastax/cloud/__init__.py +++ b/cassandra/datastax/cloud/__init__.py @@ -15,7 +15,6 @@ import os import logging import json -import sys import tempfile import shutil from urllib.request import urlopen diff --git a/cassandra/encoder.py b/cassandra/encoder.py index d803c087ba..b33be935df 100644 --- a/cassandra/encoder.py +++ b/cassandra/encoder.py @@ -25,7 +25,6 @@ import calendar import datetime import math -import sys import types from uuid import UUID import ipaddress diff --git a/cassandra/io/asyncioreactor.py b/cassandra/io/asyncioreactor.py index 66e1d7295c..92ab972e7d 100644 --- a/cassandra/io/asyncioreactor.py +++ b/cassandra/io/asyncioreactor.py @@ -7,7 +7,7 @@ import os import socket import ssl -from threading import Lock, Thread, get_ident +from threading import Lock, Thread log = logging.getLogger(__name__) @@ -23,8 +23,8 @@ asyncio.run_coroutine_threadsafe except AttributeError: raise ImportError( - 'Cannot use asyncioreactor without access to ' - 'asyncio.run_coroutine_threadsafe (added in 3.4.6 and 3.5.1)' + "Cannot use asyncioreactor without access to " + "asyncio.run_coroutine_threadsafe (added in 3.4.6 and 3.5.1)" ) @@ -38,12 +38,12 @@ class AsyncioTimer(object): @property def end(self): - raise NotImplementedError('{} is not compatible with TimerManager and ' - 'does not implement .end()') + raise NotImplementedError( + "{} is not compatible with TimerManager and does not implement .end()" + ) def __init__(self, timeout, callback, loop): - delayed = self._call_delayed_coro(timeout=timeout, - callback=callback) + delayed = self._call_delayed_coro(timeout=timeout, callback=callback) self._handle = asyncio.run_coroutine_threadsafe(delayed, loop=loop) @staticmethod @@ -63,17 +63,61 @@ def cancel(self): def finish(self): # connection.Timer method not implemented here because we can't inspect # the Handle returned from call_later - raise NotImplementedError('{} is not compatible with TimerManager and ' - 'does not implement .finish()') + raise NotImplementedError( + "{} is not compatible with TimerManager and does not implement .finish()" + ) + + +class _AsyncioProtocol(asyncio.Protocol): + """ + Protocol adapter for asyncio SSL connections. Bridges asyncio's + transport/protocol API back to AsyncioConnection's buffer processing. + """ + + def __init__(self, connection, loop_args=None): + self._connection = connection + self.transport = None + self.write_ready = asyncio.Event(**(loop_args or {})) + self.write_ready.set() + + def connection_made(self, transport): + self.transport = transport + + def data_received(self, data): + conn = self._connection + conn._iobuf.write(data) + if conn._iobuf.tell(): + conn.process_io_buffer() + + def pause_writing(self): + self.write_ready.clear() + + def resume_writing(self): + self.write_ready.set() + + def connection_lost(self, exc): + # Unblock any paused writer so shutdown does not hang + self.write_ready.set() + conn = self._connection + if exc: + log.debug("Connection %s lost: %s", conn, exc) + conn.defunct(exc) + else: + log.debug("Connection %s closed by server", conn) + conn.close() + + def eof_received(self): + return False class AsyncioConnection(Connection): """ - An experimental implementation of :class:`.Connection` that uses the - ``asyncio`` module in the Python standard library for its event loop. + An implementation of :class:`.Connection` that uses the ``asyncio`` + module in the Python standard library for its event loop. - Note that it requires ``asyncio`` features that were only introduced in the - 3.4 line in 3.4.6, and in the 3.5 line in 3.5.1. + Supports SSL connections via asyncio's native TLS transport, which + avoids the incompatibility between ``ssl.SSLSocket`` and asyncio's + low-level socket methods (``sock_sendall``, ``sock_recv``). """ _loop = None @@ -88,26 +132,109 @@ class AsyncioConnection(Connection): def __init__(self, *args, **kwargs): Connection.__init__(self, *args, **kwargs) self._background_tasks = set() + self._transport = None + self._using_ssl = bool(self.ssl_context) self._connect_socket() self._socket.setblocking(0) loop_args = dict() if sys.version_info[0] == 3 and sys.version_info[1] < 10: - loop_args['loop'] = self._loop + loop_args["loop"] = self._loop + self._protocol = _AsyncioProtocol(self, loop_args) if self._using_ssl else None + self._ssl_ready = asyncio.Event(**loop_args) if self._using_ssl else None self._write_queue = asyncio.Queue(**loop_args) self._write_queue_lock = asyncio.Lock(**loop_args) # see initialize_reactor -- loop is running in a separate thread, so we # have to use a threadsafe call - self._read_watcher = asyncio.run_coroutine_threadsafe( - self.handle_read(), loop=self._loop - ) + if self._using_ssl: + # For SSL: set up asyncio transport/protocol, then start writer + self._read_watcher = asyncio.run_coroutine_threadsafe( + self._setup_ssl_and_run(), loop=self._loop + ) + else: + # For non-SSL: use low-level sock_sendall/sock_recv as before + self._read_watcher = asyncio.run_coroutine_threadsafe( + self.handle_read(), loop=self._loop + ) self._write_watcher = asyncio.run_coroutine_threadsafe( self.handle_write(), loop=self._loop ) self._send_options_message() + def _connect_socket(self): + """ + Override base class to skip SSL wrapping of the socket. + For SSL connections, the plain TCP socket is connected here, and TLS + is set up later via asyncio's native SSL transport in _setup_ssl_and_run(). + """ + sockerr = None + addresses = self._get_socket_addresses() + for af, socktype, proto, _, sockaddr in addresses: + try: + self._socket = self._socket_impl.socket(af, socktype, proto) + # Do NOT wrap with ssl_context here -- asyncio will handle TLS + self._socket.settimeout(self.connect_timeout) + self._initiate_connection(sockaddr) + self._socket.settimeout(None) + + local_addr = self._socket.getsockname() + log.debug("Connection %s: '%s' -> '%s'", id(self), local_addr, sockaddr) + sockerr = None + break + except socket.error as err: + if self._socket: + self._socket.close() + self._socket = None + sockerr = err + + if sockerr: + raise socket.error( + sockerr.errno, + "Tried connecting to %s. Last error: %s" + % ([a[4] for a in addresses], sockerr.strerror or sockerr), + ) + + if self.sockopts: + for args in self.sockopts: + self._socket.setsockopt(*args) + + async def _setup_ssl_and_run(self): + """ + Upgrade the plain TCP connection to TLS using asyncio's native SSL + transport, then continuously read data via the protocol callbacks. + """ + try: + ssl_context = self.ssl_context + server_hostname = None + if self.ssl_options: + server_hostname = self.ssl_options.get("server_hostname", None) + if server_hostname is None: + # asyncio's create_connection requires server_hostname when + # ssl= is set. Use endpoint address for SNI/verification when + # check_hostname is enabled; otherwise pass "" to suppress SNI. + server_hostname = ( + self.endpoint.address if ssl_context.check_hostname else "" + ) + + transport, protocol = await self._loop.create_connection( + lambda: self._protocol, + sock=self._socket, + ssl=ssl_context, + server_hostname=server_hostname, + ) + self._transport = transport + + if self._check_hostname: + self._validate_hostname() + self._ssl_ready.set() + except Exception as exc: + log.debug("SSL setup failed for %s: %s", self, exc) + self.defunct(exc) + # Unblock handle_write so it can observe the defunct state and exit + self._ssl_ready.set() + return @classmethod def initialize_reactor(cls): @@ -126,8 +253,9 @@ def initialize_reactor(cls): cls._loop = asyncio.new_event_loop() # daemonize so the loop will be shut down on interpreter # shutdown - cls._loop_thread = Thread(target=cls._loop.run_forever, - daemon=True, name="asyncio_thread") + cls._loop_thread = Thread( + target=cls._loop.run_forever, daemon=True, name="asyncio_thread" + ) cls._loop_thread.start() @classmethod @@ -142,9 +270,7 @@ def close(self): # close from the loop thread to avoid races when removing file # descriptors - asyncio.run_coroutine_threadsafe( - self._close(), loop=self._loop - ) + asyncio.run_coroutine_threadsafe(self._close(), loop=self._loop) async def _close(self): log.debug("Closing connection (%s) to %s" % (id(self), self.endpoint)) @@ -152,7 +278,10 @@ async def _close(self): self._write_watcher.cancel() if self._read_watcher: self._read_watcher.cancel() - if self._socket: + if self._transport: + self._transport.close() + self._transport = None + elif self._socket: self._loop.remove_writer(self._socket.fileno()) self._loop.remove_reader(self._socket.fileno()) self._socket.close() @@ -172,15 +301,12 @@ def push(self, data): if len(data) > buff_size: chunks = [] for i in range(0, len(data), buff_size): - chunks.append(data[i:i + buff_size]) + chunks.append(data[i : i + buff_size]) else: chunks = [data] if self._loop_thread != threading.current_thread(): - asyncio.run_coroutine_threadsafe( - self._push_msg(chunks), - loop=self._loop - ) + asyncio.run_coroutine_threadsafe(self._push_msg(chunks), loop=self._loop) else: # avoid races/hangs by just scheduling this, not using threadsafe task = self._loop.create_task(self._push_msg(chunks)) @@ -194,13 +320,25 @@ async def _push_msg(self, chunks): for chunk in chunks: self._write_queue.put_nowait(chunk) - async def handle_write(self): + # For SSL connections, wait until the TLS handshake completes + if self._ssl_ready: + await self._ssl_ready.wait() + if self.is_defunct: + return while True: try: next_msg = await self._write_queue.get() if next_msg: - await self._loop.sock_sendall(self._socket, next_msg) + if self._transport: + # SSL: use asyncio transport (handles TLS transparently) + await self._protocol.write_ready.wait() + if self.is_closed or self.is_defunct or not self._transport: + return + self._transport.write(next_msg) + else: + # Non-SSL: use low-level socket API + await self._loop.sock_sendall(self._socket, next_msg) except socket.error as err: log.debug("Exception in send for %s: %s", self, err) self.defunct(err) @@ -223,8 +361,7 @@ async def handle_read(self): await asyncio.sleep(0) continue except socket.error as err: - log.debug("Exception during socket recv for %s: %s", - self, err) + log.debug("Exception during socket recv for %s: %s", self, err) self.defunct(err) return # leave the read loop except asyncio.CancelledError: diff --git a/cassandra/io/asyncorereactor.py b/cassandra/io/asyncorereactor.py index 02466ad0d2..4d19bb9849 100644 --- a/cassandra/io/asyncorereactor.py +++ b/cassandra/io/asyncorereactor.py @@ -20,7 +20,6 @@ import sys from threading import Lock, Thread, Event import time -import weakref import sys import ssl diff --git a/cassandra/io/libevreactor.py b/cassandra/io/libevreactor.py index c3f8f967ee..6cceb6c6bc 100644 --- a/cassandra/io/libevreactor.py +++ b/cassandra/io/libevreactor.py @@ -13,7 +13,6 @@ # limitations under the License. import atexit from collections import deque -from functools import partial import logging import os import socket @@ -125,6 +124,7 @@ def _cleanup(self): for watcher in (conn._write_watcher, conn._read_watcher): if watcher: watcher.stop() + conn._socket.close() self.notify() # wake the timer watcher @@ -222,6 +222,8 @@ def _loop_will_run(self, prepare): conn._read_watcher.stop() # clear reference cycles from IO callback del conn._read_watcher + conn._socket.close() + log.debug("Closed socket to %s", conn.endpoint) changed = True @@ -232,8 +234,20 @@ def _loop_will_run(self, prepare): self._notifier.send() +def _atexit_cleanup(): + """Cleanup function called by atexit that uses the current _global_loop value. + + This wrapper ensures that cleanup receives the actual LibevLoop instance + instead of None, which was the value of _global_loop when the module was + imported. + """ + global _global_loop + if _global_loop is not None: + _cleanup(_global_loop) + + _global_loop = None -atexit.register(partial(_cleanup, _global_loop)) +atexit.register(_atexit_cleanup) class LibevConnection(Connection): @@ -297,8 +311,6 @@ def close(self): log.debug("Closing connection (%s) to %s", id(self), self.endpoint) _global_loop.connection_destroyed(self) - self._socket.close() - log.debug("Closed socket to %s", self.endpoint) # don't leave in-progress operations hanging if not self.is_defunct: @@ -309,6 +321,8 @@ def close(self): self.connected_event.set() def handle_write(self, watcher, revents, errno=None): + if self.is_closed: + return if revents & libev.EV_ERROR: if errno: exc = IOError(errno, os.strerror(errno)) @@ -350,6 +364,8 @@ def handle_write(self, watcher, revents, errno=None): return def handle_read(self, watcher, revents, errno=None): + if self.is_closed: + return if revents & libev.EV_ERROR: if errno: exc = IOError(errno, os.strerror(errno)) diff --git a/cassandra/metadata.py b/cassandra/metadata.py index b85308449e..5669e6a80e 100644 --- a/cassandra/metadata.py +++ b/cassandra/metadata.py @@ -16,6 +16,7 @@ from bisect import bisect_left from collections import defaultdict from collections.abc import Mapping +from enum import Enum from functools import total_ordering from hashlib import md5 import json @@ -194,7 +195,8 @@ def _update_keyspace(self, keyspace_meta, new_user_types=None): keyspace_meta.functions = old_keyspace_meta.functions keyspace_meta.aggregates = old_keyspace_meta.aggregates keyspace_meta.views = old_keyspace_meta.views - if (keyspace_meta.replication_strategy != old_keyspace_meta.replication_strategy): + if (keyspace_meta.replication_strategy != old_keyspace_meta.replication_strategy or + keyspace_meta._consistency_mode != old_keyspace_meta._consistency_mode): self._keyspace_updated(ks_name) else: self._keyspace_added(ks_name) @@ -733,6 +735,47 @@ def __eq__(self, other): return isinstance(other, LocalStrategy) +class _ConsistencyMode(Enum): + """ + Per-keyspace consistency option reported by ScyllaDB in + ``system_schema.scylla_keyspaces``. The server represents an + eventually-consistent keyspace as ``'eventual'`` or null. + + ScyllaDB only implements ``GLOBAL`` so far, so it is currently the only mode + under which a keyspace's tablets have a Raft leader. ``LOCAL`` is reserved + for a mode that does not exist yet, and until it does it behaves exactly like + ``EVENTUAL`` everywhere in the driver. + """ + EVENTUAL = 'eventual' + LOCAL = 'local' + GLOBAL = 'global' + + +def _consistency_mode_from_string(value: Optional[str]) -> _ConsistencyMode: + """ + Map the ``consistency`` option ScyllaDB reports to a :class:`._ConsistencyMode`. + + The comparison is case-insensitive, since the option is a free-form string on + the wire. A null value -- which is how the server reports an + eventually-consistent keyspace -- or an unrecognized one mean eventually consistent: + the driver must not refuse to build metadata because a server reported a mode it + does not know. + """ + + # Unfortunately, we need to handle the case of None separately. + # When the code is compiled with Cython, calling lower() on + # None will result in a segmentation fault, not an AttributeError. + # That most likely happens as an optimization based on the type + # hint. + if value is None: + return _ConsistencyMode.EVENTUAL + + try: + return _ConsistencyMode(value.lower()) + except ValueError: + return _ConsistencyMode.EVENTUAL + + class KeyspaceMetadata(object): """ A representation of the schema for a single keyspace. @@ -801,6 +844,15 @@ class KeyspaceMetadata(object): A string indicating whether a graph engine is enabled for this keyspace (Core/Classic). """ + _consistency_mode = _ConsistencyMode.EVENTUAL + """ + The consistency mode of the keyspace, derived from the the ``consistency`` + column ScyllaDB stores in ``system_schema.scylla_keyspaces``. + + Private and unstable: it backs leader-aware routing and is not part of the + public API, so the name and semantics may change. + """ + _exc_info = None """ set if metadata parsing failed """ @@ -815,6 +867,7 @@ def __init__(self, name, durable_writes, strategy_class, strategy_options, graph self.aggregates = {} self.views = {} self.graph_engine = graph_engine + self._consistency_mode = _ConsistencyMode.EVENTUAL @property def is_graph_enabled(self): @@ -861,6 +914,15 @@ def as_cql_query(self): ret = "CREATE KEYSPACE %s WITH replication = %s " % ( protect_name(self.name), self.replication_strategy.export_for_schema()) + + if self._consistency_mode != _ConsistencyMode.EVENTUAL: + # Eventual consistency is the server's default, so it is left out. + # Any other mode is spelled exactly as the server reported it -- that + # string is where the member's value came from -- which keeps this + # correct for a mode added later without touching this method. Note + # that 'local' consistency is not implemented in ScyllaDB yet. + ret = ret + (" AND consistency = '%s'" % self._consistency_mode.value) + ret = ret + (' AND durable_writes = %s' % ("true" if self.durable_writes else "false")) if self.graph_engine is not None: ret = ret + (" AND graph_engine = '%s'" % self.graph_engine) @@ -2577,6 +2639,15 @@ class SchemaParserV3(SchemaParserV22): _SELECT_AGGREGATES = "SELECT * FROM system_schema.aggregates" _SELECT_VIEWS = "SELECT * FROM system_schema.views" + # ScyllaDB-only: per-keyspace consistency option. The column is null for + # eventually-consistent keyspaces (and the whole table is absent on Cassandra + # and on Scylla versions without strongly-consistent tablets). + _SELECT_SCYLLA_KEYSPACES = "SELECT keyspace_name, consistency FROM system_schema.scylla_keyspaces" + + def _is_not_scylla(self): + """Check if NOT connected to ScyllaDB by checking for shard awareness.""" + return getattr(getattr(self.connection, 'features', None), 'shard_id', None) is None + _table_name_col = 'table_name' _function_agg_arument_type_col = 'argument_types' @@ -2604,14 +2675,63 @@ class SchemaParserV3(SchemaParserV22): def __init__(self, connection, timeout, fetch_size, metadata_request_timeout): super(SchemaParserV3, self).__init__(connection, timeout, fetch_size, metadata_request_timeout) self.indexes_result = [] + self.scylla_keyspaces_result = [] self.keyspace_table_index_rows = defaultdict(lambda: defaultdict(list)) self.keyspace_view_rows = defaultdict(list) + self.keyspace_consistency_modes = {} + + def _tablets_routing_v2_negotiated(self): + """ + Whether this connection negotiated ``TABLETS_ROUTING_V2``. + + The per-keyspace consistency option only feeds V2 leader-aware routing, + so without the extension there is nothing to route for and the option is + not worth a query. This also subsumes a Scylla check: only ScyllaDB + advertises the extension. + """ + features = getattr(self.connection, 'features', None) + return features is not None and getattr(features, 'tablets_routing_v2', False) + + def _query_keyspace_consistency_mode(self, keyspace): + """ + Read one keyspace's consistency mode from + ``system_schema.scylla_keyspaces``. + + Used by the single-keyspace refresh path, which cannot reuse the map + ``_query_all`` builds because it does not run ``_query_all`` at all. The + read is restricted to ``keyspace``, mirroring the filtered query the + superclass uses for the keyspace row itself. + + A keyspace absent from the table, an unrecognized value, and a missing + table or column (older ScyllaDB, which answers InvalidRequest -- + absorbed by _query_build_row) all mean eventually consistent. A transient + failure propagates, which aborts the refresh and leaves the previously + known mode in place to be retried, rather than resetting the keyspace to + eventual and so silently disabling leader routing and evicting its + tablets. + """ + if not self._tablets_routing_v2_negotiated(): + return _ConsistencyMode.EVENTUAL + + where_clause = bind_params(" WHERE keyspace_name = %s", (keyspace,), _encoder) + row = self._query_build_row(self._SELECT_SCYLLA_KEYSPACES + where_clause, lambda row: row) + if row is None: + return _ConsistencyMode.EVENTUAL + return _consistency_mode_from_string(row.get("consistency")) + + def get_keyspace(self, keyspaces, keyspace): + keyspace_meta = super(SchemaParserV3, self).get_keyspace(keyspaces, keyspace) + if keyspace_meta is not None: + keyspace_meta._consistency_mode = self._query_keyspace_consistency_mode(keyspace) + return keyspace_meta def get_all_keyspaces(self): for keyspace_meta in super(SchemaParserV3, self).get_all_keyspaces(): for row in self.keyspace_view_rows[keyspace_meta.name]: view_meta = self._build_view_metadata(row) keyspace_meta._add_view_metadata(view_meta) + keyspace_meta._consistency_mode = self.keyspace_consistency_modes.get( + keyspace_meta.name, _ConsistencyMode.EVENTUAL) yield keyspace_meta def get_table(self, keyspaces, keyspace, table): @@ -2627,27 +2747,44 @@ def get_table(self, keyspaces, keyspace, table): indexes_query = QueryMessage( query=maybe_add_timeout_to_query(self._SELECT_INDEXES + where_clause, self.metadata_request_timeout), consistency_level=cl, fetch_size=fetch_size) - triggers_query = QueryMessage( - query=maybe_add_timeout_to_query(self._SELECT_TRIGGERS + where_clause, self.metadata_request_timeout), - consistency_level=cl, fetch_size=fetch_size) + + # ScyllaDB doesn't have triggers, skip the query + if self._is_not_scylla(): + triggers_query = QueryMessage( + query=maybe_add_timeout_to_query(self._SELECT_TRIGGERS + where_clause, self.metadata_request_timeout), + consistency_level=cl, fetch_size=fetch_size) # in protocol v4 we don't know if this event is a view or a table, so we look for both where_clause = bind_params(" WHERE keyspace_name = %s AND view_name = %s", (keyspace, table), _encoder) view_query = QueryMessage( query=maybe_add_timeout_to_query(self._SELECT_VIEWS + where_clause, self.metadata_request_timeout), consistency_level=cl, fetch_size=fetch_size) - ((cf_success, cf_result), (col_success, col_result), - (indexes_sucess, indexes_result), (triggers_success, triggers_result), - (view_success, view_result)) = ( - self.connection.wait_for_responses( - cf_query, col_query, indexes_query, triggers_query, - view_query, timeout=self.timeout, fail_on_error=False) - ) + + if self._is_not_scylla(): + ((cf_success, cf_result), (col_success, col_result), + (indexes_sucess, indexes_result), (triggers_success, triggers_result), + (view_success, view_result)) = ( + self.connection.wait_for_responses( + cf_query, col_query, indexes_query, triggers_query, + view_query, timeout=self.timeout, fail_on_error=False) + ) + else: + ((cf_success, cf_result), (col_success, col_result), + (indexes_sucess, indexes_result), + (view_success, view_result)) = ( + self.connection.wait_for_responses( + cf_query, col_query, indexes_query, + view_query, timeout=self.timeout, fail_on_error=False) + ) + table_result = self._handle_results(cf_success, cf_result, query_msg=cf_query) col_result = self._handle_results(col_success, col_result, query_msg=col_query) if table_result: indexes_result = self._handle_results(indexes_sucess, indexes_result, query_msg=indexes_query) - triggers_result = self._handle_results(triggers_success, triggers_result, query_msg=triggers_query) + if self._is_not_scylla(): + triggers_result = self._handle_results(triggers_success, triggers_result, query_msg=triggers_query) + else: + triggers_result = None return self._build_table_metadata(table_result[0], col_result, triggers_result, indexes_result) view_result = self._handle_results(view_success, view_result, query_msg=view_query) @@ -2696,9 +2833,10 @@ def _build_table_metadata(self, row, col_rows=None, trigger_rows=None, index_row self._build_table_columns(table_meta, col_rows, compact_static, is_dense, virtual) - for trigger_row in trigger_rows: - trigger_meta = self._build_trigger_metadata(table_meta, trigger_row) - table_meta.triggers[trigger_meta.name] = trigger_meta + if self._is_not_scylla(): + for trigger_row in trigger_rows: + trigger_meta = self._build_trigger_metadata(table_meta, trigger_row) + table_meta.triggers[trigger_meta.name] = trigger_meta for index_row in index_rows: index_meta = self._build_index_metadata(table_meta, index_row) @@ -2741,7 +2879,7 @@ def _build_table_columns(self, meta, col_rows, compact_static=False, is_dense=Fa meta.clustering_key.append(meta.columns[r.get('column_name')]) for col_row in (r for r in col_rows - if r.get('kind', None) not in ('partition_key', 'clustering_key')): + if r.get('kind', None) not in ('partition_key', 'clustering')): column_meta = self._build_column_metadata(meta, col_row) if is_dense and column_meta.cql_type == types.cql_empty_type: continue @@ -2793,6 +2931,7 @@ def _build_trigger_metadata(table_metadata, row): trigger_meta = TriggerMetadata(table_metadata, name, options) return trigger_meta + def _query_all(self): cl = ConsistencyLevel.ONE fetch_size = self.fetch_size @@ -2809,35 +2948,65 @@ def _query_all(self): fetch_size=fetch_size, consistency_level=cl), QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_AGGREGATES, self.metadata_request_timeout), fetch_size=fetch_size, consistency_level=cl), - QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_TRIGGERS, self.metadata_request_timeout), - fetch_size=fetch_size, consistency_level=cl), QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_INDEXES, self.metadata_request_timeout), fetch_size=fetch_size, consistency_level=cl), QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_VIEWS, self.metadata_request_timeout), fetch_size=fetch_size, consistency_level=cl), ] + # ScyllaDB doesn't have triggers, skip the query + if self._is_not_scylla(): + queries.append(QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_TRIGGERS, self.metadata_request_timeout), + fetch_size=fetch_size, consistency_level=cl)) + + # ScyllaDB-only: the per-keyspace consistency option, which rides along in + # this batch instead of costing a round trip of its own. + scylla_keyspaces_index = None + if self._tablets_routing_v2_negotiated(): + scylla_keyspaces_index = len(queries) + queries.append(QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_SCYLLA_KEYSPACES, self.metadata_request_timeout), + fetch_size=fetch_size, consistency_level=cl)) + + responses = self.connection.wait_for_responses(*queries, timeout=self.timeout, fail_on_error=False) + + # Unpack common responses (always present) ((ks_success, ks_result), (table_success, table_result), (col_success, col_result), (types_success, types_result), (functions_success, functions_result), (aggregates_success, aggregates_result), - (triggers_success, triggers_result), (indexes_success, indexes_result), - (views_success, views_result)) = self.connection.wait_for_responses( - *queries, timeout=self.timeout, fail_on_error=False - ) + (views_success, views_result)) = responses[:8] + + # Unpack triggers response if present (Cassandra/DSE only) + if self._is_not_scylla(): + (triggers_success, triggers_result) = responses[8] self.keyspaces_result = self._handle_results(ks_success, ks_result, query_msg=queries[0]) self.tables_result = self._handle_results(table_success, table_result, query_msg=queries[1]) self.columns_result = self._handle_results(col_success, col_result, query_msg=queries[2]) - self.triggers_result = self._handle_results(triggers_success, triggers_result, query_msg=queries[6]) self.types_result = self._handle_results(types_success, types_result, query_msg=queries[3]) self.functions_result = self._handle_results(functions_success, functions_result, query_msg=queries[4]) self.aggregates_result = self._handle_results(aggregates_success, aggregates_result, query_msg=queries[5]) - self.indexes_result = self._handle_results(indexes_success, indexes_result, query_msg=queries[7]) - self.views_result = self._handle_results(views_success, views_result, query_msg=queries[8]) + self.indexes_result = self._handle_results(indexes_success, indexes_result, query_msg=queries[6]) + self.views_result = self._handle_results(views_success, views_result, query_msg=queries[7]) + if self._is_not_scylla(): + self.triggers_result = self._handle_results(triggers_success, triggers_result, query_msg=queries[8]) + else: + self.triggers_result = [] + + if scylla_keyspaces_index is not None: + (scylla_ks_success, scylla_ks_result) = responses[scylla_keyspaces_index] + # An older ScyllaDB may lack the table or the column and answers + # InvalidRequest; that is not an error, it just means no keyspace is + # strongly consistent. Any other failure propagates, aborting the + # refresh so the modes already known are retried rather than reset. + self.scylla_keyspaces_result = self._handle_results( + scylla_ks_success, scylla_ks_result, expected_failures=(InvalidRequest,), + query_msg=queries[scylla_keyspaces_index]) + else: + self.scylla_keyspaces_result = [] self._aggregate_results() @@ -2854,6 +3023,13 @@ def _aggregate_results(self): for row in self.views_result: m[row["keyspace_name"]].append(row) + # A keyspace missing from the result -- including every keyspace when the + # read was skipped or the table was unavailable -- is eventually + # consistent, which get_all_keyspaces applies as the default. + self.keyspace_consistency_modes = { + row["keyspace_name"]: _consistency_mode_from_string(row.get("consistency")) + for row in self.scylla_keyspaces_result} + @staticmethod def _schema_type_to_cql(type_string): return type_string @@ -2915,8 +3091,6 @@ def _query_all(self): fetch_size=fetch_size, consistency_level=cl), QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_AGGREGATES, self.metadata_request_timeout), fetch_size=fetch_size, consistency_level=cl), - QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_TRIGGERS, self.metadata_request_timeout), - fetch_size=fetch_size, consistency_level=cl), QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_INDEXES, self.metadata_request_timeout), fetch_size=fetch_size, consistency_level=cl), QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_VIEWS, self.metadata_request_timeout), @@ -2930,8 +3104,15 @@ def _query_all(self): fetch_size=fetch_size, consistency_level=cl), ] + # ScyllaDB doesn't have triggers, skip the query + if self._is_not_scylla(): + queries.append(QueryMessage(query=maybe_add_timeout_to_query(self._SELECT_TRIGGERS, self.metadata_request_timeout), + fetch_size=fetch_size, consistency_level=cl)) + responses = self.connection.wait_for_responses( *queries, timeout=self.timeout, fail_on_error=False) + + # Unpack common responses (always present) ( # copied from V3 (ks_success, ks_result), @@ -2940,39 +3121,45 @@ def _query_all(self): (types_success, types_result), (functions_success, functions_result), (aggregates_success, aggregates_result), - (triggers_success, triggers_result), (indexes_success, indexes_result), (views_success, views_result), # V4-only responses (virtual_ks_success, virtual_ks_result), (virtual_table_success, virtual_table_result), - (virtual_column_success, virtual_column_result) - ) = responses + (virtual_column_success, virtual_column_result), + ) = responses[:11] + + # Unpack triggers response if present (Cassandra/DSE only) + if self._is_not_scylla(): + (triggers_success, triggers_result) = responses[11] # copied from V3 self.keyspaces_result = self._handle_results(ks_success, ks_result, query_msg=queries[0]) self.tables_result = self._handle_results(table_success, table_result, query_msg=queries[1]) self.columns_result = self._handle_results(col_success, col_result, query_msg=queries[2]) - self.triggers_result = self._handle_results(triggers_success, triggers_result, query_msg=queries[6]) self.types_result = self._handle_results(types_success, types_result, query_msg=queries[3]) self.functions_result = self._handle_results(functions_success, functions_result, query_msg=queries[4]) self.aggregates_result = self._handle_results(aggregates_success, aggregates_result, query_msg=queries[5]) - self.indexes_result = self._handle_results(indexes_success, indexes_result, query_msg=queries[7]) - self.views_result = self._handle_results(views_success, views_result, query_msg=queries[8]) + self.indexes_result = self._handle_results(indexes_success, indexes_result, query_msg=queries[6]) + self.views_result = self._handle_results(views_success, views_result, query_msg=queries[7]) + if self._is_not_scylla(): + self.triggers_result = self._handle_results(triggers_success, triggers_result, query_msg=queries[11]) + else: + self.triggers_result = [] # V4-only results # These tables don't exist in some DSE versions reporting 4.X so we can # ignore them if we got an error self.virtual_keyspaces_result = self._handle_results( virtual_ks_success, virtual_ks_result, - expected_failures=(InvalidRequest,), query_msg=queries[9] + expected_failures=(InvalidRequest,), query_msg=queries[8] ) self.virtual_tables_result = self._handle_results( virtual_table_success, virtual_table_result, - expected_failures=(InvalidRequest,), query_msg=queries[10] + expected_failures=(InvalidRequest,), query_msg=queries[9] ) self.virtual_columns_result = self._handle_results( virtual_column_success, virtual_column_result, - expected_failures=(InvalidRequest,), query_msg=queries[11] + expected_failures=(InvalidRequest,), query_msg=queries[10] ) self._aggregate_results() diff --git a/cassandra/policies.py b/cassandra/policies.py index e742708019..f1bfefb41d 100644 --- a/cassandra/policies.py +++ b/cassandra/policies.py @@ -464,6 +464,13 @@ class TokenAwarePolicy(LoadBalancingPolicy): If no :attr:`~.Statement.routing_key` is set on the query, the child policy's query plan will be used as is. + + For a table in a strongly-consistent ScyllaDB keyspace, one replica of each + tablet is the Raft leader that coordinates its writes and its linearizable + reads. By default that replica is yielded first -- as long as the child policy + would contact it at all -- so the request reaches it directly instead of being + forwarded there by another coordinator. The private + ``_prefer_tablet_leader`` option turns that off. """ _child_policy = None @@ -473,9 +480,41 @@ class TokenAwarePolicy(LoadBalancingPolicy): Yield local replicas in a random order. """ - def __init__(self, child_policy, shuffle_replicas=True): + _prefer_tablet_leader = True + """ + Yield the Raft leader of a tablet first, for tables in a strongly-consistent + keyspace (one created with ``consistency = 'global'``). Has no effect on + eventually-consistent tables, which have no leader, or on clusters without + the ``TABLETS_ROUTING_V2`` protocol extension, which does not report one. + + The leader outranks distance among the hosts the child policy is willing to + use: it is yielded ahead of nearer replicas, a ``REMOTE`` leader before a + ``LOCAL_RACK`` one included. Every write and every linearizable read on such a + table has to be coordinated by the leader, so contacting a nearer replica only + adds a forwarding hop -- and because the table is globally consistent, keeping + the request inside one datacenter buys no consistency either. + + It does not override the child policy's own filter, though: a leader the child + policy reports as ``IGNORED`` is never contacted. With the default + ``DCAwareRoundRobinPolicy(used_hosts_per_remote_dc=0)`` a leader in a remote + datacenter is ignored, so the request goes to a local replica and the server + forwards it to the leader, exactly as it would without V2. + + Requests at consistency level ``ONE`` or ``LOCAL_ONE`` are exempt regardless + of this setting: any single replica satisfies them, so preferring the leader + would only concentrate load on it. + + Set this to ``False`` to keep plain token-aware ordering for + strongly-consistent tables as well. + + Private and unstable: strong consistency is still experimental, so the name + and the default may change before it is part of the public API. + """ + + def __init__(self, child_policy, shuffle_replicas=True, _prefer_tablet_leader=True): self._child_policy = child_policy self.shuffle_replicas = shuffle_replicas + self._prefer_tablet_leader = _prefer_tablet_leader def populate(self, cluster, hosts): self._cluster_metadata = cluster.metadata @@ -502,19 +541,63 @@ def make_query_plan(self, working_keyspace=None, query=None): yield host return + # Deferred: cassandra.metadata reaches this module through + # cassandra.protocol, so importing it at module scope closes an import + # cycle. Same reason cassandra.connection imports from metadata inside + # its functions. + from cassandra.metadata import _ConsistencyMode + replicas = [] - tablet = self._cluster_metadata._tablets.get_tablet_for_key( - keyspace, query.table, self._cluster_metadata.token_map.token_class.from_key(query.routing_key)) + leader_host = None + token = self._cluster_metadata.token_map.token_class.from_key(query.routing_key) + tablet = self._cluster_metadata._tablets.get_tablet_for_key(keyspace, query.table, token) if tablet is not None: replicas_mapped = set(map(lambda r: r[0], tablet.replicas)) child_plan = child.make_query_plan(keyspace, query) replicas = [host for host in child_plan if host.host_id in replicas_mapped] + + # The leader concept only exists for strongly-consistent keyspaces, + # which today means exactly the keyspaces whose consistency mode is + # GLOBAL: it is the only mode ScyllaDB implements so far, so LOCAL + # (reserved, unimplemented) and EVENTUAL both have no leader. This + # comparison has to widen once 'local' consistency exists. + # TABLETS_ROUTING_V2 assigns a tablet_version to *every* tablet table + # (eventually- and strongly-consistent alike), so the version alone + # must not be used to infer a leader. Conversely, replicas[0] is only + # leader-ordered for a tablet that came from a V2 payload, so a + # versionless tablet (V1-sourced, or stale across a consistency flip) + # must not be treated as a leader hint either. Require both a + # strongly-consistent keyspace and a versioned tablet; otherwise keep + # normal token-aware/shuffled ordering. + ks_meta = self._cluster_metadata.keyspaces.get(keyspace) + if (self._prefer_tablet_leader + and ks_meta is not None and ks_meta._consistency_mode == _ConsistencyMode.GLOBAL + and tablet.tablet_version is not None): + # Even for a leader-eligible tablet, a request at consistency + # level ONE or LOCAL_ONE is satisfied by any single replica, so + # preferring the leader would only concentrate load into a + # hotspot without buying any consistency; spread those instead. + # TODO: This reads the level off the statement, so a request that + # inherits its consistency level from an execution profile + # looks unset here and is routed to the leader anyway. See + # https://github.com/scylladb/python-driver/issues/953 + effective_cl = query.consistency_level + prefer_leader = effective_cl not in (ConsistencyLevel.ONE, ConsistencyLevel.LOCAL_ONE) + if prefer_leader: + leader_host_id = tablet.leader + # A tablet with no replicas reports no leader; guard against + # matching a host whose own host_id is still unknown. + if leader_host_id is not None: + for host in replicas: + if host.host_id == leader_host_id: + leader_host = host + break else: replicas = self._cluster_metadata.get_replicas(keyspace, query.routing_key) - if self.shuffle_replicas and not query.is_lwt(): + if self.shuffle_replicas and not query.is_lwt() and not ConsistencyLevel.is_serial(query.consistency_level): shuffle(replicas) def yield_in_order(hosts): @@ -523,9 +606,20 @@ def yield_in_order(hosts): if replica.is_up and child.distance(replica) == distance: yield replica - # yield replicas: local_rack, local, remote - yield from yield_in_order(replicas) + # If we have a leader hint, yield it first -- but respect the child + # policy's own filter: never front-run a host the child policy would + # exclude (e.g. one a custom policy reports as IGNORED). + if (leader_host is not None and leader_host.is_up + and child.distance(leader_host) != HostDistance.IGNORED): + yield leader_host + + # yield replicas: local_rack, local, remote (skipping leader already yielded) + for host in yield_in_order(replicas): + if host is not leader_host: + yield host + # yield rest of the cluster: local_rack, local, remote + # Note: The leader is always a replica, so we don't need to filter it out here. yield from yield_in_order([host for host in child.make_query_plan(keyspace, query) if host not in replicas]) def on_up(self, *args, **kwargs): @@ -773,7 +867,7 @@ class ConstantReconnectionPolicy(ReconnectionPolicy): in-between each reconnection attempt. """ - def __init__(self, delay, max_attempts=64): + def __init__(self, delay, max_attempts=None): """ `delay` should be a floating point number of seconds to wait in-between each attempt. @@ -807,10 +901,7 @@ class ExponentialReconnectionPolicy(ReconnectionPolicy): trying to reconnect at exactly the same time. """ - # TODO: max_attempts is 64 to preserve legacy default behavior - # consider changing to None in major release to prevent the policy - # giving up forever - def __init__(self, base_delay, max_delay, max_attempts=64): + def __init__(self, base_delay, max_delay, max_attempts=None): """ `base_delay` and `max_delay` should be in floating point units of seconds. @@ -1158,7 +1249,7 @@ def __init__(self, max_num_retries: float, min_interval: float = 0.1, max_interv self.min_interval = min_interval self.max_num_retries = max_num_retries self.max_interval = max_interval - super(ExponentialBackoffRetryPolicy).__init__(*args, **kwargs) + super(ExponentialBackoffRetryPolicy, self).__init__(*args, **kwargs) def _calculate_backoff(self, attempt: int): delay = min(self.max_interval, self.min_interval * 2 ** attempt) diff --git a/cassandra/pool.py b/cassandra/pool.py index 2da657256f..1d90e3233f 100644 --- a/cassandra/pool.py +++ b/cassandra/pool.py @@ -18,11 +18,9 @@ from concurrent.futures import Future from functools import total_ordering import logging -import socket import time import random import copy -import uuid from threading import Lock, RLock, Condition import weakref try: @@ -391,7 +389,7 @@ class HostConnection(object): # the number below, all excess connections will be closed. max_excess_connections_per_shard_multiplier = 3 - tablets_routing_v1 = False + supports_tablet_routing = False def __init__(self, host, host_distance, session): self.host = host @@ -438,11 +436,13 @@ def __init__(self, host, host_distance, session): if first_connection.features.sharding_info and not self._session.cluster.shard_aware_options.disable: self.host.sharding_info = first_connection.features.sharding_info self._open_connections_for_all_shards(first_connection.features.shard_id) - self.tablets_routing_v1 = first_connection.features.tablets_routing_v1 + + self.supports_tablet_routing = first_connection.features.tablets_routing_v1 \ + or first_connection.features.tablets_routing_v2 log.debug("Finished initializing connection for host %s", self.host) - def _get_connection_for_routing_key(self, routing_key=None, keyspace=None, table=None): + def _get_connection_for_routing_key(self, routing_key=None, keyspace=None, table=None, routing_token=None): if self.is_shutdown: raise ConnectionException( "Pool for %s is shutdown" % (self.host,), self.host) @@ -452,22 +452,32 @@ def _get_connection_for_routing_key(self, routing_key=None, keyspace=None, table shard_id = None if not self._session.cluster.shard_aware_options.disable and self.host.sharding_info and routing_key: - t = self._session.cluster.metadata.token_map.token_class.from_key(routing_key) - - shard_id = None - if self.tablets_routing_v1 and table is not None: + # Reuse the token computed once for this request when available, so + # the routing-key hash runs once per request instead of again here; + # fall back to hashing the routing key directly otherwise. The caller + # leaves the token unset when the cluster's partitioner cannot be + # hashed (see Session._create_response_future), so the fallback has to + # make the same check rather than retry a hash that would raise. + metadata = self._session.cluster.metadata + t = routing_token + if t is None and metadata.token_map is not None and metadata.can_support_partitioner(): + t = metadata.token_map.token_class.from_key(routing_key) + if t is not None and self.supports_tablet_routing and table is not None: if keyspace is None: keyspace = self._keyspace tablet = self._session.cluster.metadata._tablets.get_tablet_for_key(keyspace, table, t) + # In both V1 and V2 the request is sent to this host, so we pick + # the shard that this host owns for the tablet. Leader-aware host + # selection (V2) happens earlier, in the load balancing policy. if tablet is not None: for replica in tablet.replicas: if replica[0] == self.host.host_id: shard_id = replica[1] break - if shard_id is None: + if shard_id is None and t is not None: shard_id = self.host.sharding_info.shard_id_from_token(t.value) conn = self._connections.get(shard_id) @@ -476,12 +486,6 @@ def _get_connection_for_routing_key(self, routing_key=None, keyspace=None, table # optimistic try to connect to it if shard_id is not None: if conn: - log.debug( - "Using connection to shard_id=%i on host %s for routing_key=%s", - shard_id, - self.host, - routing_key - ) if conn.orphaned_threshold_reached and shard_id not in self._connecting: # The connection has met its orphaned stream ID limit # and needs to be replaced. Start opening a connection @@ -514,15 +518,15 @@ def _get_connection_for_routing_key(self, routing_key=None, keyspace=None, table return random.choice(active_connections) return random.choice(list(self._connections.values())) - def borrow_connection(self, timeout, routing_key=None, keyspace=None, table=None): - conn = self._get_connection_for_routing_key(routing_key, keyspace, table) + def borrow_connection(self, timeout, routing_key=None, keyspace=None, table=None, routing_token=None): + conn = self._get_connection_for_routing_key(routing_key, keyspace, table, routing_token) start = time.time() remaining = timeout last_retry = False while True: if conn.is_closed: # The connection might have been closed in the meantime - if so, try again - conn = self._get_connection_for_routing_key(routing_key, keyspace, table) + conn = self._get_connection_for_routing_key(routing_key, keyspace, table, routing_token) with conn.lock: if (not conn.is_closed or last_retry) and conn.in_flight < conn.max_request_id: # On last retry we ignore connection status, since it is better to return closed connection than @@ -683,15 +687,26 @@ def disable_advanced_shard_aware(self, secs): self.advanced_shardaware_block_until = max(time.time() + secs, self.advanced_shardaware_block_until) def _get_shard_aware_endpoint(self): - if (self.advanced_shardaware_block_until and self.advanced_shardaware_block_until < time.time()) or \ + """ + Return an endpoint for the advertised shard-aware port, if usable. + + Plaintext clusters use shard_aware_port. SSL-enabled clusters use only + shard_aware_port_ssl; if it is absent, return None so the pool opens a + regular SSL connection instead of falling back to the plaintext port. + Explicit ssl_options={}, like ssl_context, marks the cluster SSL-enabled. + """ + if (self.advanced_shardaware_block_until and self.advanced_shardaware_block_until > time.time()) or \ self._session.cluster.shard_aware_options.disable_shardaware_port: return None + cluster = self._session.cluster + ssl_enabled = cluster.ssl_context is not None or cluster.ssl_options is not None + endpoint = None - if self._session.cluster.ssl_options and self.host.sharding_info.shard_aware_port_ssl: + if ssl_enabled and self.host.sharding_info.shard_aware_port_ssl: endpoint = copy.copy(self.host.endpoint) endpoint._port = self.host.sharding_info.shard_aware_port_ssl - elif self.host.sharding_info.shard_aware_port: + elif not ssl_enabled and self.host.sharding_info.shard_aware_port: endpoint = copy.copy(self.host.endpoint) endpoint._port = self.host.sharding_info.shard_aware_port @@ -926,5 +941,3 @@ def open_count(self): @property def _excess_connection_limit(self): return self.host.sharding_info.shards_count * self.max_excess_connections_per_shard_multiplier - - diff --git a/cassandra/protocol.py b/cassandra/protocol.py index f37633a756..4a2444da88 100644 --- a/cassandra/protocol.py +++ b/cassandra/protocol.py @@ -12,7 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import # to enable import io from stdlib from collections import namedtuple import logging import socket @@ -27,14 +26,17 @@ AlreadyExists, InvalidRequest, Unauthorized, UnsupportedOperation, UserFunctionDescriptor, UserAggregateDescriptor, SchemaTargetType) -from cassandra.cqltypes import (AsciiType, BytesType, BooleanType, - CounterColumnType, DateType, DecimalType, - DoubleType, FloatType, Int32Type, - InetAddressType, IntegerType, ListType, - LongType, MapType, SetType, TimeUUIDType, - UTF8Type, VarcharType, UUIDType, UserType, - TupleType, lookup_casstype, SimpleDateType, - TimeType, ByteType, ShortType, DurationType) +# NOTE: many of these names are not referenced directly, but are required in module +# scope because ResultMessage.type_codes resolves them dynamically via globals()[name] +# (see the type_codes mapping below). Do not remove as "unused imports". +from cassandra.cqltypes import (AsciiType, BytesType, BooleanType, # noqa: F401 + CounterColumnType, DateType, DecimalType, # noqa: F401 + DoubleType, FloatType, Int32Type, # noqa: F401 + InetAddressType, IntegerType, ListType, # noqa: F401 + LongType, MapType, SetType, TimeUUIDType, # noqa: F401 + UTF8Type, VarcharType, UUIDType, UserType, # noqa: F401 + TupleType, lookup_casstype, SimpleDateType, # noqa: F401 + TimeType, ByteType, ShortType, DurationType) # noqa: F401 from cassandra.marshal import (int32_pack, int32_unpack, uint16_pack, uint16_unpack, uint8_pack, int8_unpack, uint64_pack, v3_header_pack, uint32_pack, uint32_le_unpack, uint32_le_pack) @@ -421,7 +423,7 @@ def __init__(self, cqlversion, options): self.cqlversion = cqlversion self.options = options - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): optmap = self.options.copy() optmap['CQL_VERSION'] = self.cqlversion write_stringmap(f, optmap) @@ -456,7 +458,7 @@ class CredentialsMessage(_MessageType): def __init__(self, creds): self.creds = creds - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): if protocol_version > 1: raise UnsupportedOperation( "Credentials-based authentication is not supported with " @@ -487,7 +489,7 @@ class AuthResponseMessage(_MessageType): def __init__(self, response): self.response = response - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): write_longstring(f, self.response) @@ -507,7 +509,7 @@ class OptionsMessage(_MessageType): opcode = 0x05 name = 'OPTIONS' - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): pass @@ -555,7 +557,15 @@ def __init__(self, query_params, consistency_level, self.skip_meta = skip_meta self.keyspace = keyspace - def _write_query_params(self, f, protocol_version): + def _should_skip_metadata(self, protocol_version, protocol_features): + """Whether to set ``_SKIP_METADATA_FLAG`` on this message. + + The base is unconditional (the message's own ``skip_meta``); subclasses + narrow it based on the connection's negotiated features. + """ + return self.skip_meta + + def _write_query_params(self, f, protocol_version, protocol_features=None): write_consistency_level(f, self.consistency_level) flags = 0x00 if self.query_params is not None: @@ -573,6 +583,9 @@ def _write_query_params(self, f, protocol_version): if self.timestamp is not None: flags |= _PROTOCOL_TIMESTAMP_FLAG + if self._should_skip_metadata(protocol_version, protocol_features): + flags |= _SKIP_METADATA_FLAG + if self.keyspace is not None: if ProtocolVersion.uses_keyspace_flag(protocol_version): flags |= _WITH_KEYSPACE_FLAG @@ -611,14 +624,26 @@ class QueryMessage(_QueryMessage): name = 'QUERY' def __init__(self, query, consistency_level, serial_consistency_level=None, - fetch_size=None, paging_state=None, timestamp=None, continuous_paging_options=None, keyspace=None): + fetch_size=None, paging_state=None, timestamp=None, continuous_paging_options=None, keyspace=None, + query_params=None): self.query = query - super(QueryMessage, self).__init__(None, consistency_level, serial_consistency_level, fetch_size, + super(QueryMessage, self).__init__(query_params, consistency_level, serial_consistency_level, fetch_size, paging_state, timestamp, False, continuous_paging_options, keyspace) - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): write_longstring(f, self.query) - self._write_query_params(f, protocol_version) + self._write_query_params(f, protocol_version, protocol_features) + + +def _metadata_id_negotiated(protocol_version, protocol_features): + """Whether the result-metadata-id field is part of the frame layout. + + It is part of the layout of EXECUTE requests and PREPARE responses whenever + the connection speaks CQL v5+ natively or negotiated SCYLLA_USE_METADATA_ID, + so on such connections it must always be written and always be read. + """ + return (ProtocolVersion.uses_prepared_metadata(protocol_version) + or (protocol_features is not None and protocol_features.use_metadata_id)) class ExecuteMessage(_QueryMessage): @@ -628,20 +653,48 @@ class ExecuteMessage(_QueryMessage): def __init__(self, query_id, query_params, consistency_level, serial_consistency_level=None, fetch_size=None, paging_state=None, timestamp=None, skip_meta=False, - continuous_paging_options=None, result_metadata_id=None): + continuous_paging_options=None, result_metadata_id=None, + tablet_version_block=None): self.query_id = query_id self.result_metadata_id = result_metadata_id + self.tablet_version_block = tablet_version_block super(ExecuteMessage, self).__init__(query_params, consistency_level, serial_consistency_level, fetch_size, paging_state, timestamp, skip_meta, continuous_paging_options) - def _write_query_params(self, f, protocol_version): - super(ExecuteMessage, self)._write_query_params(f, protocol_version) + def _should_skip_metadata(self, protocol_version, protocol_features): + """Whether to ask the server to skip sending result metadata. + + Only when the SCYLLA_USE_METADATA_ID extension is negotiated on this + connection. Without the metadata-id mechanism a schema change after + PREPARE would leave the driver decoding rows with stale cached metadata. + + This is deliberately narrower than :func:`_metadata_id_negotiated`: on + native CQL v5 the metadata-id field is part of the frame layout, but we + do NOT emit ``_SKIP_METADATA_FLAG`` there. Upstream never emitted it on + any version, and turning the skip optimization on for native v5 is a + separate behavior change out of scope for this Scylla extension. + """ + return (self.skip_meta + and protocol_features is not None + and protocol_features.use_metadata_id) + + def _write_query_params(self, f, protocol_version, protocol_features=None): + super(ExecuteMessage, self)._write_query_params(f, protocol_version, protocol_features) - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): write_string(f, self.query_id) - if ProtocolVersion.uses_prepared_metadata(protocol_version): - write_string(f, self.result_metadata_id) - self._write_query_params(f, protocol_version) + if _metadata_id_negotiated(protocol_version, protocol_features): + # An empty id is written when the statement has no cached metadata id + # (prepared before the extension was negotiated, e.g. in a mixed + # cluster): the server treats the mismatch as METADATA_CHANGED and + # responds with full metadata plus the current id. + write_string(f, self.result_metadata_id if self.result_metadata_id is not None else b'') + self._write_query_params(f, protocol_version, protocol_features) + if protocol_features is not None and protocol_features.tablets_routing_v2: + # A V2 connection makes the server read exactly one trailing byte per + # EXECUTE, so always write one. Coalesce a missing value to 0 to keep + # the frame in sync. + write_byte(f, self.tablet_version_block if self.tablet_version_block is not None else 0) CUSTOM_TYPE = object() @@ -744,7 +797,7 @@ def decode_row(row): def recv_results_prepared(self, f, protocol_version, protocol_features, user_type_map): self.query_id = read_binary_string(f) - if ProtocolVersion.uses_prepared_metadata(protocol_version): + if _metadata_id_negotiated(protocol_version, protocol_features): self.result_metadata_id = read_binary_string(f) else: self.result_metadata_id = None @@ -866,7 +919,7 @@ def __init__(self, query, keyspace=None): self.query = query self.keyspace = keyspace - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): write_longstring(f, self.query) flags = 0x00 @@ -910,7 +963,7 @@ def __init__(self, batch_type, queries, consistency_level, self.timestamp = timestamp self.keyspace = keyspace - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): write_byte(f, self.batch_type.value) write_short(f, len(self.queries)) for prepared, string_or_query_id, params in self.queries: @@ -968,7 +1021,7 @@ class RegisterMessage(_MessageType): def __init__(self, event_list): self.event_list = event_list - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): write_stringlist(f, self.event_list) @@ -1042,7 +1095,7 @@ def __init__(self, op_type, op_id, next_pages=0): self.op_id = op_id self.next_pages = next_pages - def send_body(self, f, protocol_version): + def send_body(self, f, protocol_version, protocol_features=None): write_int(f, self.op_type) write_int(f, self.op_id) if self.op_type == ReviseRequestMessage.RevisionType.PAGING_BACKPRESSURE: @@ -1075,7 +1128,8 @@ class _ProtocolHandler(object): """Instance of :class:`cassandra.policies.ColumnEncryptionPolicy` in use by this handler""" @classmethod - def encode_message(cls, msg, stream_id, protocol_version, compressor, allow_beta_protocol_version): + def encode_message(cls, msg, stream_id, protocol_version, compressor, allow_beta_protocol_version, + protocol_features): """ Encodes a message using the specified frame parameters, and compressor @@ -1083,6 +1137,11 @@ def encode_message(cls, msg, stream_id, protocol_version, compressor, allow_beta :param stream_id: protocol stream id for the frame header :param protocol_version: version for the frame header, and used encoding contents :param compressor: optional compression function to be used on the body + :param protocol_features: :class:`~cassandra.protocol_features.ProtocolFeatures` negotiated on the connection + this message is sent over, forwarded to ``send_body``. Messages carry + connection-independent request data; ``send_body`` decides the wire format from + ``(protocol_version, protocol_features)``, so fields belonging to a negotiated + protocol extension are emitted exactly on the connections that negotiated it. """ flags = 0 if msg.custom_payload: @@ -1104,7 +1163,7 @@ def encode_message(cls, msg, stream_id, protocol_version, compressor, allow_beta body = io.BytesIO() if msg.custom_payload: write_bytesmap(body, msg.custom_payload) - msg.send_body(body, protocol_version) + msg.send_body(body, protocol_version, protocol_features) body = body.getvalue() if len(body) > 0: @@ -1116,7 +1175,7 @@ def encode_message(cls, msg, stream_id, protocol_version, compressor, allow_beta else: if msg.custom_payload: write_bytesmap(buff, msg.custom_payload) - msg.send_body(buff, protocol_version) + msg.send_body(buff, protocol_version, protocol_features) length = buff.tell() - 9 diff --git a/cassandra/protocol_features.py b/cassandra/protocol_features.py index 877998be7d..c2bc7ca417 100644 --- a/cassandra/protocol_features.py +++ b/cassandra/protocol_features.py @@ -10,28 +10,46 @@ LWT_OPTIMIZATION_META_BIT_MASK = "LWT_OPTIMIZATION_META_BIT_MASK" RATE_LIMIT_ERROR_EXTENSION = "SCYLLA_RATE_LIMIT_ERROR" TABLETS_ROUTING_V1 = "TABLETS_ROUTING_V1" +USE_METADATA_ID = "SCYLLA_USE_METADATA_ID" +# The server advertises and expects this exact extension name in SUPPORTED/STARTUP +# (see scylladb transport/cql_protocol_extension.cc). While the feature is gated +# behind the server's `strongly-consistent-tables` experimental flag, the wire +# name carries the `_EXPERIMENTAL` suffix. +TABLETS_ROUTING_V2 = "TABLETS_ROUTING_V2_EXPERIMENTAL" class ProtocolFeatures(object): rate_limit_error = None shard_id = 0 sharding_info = None tablets_routing_v1 = False + tablets_routing_v2 = False lwt_info = None + use_metadata_id = False - def __init__(self, rate_limit_error=None, shard_id=0, sharding_info=None, tablets_routing_v1=False, lwt_info=None): + # Keyword-only so that independently developed protocol extensions can add + # new fields without conflicting over positional-argument order. + def __init__(self, *, rate_limit_error=None, shard_id=0, sharding_info=None, + tablets_routing_v1=False, tablets_routing_v2=False, lwt_info=None, + use_metadata_id=False): self.rate_limit_error = rate_limit_error self.shard_id = shard_id self.sharding_info = sharding_info self.tablets_routing_v1 = tablets_routing_v1 + self.tablets_routing_v2 = tablets_routing_v2 self.lwt_info = lwt_info + self.use_metadata_id = use_metadata_id @staticmethod def parse_from_supported(supported): rate_limit_error = ProtocolFeatures.maybe_parse_rate_limit_error(supported) shard_id, sharding_info = ProtocolFeatures.parse_sharding_info(supported) tablets_routing_v1 = ProtocolFeatures.parse_tablets_info(supported) + tablets_routing_v2 = ProtocolFeatures.parse_tablets_v2_info(supported) lwt_info = ProtocolFeatures.parse_lwt_info(supported) - return ProtocolFeatures(rate_limit_error, shard_id, sharding_info, tablets_routing_v1, lwt_info) + use_metadata_id = ProtocolFeatures.parse_use_metadata_id(supported) + return ProtocolFeatures(rate_limit_error=rate_limit_error, shard_id=shard_id, sharding_info=sharding_info, + tablets_routing_v1=tablets_routing_v1, tablets_routing_v2=tablets_routing_v2, + lwt_info=lwt_info, use_metadata_id=use_metadata_id) @staticmethod def maybe_parse_rate_limit_error(supported): @@ -53,10 +71,16 @@ def get_cql_extension_field(vals, key): def add_startup_options(self, options): if self.rate_limit_error is not None: options[RATE_LIMIT_ERROR_EXTENSION] = "" - if self.tablets_routing_v1: + # Only one of TABLETS_ROUTING_V{1,2} should be negotiated + # per connection. Hence the if-else branch. + if self.tablets_routing_v2: + options[TABLETS_ROUTING_V2] = "" + elif self.tablets_routing_v1: options[TABLETS_ROUTING_V1] = "" if self.lwt_info is not None: options[LWT_ADD_METADATA_MARK] = str(self.lwt_info.lwt_meta_bit_mask) + if self.use_metadata_id: + options[USE_METADATA_ID] = "" @staticmethod def parse_sharding_info(options): @@ -81,6 +105,15 @@ def parse_sharding_info(options): def parse_tablets_info(options): return TABLETS_ROUTING_V1 in options + @staticmethod + def parse_tablets_v2_info(options): + return TABLETS_ROUTING_V2 in options + + @staticmethod + def parse_use_metadata_id(options): + """Return True if the ``SCYLLA_USE_METADATA_ID`` extension is advertised in ``options``.""" + return USE_METADATA_ID in options + @staticmethod def parse_lwt_info(options): value_list = options.get(LWT_ADD_METADATA_MARK, [None]) diff --git a/cassandra/query.py b/cassandra/query.py index 6c6878fdb4..39b9fdb0ad 100644 --- a/cassandra/query.py +++ b/cassandra/query.py @@ -451,13 +451,16 @@ class PreparedStatement(object): protocol_version = None query_id = None query_string = None - result_metadata = None - result_metadata_id = None + _result_metadata_and_id = (None, None) column_encryption_policy = None routing_key_indexes = None _routing_key_index_set = None serial_consistency_level = None # TODO never used? _is_lwt = False + # Set once we've logged the "new metadata id without column metadata" anomaly + # for this statement, to avoid logging it on every execute while a misbehaving + # server keeps returning it. Re-armed whenever the metadata is updated. + _warned_missing_column_metadata = False def __init__(self, column_metadata, query_id, routing_key_indexes, query, keyspace, protocol_version, result_metadata, result_metadata_id, @@ -468,12 +471,57 @@ def __init__(self, column_metadata, query_id, routing_key_indexes, query, self.query_string = query self.keyspace = keyspace self.protocol_version = protocol_version - self.result_metadata = result_metadata - self.result_metadata_id = result_metadata_id + self._result_metadata_and_id = (result_metadata, result_metadata_id) self.column_encryption_policy = column_encryption_policy self.is_idempotent = False self._is_lwt = is_lwt + @property + def result_metadata_and_id(self): + """ + The cached result metadata and its metadata id as one immutable + ``(result_metadata, result_metadata_id)`` pair. + + Read this property when both values are needed together: the tuple is + replaced atomically by :meth:`update_result_metadata`, so a single read + can never observe the metadata of one schema version paired with the + metadata id of another. + """ + return self._result_metadata_and_id + + @property + def result_metadata(self): + """ + Cached result metadata (column definitions) from PREPARE. Read-only: + :meth:`update_result_metadata` is the only way to replace it, so it can + never be assigned separately from the id it belongs to. + """ + return self._result_metadata_and_id[0] + + @property + def result_metadata_id(self): + """ + Cached result metadata id (hash) from PREPARE. Read-only: + :meth:`update_result_metadata` is the only way to replace it, so it can + never be assigned separately from the metadata it describes. + """ + return self._result_metadata_and_id[1] + + def update_result_metadata(self, result_metadata, result_metadata_id): + """ + Replace the cached result metadata and metadata id together, in a single + atomic attribute store. Response callbacks may update a statement while + request threads read it; updating the pair in one step (rather than the + two fields separately) prevents a reader from pairing a fresh metadata id + with stale metadata — a state in which the server would skip sending + metadata and rows would be decoded against the wrong columns. + + Also re-arms :attr:`_warned_missing_column_metadata`, so an anomaly that + recurs after the metadata was recovered is logged again. + """ + self._result_metadata_and_id = (result_metadata, result_metadata_id) + self._warned_missing_column_metadata = False + @classmethod def from_message(cls, query_id, column_metadata, pk_indexes, cluster_metadata, query, prepared_keyspace, protocol_version, result_metadata, diff --git a/cassandra/tablets.py b/cassandra/tablets.py index dca26ab0df..b386d1a372 100644 --- a/cassandra/tablets.py +++ b/cassandra/tablets.py @@ -1,7 +1,40 @@ +from bisect import bisect_left +from operator import attrgetter +from random import getrandbits from threading import Lock from typing import Optional from uuid import UUID +# C-accelerated attrgetter avoids per-call lambda allocation overhead +_get_first_token = attrgetter("first_token") +_get_last_token = attrgetter("last_token") + + +def choose_tablet_version_block(tablet_version: int) -> int: + """ + Encode a tablet_version_block byte from a cached tablet_version. + Picks a block index at random across calls. + Returns an int in [0, 255]. + + The byte layout: the high nibble is the block index, the low nibble is the value + of that block. Blocks are indexed from the least significant bits to the most + significant ones, so block `idx` occupies bits [idx*4, idx*4 + 4). + """ + # Pick the block index in [0, 15]; getrandbits(4) is a fast C call with no + # application-level shared state. + idx = getrandbits(4) + # Extract the 4-bit nibble at block index `idx` (0 = least significant). + shift = idx * 4 + nibble = (tablet_version >> shift) & 0xF + return (idx << 4) | nibble + + +def random_tablet_version_block() -> int: + """ + Generate a random tablet_version_block byte for cold start. + """ + return getrandbits(8) + class Tablet(object): """ @@ -12,15 +45,19 @@ class Tablet(object): first_token = 0 last_token = 0 replicas = None + # uint64 hash; None means unknown -- a cold start, or a tablet learned over + # TABLETS_ROUTING_V1, which does not report a version. + tablet_version = None - def __init__(self, first_token=0, last_token=0, replicas=None): + def __init__(self, first_token=0, last_token=0, replicas=None, tablet_version=None): self.first_token = first_token self.last_token = last_token self.replicas = replicas + self.tablet_version = tablet_version def __str__(self): - return "" \ - % (self.first_token, self.last_token, self.replicas) + return "" \ + % (self.first_token, self.last_token, self.replicas, self.tablet_version) __repr__ = __str__ @staticmethod @@ -28,12 +65,44 @@ def _is_valid_tablet(replicas): return replicas is not None and len(replicas) != 0 @staticmethod - def from_row(first_token, last_token, replicas): + def from_row(first_token, last_token, replicas, tablet_version=None): if Tablet._is_valid_tablet(replicas): - tablet = Tablet(first_token, last_token, replicas) + if tablet_version is not None: + # tablet_version is an unsigned 64-bit value, but it is + # deserialized from the wire as a signed LongType; normalize it + # back to unsigned so it matches the server's representation. + tablet_version &= 0xFFFFFFFFFFFFFFFF + tablet = Tablet(first_token, last_token, replicas, tablet_version) return tablet return None + @property + def leader(self) -> Optional[UUID]: + """ + The ``host_id`` of this tablet's Raft leader, or ``None`` if there is + none to report. + + A strongly-consistent tablet has one distinguished replica, the leader, + that coordinates its writes and its linearizable reads. The server does + not name it in a separate field: ``TABLETS_ROUTING_V2`` orders the + replica set so that the leader comes first, which is why this is simply + ``replicas[0]``. + + That ordering only carries meaning for a tablet of a strongly-consistent + keyspace that was learned over V2. An eventually-consistent tablet has no + leader at all, and a tablet learned over ``TABLETS_ROUTING_V1`` -- which + reports no ``tablet_version``, so ``tablet_version`` is ``None`` -- has no + leader ordering either. Callers must establish both of those before + treating the result as a leader; this property only answers "which + replica is first, if any". + + Returns ``None`` for a tablet with no replicas rather than raising, so + callers do not have to guard the lookup themselves. + """ + if not self.replicas: + return None + return self.replicas[0][0] + def replica_contains_host_id(self, uuid: UUID) -> bool: for replica in self.replicas: if replica[0] == uuid: @@ -57,7 +126,7 @@ def get_tablet_for_key(self, keyspace, table, t): if not tablet: return None - id = bisect_left(tablet, t.value, key=lambda tablet: tablet.last_token) + id = bisect_left(tablet, t.value, key=_get_last_token) if id < len(tablet) and t.value > tablet[id].first_token: return tablet[id] return None @@ -94,12 +163,12 @@ def add_tablet(self, keyspace, table, tablet): tablets_for_table = self._tablets.setdefault((keyspace, table), []) # find first overlapping range - start = bisect_left(tablets_for_table, tablet.first_token, key=lambda t: t.first_token) + start = bisect_left(tablets_for_table, tablet.first_token, key=_get_first_token) if start > 0 and tablets_for_table[start - 1].last_token > tablet.first_token: start = start - 1 # find last overlapping range - end = bisect_left(tablets_for_table, tablet.last_token, key=lambda t: t.last_token) + end = bisect_left(tablets_for_table, tablet.last_token, key=_get_last_token) if end < len(tablets_for_table) and tablets_for_table[end].first_token >= tablet.last_token: end = end - 1 @@ -108,39 +177,3 @@ def add_tablet(self, keyspace, table, tablet): tablets_for_table.insert(start, tablet) - -# bisect.bisect_left implementation from Python 3.11, needed untill support for -# Python < 3.10 is dropped, it is needed to use `key` to extract last_token from -# Tablet list - better solution performance-wise than materialize list of last_tokens -def bisect_left(a, x, lo=0, hi=None, *, key=None): - """Return the index where to insert item x in list a, assuming a is sorted. - - The return value i is such that all e in a[:i] have e < x, and all e in - a[i:] have e >= x. So if x already appears in the list, a.insert(i, x) will - insert just before the leftmost x already there. - - Optional args lo (default 0) and hi (default len(a)) bound the - slice of a to be searched. - """ - - if lo < 0: - raise ValueError('lo must be non-negative') - if hi is None: - hi = len(a) - # Note, the comparison uses "<" to match the - # __lt__() logic in list.sort() and in heapq. - if key is None: - while lo < hi: - mid = (lo + hi) // 2 - if a[mid] < x: - lo = mid + 1 - else: - hi = mid - return - while lo < hi: - mid = (lo + hi) // 2 - if key(a[mid]) < x: - lo = mid + 1 - else: - hi = mid - return lo diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..733bc65597 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +# Track uv.lock for reproducible docs builds +!uv.lock diff --git a/docs/api/cassandra/cluster.rst b/docs/api/cassandra/cluster.rst index 51f03f3d97..44b7b63f67 100644 --- a/docs/api/cassandra/cluster.rst +++ b/docs/api/cassandra/cluster.rst @@ -48,6 +48,8 @@ Clusters and Sessions .. autoattribute:: control_connection_timeout + .. autoattribute:: allow_control_connection_query_fallback + .. autoattribute:: idle_heartbeat_interval .. autoattribute:: idle_heartbeat_timeout @@ -106,6 +108,9 @@ Clusters and Sessions .. automethod:: set_meta_refresh_enabled +.. autoclass:: ControlConnectionQueryFallback + :members: + .. autoclass:: ExecutionProfile (load_balancing_policy=, retry_policy=None, consistency_level=ConsistencyLevel.LOCAL_ONE, serial_consistency_level=None, request_timeout=10.0, row_factory=, speculative_execution_policy=None) :members: :exclude-members: consistency_level @@ -169,6 +174,8 @@ Clusters and Sessions .. automethod:: set_keyspace(keyspace) + .. automethod:: wait_for_schema_agreement + .. automethod:: get_execution_profile .. automethod:: execution_profile_clone_update diff --git a/docs/api/cassandra/protocol.rst b/docs/api/cassandra/protocol.rst index 8b8f303574..745011c01a 100644 --- a/docs/api/cassandra/protocol.rst +++ b/docs/api/cassandra/protocol.rst @@ -27,6 +27,11 @@ See :meth:`.Session.execute`, :meth:`.Session.execute_async`, :attr:`.ResponseFu .. automethod:: decode_message +.. note:: + Both contracted methods receive the ``ProtocolFeatures`` negotiated on the connection + carrying the message: ``decode_message`` positionally, ``encode_message`` as the required + ``protocol_features`` keyword argument (overrides must keep that parameter name). + .. _faster_deser: Faster Deserialization diff --git a/docs/conf.py b/docs/conf.py index 403908c29e..b43d2ca948 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,16 +29,17 @@ '3.29.6-scylla', '3.29.7-scylla', '3.29.8-scylla', + '3.29.11-scylla', ] BRANCHES = ['master'] # Set the latest version. -LATEST_VERSION = '3.29.8-scylla' +LATEST_VERSION = '3.29.11-scylla' # Set which versions are not released yet. UNSTABLE_VERSIONS = ['master'] # Set which versions are deprecated DEPRECATED_VERSIONS = ['3.21.0-scylla', '3.22.3-scylla', '3.24.8-scylla', '3.25.4-scylla', '3.25.11-scylla', '3.26.9-scylla', '3.28.1-scylla', '3.29.1-scylla'] -# -- General configuration +# -- General configuration # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. @@ -51,7 +52,7 @@ 'sphinx_sitemap', 'sphinx_scylladb_theme', 'sphinx_multiversion', # optional - 'recommonmark', # optional + 'myst_parser', # optional ] # Add any paths that contain templates here, relative to this directory. @@ -156,7 +157,7 @@ # Output file base name for HTML help builder. htmlhelp_basename = 'CassandraDriverdoc' -# URL which points to the root of the HTML documentation. +# URL which points to the root of the HTML documentation. html_baseurl = 'https://python-driver.docs.scylladb.com' # Dictionary of values to pass into the template engine’s context for all pages diff --git a/docs/installation.rst b/docs/installation.rst index 4207c46092..b3a79f2940 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -26,7 +26,7 @@ To check if the installation was successful, you can run:: python -c 'import cassandra; print(cassandra.__version__)' -It should print something like "3.29.8". +It should print something like "3.29.11". (*Optional*) Compression Support -------------------------------- @@ -62,9 +62,6 @@ threads used to build the driver and any C extensions: .. code-block:: bash - $ # installing from source - $ CASS_DRIVER_BUILD_CONCURRENCY=8 python setup.py install - $ # installing from pip $ CASS_DRIVER_BUILD_CONCURRENCY=8 pip install scylla-driver Note that by default (when CASS_DRIVER_BUILD_CONCURRENCY is not specified), concurrency will be equal to the number of @@ -108,7 +105,7 @@ installed. You can find the list of dependencies in Once the dependencies are installed, simply run:: - python setup.py install + pip install . (*Optional*) Non-python Dependencies @@ -122,9 +119,9 @@ for token-aware routing with the ``Murmur3Partitioner``, `libev `_ event loop integration, and Cython optimized extensions. -When installing manually through setup.py, you can disable both with -the ``--no-extensions`` option, or selectively disable them with -with ``--no-murmur3``, ``--no-libev``, or ``--no-cython``. +Extensions can be selectively disabled using environment variables: +``CASS_DRIVER_NO_EXTENSIONS=1`` (disable all), ``CASS_DRIVER_NO_CYTHON=1``, +or ``CASS_DRIVER_NO_LIBEV=1``. To compile the extensions, ensure that GCC and the Python headers are available. @@ -149,31 +146,25 @@ This is not a hard requirement, but is engaged by default to build extensions of pure Python implementation. This is a costly build phase, especially in clean environments where the Cython compiler must be built -This build phase can be avoided using the build switch, or an environment variable:: +This build phase can be avoided using an environment variable:: - python setup.py install --no-cython + CASS_DRIVER_NO_CYTHON=1 pip install scylla-driver -Alternatively, an environment variable can be used to switch this option regardless of +Alternatively, the environment variable can be used to switch this option regardless of context:: CASS_DRIVER_NO_CYTHON=1 - or, to disable all extensions: CASS_DRIVER_NO_EXTENSIONS=1 -This method is required when using pip, which provides no other way of injecting user options in a single command:: - - CASS_DRIVER_NO_CYTHON=1 pip install scylla-driver - CASS_DRIVER_NO_CYTHON=1 sudo -E pip install ~/python-driver - -The environment variable is the preferred option because it spans all invocations of setup.py, and will +These environment variables are the preferred option, and will prevent Cython from being materialized as a setup requirement. -If your sudo configuration does not allow SETENV, you must push the option flag down via pip. However, pip -applies these options to all dependencies (which break on the custom flag). Therefore, you must first install -dependencies, then use install-option:: +If your sudo configuration does not allow SETENV, you must first install +dependencies, then install the driver:: sudo pip install futures - sudo pip install --install-option="--no-cython" + sudo CASS_DRIVER_NO_CYTHON=1 pip install scylla-driver Supported Event Loops @@ -199,13 +190,13 @@ through `Homebrew `_. For example, on Mac OS X:: $ brew install libev -The libev extension can now be built for Windows as of Python driver version 3.29.8. You can +The libev extension can now be built for Windows as of Python driver version 3.29.11. You can install libev using any Windows package manager. For example, to install using `vcpkg `_: $ vcpkg install libev If successful, you should be able to build and install the extension -(just using ``setup.py build`` or ``setup.py install``) and then use +(just using ``pip install .``) and then use the libev event loop by doing the following: .. code-block:: python diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 59c425229a..f49bc3f520 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -11,13 +11,13 @@ dependencies = [ "gevent>=25.9.1,<26.0.0", "gremlinpython==3.7.4", "pygments>=2.19.2,<3.0.0", - "recommonmark==0.7.1", + "myst-parser>=5.0.0", "redirects_cli~=0.1.3", "sphinx-autobuild>=2025.0.0,<2026.0.0", "sphinx-sitemap>=2.8.0,<3.0.0", - "sphinx-scylladb-theme>=1.8.2,<2.0.0", + "sphinx-scylladb-theme>=1.9.3", "sphinx-multiversion-scylla>=0.3.2,<1.0.0", - "sphinx>=8.2.3,<9.0.0", + "sphinx>=9.0", "six>=1.9", "tornado>=6.5,<7.0", ] @@ -57,4 +57,4 @@ exclude = [ "**/__pycache__/**", "**/*.pyc", ".venv/**", -] \ No newline at end of file +] diff --git a/docs/scylla-specific.rst b/docs/scylla-specific.rst index e9fe695f8f..e7cb986b6d 100644 --- a/docs/scylla-specific.rst +++ b/docs/scylla-specific.rst @@ -91,7 +91,7 @@ New Error Types session = cluster.connect() session.execute(""" CREATE KEYSPACE IF NOT EXISTS keyspace1 - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'} """) session.execute("USE keyspace1") @@ -148,7 +148,7 @@ For more details on paging, see :ref:`query-paging`. Tablet Awareness ---------------- -**scylla-driver** is tablet-aware, which means that it is able to parse `TABLETS_ROUTING_V1` extension to ProtocolFeatures, recieve tablet information sent by Scylla in the `custom_payload` part of the `RESULT` message, and utilize it. +**scylla-driver** is tablet-aware, which means that it is able to parse the `TABLETS_ROUTING_V1` and `TABLETS_ROUTING_V2` extensions to ProtocolFeatures, receive tablet information sent by Scylla in the `custom_payload` part of the `RESULT` message, and utilize it. Thanks to this, queries to tablet-based tables are still shard-aware. Details on the scylla cql protocol extensions @@ -156,3 +156,137 @@ https://github.com/scylladb/scylladb/blob/master/docs/dev/protocol-extensions.md Details on the sending tablet information to the drivers https://github.com/scylladb/scylladb/blob/master/docs/dev/protocol-extensions.md#sending-tablet-info-to-the-drivers + + +Tablet version tracking and leader-aware routing +------------------------------------------------ + +When the cluster offers it, the driver negotiates ``TABLETS_ROUTING_V2`` in +preference to V1. The negotiation happens per connection, so V2 and V1 +connections can coexist in the same cluster; each connection uses whichever +extension its node offers. V2 adds two capabilities on top of V1, both +invisible to application code. + +**Tablet version tracking.** Every tablet now carries a ``tablet_version`` that +changes whenever its replica set or leader changes. The driver caches the version +it last saw for each tablet and, on every prepared-statement execution over a V2 +connection, appends a single ``tablet_version_block`` byte derived from it. The +server returns updated routing information in the ``custom_payload`` only when +that byte shows the driver's cached view is stale, instead of attaching it to +every response. This keeps the cached routing information fresh while avoiding +the per-response overhead that V1 incurs. + +**Leader-aware routing for strongly-consistent tables.** Tables in a +strongly-consistent keyspace -- one created with a ``consistency`` option and +backed by Raft -- have a tablet leader that coordinates operations. For those +tables, the driver sends each request directly to the leader, saving the extra +hop the coordinator would otherwise take to forward it. Reads with consistency +level ``ONE`` or ``LOCAL_ONE`` are an exception to this and retain normal +token-aware replica ordering. Eventually-consistent tables are completely +unaffected and keep their usual token-aware (optionally shuffled) replica +ordering. + +The distinction follows from how ScyllaDB serves each operation on a +strongly-consistent table: + +.. list-table:: + :header-rows: 1 + :widths: 15 25 60 + + * - Operation + - Consistency level + - How it is served + * - Read + - ``ONE``, ``LOCAL_ONE`` + - Non-linearizable: served by any replica, without taking a Raft read + barrier. There is nothing to gain from preferring the leader, so the + driver keeps normal token-aware ordering. + * - Read + - ``QUORUM``, ``LOCAL_QUORUM`` + - Linearizable: goes through the Raft leader, so the driver routes it to + the leader directly. + * - Write + - ``QUORUM``, ``LOCAL_QUORUM`` + - Committed through Raft by the leader, so the driver routes it to the + leader directly. + * - Write + - anything else + - Rejected by the server: strongly-consistent tables accept only + ``QUORUM`` and ``LOCAL_QUORUM`` writes. + +Leader-aware routing is best-effort and bounded by the load-balancing policy: +the leader is only targeted directly if the wrapped policy would consider it in +the first place. For example, a ``DCAwareRoundRobinPolicy`` configured with no +remote hosts will not send cross-datacenter traffic to a leader in another +datacenter; the request goes to a local replica and the server forwards it to +the leader, exactly as it would without V2. + +Within the hosts the wrapped policy allows, though, the leader does outrank +distance: it is yielded ahead of a nearer replica, since every write and every +linearizable read has to be coordinated by it anyway and a globally-consistent +table gains no consistency from staying in one datacenter. + +No configuration is required: as with V1, a ``TokenAwarePolicy`` is all that is +needed. Leader preference can be turned off per policy instance with its private +``_prefer_tablet_leader`` option, which leaves strongly-consistent tables with +plain token-aware ordering. The option is private and unstable while strong +consistency is experimental. + +.. note:: + + ``TABLETS_ROUTING_V2`` is still experimental: a Scylla node advertises it + (on the wire as ``TABLETS_ROUTING_V2_EXPERIMENTAL``) only when started with + the ``strongly-consistent-tables`` experimental feature enabled. A node + without it offers only ``TABLETS_ROUTING_V1``. + + +Prepared Statement Metadata Caching (``SCYLLA_USE_METADATA_ID``) +---------------------------------------------------------------- + +When the ``SCYLLA_USE_METADATA_ID`` extension is negotiated, the driver requests the +server to skip sending full result metadata with each prepared SELECT's EXECUTE +response (the ``skip_meta`` optimization), relying instead on the metadata cached +from the initial ``PREPARE`` call. Without change detection this would be unsafe: if +the table schema changes after a statement is prepared (e.g., a column is added, +removed, or its type is altered), the cached metadata becomes stale — leading to +decoding errors or incorrect data. + +ScyllaDB solves this by backporting the ``metadata_id`` mechanism from CQL native +protocol v5 as a v4 extension: ``SCYLLA_USE_METADATA_ID``. When this extension is +negotiated, the server includes a hash of the result metadata in the ``PREPARE`` +response. The driver sends this hash back with every ``EXECUTE`` request. If the +schema has changed, the server sets the ``METADATA_CHANGED`` flag and returns the +new metadata hash together with the updated column definitions. The driver +automatically updates its cache and uses the new metadata to decode the current +response — all transparently, with no application code change required. + +**Behaviour summary:** + +- Automatically negotiated at connection time when the ScyllaDB node supports it. +- ``skip_meta`` is enabled (metadata omitted from EXECUTE responses) only when it + is safe: the prepared statement must carry both a ``result_metadata_id`` and + usable cached result metadata from PREPARE, *and* the connection serving the + request must have negotiated ``SCYLLA_USE_METADATA_ID`` — decided per + connection when the request is serialized. +- Plain CQL v5 connections are unaffected: the metadata id is part of the native + v5 EXECUTE frame layout and is still sent, but the driver does not request + skip-metadata there, so such connections keep receiving full result metadata. +- When a schema change is detected by the server, the driver refreshes both the + cached column metadata and the metadata hash for that prepared statement so that + all subsequent executions benefit immediately. +- Statements prepared before the extension was negotiated (e.g., during a rolling + upgrade) start without a metadata hash, but acquire one automatically: on their + first execution over a connection with the extension, the driver sends an empty + hash, the server detects the mismatch and responds with the current hash and + full metadata, and the driver caches both. Subsequent executions get the + ``skip_meta`` optimization — no re-prepare or client restart is needed. + +**Current scope:** the optimization applies to any prepared statement that has +non-empty cached result columns — in practice, SELECT queries. +UPDATE/INSERT/DELETE statements naturally return no result columns, so +their ``result_metadata`` is always empty and ``skip_meta`` is never set for +them. There is no code-level restriction to SELECT; the behaviour follows +directly from the data. + +For full protocol details see the ScyllaDB CQL protocol extensions documentation: +https://github.com/scylladb/scylladb/blob/master/docs/dev/protocol-extensions.md diff --git a/docs/uv.lock b/docs/uv.lock index d6b5359d21..16e14fdd51 100644 --- a/docs/uv.lock +++ b/docs/uv.lock @@ -4,11 +4,11 @@ requires-python = "==3.13.*" [[package]] name = "aenum" -version = "3.1.16" +version = "3.1.17" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/09/7a/61ed58e8be9e30c3fe518899cc78c284896d246d51381bab59b5db11e1f3/aenum-3.1.16.tar.gz", hash = "sha256:bfaf9589bdb418ee3a986d85750c7318d9d2839c1b1a1d6fe8fc53ec201cf140", size = 137693, upload-time = "2026-01-12T22:34:38.819Z" } +sdist = { url = "https://files.pythonhosted.org/packages/07/e9/8b283567c1fef7c24d1f390b37daede8b61593d8cdaffb8e95d571699e83/aenum-3.1.17.tar.gz", hash = "sha256:a969a4516b194895de72c875ece355f17c0d272146f7fda346ef74f93cf4d5ba", size = 137648, upload-time = "2026-03-20T20:43:29.846Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/e3/52/6ad8f63ec8da1bf40f96996d25d5b650fdd38f5975f8c813732c47388f18/aenum-3.1.16-py3-none-any.whl", hash = "sha256:9035092855a98e41b66e3d0998bd7b96280e85ceb3a04cc035636138a1943eaf", size = 165627, upload-time = "2025-04-25T03:17:58.89Z" }, + { url = "https://files.pythonhosted.org/packages/48/8d/1fe30c6fd8999b9d462547c4a1bb6690bda24af38f2913c4bec7decb81f2/aenum-3.1.17-py3-none-any.whl", hash = "sha256:8b883a37a04e74cc838ac442bdd28c266eae5bbf13e1342c7ef123ed25230139", size = 165560, upload-time = "2026-03-20T20:43:27.681Z" }, ] [[package]] @@ -22,7 +22,7 @@ wheels = [ [[package]] name = "aiohttp" -version = "3.13.3" +version = "3.14.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "aiohappyeyeballs" }, @@ -33,25 +33,31 @@ dependencies = [ { name = "propcache" }, { name = "yarl" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/50/42/32cf8e7704ceb4481406eb87161349abb46a57fee3f008ba9cb610968646/aiohttp-3.13.3.tar.gz", hash = "sha256:a949eee43d3782f2daae4f4a2819b2cb9b0c5d3b7f7a927067cc84dafdbb9f88", size = 7844556, upload-time = "2026-01-03T17:33:05.204Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/97/8a/12ca489246ca1faaf5432844adbfce7ff2cc4997733e0af120869345643a/aiohttp-3.13.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:5dff64413671b0d3e7d5918ea490bdccb97a4ad29b3f311ed423200b2203e01c", size = 734190, upload-time = "2026-01-03T17:30:45.832Z" }, - { url = "https://files.pythonhosted.org/packages/32/08/de43984c74ed1fca5c014808963cc83cb00d7bb06af228f132d33862ca76/aiohttp-3.13.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:87b9aab6d6ed88235aa2970294f496ff1a1f9adcd724d800e9b952395a80ffd9", size = 491783, upload-time = "2026-01-03T17:30:47.466Z" }, - { url = "https://files.pythonhosted.org/packages/17/f8/8dd2cf6112a5a76f81f81a5130c57ca829d101ad583ce57f889179accdda/aiohttp-3.13.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:425c126c0dc43861e22cb1c14ba4c8e45d09516d0a3ae0a3f7494b79f5f233a3", size = 490704, upload-time = "2026-01-03T17:30:49.373Z" }, - { url = "https://files.pythonhosted.org/packages/6d/40/a46b03ca03936f832bc7eaa47cfbb1ad012ba1be4790122ee4f4f8cba074/aiohttp-3.13.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7f9120f7093c2a32d9647abcaf21e6ad275b4fbec5b55969f978b1a97c7c86bf", size = 1720652, upload-time = "2026-01-03T17:30:50.974Z" }, - { url = "https://files.pythonhosted.org/packages/f7/7e/917fe18e3607af92657e4285498f500dca797ff8c918bd7d90b05abf6c2a/aiohttp-3.13.3-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:697753042d57f4bf7122cab985bf15d0cef23c770864580f5af4f52023a56bd6", size = 1692014, upload-time = "2026-01-03T17:30:52.729Z" }, - { url = "https://files.pythonhosted.org/packages/71/b6/cefa4cbc00d315d68973b671cf105b21a609c12b82d52e5d0c9ae61d2a09/aiohttp-3.13.3-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6de499a1a44e7de70735d0b39f67c8f25eb3d91eb3103be99ca0fa882cdd987d", size = 1759777, upload-time = "2026-01-03T17:30:54.537Z" }, - { url = "https://files.pythonhosted.org/packages/fb/e3/e06ee07b45e59e6d81498b591fc589629be1553abb2a82ce33efe2a7b068/aiohttp-3.13.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:37239e9f9a7ea9ac5bf6b92b0260b01f8a22281996da609206a84df860bc1261", size = 1861276, upload-time = "2026-01-03T17:30:56.512Z" }, - { url = "https://files.pythonhosted.org/packages/7c/24/75d274228acf35ceeb2850b8ce04de9dd7355ff7a0b49d607ee60c29c518/aiohttp-3.13.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f76c1e3fe7d7c8afad7ed193f89a292e1999608170dcc9751a7462a87dfd5bc0", size = 1743131, upload-time = "2026-01-03T17:30:58.256Z" }, - { url = "https://files.pythonhosted.org/packages/04/98/3d21dde21889b17ca2eea54fdcff21b27b93f45b7bb94ca029c31ab59dc3/aiohttp-3.13.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fc290605db2a917f6e81b0e1e0796469871f5af381ce15c604a3c5c7e51cb730", size = 1556863, upload-time = "2026-01-03T17:31:00.445Z" }, - { url = "https://files.pythonhosted.org/packages/9e/84/da0c3ab1192eaf64782b03971ab4055b475d0db07b17eff925e8c93b3aa5/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:4021b51936308aeea0367b8f006dc999ca02bc118a0cc78c303f50a2ff6afb91", size = 1682793, upload-time = "2026-01-03T17:31:03.024Z" }, - { url = "https://files.pythonhosted.org/packages/ff/0f/5802ada182f575afa02cbd0ec5180d7e13a402afb7c2c03a9aa5e5d49060/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:49a03727c1bba9a97d3e93c9f93ca03a57300f484b6e935463099841261195d3", size = 1716676, upload-time = "2026-01-03T17:31:04.842Z" }, - { url = "https://files.pythonhosted.org/packages/3f/8c/714d53bd8b5a4560667f7bbbb06b20c2382f9c7847d198370ec6526af39c/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:3d9908a48eb7416dc1f4524e69f1d32e5d90e3981e4e37eb0aa1cd18f9cfa2a4", size = 1733217, upload-time = "2026-01-03T17:31:06.868Z" }, - { url = "https://files.pythonhosted.org/packages/7d/79/e2176f46d2e963facea939f5be2d26368ce543622be6f00a12844d3c991f/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2712039939ec963c237286113c68dbad80a82a4281543f3abf766d9d73228998", size = 1552303, upload-time = "2026-01-03T17:31:08.958Z" }, - { url = "https://files.pythonhosted.org/packages/ab/6a/28ed4dea1759916090587d1fe57087b03e6c784a642b85ef48217b0277ae/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:7bfdc049127717581866fa4708791220970ce291c23e28ccf3922c700740fdc0", size = 1763673, upload-time = "2026-01-03T17:31:10.676Z" }, - { url = "https://files.pythonhosted.org/packages/e8/35/4a3daeb8b9fab49240d21c04d50732313295e4bd813a465d840236dd0ce1/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8057c98e0c8472d8846b9c79f56766bcc57e3e8ac7bfd510482332366c56c591", size = 1721120, upload-time = "2026-01-03T17:31:12.575Z" }, - { url = "https://files.pythonhosted.org/packages/bc/9f/d643bb3c5fb99547323e635e251c609fbbc660d983144cfebec529e09264/aiohttp-3.13.3-cp313-cp313-win32.whl", hash = "sha256:1449ceddcdbcf2e0446957863af03ebaaa03f94c090f945411b61269e2cb5daf", size = 427383, upload-time = "2026-01-03T17:31:14.382Z" }, - { url = "https://files.pythonhosted.org/packages/4e/f1/ab0395f8a79933577cdd996dd2f9aa6014af9535f65dddcf88204682fe62/aiohttp-3.13.3-cp313-cp313-win_amd64.whl", hash = "sha256:693781c45a4033d31d4187d2436f5ac701e7bbfe5df40d917736108c1cc7436e", size = 453899, upload-time = "2026-01-03T17:31:15.958Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/82/78/8ea7308cac6934de8c74a14f3d5f65d1c89287426688be79538d0e5c013d/aiohttp-3.14.1.tar.gz", hash = "sha256:307f2cff90a764d329e77040603fa032db89c5c24fdad50c4c15334cba744035", size = 7955794, upload-time = "2026-06-07T21:09:35.529Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/bc/97/bd137012dd97e1649162b099135a80e1fd59aaa807b2430fc448d1029aff/aiohttp-3.14.1-cp313-cp313-android_21_arm64_v8a.whl", hash = "sha256:b3a03285a7f9c7b016324574a6d92a1c895da6b978cb8f1deee3ac72bc6da178", size = 506882, upload-time = "2026-06-07T21:07:15.501Z" }, + { url = "https://files.pythonhosted.org/packages/ef/79/e5cc690e9d922a66887ceeaca53a8ffd5a7b0be3816142b7abc433742d89/aiohttp-3.14.1-cp313-cp313-android_21_x86_64.whl", hash = "sha256:2a73f487ab8ef5abbb24b7aa9b73e98eaba9e9e031804ff2416f02eca315ccaf", size = 515270, upload-time = "2026-06-07T21:07:17.53Z" }, + { url = "https://files.pythonhosted.org/packages/fe/22/a73ccbf9dbd6e26dda0b24d5fd5db7da92ee3383a79f47677ffb834c5c5b/aiohttp-3.14.1-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:915fbb7b41b115192259f8c9ae58f3ddc444d2b5579917270211858e606a4afd", size = 485841, upload-time = "2026-06-07T21:07:19.555Z" }, + { url = "https://files.pythonhosted.org/packages/3b/b9/57ed8eaf596321c2ad747bd480fb1700dbd7177c60dfc9e4c187f629662e/aiohttp-3.14.1-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:7fb4bdf95b0561a79f259f9d28fbc109728c5ee7f27aff6391f0ca703a329abe", size = 492088, upload-time = "2026-06-07T21:07:21.581Z" }, + { url = "https://files.pythonhosted.org/packages/78/c0/5ebe5270a7c140d7c6f79dcb018640225f14d406c149e4eec04a7d82fe71/aiohttp-3.14.1-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:1b9748363260121d2927704f5d4fc498150669ca3ae93625986ee89c8f80dcd4", size = 501564, upload-time = "2026-06-07T21:07:23.388Z" }, + { url = "https://files.pythonhosted.org/packages/75/7f/8cdaa24fc7983865e0915153b96a9ac5bcdd3548d64c5a27d17cecccad2d/aiohttp-3.14.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:86a6dab78b0e43e2897a3bbe15745aa60dc5423ca437b7b0b164c069bf91b876", size = 751998, upload-time = "2026-06-07T21:07:25.046Z" }, + { url = "https://files.pythonhosted.org/packages/b2/f4/c4227aacfacc5cb0cc2d119b65301d177912a6842cd64e120c47af76064f/aiohttp-3.14.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:4dfd6e47d3c44c2279907607f73a4240b88c69eb8b90da7e2441a8045dfd21da", size = 510918, upload-time = "2026-06-07T21:07:27.28Z" }, + { url = "https://files.pythonhosted.org/packages/ab/01/a2d5f96cd4e74424864d30bc0a7e44d0a12dacdcfa91b5b2d1bd3dca6bf3/aiohttp-3.14.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:317acd9f8602858dc7d59679812c376c7f0b97bcbbf16e0d6237f54141d8a8a6", size = 508657, upload-time = "2026-06-07T21:07:29.252Z" }, + { url = "https://files.pythonhosted.org/packages/e8/ed/3c0fb5c500fdd8e7ebc10d1889c04384fffa1a9163eac1356088ca9da1b1/aiohttp-3.14.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:bd869c427324e5cb15195793de951295710db28be7d818247f3097b4ab5d4b96", size = 1757907, upload-time = "2026-06-07T21:07:31.03Z" }, + { url = "https://files.pythonhosted.org/packages/0b/ab/d4c924d9bd5be3050c226612413ce68cb54c70d2c31b661bfc8d9a5b6a70/aiohttp-3.14.1-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:93b032b5ec3255473c143627d21a69ac74ae12f7f33974cb587c564d11b1066f", size = 1737565, upload-time = "2026-06-07T21:07:33.031Z" }, + { url = "https://files.pythonhosted.org/packages/19/2a/37326821ff779084020cdc33224d20b19f42f4183a500ff92022a739eda7/aiohttp-3.14.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f234b4deb12f3ad59127e037bc57c40c21e45b45282df7d3a55a0f409f595296", size = 1799018, upload-time = "2026-06-07T21:07:35.003Z" }, + { url = "https://files.pythonhosted.org/packages/b3/4f/6e947ba73e4ce09070761c05ed3a8ceb7c21f5e46798671d8b2aac0e4626/aiohttp-3.14.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:9af6779bfb46abf124068327abcdf9ce95c9ef8287a3e8da76ccf2d0f16c28fa", size = 1894416, upload-time = "2026-06-07T21:07:36.956Z" }, + { url = "https://files.pythonhosted.org/packages/9d/6e/dbf1d0625dc711fb2851f4f3c3055c39ed58bae92082d8c627dbe6013736/aiohttp-3.14.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:faccab372e66bc76d5731525e7f1143c922271725b9d38c9f97edcc66266b451", size = 1783881, upload-time = "2026-06-07T21:07:39.063Z" }, + { url = "https://files.pythonhosted.org/packages/44/c2/5e25098a67268ed369483ae7d1a58bd0a13d03aab860d2a0e4a6eb25b046/aiohttp-3.14.1-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f380468b09d2a81633ee863b0ec5648d364bd17bb8ecfb8c2f387f7ac1faf42c", size = 1587572, upload-time = "2026-06-07T21:07:41.058Z" }, + { url = "https://files.pythonhosted.org/packages/2a/bd/cf9cee17e140f942a3de73e658a543aa8fbf35a5fc67a9d2538d52d77f0b/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:97e704dcd26271f5bda3fa07c3ce0fb76d6d3f8659f4baa1a24442cc9ba177ca", size = 1722137, upload-time = "2026-06-07T21:07:43.014Z" }, + { url = "https://files.pythonhosted.org/packages/89/6d/5684f8c59045c96f81a18cefbc1fbbd79d25b88f1c622f2a5c5c08fcb632/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:269b76ac5394092b95bc4a098f4fc6c191c083c3bd12775d1e30e663132f6a09", size = 1755953, upload-time = "2026-06-07T21:07:45.933Z" }, + { url = "https://files.pythonhosted.org/packages/a8/40/35caf3170f8359760740a7d9aa0fff2e344bef98e1d1186f5a0f6dec17e6/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:5c0b3e614340c889d575451696374c9d17affd54cd607ca0babed8f8c37b9397", size = 1766479, upload-time = "2026-06-07T21:07:48.047Z" }, + { url = "https://files.pythonhosted.org/packages/6d/a1/b0c61e7a137f0d81de49a82023a6df73c3c16d6fefb0f8e4a93d21639002/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:5663ee9257cfa1add7253a7da3035a02f31b6600ec48261585e1800a81533080", size = 1580077, upload-time = "2026-06-07T21:07:50.069Z" }, + { url = "https://files.pythonhosted.org/packages/0b/41/194ea4623693009fcefebef7aef63c141754f153e9cd0d39d3b9e36c175c/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:603a2c834142172ffddc054067f5ec0ca65d57a0aa98a71bc81952573208e345", size = 1791688, upload-time = "2026-06-07T21:07:52.106Z" }, + { url = "https://files.pythonhosted.org/packages/ba/45/4de841f005cfe1fd63e2a2fe011262c515e2a62aa6994b15947e7d717ac9/aiohttp-3.14.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:cb21957bb8aca671c1765e32f58164cf0c50e6bf41c0bbbd16da20732ecaf588", size = 1761094, upload-time = "2026-06-07T21:07:54.113Z" }, + { url = "https://files.pythonhosted.org/packages/e4/ae/dbce10533d3896d544d5053939ed75b7dc31a1b0973d959b1b5ae21028d6/aiohttp-3.14.1-cp313-cp313-win32.whl", hash = "sha256:e509a55f681e6158c20f70f102f9cf61fb20fbc382272bc6d94b7343f2582780", size = 452662, upload-time = "2026-06-07T21:07:56.06Z" }, + { url = "https://files.pythonhosted.org/packages/7b/d9/0bf1a19362c32f06229da5e7ddfcec91f93474d6307f7a2d3135e9c674dc/aiohttp-3.14.1-cp313-cp313-win_amd64.whl", hash = "sha256:1ac8531b638959718e18c2207fbfe297819875da46a740b29dfa29beba64355a", size = 479748, upload-time = "2026-06-07T21:07:58.319Z" }, + { url = "https://files.pythonhosted.org/packages/22/0a/62e7232dc9484fbec112ceb32efb6a624cc7994ec6e2b019286f17c4e8f2/aiohttp-3.14.1-cp313-cp313-win_arm64.whl", hash = "sha256:250d14af67f6b6a1a4a811049b1afa69d61d617fca6bf33149b3ab1a6dbcf7b8", size = 447723, upload-time = "2026-06-07T21:08:00.154Z" }, ] [[package]] @@ -75,16 +81,25 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/7e/b3/6b4067be973ae96ba0d615946e314c5ae35f9f993eca561b356540bb0c2b/alabaster-1.0.0-py3-none-any.whl", hash = "sha256:fc6786402dc3fcb2de3cabd5fe455a2db534b371124f1f21de8731783dec828b", size = 13929, upload-time = "2024-07-26T18:15:02.05Z" }, ] +[[package]] +name = "annotated-doc" +version = "0.0.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" }, +] + [[package]] name = "anyio" -version = "4.12.0" +version = "4.13.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "idna" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/16/ce/8a777047513153587e5434fd752e89334ac33e379aa3497db860eeb60377/anyio-4.12.0.tar.gz", hash = "sha256:73c693b567b0c55130c104d0b43a9baf3aa6a31fc6110116509f27bf75e21ec0", size = 228266, upload-time = "2025-11-28T23:37:38.911Z" } +sdist = { url = "https://files.pythonhosted.org/packages/19/14/2c5dd9f512b66549ae92767a9c7b330ae88e1932ca57876909410251fe13/anyio-4.13.0.tar.gz", hash = "sha256:334b70e641fd2221c1505b3890c69882fe4a2df910cba14d97019b90b24439dc", size = 231622, upload-time = "2026-03-24T12:59:09.671Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/7f/9c/36c5c37947ebfb8c7f22e0eb6e4d188ee2d53aa3880f3f2744fb894f0cb1/anyio-4.12.0-py3-none-any.whl", hash = "sha256:dad2376a628f98eeca4881fc56cd06affd18f659b17a747d3ff0307ced94b1bb", size = 113362, upload-time = "2025-11-28T23:36:57.897Z" }, + { url = "https://files.pythonhosted.org/packages/da/42/e921fccf5015463e32a3cf6ee7f980a6ed0f395ceeaa45060b61d86486c2/anyio-4.13.0-py3-none-any.whl", hash = "sha256:08b310f9e24a9594186fd75b4f73f4a4152069e3853f1ed8bfbf58369f4ad708", size = 114353, upload-time = "2026-03-24T12:59:08.246Z" }, ] [[package]] @@ -98,29 +113,29 @@ wheels = [ [[package]] name = "attrs" -version = "25.4.0" +version = "26.1.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/6b/5c/685e6633917e101e5dcb62b9dd76946cbb57c26e133bae9e0cd36033c0a9/attrs-25.4.0.tar.gz", hash = "sha256:16d5969b87f0859ef33a48b35d55ac1be6e42ae49d5e853b597db70c35c57e11", size = 934251, upload-time = "2025-10-06T13:54:44.725Z" } +sdist = { url = "https://files.pythonhosted.org/packages/9a/8e/82a0fe20a541c03148528be8cac2408564a6c9a0cc7e9171802bc1d26985/attrs-26.1.0.tar.gz", hash = "sha256:d03ceb89cb322a8fd706d4fb91940737b6642aa36998fe130a9bc96c985eff32", size = 952055, upload-time = "2026-03-19T14:22:25.026Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/3a/2a/7cc015f5b9f5db42b7d48157e23356022889fc354a2813c15934b7cb5c0e/attrs-25.4.0-py3-none-any.whl", hash = "sha256:adcf7e2a1fb3b36ac48d97835bb6d8ade15b8dcce26aba8bf1d14847b57a3373", size = 67615, upload-time = "2025-10-06T13:54:43.17Z" }, + { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" }, ] [[package]] name = "babel" -version = "2.17.0" +version = "2.18.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/7d/6b/d52e42361e1aa00709585ecc30b3f9684b3ab62530771402248b1b1d6240/babel-2.17.0.tar.gz", hash = "sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d", size = 9951852, upload-time = "2025-02-01T15:17:41.026Z" } +sdist = { url = "https://files.pythonhosted.org/packages/7d/b2/51899539b6ceeeb420d40ed3cd4b7a40519404f9baf3d4ac99dc413a834b/babel-2.18.0.tar.gz", hash = "sha256:b80b99a14bd085fcacfa15c9165f651fbb3406e66cc603abf11c5750937c992d", size = 9959554, upload-time = "2026-02-01T12:30:56.078Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537, upload-time = "2025-02-01T15:17:37.39Z" }, + { url = "https://files.pythonhosted.org/packages/77/f5/21d2de20e8b8b0408f0681956ca2c69f1320a3848ac50e6e7f39c6159675/babel-2.18.0-py3-none-any.whl", hash = "sha256:e2b422b277c2b9a9630c1d7903c2a00d0830c409c59ac8cae9081c92f1aeba35", size = 10196845, upload-time = "2026-02-01T12:30:53.445Z" }, ] [[package]] name = "beartype" -version = "0.22.8" +version = "0.22.9" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/8c/1d/794ae2acaa67c8b216d91d5919da2606c2bb14086849ffde7f5555f3a3a5/beartype-0.22.8.tar.gz", hash = "sha256:b19b21c9359722ee3f7cc433f063b3e13997b27ae8226551ea5062e621f61165", size = 1602262, upload-time = "2025-12-03T05:11:10.766Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c7/94/1009e248bbfbab11397abca7193bea6626806be9a327d399810d523a07cb/beartype-0.22.9.tar.gz", hash = "sha256:8f82b54aa723a2848a56008d18875f91c1db02c32ef6a62319a002e3e25a975f", size = 1608866, upload-time = "2025-12-13T06:50:30.72Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/14/2a/fbcbf5a025d3e71ddafad7efd43e34ec4362f4d523c3c471b457148fb211/beartype-0.22.8-py3-none-any.whl", hash = "sha256:b832882d04e41a4097bab9f63e6992bc6de58c414ee84cba9b45b67314f5ab2e", size = 1331895, upload-time = "2025-12-03T05:11:08.373Z" }, + { url = "https://files.pythonhosted.org/packages/71/cc/18245721fa7747065ab478316c7fea7c74777d07f37ae60db2e84f8172e8/beartype-0.22.9-py3-none-any.whl", hash = "sha256:d16c9bbc61ea14637596c5f6fbff2ee99cbe3573e46a716401734ef50c3060c2", size = 1333658, upload-time = "2025-12-13T06:50:28.266Z" }, ] [[package]] @@ -138,11 +153,11 @@ wheels = [ [[package]] name = "certifi" -version = "2025.11.12" +version = "2026.2.25" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/a2/8c/58f469717fa48465e4a50c014a0400602d3c437d7c0c468e17ada824da3a/certifi-2025.11.12.tar.gz", hash = "sha256:d8ab5478f2ecd78af242878415affce761ca6bc54a22a27e026d7c25357c3316", size = 160538, upload-time = "2025-11-12T02:54:51.517Z" } +sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/70/7d/9bc192684cea499815ff478dfcdc13835ddf401365057044fb721ec6bddb/certifi-2025.11.12-py3-none-any.whl", hash = "sha256:97de8790030bbd5c2d96b7ec782fc2f7820ef8dba6db909ccf95449f2d062d4b", size = 159438, upload-time = "2025-11-12T02:54:49.735Z" }, + { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" }, ] [[package]] @@ -161,39 +176,39 @@ wheels = [ [[package]] name = "charset-normalizer" -version = "3.4.4" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/13/69/33ddede1939fdd074bce5434295f38fae7136463422fe4fd3e0e89b98062/charset_normalizer-3.4.4.tar.gz", hash = "sha256:94537985111c35f28720e43603b8e7b43a6ecfb2ce1d3058bbe955b73404e21a", size = 129418, upload-time = "2025-10-14T04:42:32.879Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/97/45/4b3a1239bbacd321068ea6e7ac28875b03ab8bc0aa0966452db17cd36714/charset_normalizer-3.4.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e1f185f86a6f3403aa2420e815904c67b2f9ebc443f045edd0de921108345794", size = 208091, upload-time = "2025-10-14T04:41:13.346Z" }, - { url = "https://files.pythonhosted.org/packages/7d/62/73a6d7450829655a35bb88a88fca7d736f9882a27eacdca2c6d505b57e2e/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6b39f987ae8ccdf0d2642338faf2abb1862340facc796048b604ef14919e55ed", size = 147936, upload-time = "2025-10-14T04:41:14.461Z" }, - { url = "https://files.pythonhosted.org/packages/89/c5/adb8c8b3d6625bef6d88b251bbb0d95f8205831b987631ab0c8bb5d937c2/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3162d5d8ce1bb98dd51af660f2121c55d0fa541b46dff7bb9b9f86ea1d87de72", size = 144180, upload-time = "2025-10-14T04:41:15.588Z" }, - { url = "https://files.pythonhosted.org/packages/91/ed/9706e4070682d1cc219050b6048bfd293ccf67b3d4f5a4f39207453d4b99/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:81d5eb2a312700f4ecaa977a8235b634ce853200e828fbadf3a9c50bab278328", size = 161346, upload-time = "2025-10-14T04:41:16.738Z" }, - { url = "https://files.pythonhosted.org/packages/d5/0d/031f0d95e4972901a2f6f09ef055751805ff541511dc1252ba3ca1f80cf5/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5bd2293095d766545ec1a8f612559f6b40abc0eb18bb2f5d1171872d34036ede", size = 158874, upload-time = "2025-10-14T04:41:17.923Z" }, - { url = "https://files.pythonhosted.org/packages/f5/83/6ab5883f57c9c801ce5e5677242328aa45592be8a00644310a008d04f922/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a8a8b89589086a25749f471e6a900d3f662d1d3b6e2e59dcecf787b1cc3a1894", size = 153076, upload-time = "2025-10-14T04:41:19.106Z" }, - { url = "https://files.pythonhosted.org/packages/75/1e/5ff781ddf5260e387d6419959ee89ef13878229732732ee73cdae01800f2/charset_normalizer-3.4.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:bc7637e2f80d8530ee4a78e878bce464f70087ce73cf7c1caf142416923b98f1", size = 150601, upload-time = "2025-10-14T04:41:20.245Z" }, - { url = "https://files.pythonhosted.org/packages/d7/57/71be810965493d3510a6ca79b90c19e48696fb1ff964da319334b12677f0/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f8bf04158c6b607d747e93949aa60618b61312fe647a6369f88ce2ff16043490", size = 150376, upload-time = "2025-10-14T04:41:21.398Z" }, - { url = "https://files.pythonhosted.org/packages/e5/d5/c3d057a78c181d007014feb7e9f2e65905a6c4ef182c0ddf0de2924edd65/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:554af85e960429cf30784dd47447d5125aaa3b99a6f0683589dbd27e2f45da44", size = 144825, upload-time = "2025-10-14T04:41:22.583Z" }, - { url = "https://files.pythonhosted.org/packages/e6/8c/d0406294828d4976f275ffbe66f00266c4b3136b7506941d87c00cab5272/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:74018750915ee7ad843a774364e13a3db91682f26142baddf775342c3f5b1133", size = 162583, upload-time = "2025-10-14T04:41:23.754Z" }, - { url = "https://files.pythonhosted.org/packages/d7/24/e2aa1f18c8f15c4c0e932d9287b8609dd30ad56dbe41d926bd846e22fb8d/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:c0463276121fdee9c49b98908b3a89c39be45d86d1dbaa22957e38f6321d4ce3", size = 150366, upload-time = "2025-10-14T04:41:25.27Z" }, - { url = "https://files.pythonhosted.org/packages/e4/5b/1e6160c7739aad1e2df054300cc618b06bf784a7a164b0f238360721ab86/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:362d61fd13843997c1c446760ef36f240cf81d3ebf74ac62652aebaf7838561e", size = 160300, upload-time = "2025-10-14T04:41:26.725Z" }, - { url = "https://files.pythonhosted.org/packages/7a/10/f882167cd207fbdd743e55534d5d9620e095089d176d55cb22d5322f2afd/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9a26f18905b8dd5d685d6d07b0cdf98a79f3c7a918906af7cc143ea2e164c8bc", size = 154465, upload-time = "2025-10-14T04:41:28.322Z" }, - { url = "https://files.pythonhosted.org/packages/89/66/c7a9e1b7429be72123441bfdbaf2bc13faab3f90b933f664db506dea5915/charset_normalizer-3.4.4-cp313-cp313-win32.whl", hash = "sha256:9b35f4c90079ff2e2edc5b26c0c77925e5d2d255c42c74fdb70fb49b172726ac", size = 99404, upload-time = "2025-10-14T04:41:29.95Z" }, - { url = "https://files.pythonhosted.org/packages/c4/26/b9924fa27db384bdcd97ab83b4f0a8058d96ad9626ead570674d5e737d90/charset_normalizer-3.4.4-cp313-cp313-win_amd64.whl", hash = "sha256:b435cba5f4f750aa6c0a0d92c541fb79f69a387c91e61f1795227e4ed9cece14", size = 107092, upload-time = "2025-10-14T04:41:31.188Z" }, - { url = "https://files.pythonhosted.org/packages/af/8f/3ed4bfa0c0c72a7ca17f0380cd9e4dd842b09f664e780c13cff1dcf2ef1b/charset_normalizer-3.4.4-cp313-cp313-win_arm64.whl", hash = "sha256:542d2cee80be6f80247095cc36c418f7bddd14f4a6de45af91dfad36d817bba2", size = 100408, upload-time = "2025-10-14T04:41:32.624Z" }, - { url = "https://files.pythonhosted.org/packages/0a/4c/925909008ed5a988ccbb72dcc897407e5d6d3bd72410d69e051fc0c14647/charset_normalizer-3.4.4-py3-none-any.whl", hash = "sha256:7a32c560861a02ff789ad905a2fe94e3f840803362c84fecf1851cb4cf3dc37f", size = 53402, upload-time = "2025-10-14T04:42:31.76Z" }, +version = "3.4.7" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e7/a1/67fe25fac3c7642725500a3f6cfe5821ad557c3abb11c9d20d12c7008d3e/charset_normalizer-3.4.7.tar.gz", hash = "sha256:ae89db9e5f98a11a4bf50407d4363e7b09b31e55bc117b4f7d80aab97ba009e5", size = 144271, upload-time = "2026-04-02T09:28:39.342Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c1/3b/66777e39d3ae1ddc77ee606be4ec6d8cbd4c801f65e5a1b6f2b11b8346dd/charset_normalizer-3.4.7-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:f496c9c3cc02230093d8330875c4c3cdfc3b73612a5fd921c65d39cbcef08063", size = 309627, upload-time = "2026-04-02T09:26:45.198Z" }, + { url = "https://files.pythonhosted.org/packages/2e/4e/b7f84e617b4854ade48a1b7915c8ccfadeba444d2a18c291f696e37f0d3b/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ea948db76d31190bf08bd371623927ee1339d5f2a0b4b1b4a4439a65298703c", size = 207008, upload-time = "2026-04-02T09:26:46.824Z" }, + { url = "https://files.pythonhosted.org/packages/c4/bb/ec73c0257c9e11b268f018f068f5d00aa0ef8c8b09f7753ebd5f2880e248/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a277ab8928b9f299723bc1a2dabb1265911b1a76341f90a510368ca44ad9ab66", size = 228303, upload-time = "2026-04-02T09:26:48.397Z" }, + { url = "https://files.pythonhosted.org/packages/85/fb/32d1f5033484494619f701e719429c69b766bfc4dbc61aa9e9c8c166528b/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3bec022aec2c514d9cf199522a802bd007cd588ab17ab2525f20f9c34d067c18", size = 224282, upload-time = "2026-04-02T09:26:49.684Z" }, + { url = "https://files.pythonhosted.org/packages/fa/07/330e3a0dda4c404d6da83b327270906e9654a24f6c546dc886a0eb0ffb23/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e044c39e41b92c845bc815e5ae4230804e8e7bc29e399b0437d64222d92809dd", size = 215595, upload-time = "2026-04-02T09:26:50.915Z" }, + { url = "https://files.pythonhosted.org/packages/e3/7c/fc890655786e423f02556e0216d4b8c6bcb6bdfa890160dc66bf52dee468/charset_normalizer-3.4.7-cp313-cp313-manylinux_2_31_armv7l.whl", hash = "sha256:f495a1652cf3fbab2eb0639776dad966c2fb874d79d87ca07f9d5f059b8bd215", size = 201986, upload-time = "2026-04-02T09:26:52.197Z" }, + { url = "https://files.pythonhosted.org/packages/d8/97/bfb18b3db2aed3b90cf54dc292ad79fdd5ad65c4eae454099475cbeadd0d/charset_normalizer-3.4.7-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e712b419df8ba5e42b226c510472b37bd57b38e897d3eca5e8cfd410a29fa859", size = 211711, upload-time = "2026-04-02T09:26:53.49Z" }, + { url = "https://files.pythonhosted.org/packages/6f/a5/a581c13798546a7fd557c82614a5c65a13df2157e9ad6373166d2a3e645d/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:7804338df6fcc08105c7745f1502ba68d900f45fd770d5bdd5288ddccb8a42d8", size = 210036, upload-time = "2026-04-02T09:26:54.975Z" }, + { url = "https://files.pythonhosted.org/packages/8c/bf/b3ab5bcb478e4193d517644b0fb2bf5497fbceeaa7a1bc0f4d5b50953861/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:481551899c856c704d58119b5025793fa6730adda3571971af568f66d2424bb5", size = 202998, upload-time = "2026-04-02T09:26:56.303Z" }, + { url = "https://files.pythonhosted.org/packages/e7/4e/23efd79b65d314fa320ec6017b4b5834d5c12a58ba4610aa353af2e2f577/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:f59099f9b66f0d7145115e6f80dd8b1d847176df89b234a5a6b3f00437aa0832", size = 230056, upload-time = "2026-04-02T09:26:57.554Z" }, + { url = "https://files.pythonhosted.org/packages/b9/9f/1e1941bc3f0e01df116e68dc37a55c4d249df5e6fa77f008841aef68264f/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:f59ad4c0e8f6bba240a9bb85504faa1ab438237199d4cce5f622761507b8f6a6", size = 211537, upload-time = "2026-04-02T09:26:58.843Z" }, + { url = "https://files.pythonhosted.org/packages/80/0f/088cbb3020d44428964a6c97fe1edfb1b9550396bf6d278330281e8b709c/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:3dedcc22d73ec993f42055eff4fcfed9318d1eeb9a6606c55892a26964964e48", size = 226176, upload-time = "2026-04-02T09:27:00.437Z" }, + { url = "https://files.pythonhosted.org/packages/6a/9f/130394f9bbe06f4f63e22641d32fc9b202b7e251c9aef4db044324dac493/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:64f02c6841d7d83f832cd97ccf8eb8a906d06eb95d5276069175c696b024b60a", size = 217723, upload-time = "2026-04-02T09:27:02.021Z" }, + { url = "https://files.pythonhosted.org/packages/73/55/c469897448a06e49f8fa03f6caae97074fde823f432a98f979cc42b90e69/charset_normalizer-3.4.7-cp313-cp313-win32.whl", hash = "sha256:4042d5c8f957e15221d423ba781e85d553722fc4113f523f2feb7b188cc34c5e", size = 148085, upload-time = "2026-04-02T09:27:03.192Z" }, + { url = "https://files.pythonhosted.org/packages/5d/78/1b74c5bbb3f99b77a1715c91b3e0b5bdb6fe302d95ace4f5b1bec37b0167/charset_normalizer-3.4.7-cp313-cp313-win_amd64.whl", hash = "sha256:3946fa46a0cf3e4c8cb1cc52f56bb536310d34f25f01ca9b6c16afa767dab110", size = 158819, upload-time = "2026-04-02T09:27:04.454Z" }, + { url = "https://files.pythonhosted.org/packages/68/86/46bd42279d323deb8687c4a5a811fd548cb7d1de10cf6535d099877a9a9f/charset_normalizer-3.4.7-cp313-cp313-win_arm64.whl", hash = "sha256:80d04837f55fc81da168b98de4f4b797ef007fc8a79ab71c6ec9bc4dd662b15b", size = 147915, upload-time = "2026-04-02T09:27:05.971Z" }, + { url = "https://files.pythonhosted.org/packages/db/8f/61959034484a4a7c527811f4721e75d02d653a35afb0b6054474d8185d4c/charset_normalizer-3.4.7-py3-none-any.whl", hash = "sha256:3dce51d0f5e7951f8bb4900c257dad282f49190fdbebecd4ba99bcc41fef404d", size = 61958, upload-time = "2026-04-02T09:28:37.794Z" }, ] [[package]] name = "click" -version = "8.3.1" +version = "8.3.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "colorama", marker = "sys_platform == 'win32'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" } +sdist = { url = "https://files.pythonhosted.org/packages/57/75/31212c6bf2503fdf920d87fee5d7a86a2e3bcf444984126f13d8e4016804/click-8.3.2.tar.gz", hash = "sha256:14162b8b3b3550a7d479eafa77dfd3c38d9dc8951f6f69c78913a8f9a7540fd5", size = 302856, upload-time = "2026-04-03T19:14:45.118Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" }, + { url = "https://files.pythonhosted.org/packages/e4/20/71885d8b97d4f3dde17b1fdb92dbd4908b00541c5a3379787137285f602e/click-8.3.2-py3-none-any.whl", hash = "sha256:1924d2c27c5653561cd2cae4548d1406039cb79b858b747cfea24924bbc1616d", size = 108379, upload-time = "2026-04-03T19:14:43.505Z" }, ] [[package]] @@ -205,15 +220,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" }, ] -[[package]] -name = "commonmark" -version = "0.9.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/60/48/a60f593447e8f0894ebb7f6e6c1f25dafc5e89c5879fdc9360ae93ff83f0/commonmark-0.9.1.tar.gz", hash = "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60", size = 95764, upload-time = "2019-10-04T15:37:39.817Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/b1/92/dfd892312d822f36c55366118b95d914e5f16de11044a27cf10a7d71bbbf/commonmark-0.9.1-py2.py3-none-any.whl", hash = "sha256:da2f38c92590f83de410ba1a3cbceafbc74fee9def35f9251ba9a971d6d66fd9", size = 51068, upload-time = "2019-10-04T15:37:37.674Z" }, -] - [[package]] name = "dnspython" version = "2.8.0" @@ -225,24 +231,24 @@ wheels = [ [[package]] name = "docutils" -version = "0.21.2" +version = "0.22.4" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/ae/ed/aefcc8cd0ba62a0560c3c18c33925362d46c6075480bfa4df87b28e169a9/docutils-0.21.2.tar.gz", hash = "sha256:3a6b18732edf182daa3cd12775bbb338cf5691468f91eeeb109deff6ebfa986f", size = 2204444, upload-time = "2024-04-23T18:57:18.24Z" } +sdist = { url = "https://files.pythonhosted.org/packages/ae/b6/03bb70946330e88ffec97aefd3ea75ba575cb2e762061e0e62a213befee8/docutils-0.22.4.tar.gz", hash = "sha256:4db53b1fde9abecbb74d91230d32ab626d94f6badfc575d6db9194a49df29968", size = 2291750, upload-time = "2025-12-18T19:00:26.443Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/8f/d7/9322c609343d929e75e7e5e6255e614fcc67572cfd083959cdef3b7aad79/docutils-0.21.2-py3-none-any.whl", hash = "sha256:dafca5b9e384f0e419294eb4d2ff9fa826435bf15f15b7bd45723e8ad76811b2", size = 587408, upload-time = "2024-04-23T18:57:14.835Z" }, + { url = "https://files.pythonhosted.org/packages/02/10/5da547df7a391dcde17f59520a231527b8571e6f46fc8efb02ccb370ab12/docutils-0.22.4-py3-none-any.whl", hash = "sha256:d0013f540772d1420576855455d050a2180186c91c15779301ac2ccb3eeb68de", size = 633196, upload-time = "2025-12-18T19:00:18.077Z" }, ] [[package]] name = "eventlet" -version = "0.40.4" +version = "0.41.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "dnspython" }, { name = "greenlet" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/d1/d8/f72d8583db7c559445e0e9500a9b9787332370c16980802204a403634585/eventlet-0.40.4.tar.gz", hash = "sha256:69bef712b1be18b4930df6f0c495d2a882bf7b63aa111e7b6eeff461cfcaf26f", size = 565920, upload-time = "2025-11-26T13:57:31.126Z" } +sdist = { url = "https://files.pythonhosted.org/packages/d3/90/32772ae7c9897554c56b9367b67478a3dc89c70d9b4d12e241746f6fdae3/eventlet-0.41.0.tar.gz", hash = "sha256:35df85f0ccd3e73effb6fd9f1ceae46b500b966c7da1817289c323a307bd397b", size = 565911, upload-time = "2026-04-02T07:33:23.605Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/22/6d/8e1fa901f6a8307f90e7bd932064e27a0062a4a7a16af38966a9c3293c52/eventlet-0.40.4-py3-none-any.whl", hash = "sha256:6326c6d0bf55810bece151f7a5750207c610f389ba110ffd1541ed6e5215485b", size = 364588, upload-time = "2025-11-26T13:57:29.09Z" }, + { url = "https://files.pythonhosted.org/packages/c3/1c/febe9acf1b4f0d67603b231c28d6d17d647d68c90c1963fecdeb64046d6d/eventlet-0.41.0-py3-none-any.whl", hash = "sha256:bc22396093cb4119ff7007776be6a5348a613ccd42eeb0f9519853a6efcbcabe", size = 364574, upload-time = "2026-04-02T07:33:21.756Z" }, ] [[package]] @@ -310,18 +316,20 @@ wheels = [ [[package]] name = "greenlet" -version = "3.3.0" +version = "3.4.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/c7/e5/40dbda2736893e3e53d25838e0f19a2b417dfc122b9989c91918db30b5d3/greenlet-3.3.0.tar.gz", hash = "sha256:a82bb225a4e9e4d653dd2fb7b8b2d36e4fb25bc0165422a11e48b88e9e6f78fb", size = 190651, upload-time = "2025-12-04T14:49:44.05Z" } +sdist = { url = "https://files.pythonhosted.org/packages/86/94/a5935717b307d7c71fe877b52b884c6af707d2d2090db118a03fbd799369/greenlet-3.4.0.tar.gz", hash = "sha256:f50a96b64dafd6169e595a5c56c9146ef80333e67d4476a65a9c55f400fc22ff", size = 195913, upload-time = "2026-04-08T17:08:00.863Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/02/2f/28592176381b9ab2cafa12829ba7b472d177f3acc35d8fbcf3673d966fff/greenlet-3.3.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:a1e41a81c7e2825822f4e068c48cb2196002362619e2d70b148f20a831c00739", size = 275140, upload-time = "2025-12-04T14:23:01.282Z" }, - { url = "https://files.pythonhosted.org/packages/2c/80/fbe937bf81e9fca98c981fe499e59a3f45df2a04da0baa5c2be0dca0d329/greenlet-3.3.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9f515a47d02da4d30caaa85b69474cec77b7929b2e936ff7fb853d42f4bf8808", size = 599219, upload-time = "2025-12-04T14:50:08.309Z" }, - { url = "https://files.pythonhosted.org/packages/c2/ff/7c985128f0514271b8268476af89aee6866df5eec04ac17dcfbc676213df/greenlet-3.3.0-cp313-cp313-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7d2d9fd66bfadf230b385fdc90426fcd6eb64db54b40c495b72ac0feb5766c54", size = 610211, upload-time = "2025-12-04T14:57:43.968Z" }, - { url = "https://files.pythonhosted.org/packages/79/07/c47a82d881319ec18a4510bb30463ed6891f2ad2c1901ed5ec23d3de351f/greenlet-3.3.0-cp313-cp313-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:30a6e28487a790417d036088b3bcb3f3ac7d8babaa7d0139edbaddebf3af9492", size = 624311, upload-time = "2025-12-04T15:07:14.697Z" }, - { url = "https://files.pythonhosted.org/packages/fd/8e/424b8c6e78bd9837d14ff7df01a9829fc883ba2ab4ea787d4f848435f23f/greenlet-3.3.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:087ea5e004437321508a8d6f20efc4cfec5e3c30118e1417ea96ed1d93950527", size = 612833, upload-time = "2025-12-04T14:26:03.669Z" }, - { url = "https://files.pythonhosted.org/packages/b5/ba/56699ff9b7c76ca12f1cdc27a886d0f81f2189c3455ff9f65246780f713d/greenlet-3.3.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ab97cf74045343f6c60a39913fa59710e4bd26a536ce7ab2397adf8b27e67c39", size = 1567256, upload-time = "2025-12-04T15:04:25.276Z" }, - { url = "https://files.pythonhosted.org/packages/1e/37/f31136132967982d698c71a281a8901daf1a8fbab935dce7c0cf15f942cc/greenlet-3.3.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5375d2e23184629112ca1ea89a53389dddbffcf417dad40125713d88eb5f96e8", size = 1636483, upload-time = "2025-12-04T14:27:30.804Z" }, - { url = "https://files.pythonhosted.org/packages/7e/71/ba21c3fb8c5dce83b8c01f458a42e99ffdb1963aeec08fff5a18588d8fd7/greenlet-3.3.0-cp313-cp313-win_amd64.whl", hash = "sha256:9ee1942ea19550094033c35d25d20726e4f1c40d59545815e1128ac58d416d38", size = 301833, upload-time = "2025-12-04T14:32:23.929Z" }, + { url = "https://files.pythonhosted.org/packages/7a/75/7e9cd1126a1e1f0cd67b0eda02e5221b28488d352684704a78ed505bd719/greenlet-3.4.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:43748988b097f9c6f09364f260741aa73c80747f63389824435c7a50bfdfd5c1", size = 285856, upload-time = "2026-04-08T15:52:45.82Z" }, + { url = "https://files.pythonhosted.org/packages/9d/c4/3e2df392e5cb199527c4d9dbcaa75c14edcc394b45040f0189f649631e3c/greenlet-3.4.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5566e4e2cd7a880e8c27618e3eab20f3494452d12fd5129edef7b2f7aa9a36d1", size = 610208, upload-time = "2026-04-08T16:24:39.674Z" }, + { url = "https://files.pythonhosted.org/packages/da/af/750cdfda1d1bd30a6c28080245be8d0346e669a98fdbae7f4102aa95fff3/greenlet-3.4.0-cp313-cp313-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1054c5a3c78e2ab599d452f23f7adafef55062a783a8e241d24f3b633ba6ff82", size = 621269, upload-time = "2026-04-08T16:30:59.767Z" }, + { url = "https://files.pythonhosted.org/packages/e0/93/c8c508d68ba93232784bbc1b5474d92371f2897dfc6bc281b419f2e0d492/greenlet-3.4.0-cp313-cp313-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:98eedd1803353daf1cd9ef23eef23eda5a4d22f99b1f998d273a8b78b70dd47f", size = 628455, upload-time = "2026-04-08T16:40:40.698Z" }, + { url = "https://files.pythonhosted.org/packages/54/78/0cbc693622cd54ebe25207efbb3a0eb07c2639cb8594f6e3aaaa0bb077a8/greenlet-3.4.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f82cb6cddc27dd81c96b1506f4aa7def15070c3b2a67d4e46fd19016aacce6cf", size = 617549, upload-time = "2026-04-08T15:56:34.893Z" }, + { url = "https://files.pythonhosted.org/packages/7f/46/cfaaa0ade435a60550fd83d07dfd5c41f873a01da17ede5c4cade0b9bab8/greenlet-3.4.0-cp313-cp313-manylinux_2_39_riscv64.whl", hash = "sha256:b7857e2202aae67bc5725e0c1f6403c20a8ff46094ece015e7d474f5f7020b55", size = 426238, upload-time = "2026-04-08T16:43:06.865Z" }, + { url = "https://files.pythonhosted.org/packages/ba/c0/8966767de01343c1ff47e8b855dc78e7d1a8ed2b7b9c83576a57e289f81d/greenlet-3.4.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:227a46251ecba4ff46ae742bc5ce95c91d5aceb4b02f885487aff269c127a729", size = 1575310, upload-time = "2026-04-08T16:26:21.671Z" }, + { url = "https://files.pythonhosted.org/packages/b8/38/bcdc71ba05e9a5fda87f63ffc2abcd1f15693b659346df994a48c968003d/greenlet-3.4.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5b99e87be7eba788dd5b75ba1cde5639edffdec5f91fe0d734a249535ec3408c", size = 1640435, upload-time = "2026-04-08T15:57:32.572Z" }, + { url = "https://files.pythonhosted.org/packages/a1/c2/19b664b7173b9e4ef5f77e8cef9f14c20ec7fce7920dc1ccd7afd955d093/greenlet-3.4.0-cp313-cp313-win_amd64.whl", hash = "sha256:849f8bc17acd6295fcb5de8e46d55cc0e52381c56eaf50a2afd258e97bc65940", size = 238760, upload-time = "2026-04-08T17:04:03.878Z" }, + { url = "https://files.pythonhosted.org/packages/9b/96/795619651d39c7fbd809a522f881aa6f0ead504cc8201c3a5b789dfaef99/greenlet-3.4.0-cp313-cp313-win_arm64.whl", hash = "sha256:9390ad88b652b1903814eaabd629ca184db15e0eeb6fe8a390bbf8b9106ae15a", size = 235498, upload-time = "2026-04-08T17:05:00.584Z" }, ] [[package]] @@ -375,11 +383,11 @@ wheels = [ [[package]] name = "imagesize" -version = "1.4.1" +version = "2.0.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/a7/84/62473fb57d61e31fef6e36d64a179c8781605429fd927b5dd608c997be31/imagesize-1.4.1.tar.gz", hash = "sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a", size = 1280026, upload-time = "2022-07-01T12:21:05.687Z" } +sdist = { url = "https://files.pythonhosted.org/packages/6c/e6/7bf14eeb8f8b7251141944835abd42eb20a658d89084b7e1f3e5fe394090/imagesize-2.0.0.tar.gz", hash = "sha256:8e8358c4a05c304f1fccf7ff96f036e7243a189e9e42e90851993c558cfe9ee3", size = 1773045, upload-time = "2026-03-03T14:18:29.941Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/ff/62/85c4c919272577931d407be5ba5d71c20f0b616d31a0befe0ae45bb79abd/imagesize-1.4.1-py2.py3-none-any.whl", hash = "sha256:0d8d18d08f840c19d0ee7ca1fd82490fdc3729b7ac93f49870406ddde8ef8d8b", size = 8769, upload-time = "2022-07-01T12:21:02.467Z" }, + { url = "https://files.pythonhosted.org/packages/5f/53/fb7122b71361a0d121b669dcf3d31244ef75badbbb724af388948de543e2/imagesize-2.0.0-py2.py3-none-any.whl", hash = "sha256:5667c5bbb57ab3f1fa4bc366f4fbc971db3d5ed011fd2715fd8001f782718d96", size = 9441, upload-time = "2026-03-03T14:18:27.892Z" }, ] [[package]] @@ -405,14 +413,14 @@ wheels = [ [[package]] name = "markdown-it-py" -version = "3.0.0" +version = "4.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "mdurl" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/38/71/3b932df36c1a044d397a1f92d1cf91ee0a503d91e470cbd670aa66b07ed0/markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb", size = 74596, upload-time = "2023-06-03T06:41:14.443Z" } +sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070, upload-time = "2025-08-11T12:57:52.854Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/42/d7/1ec15b46af6af88f19b8e5ffea08fa375d433c998b8a7639e76935c14f1f/markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1", size = 87528, upload-time = "2023-06-03T06:41:11.019Z" }, + { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" }, ] [[package]] @@ -468,52 +476,52 @@ wheels = [ [[package]] name = "multidict" -version = "6.7.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/80/1e/5492c365f222f907de1039b91f922b93fa4f764c713ee858d235495d8f50/multidict-6.7.0.tar.gz", hash = "sha256:c6e99d9a65ca282e578dfea819cfa9c0a62b2499d8677392e09feaf305e9e6f5", size = 101834, upload-time = "2025-10-06T14:52:30.657Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/d2/86/33272a544eeb36d66e4d9a920602d1a2f57d4ebea4ef3cdfe5a912574c95/multidict-6.7.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:bee7c0588aa0076ce77c0ea5d19a68d76ad81fcd9fe8501003b9a24f9d4000f6", size = 76135, upload-time = "2025-10-06T14:49:54.26Z" }, - { url = "https://files.pythonhosted.org/packages/91/1c/eb97db117a1ebe46d457a3d235a7b9d2e6dcab174f42d1b67663dd9e5371/multidict-6.7.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:7ef6b61cad77091056ce0e7ce69814ef72afacb150b7ac6a3e9470def2198159", size = 45117, upload-time = "2025-10-06T14:49:55.82Z" }, - { url = "https://files.pythonhosted.org/packages/f1/d8/6c3442322e41fb1dd4de8bd67bfd11cd72352ac131f6368315617de752f1/multidict-6.7.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:9c0359b1ec12b1d6849c59f9d319610b7f20ef990a6d454ab151aa0e3b9f78ca", size = 43472, upload-time = "2025-10-06T14:49:57.048Z" }, - { url = "https://files.pythonhosted.org/packages/75/3f/e2639e80325af0b6c6febdf8e57cc07043ff15f57fa1ef808f4ccb5ac4cd/multidict-6.7.0-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:cd240939f71c64bd658f186330603aac1a9a81bf6273f523fca63673cb7378a8", size = 249342, upload-time = "2025-10-06T14:49:58.368Z" }, - { url = "https://files.pythonhosted.org/packages/5d/cc/84e0585f805cbeaa9cbdaa95f9a3d6aed745b9d25700623ac89a6ecff400/multidict-6.7.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a60a4d75718a5efa473ebd5ab685786ba0c67b8381f781d1be14da49f1a2dc60", size = 257082, upload-time = "2025-10-06T14:49:59.89Z" }, - { url = "https://files.pythonhosted.org/packages/b0/9c/ac851c107c92289acbbf5cfb485694084690c1b17e555f44952c26ddc5bd/multidict-6.7.0-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:53a42d364f323275126aff81fb67c5ca1b7a04fda0546245730a55c8c5f24bc4", size = 240704, upload-time = "2025-10-06T14:50:01.485Z" }, - { url = "https://files.pythonhosted.org/packages/50/cc/5f93e99427248c09da95b62d64b25748a5f5c98c7c2ab09825a1d6af0e15/multidict-6.7.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:3b29b980d0ddbecb736735ee5bef69bb2ddca56eff603c86f3f29a1128299b4f", size = 266355, upload-time = "2025-10-06T14:50:02.955Z" }, - { url = "https://files.pythonhosted.org/packages/ec/0c/2ec1d883ceb79c6f7f6d7ad90c919c898f5d1c6ea96d322751420211e072/multidict-6.7.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f8a93b1c0ed2d04b97a5e9336fd2d33371b9a6e29ab7dd6503d63407c20ffbaf", size = 267259, upload-time = "2025-10-06T14:50:04.446Z" }, - { url = "https://files.pythonhosted.org/packages/c6/2d/f0b184fa88d6630aa267680bdb8623fb69cb0d024b8c6f0d23f9a0f406d3/multidict-6.7.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9ff96e8815eecacc6645da76c413eb3b3d34cfca256c70b16b286a687d013c32", size = 254903, upload-time = "2025-10-06T14:50:05.98Z" }, - { url = "https://files.pythonhosted.org/packages/06/c9/11ea263ad0df7dfabcad404feb3c0dd40b131bc7f232d5537f2fb1356951/multidict-6.7.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:7516c579652f6a6be0e266aec0acd0db80829ca305c3d771ed898538804c2036", size = 252365, upload-time = "2025-10-06T14:50:07.511Z" }, - { url = "https://files.pythonhosted.org/packages/41/88/d714b86ee2c17d6e09850c70c9d310abac3d808ab49dfa16b43aba9d53fd/multidict-6.7.0-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:040f393368e63fb0f3330e70c26bfd336656bed925e5cbe17c9da839a6ab13ec", size = 250062, upload-time = "2025-10-06T14:50:09.074Z" }, - { url = "https://files.pythonhosted.org/packages/15/fe/ad407bb9e818c2b31383f6131ca19ea7e35ce93cf1310fce69f12e89de75/multidict-6.7.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:b3bc26a951007b1057a1c543af845f1c7e3e71cc240ed1ace7bf4484aa99196e", size = 249683, upload-time = "2025-10-06T14:50:10.714Z" }, - { url = "https://files.pythonhosted.org/packages/8c/a4/a89abdb0229e533fb925e7c6e5c40201c2873efebc9abaf14046a4536ee6/multidict-6.7.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:7b022717c748dd1992a83e219587aabe45980d88969f01b316e78683e6285f64", size = 261254, upload-time = "2025-10-06T14:50:12.28Z" }, - { url = "https://files.pythonhosted.org/packages/8d/aa/0e2b27bd88b40a4fb8dc53dd74eecac70edaa4c1dd0707eb2164da3675b3/multidict-6.7.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:9600082733859f00d79dee64effc7aef1beb26adb297416a4ad2116fd61374bd", size = 257967, upload-time = "2025-10-06T14:50:14.16Z" }, - { url = "https://files.pythonhosted.org/packages/d0/8e/0c67b7120d5d5f6d874ed85a085f9dc770a7f9d8813e80f44a9fec820bb7/multidict-6.7.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:94218fcec4d72bc61df51c198d098ce2b378e0ccbac41ddbed5ef44092913288", size = 250085, upload-time = "2025-10-06T14:50:15.639Z" }, - { url = "https://files.pythonhosted.org/packages/ba/55/b73e1d624ea4b8fd4dd07a3bb70f6e4c7c6c5d9d640a41c6ffe5cdbd2a55/multidict-6.7.0-cp313-cp313-win32.whl", hash = "sha256:a37bd74c3fa9d00be2d7b8eca074dc56bd8077ddd2917a839bd989612671ed17", size = 41713, upload-time = "2025-10-06T14:50:17.066Z" }, - { url = "https://files.pythonhosted.org/packages/32/31/75c59e7d3b4205075b4c183fa4ca398a2daf2303ddf616b04ae6ef55cffe/multidict-6.7.0-cp313-cp313-win_amd64.whl", hash = "sha256:30d193c6cc6d559db42b6bcec8a5d395d34d60c9877a0b71ecd7c204fcf15390", size = 45915, upload-time = "2025-10-06T14:50:18.264Z" }, - { url = "https://files.pythonhosted.org/packages/31/2a/8987831e811f1184c22bc2e45844934385363ee61c0a2dcfa8f71b87e608/multidict-6.7.0-cp313-cp313-win_arm64.whl", hash = "sha256:ea3334cabe4d41b7ccd01e4d349828678794edbc2d3ae97fc162a3312095092e", size = 43077, upload-time = "2025-10-06T14:50:19.853Z" }, - { url = "https://files.pythonhosted.org/packages/e8/68/7b3a5170a382a340147337b300b9eb25a9ddb573bcdfff19c0fa3f31ffba/multidict-6.7.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:ad9ce259f50abd98a1ca0aa6e490b58c316a0fce0617f609723e40804add2c00", size = 83114, upload-time = "2025-10-06T14:50:21.223Z" }, - { url = "https://files.pythonhosted.org/packages/55/5c/3fa2d07c84df4e302060f555bbf539310980362236ad49f50eeb0a1c1eb9/multidict-6.7.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:07f5594ac6d084cbb5de2df218d78baf55ef150b91f0ff8a21cc7a2e3a5a58eb", size = 48442, upload-time = "2025-10-06T14:50:22.871Z" }, - { url = "https://files.pythonhosted.org/packages/fc/56/67212d33239797f9bd91962bb899d72bb0f4c35a8652dcdb8ed049bef878/multidict-6.7.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:0591b48acf279821a579282444814a2d8d0af624ae0bc600aa4d1b920b6e924b", size = 46885, upload-time = "2025-10-06T14:50:24.258Z" }, - { url = "https://files.pythonhosted.org/packages/46/d1/908f896224290350721597a61a69cd19b89ad8ee0ae1f38b3f5cd12ea2ac/multidict-6.7.0-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:749a72584761531d2b9467cfbdfd29487ee21124c304c4b6cb760d8777b27f9c", size = 242588, upload-time = "2025-10-06T14:50:25.716Z" }, - { url = "https://files.pythonhosted.org/packages/ab/67/8604288bbd68680eee0ab568fdcb56171d8b23a01bcd5cb0c8fedf6e5d99/multidict-6.7.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6b4c3d199f953acd5b446bf7c0de1fe25d94e09e79086f8dc2f48a11a129cdf1", size = 249966, upload-time = "2025-10-06T14:50:28.192Z" }, - { url = "https://files.pythonhosted.org/packages/20/33/9228d76339f1ba51e3efef7da3ebd91964d3006217aae13211653193c3ff/multidict-6.7.0-cp313-cp313t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:9fb0211dfc3b51efea2f349ec92c114d7754dd62c01f81c3e32b765b70c45c9b", size = 228618, upload-time = "2025-10-06T14:50:29.82Z" }, - { url = "https://files.pythonhosted.org/packages/f8/2d/25d9b566d10cab1c42b3b9e5b11ef79c9111eaf4463b8c257a3bd89e0ead/multidict-6.7.0-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a027ec240fe73a8d6281872690b988eed307cd7d91b23998ff35ff577ca688b5", size = 257539, upload-time = "2025-10-06T14:50:31.731Z" }, - { url = "https://files.pythonhosted.org/packages/b6/b1/8d1a965e6637fc33de3c0d8f414485c2b7e4af00f42cab3d84e7b955c222/multidict-6.7.0-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d1d964afecdf3a8288789df2f5751dc0a8261138c3768d9af117ed384e538fad", size = 256345, upload-time = "2025-10-06T14:50:33.26Z" }, - { url = "https://files.pythonhosted.org/packages/ba/0c/06b5a8adbdeedada6f4fb8d8f193d44a347223b11939b42953eeb6530b6b/multidict-6.7.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:caf53b15b1b7df9fbd0709aa01409000a2b4dd03a5f6f5cc548183c7c8f8b63c", size = 247934, upload-time = "2025-10-06T14:50:34.808Z" }, - { url = "https://files.pythonhosted.org/packages/8f/31/b2491b5fe167ca044c6eb4b8f2c9f3b8a00b24c432c365358eadac5d7625/multidict-6.7.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:654030da3197d927f05a536a66186070e98765aa5142794c9904555d3a9d8fb5", size = 245243, upload-time = "2025-10-06T14:50:36.436Z" }, - { url = "https://files.pythonhosted.org/packages/61/1a/982913957cb90406c8c94f53001abd9eafc271cb3e70ff6371590bec478e/multidict-6.7.0-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:2090d3718829d1e484706a2f525e50c892237b2bf9b17a79b059cb98cddc2f10", size = 235878, upload-time = "2025-10-06T14:50:37.953Z" }, - { url = "https://files.pythonhosted.org/packages/be/c0/21435d804c1a1cf7a2608593f4d19bca5bcbd7a81a70b253fdd1c12af9c0/multidict-6.7.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:2d2cfeec3f6f45651b3d408c4acec0ebf3daa9bc8a112a084206f5db5d05b754", size = 243452, upload-time = "2025-10-06T14:50:39.574Z" }, - { url = "https://files.pythonhosted.org/packages/54/0a/4349d540d4a883863191be6eb9a928846d4ec0ea007d3dcd36323bb058ac/multidict-6.7.0-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:4ef089f985b8c194d341eb2c24ae6e7408c9a0e2e5658699c92f497437d88c3c", size = 252312, upload-time = "2025-10-06T14:50:41.612Z" }, - { url = "https://files.pythonhosted.org/packages/26/64/d5416038dbda1488daf16b676e4dbfd9674dde10a0cc8f4fc2b502d8125d/multidict-6.7.0-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:e93a0617cd16998784bf4414c7e40f17a35d2350e5c6f0bd900d3a8e02bd3762", size = 246935, upload-time = "2025-10-06T14:50:43.972Z" }, - { url = "https://files.pythonhosted.org/packages/9f/8c/8290c50d14e49f35e0bd4abc25e1bc7711149ca9588ab7d04f886cdf03d9/multidict-6.7.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:f0feece2ef8ebc42ed9e2e8c78fc4aa3cf455733b507c09ef7406364c94376c6", size = 243385, upload-time = "2025-10-06T14:50:45.648Z" }, - { url = "https://files.pythonhosted.org/packages/ef/a0/f83ae75e42d694b3fbad3e047670e511c138be747bc713cf1b10d5096416/multidict-6.7.0-cp313-cp313t-win32.whl", hash = "sha256:19a1d55338ec1be74ef62440ca9e04a2f001a04d0cc49a4983dc320ff0f3212d", size = 47777, upload-time = "2025-10-06T14:50:47.154Z" }, - { url = "https://files.pythonhosted.org/packages/dc/80/9b174a92814a3830b7357307a792300f42c9e94664b01dee8e457551fa66/multidict-6.7.0-cp313-cp313t-win_amd64.whl", hash = "sha256:3da4fb467498df97e986af166b12d01f05d2e04f978a9c1c680ea1988e0bc4b6", size = 53104, upload-time = "2025-10-06T14:50:48.851Z" }, - { url = "https://files.pythonhosted.org/packages/cc/28/04baeaf0428d95bb7a7bea0e691ba2f31394338ba424fb0679a9ed0f4c09/multidict-6.7.0-cp313-cp313t-win_arm64.whl", hash = "sha256:b4121773c49a0776461f4a904cdf6264c88e42218aaa8407e803ca8025872792", size = 45503, upload-time = "2025-10-06T14:50:50.16Z" }, - { url = "https://files.pythonhosted.org/packages/b7/da/7d22601b625e241d4f23ef1ebff8acfc60da633c9e7e7922e24d10f592b3/multidict-6.7.0-py3-none-any.whl", hash = "sha256:394fc5c42a333c9ffc3e421a4c85e08580d990e08b99f6bf35b4132114c5dcb3", size = 12317, upload-time = "2025-10-06T14:52:29.272Z" }, +version = "6.7.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/1a/c2/c2d94cbe6ac1753f3fc980da97b3d930efe1da3af3c9f5125354436c073d/multidict-6.7.1.tar.gz", hash = "sha256:ec6652a1bee61c53a3e5776b6049172c53b6aaba34f18c9ad04f82712bac623d", size = 102010, upload-time = "2026-01-26T02:46:45.979Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f2/22/929c141d6c0dba87d3e1d38fbdf1ba8baba86b7776469f2bc2d3227a1e67/multidict-6.7.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2b41f5fed0ed563624f1c17630cb9941cf2309d4df00e494b551b5f3e3d67a23", size = 76174, upload-time = "2026-01-26T02:44:18.509Z" }, + { url = "https://files.pythonhosted.org/packages/c7/75/bc704ae15fee974f8fccd871305e254754167dce5f9e42d88a2def741a1d/multidict-6.7.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:84e61e3af5463c19b67ced91f6c634effb89ef8bfc5ca0267f954451ed4bb6a2", size = 45116, upload-time = "2026-01-26T02:44:19.745Z" }, + { url = "https://files.pythonhosted.org/packages/79/76/55cd7186f498ed080a18440c9013011eb548f77ae1b297206d030eb1180a/multidict-6.7.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:935434b9853c7c112eee7ac891bc4cb86455aa631269ae35442cb316790c1445", size = 43524, upload-time = "2026-01-26T02:44:21.571Z" }, + { url = "https://files.pythonhosted.org/packages/e9/3c/414842ef8d5a1628d68edee29ba0e5bcf235dbfb3ccd3ea303a7fe8c72ff/multidict-6.7.1-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:432feb25a1cb67fe82a9680b4d65fb542e4635cb3166cd9c01560651ad60f177", size = 249368, upload-time = "2026-01-26T02:44:22.803Z" }, + { url = "https://files.pythonhosted.org/packages/f6/32/befed7f74c458b4a525e60519fe8d87eef72bb1e99924fa2b0f9d97a221e/multidict-6.7.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e82d14e3c948952a1a85503817e038cba5905a3352de76b9a465075d072fba23", size = 256952, upload-time = "2026-01-26T02:44:24.306Z" }, + { url = "https://files.pythonhosted.org/packages/03/d6/c878a44ba877f366630c860fdf74bfb203c33778f12b6ac274936853c451/multidict-6.7.1-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:4cfb48c6ea66c83bcaaf7e4dfa7ec1b6bbcf751b7db85a328902796dfde4c060", size = 240317, upload-time = "2026-01-26T02:44:25.772Z" }, + { url = "https://files.pythonhosted.org/packages/68/49/57421b4d7ad2e9e60e25922b08ceb37e077b90444bde6ead629095327a6f/multidict-6.7.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1d540e51b7e8e170174555edecddbd5538105443754539193e3e1061864d444d", size = 267132, upload-time = "2026-01-26T02:44:27.648Z" }, + { url = "https://files.pythonhosted.org/packages/b7/fe/ec0edd52ddbcea2a2e89e174f0206444a61440b40f39704e64dc807a70bd/multidict-6.7.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:273d23f4b40f3dce4d6c8a821c741a86dec62cded82e1175ba3d99be128147ed", size = 268140, upload-time = "2026-01-26T02:44:29.588Z" }, + { url = "https://files.pythonhosted.org/packages/b0/73/6e1b01cbeb458807aa0831742232dbdd1fa92bfa33f52a3f176b4ff3dc11/multidict-6.7.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d624335fd4fa1c08a53f8b4be7676ebde19cd092b3895c421045ca87895b429", size = 254277, upload-time = "2026-01-26T02:44:30.902Z" }, + { url = "https://files.pythonhosted.org/packages/6a/b2/5fb8c124d7561a4974c342bc8c778b471ebbeb3cc17df696f034a7e9afe7/multidict-6.7.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:12fad252f8b267cc75b66e8fc51b3079604e8d43a75428ffe193cd9e2195dfd6", size = 252291, upload-time = "2026-01-26T02:44:32.31Z" }, + { url = "https://files.pythonhosted.org/packages/5a/96/51d4e4e06bcce92577fcd488e22600bd38e4fd59c20cb49434d054903bd2/multidict-6.7.1-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:03ede2a6ffbe8ef936b92cb4529f27f42be7f56afcdab5ab739cd5f27fb1cbf9", size = 250156, upload-time = "2026-01-26T02:44:33.734Z" }, + { url = "https://files.pythonhosted.org/packages/db/6b/420e173eec5fba721a50e2a9f89eda89d9c98fded1124f8d5c675f7a0c0f/multidict-6.7.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:90efbcf47dbe33dcf643a1e400d67d59abeac5db07dc3f27d6bdeae497a2198c", size = 249742, upload-time = "2026-01-26T02:44:35.222Z" }, + { url = "https://files.pythonhosted.org/packages/44/a3/ec5b5bd98f306bc2aa297b8c6f11a46714a56b1e6ef5ebda50a4f5d7c5fb/multidict-6.7.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:5c4b9bfc148f5a91be9244d6264c53035c8a0dcd2f51f1c3c6e30e30ebaa1c84", size = 262221, upload-time = "2026-01-26T02:44:36.604Z" }, + { url = "https://files.pythonhosted.org/packages/cd/f7/e8c0d0da0cd1e28d10e624604e1a36bcc3353aaebdfdc3a43c72bc683a12/multidict-6.7.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:401c5a650f3add2472d1d288c26deebc540f99e2fb83e9525007a74cd2116f1d", size = 258664, upload-time = "2026-01-26T02:44:38.008Z" }, + { url = "https://files.pythonhosted.org/packages/52/da/151a44e8016dd33feed44f730bd856a66257c1ee7aed4f44b649fb7edeb3/multidict-6.7.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:97891f3b1b3ffbded884e2916cacf3c6fc87b66bb0dde46f7357404750559f33", size = 249490, upload-time = "2026-01-26T02:44:39.386Z" }, + { url = "https://files.pythonhosted.org/packages/87/af/a3b86bf9630b732897f6fc3f4c4714b90aa4361983ccbdcd6c0339b21b0c/multidict-6.7.1-cp313-cp313-win32.whl", hash = "sha256:e1c5988359516095535c4301af38d8a8838534158f649c05dd1050222321bcb3", size = 41695, upload-time = "2026-01-26T02:44:41.318Z" }, + { url = "https://files.pythonhosted.org/packages/b2/35/e994121b0e90e46134673422dd564623f93304614f5d11886b1b3e06f503/multidict-6.7.1-cp313-cp313-win_amd64.whl", hash = "sha256:960c83bf01a95b12b08fd54324a4eb1d5b52c88932b5cba5d6e712bb3ed12eb5", size = 45884, upload-time = "2026-01-26T02:44:42.488Z" }, + { url = "https://files.pythonhosted.org/packages/ca/61/42d3e5dbf661242a69c97ea363f2d7b46c567da8eadef8890022be6e2ab0/multidict-6.7.1-cp313-cp313-win_arm64.whl", hash = "sha256:563fe25c678aaba333d5399408f5ec3c383ca5b663e7f774dd179a520b8144df", size = 43122, upload-time = "2026-01-26T02:44:43.664Z" }, + { url = "https://files.pythonhosted.org/packages/6d/b3/e6b21c6c4f314bb956016b0b3ef2162590a529b84cb831c257519e7fde44/multidict-6.7.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:c76c4bec1538375dad9d452d246ca5368ad6e1c9039dadcf007ae59c70619ea1", size = 83175, upload-time = "2026-01-26T02:44:44.894Z" }, + { url = "https://files.pythonhosted.org/packages/fb/76/23ecd2abfe0957b234f6c960f4ade497f55f2c16aeb684d4ecdbf1c95791/multidict-6.7.1-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:57b46b24b5d5ebcc978da4ec23a819a9402b4228b8a90d9c656422b4bdd8a963", size = 48460, upload-time = "2026-01-26T02:44:46.106Z" }, + { url = "https://files.pythonhosted.org/packages/c4/57/a0ed92b23f3a042c36bc4227b72b97eca803f5f1801c1ab77c8a212d455e/multidict-6.7.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:e954b24433c768ce78ab7929e84ccf3422e46deb45a4dc9f93438f8217fa2d34", size = 46930, upload-time = "2026-01-26T02:44:47.278Z" }, + { url = "https://files.pythonhosted.org/packages/b5/66/02ec7ace29162e447f6382c495dc95826bf931d3818799bbef11e8f7df1a/multidict-6.7.1-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:3bd231490fa7217cc832528e1cd8752a96f0125ddd2b5749390f7c3ec8721b65", size = 242582, upload-time = "2026-01-26T02:44:48.604Z" }, + { url = "https://files.pythonhosted.org/packages/58/18/64f5a795e7677670e872673aca234162514696274597b3708b2c0d276cce/multidict-6.7.1-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:253282d70d67885a15c8a7716f3a73edf2d635793ceda8173b9ecc21f2fb8292", size = 250031, upload-time = "2026-01-26T02:44:50.544Z" }, + { url = "https://files.pythonhosted.org/packages/c8/ed/e192291dbbe51a8290c5686f482084d31bcd9d09af24f63358c3d42fd284/multidict-6.7.1-cp313-cp313t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0b4c48648d7649c9335cf1927a8b87fa692de3dcb15faa676c6a6f1f1aabda43", size = 228596, upload-time = "2026-01-26T02:44:51.951Z" }, + { url = "https://files.pythonhosted.org/packages/1e/7e/3562a15a60cf747397e7f2180b0a11dc0c38d9175a650e75fa1b4d325e15/multidict-6.7.1-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:98bc624954ec4d2c7cb074b8eefc2b5d0ce7d482e410df446414355d158fe4ca", size = 257492, upload-time = "2026-01-26T02:44:53.902Z" }, + { url = "https://files.pythonhosted.org/packages/24/02/7d0f9eae92b5249bb50ac1595b295f10e263dd0078ebb55115c31e0eaccd/multidict-6.7.1-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:1b99af4d9eec0b49927b4402bcbb58dea89d3e0db8806a4086117019939ad3dd", size = 255899, upload-time = "2026-01-26T02:44:55.316Z" }, + { url = "https://files.pythonhosted.org/packages/00/e3/9b60ed9e23e64c73a5cde95269ef1330678e9c6e34dd4eb6b431b85b5a10/multidict-6.7.1-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6aac4f16b472d5b7dc6f66a0d49dd57b0e0902090be16594dc9ebfd3d17c47e7", size = 247970, upload-time = "2026-01-26T02:44:56.783Z" }, + { url = "https://files.pythonhosted.org/packages/3e/06/538e58a63ed5cfb0bd4517e346b91da32fde409d839720f664e9a4ae4f9d/multidict-6.7.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:21f830fe223215dffd51f538e78c172ed7c7f60c9b96a2bf05c4848ad49921c3", size = 245060, upload-time = "2026-01-26T02:44:58.195Z" }, + { url = "https://files.pythonhosted.org/packages/b2/2f/d743a3045a97c895d401e9bd29aaa09b94f5cbdf1bd561609e5a6c431c70/multidict-6.7.1-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:f5dd81c45b05518b9aa4da4aa74e1c93d715efa234fd3e8a179df611cc85e5f4", size = 235888, upload-time = "2026-01-26T02:44:59.57Z" }, + { url = "https://files.pythonhosted.org/packages/38/83/5a325cac191ab28b63c52f14f1131f3b0a55ba3b9aa65a6d0bf2a9b921a0/multidict-6.7.1-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:eb304767bca2bb92fb9c5bd33cedc95baee5bb5f6c88e63706533a1c06ad08c8", size = 243554, upload-time = "2026-01-26T02:45:01.054Z" }, + { url = "https://files.pythonhosted.org/packages/20/1f/9d2327086bd15da2725ef6aae624208e2ef828ed99892b17f60c344e57ed/multidict-6.7.1-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:c9035dde0f916702850ef66460bc4239d89d08df4d02023a5926e7446724212c", size = 252341, upload-time = "2026-01-26T02:45:02.484Z" }, + { url = "https://files.pythonhosted.org/packages/e8/2c/2a1aa0280cf579d0f6eed8ee5211c4f1730bd7e06c636ba2ee6aafda302e/multidict-6.7.1-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:af959b9beeb66c822380f222f0e0a1889331597e81f1ded7f374f3ecb0fd6c52", size = 246391, upload-time = "2026-01-26T02:45:03.862Z" }, + { url = "https://files.pythonhosted.org/packages/e5/03/7ca022ffc36c5a3f6e03b179a5ceb829be9da5783e6fe395f347c0794680/multidict-6.7.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:41f2952231456154ee479651491e94118229844dd7226541788be783be2b5108", size = 243422, upload-time = "2026-01-26T02:45:05.296Z" }, + { url = "https://files.pythonhosted.org/packages/dc/1d/b31650eab6c5778aceed46ba735bd97f7c7d2f54b319fa916c0f96e7805b/multidict-6.7.1-cp313-cp313t-win32.whl", hash = "sha256:df9f19c28adcb40b6aae30bbaa1478c389efd50c28d541d76760199fc1037c32", size = 47770, upload-time = "2026-01-26T02:45:06.754Z" }, + { url = "https://files.pythonhosted.org/packages/ac/5b/2d2d1d522e51285bd61b1e20df8f47ae1a9d80839db0b24ea783b3832832/multidict-6.7.1-cp313-cp313t-win_amd64.whl", hash = "sha256:d54ecf9f301853f2c5e802da559604b3e95bb7a3b01a9c295c6ee591b9882de8", size = 53109, upload-time = "2026-01-26T02:45:08.044Z" }, + { url = "https://files.pythonhosted.org/packages/3d/a3/cc409ba012c83ca024a308516703cf339bdc4b696195644a7215a5164a24/multidict-6.7.1-cp313-cp313t-win_arm64.whl", hash = "sha256:5a37ca18e360377cfda1d62f5f382ff41f2b8c4ccb329ed974cc2e1643440118", size = 45573, upload-time = "2026-01-26T02:45:09.349Z" }, + { url = "https://files.pythonhosted.org/packages/81/08/7036c080d7117f28a4af526d794aab6a84463126db031b007717c1a6676e/multidict-6.7.1-py3-none-any.whl", hash = "sha256:55d97cc6dae627efa6a6e548885712d4864b81110ac76fa4e534c03819fa4a56", size = 12319, upload-time = "2026-01-26T02:46:44.004Z" }, ] [[package]] name = "myst-parser" -version = "4.0.1" +version = "5.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "docutils" }, @@ -523,9 +531,9 @@ dependencies = [ { name = "pyyaml" }, { name = "sphinx" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/66/a5/9626ba4f73555b3735ad86247a8077d4603aa8628537687c839ab08bfe44/myst_parser-4.0.1.tar.gz", hash = "sha256:5cfea715e4f3574138aecbf7d54132296bfd72bb614d31168f48c477a830a7c4", size = 93985, upload-time = "2025-02-12T10:53:03.833Z" } +sdist = { url = "https://files.pythonhosted.org/packages/33/fa/7b45eef11b7971f0beb29d27b7bfe0d747d063aa29e170d9edd004733c8a/myst_parser-5.0.0.tar.gz", hash = "sha256:f6f231452c56e8baa662cc352c548158f6a16fcbd6e3800fc594978002b94f3a", size = 98535, upload-time = "2026-01-15T09:08:18.036Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/5f/df/76d0321c3797b54b60fef9ec3bd6f4cfd124b9e422182156a1dd418722cf/myst_parser-4.0.1-py3-none-any.whl", hash = "sha256:9134e88959ec3b5780aedf8a99680ea242869d012e8821db3126d427edc9c95d", size = 84579, upload-time = "2025-02-12T10:53:02.078Z" }, + { url = "https://files.pythonhosted.org/packages/d3/ac/686789b9145413f1a61878c407210e41bfdb097976864e0913078b24098c/myst_parser-5.0.0-py3-none-any.whl", hash = "sha256:ab31e516024918296e169139072b81592336f2fef55b8986aa31c9f04b5f7211", size = 84533, upload-time = "2026-01-15T09:08:16.788Z" }, ] [[package]] @@ -539,20 +547,20 @@ wheels = [ [[package]] name = "packaging" -version = "25.0" +version = "26.1" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/a1/d4/1fc4078c65507b51b96ca8f8c3ba19e6a61c8253c72794544580a7b6c24d/packaging-25.0.tar.gz", hash = "sha256:d443872c98d677bf60f6a1f2f8c1cb748e8fe762d2bf9d3148b5599295b0fc4f", size = 165727, upload-time = "2025-04-19T11:48:59.673Z" } +sdist = { url = "https://files.pythonhosted.org/packages/df/de/0d2b39fb4af88a0258f3bac87dfcbb48e73fbdea4a2ed0e2213f9a4c2f9a/packaging-26.1.tar.gz", hash = "sha256:f042152b681c4bfac5cae2742a55e103d27ab2ec0f3d88037136b6bfe7c9c5de", size = 215519, upload-time = "2026-04-14T21:12:49.362Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" }, + { url = "https://files.pythonhosted.org/packages/7a/c2/920ef838e2f0028c8262f16101ec09ebd5969864e5a64c4c05fad0617c56/packaging-26.1-py3-none-any.whl", hash = "sha256:5d9c0669c6285e491e0ced2eee587eaf67b670d94a19e94e3984a481aba6802f", size = 95831, upload-time = "2026-04-14T21:12:47.56Z" }, ] [[package]] name = "pathspec" -version = "0.12.1" +version = "1.0.4" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/ca/bc/f35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf/pathspec-0.12.1.tar.gz", hash = "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712", size = 51043, upload-time = "2023-12-10T22:30:45Z" } +sdist = { url = "https://files.pythonhosted.org/packages/fa/36/e27608899f9b8d4dff0617b2d9ab17ca5608956ca44461ac14ac48b44015/pathspec-1.0.4.tar.gz", hash = "sha256:0210e2ae8a21a9137c0d470578cb0e595af87edaa6ebf12ff176f14a02e0e645", size = 131200, upload-time = "2026-01-27T03:59:46.938Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl", hash = "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08", size = 31191, upload-time = "2023-12-10T22:30:43.14Z" }, + { url = "https://files.pythonhosted.org/packages/ef/3c/2c197d226f9ea224a9ab8d197933f9da0ae0aac5b6e0f884e2b8d9c8e9f7/pathspec-1.0.4-py3-none-any.whl", hash = "sha256:fb6ae2fd4e7c921a165808a552060e722767cfa526f99ca5156ed2ce45a5c723", size = 55206, upload-time = "2026-01-27T03:59:45.137Z" }, ] [[package]] @@ -605,20 +613,20 @@ wheels = [ [[package]] name = "pycparser" -version = "2.23" +version = "3.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/fe/cf/d2d3b9f5699fb1e4615c8e32ff220203e43b248e1dfcc6736ad9057731ca/pycparser-2.23.tar.gz", hash = "sha256:78816d4f24add8f10a06d6f05b4d424ad9e96cfebf68a4ddc99c65c0720d00c2", size = 173734, upload-time = "2025-09-09T13:23:47.91Z" } +sdist = { url = "https://files.pythonhosted.org/packages/1b/7d/92392ff7815c21062bea51aa7b87d45576f649f16458d78b7cf94b9ab2e6/pycparser-3.0.tar.gz", hash = "sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29", size = 103492, upload-time = "2026-01-21T14:26:51.89Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/a0/e3/59cd50310fc9b59512193629e1984c1f95e5c8ae6e5d8c69532ccc65a7fe/pycparser-2.23-py3-none-any.whl", hash = "sha256:e5c6e8d3fbad53479cab09ac03729e0a9faf2bee3db8208a550daf5af81a5934", size = 118140, upload-time = "2025-09-09T13:23:46.651Z" }, + { url = "https://files.pythonhosted.org/packages/0c/c3/44f3fbbfa403ea2a7c779186dc20772604442dde72947e7d01069cbe98e3/pycparser-3.0-py3-none-any.whl", hash = "sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992", size = 48172, upload-time = "2026-01-21T14:26:50.693Z" }, ] [[package]] name = "pygments" -version = "2.19.2" +version = "2.20.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" }, + { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" }, ] [[package]] @@ -629,8 +637,8 @@ dependencies = [ { name = "eventlet" }, { name = "gevent" }, { name = "gremlinpython" }, + { name = "myst-parser" }, { name = "pygments" }, - { name = "recommonmark" }, { name = "redirects-cli" }, { name = "six" }, { name = "sphinx" }, @@ -651,14 +659,14 @@ requires-dist = [ { name = "eventlet", specifier = ">=0.40.3,<1.0.0" }, { name = "gevent", specifier = ">=25.9.1,<26.0.0" }, { name = "gremlinpython", specifier = "==3.7.4" }, + { name = "myst-parser", specifier = ">=5.0.0" }, { name = "pygments", specifier = ">=2.19.2,<3.0.0" }, - { name = "recommonmark", specifier = "==0.7.1" }, { name = "redirects-cli", specifier = "~=0.1.3" }, { name = "six", specifier = ">=1.9" }, - { name = "sphinx", specifier = ">=8.2.3,<9.0.0" }, + { name = "sphinx", specifier = ">=9.0" }, { name = "sphinx-autobuild", specifier = ">=2025.0.0,<2026.0.0" }, { name = "sphinx-multiversion-scylla", specifier = ">=0.3.2,<1.0.0" }, - { name = "sphinx-scylladb-theme", specifier = ">=1.8.2,<2.0.0" }, + { name = "sphinx-scylladb-theme", specifier = ">=1.9.3" }, { name = "sphinx-sitemap", specifier = ">=2.8.0,<3.0.0" }, { name = "tornado", specifier = ">=6.5,<7.0" }, ] @@ -684,20 +692,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" }, ] -[[package]] -name = "recommonmark" -version = "0.7.1" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "commonmark" }, - { name = "docutils" }, - { name = "sphinx" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/1c/00/3dd2bdc4184b0ce754b5b446325abf45c2e0a347e022292ddc44670f628c/recommonmark-0.7.1.tar.gz", hash = "sha256:bdb4db649f2222dcd8d2d844f0006b958d627f732415d399791ee436a3686d67", size = 34444, upload-time = "2020-12-17T19:24:56.523Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/c6/77/ed589c75db5d02a77a1d5d2d9abc63f29676467d396c64277f98b50b79c2/recommonmark-0.7.1-py2.py3-none-any.whl", hash = "sha256:1b1db69af0231efce3fa21b94ff627ea33dee7079a01dd0a7f8482c3da148b3f", size = 10214, upload-time = "2020-12-17T19:24:55.137Z" }, -] - [[package]] name = "redirects-cli" version = "0.1.3" @@ -713,7 +707,7 @@ wheels = [ [[package]] name = "requests" -version = "2.32.5" +version = "2.33.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "certifi" }, @@ -721,40 +715,40 @@ dependencies = [ { name = "idna" }, { name = "urllib3" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" } +sdist = { url = "https://files.pythonhosted.org/packages/5f/a4/98b9c7c6428a668bf7e42ebb7c79d576a1c3c1e3ae2d47e674b468388871/requests-2.33.1.tar.gz", hash = "sha256:18817f8c57c6263968bc123d237e3b8b08ac046f5456bd1e307ee8f4250d3517", size = 134120, upload-time = "2026-03-30T16:09:15.531Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" }, + { url = "https://files.pythonhosted.org/packages/d7/8e/7540e8a2036f79a125c1d2ebadf69ed7901608859186c856fa0388ef4197/requests-2.33.1-py3-none-any.whl", hash = "sha256:4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a", size = 64947, upload-time = "2026-03-30T16:09:13.83Z" }, ] [[package]] name = "rich" -version = "14.2.0" +version = "15.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "markdown-it-py" }, { name = "pygments" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/fb/d2/8920e102050a0de7bfabeb4c4614a49248cf8d5d7a8d01885fbb24dc767a/rich-14.2.0.tar.gz", hash = "sha256:73ff50c7c0c1c77c8243079283f4edb376f0f6442433aecb8ce7e6d0b92d1fe4", size = 219990, upload-time = "2025-10-09T14:16:53.064Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/25/7a/b0178788f8dc6cafce37a212c99565fa1fe7872c70c6c9c1e1a372d9d88f/rich-14.2.0-py3-none-any.whl", hash = "sha256:76bc51fe2e57d2b1be1f96c524b890b816e334ab4c1e45888799bfaab0021edd", size = 243393, upload-time = "2025-10-09T14:16:51.245Z" }, + { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" }, ] [[package]] -name = "roman-numerals-py" -version = "3.1.0" +name = "roman-numerals" +version = "4.1.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/30/76/48fd56d17c5bdbdf65609abbc67288728a98ed4c02919428d4f52d23b24b/roman_numerals_py-3.1.0.tar.gz", hash = "sha256:be4bf804f083a4ce001b5eb7e3c0862479d10f94c936f6c4e5f250aa5ff5bd2d", size = 9017, upload-time = "2025-02-22T07:34:54.333Z" } +sdist = { url = "https://files.pythonhosted.org/packages/ae/f9/41dc953bbeb056c17d5f7a519f50fdf010bd0553be2d630bc69d1e022703/roman_numerals-4.1.0.tar.gz", hash = "sha256:1af8b147eb1405d5839e78aeb93131690495fe9da5c91856cb33ad55a7f1e5b2", size = 9077, upload-time = "2025-12-17T18:25:34.381Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/53/97/d2cbbaa10c9b826af0e10fdf836e1bf344d9f0abb873ebc34d1f49642d3f/roman_numerals_py-3.1.0-py3-none-any.whl", hash = "sha256:9da2ad2fb670bcf24e81070ceb3be72f6c11c440d73bd579fbeca1e9f330954c", size = 7742, upload-time = "2025-02-22T07:34:52.422Z" }, + { url = "https://files.pythonhosted.org/packages/04/54/6f679c435d28e0a568d8e8a7c0a93a09010818634c3c3907fc98d8983770/roman_numerals-4.1.0-py3-none-any.whl", hash = "sha256:647ba99caddc2cc1e55a51e4360689115551bf4476d90e8162cf8c345fe233c7", size = 7676, upload-time = "2025-12-17T18:25:33.098Z" }, ] [[package]] name = "setuptools" -version = "80.9.0" +version = "82.0.1" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/18/5d/3bf57dcd21979b887f014ea83c24ae194cfcd12b9e0fda66b957c69d1fca/setuptools-80.9.0.tar.gz", hash = "sha256:f36b47402ecde768dbfafc46e8e4207b4360c654f1f3bb84475f0a28628fb19c", size = 1319958, upload-time = "2025-05-27T00:56:51.443Z" } +sdist = { url = "https://files.pythonhosted.org/packages/4f/db/cfac1baf10650ab4d1c111714410d2fbb77ac5a616db26775db562c8fab2/setuptools-82.0.1.tar.gz", hash = "sha256:7d872682c5d01cfde07da7bccc7b65469d3dca203318515ada1de5eda35efbf9", size = 1152316, upload-time = "2026-03-09T12:47:17.221Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/a3/dc/17031897dae0efacfea57dfd3a82fdd2a2aeb58e0ff71b77b87e44edc772/setuptools-80.9.0-py3-none-any.whl", hash = "sha256:062d34222ad13e0cc312a4c02d73f059e86a4acbfbdea8f8f76b28c99f306922", size = 1201486, upload-time = "2025-05-27T00:56:49.664Z" }, + { url = "https://files.pythonhosted.org/packages/9d/76/f789f7a86709c6b087c5a2f52f911838cad707cc613162401badc665acfe/setuptools-82.0.1-py3-none-any.whl", hash = "sha256:a59e362652f08dcd477c78bb6e7bd9d80a7995bc73ce773050228a348ce2e5bb", size = 1006223, upload-time = "2026-03-09T12:47:15.026Z" }, ] [[package]] @@ -786,16 +780,16 @@ wheels = [ [[package]] name = "soupsieve" -version = "2.8" +version = "2.8.4" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/6d/e6/21ccce3262dd4889aa3332e5a119a3491a95e8f60939870a3a035aabac0d/soupsieve-2.8.tar.gz", hash = "sha256:e2dd4a40a628cb5f28f6d4b0db8800b8f581b65bb380b97de22ba5ca8d72572f", size = 103472, upload-time = "2025-08-27T15:39:51.78Z" } +sdist = { url = "https://files.pythonhosted.org/packages/47/2c/0a5f6f8ee0d5589e48c7640213ed5175d52cf540a06725b628cc1a45d6ce/soupsieve-2.8.4.tar.gz", hash = "sha256:e121fd02e975c695e4e9e8774a5ee35d74714b59307868dcc5319ad2d9e3328e", size = 121110, upload-time = "2026-05-24T13:55:57.154Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/14/a0/bb38d3b76b8cae341dad93a2dd83ab7462e6dbcdd84d43f54ee60a8dc167/soupsieve-2.8-py3-none-any.whl", hash = "sha256:0cc76456a30e20f5d7f2e14a98a4ae2ee4e5abdc7c5ea0aafe795f344bc7984c", size = 36679, upload-time = "2025-08-27T15:39:50.179Z" }, + { url = "https://files.pythonhosted.org/packages/5e/f5/0c41cb68dcae6b7de4fac4188a3a9589e21fb31df21ea3a2e888db95e6c9/soupsieve-2.8.4-py3-none-any.whl", hash = "sha256:e7e6b0769c8f51ed59acab6e994b00621096cfb1c640a7509295987388fbaf65", size = 37304, upload-time = "2026-05-24T13:55:55.406Z" }, ] [[package]] name = "sphinx" -version = "8.2.3" +version = "9.1.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "alabaster" }, @@ -807,7 +801,7 @@ dependencies = [ { name = "packaging" }, { name = "pygments" }, { name = "requests" }, - { name = "roman-numerals-py" }, + { name = "roman-numerals" }, { name = "snowballstemmer" }, { name = "sphinxcontrib-applehelp" }, { name = "sphinxcontrib-devhelp" }, @@ -816,9 +810,9 @@ dependencies = [ { name = "sphinxcontrib-qthelp" }, { name = "sphinxcontrib-serializinghtml" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/38/ad/4360e50ed56cb483667b8e6dadf2d3fda62359593faabbe749a27c4eaca6/sphinx-8.2.3.tar.gz", hash = "sha256:398ad29dee7f63a75888314e9424d40f52ce5a6a87ae88e7071e80af296ec348", size = 8321876, upload-time = "2025-03-02T22:31:59.658Z" } +sdist = { url = "https://files.pythonhosted.org/packages/cd/bd/f08eb0f4eed5c83f1ba2a3bd18f7745a2b1525fad70660a1c00224ec468a/sphinx-9.1.0.tar.gz", hash = "sha256:7741722357dd75f8190766926071fed3bdc211c74dd2d7d4df5404da95930ddb", size = 8718324, upload-time = "2025-12-31T15:09:27.646Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/31/53/136e9eca6e0b9dc0e1962e2c908fbea2e5ac000c2a2fbd9a35797958c48b/sphinx-8.2.3-py3-none-any.whl", hash = "sha256:4405915165f13521d875a8c29c8970800a0141c14cc5416a38feca4ea5d9b9c3", size = 3589741, upload-time = "2025-03-02T22:31:56.836Z" }, + { url = "https://files.pythonhosted.org/packages/73/f7/b1884cb3188ab181fc81fa00c266699dab600f927a964df02ec3d5d1916a/sphinx-9.1.0-py3-none-any.whl", hash = "sha256:c84fdd4e782504495fe4f2c0b3413d6c2bf388589bb352d439b2a3bb99991978", size = 3921742, upload-time = "2025-12-31T15:09:25.561Z" }, ] [[package]] @@ -840,14 +834,14 @@ wheels = [ [[package]] name = "sphinx-collapse" -version = "0.1.3" +version = "0.1.4" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "sphinx" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/e7/02/183559e508906f7282d4dd6ccbf443efddaa3114b7f6fab425949b37a003/sphinx_collapse-0.1.3.tar.gz", hash = "sha256:cae141e6f03ecd52ed246a305a69e1b0d5d05e6cdf3fe803d40d583ad6ad895a", size = 18540, upload-time = "2024-02-22T15:24:38.735Z" } +sdist = { url = "https://files.pythonhosted.org/packages/14/a1/cb5bb03a5081bd1229b3296c2af347b4147017fdb62777d2aad855cd349f/sphinx_collapse-0.1.4.tar.gz", hash = "sha256:ba860e50839c026cd1abcc164e1e7cb18bcc11c8214150e34a6550461be3229f", size = 19412, upload-time = "2026-02-27T17:47:24.191Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/2f/2f/5889082a6a535aa8613a327308582914517082967583ad45586b7d61c145/sphinx_collapse-0.1.3-py3-none-any.whl", hash = "sha256:85fadb2ec8769b93fd04276538668fa96239ef60c20c4a9eaa3e480387a6e65b", size = 4688, upload-time = "2024-02-22T15:24:29.365Z" }, + { url = "https://files.pythonhosted.org/packages/9a/18/277f4663c97073606917becab629938237f1e03952f4e339f8b7d1f3096b/sphinx_collapse-0.1.4-py3-none-any.whl", hash = "sha256:76e9fa531bafb4984d6ef5f3dbe311982837f5965b7a35eda013bbd9dd41445e", size = 4811, upload-time = "2026-02-27T17:47:22.622Z" }, ] [[package]] @@ -874,16 +868,43 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e1/fb/e496f16fa11fbe2dbdd0b5e306ede153dfed050aae4766fc89d500720dc7/sphinx_last_updated_by_git-0.3.8-py3-none-any.whl", hash = "sha256:6382c8285ac1f222483a58569b78c0371af5e55f7fbf9c01e5e8a72d6fdfa499", size = 8580, upload-time = "2024-08-11T07:15:53.244Z" }, ] +[[package]] +name = "sphinx-llm" +version = "0.4.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, + { name = "sphinx-markdown-builder" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/59/23/fe184bf9c6761c2cd04dc5b5456b717f626143663a3004f628636a2f7b0e/sphinx_llm-0.4.1.tar.gz", hash = "sha256:0789185dcbbecc00b5e25aa3db6342b98dad6a9def96088a9e50fa0203fda090", size = 280250, upload-time = "2026-04-02T09:09:18.881Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/31/2b/a54c49b42b25a6eb6039daf882f06488812c28e32734e944b2f7b6f82554/sphinx_llm-0.4.1-py3-none-any.whl", hash = "sha256:d7c8ee2a6335636b628ea2b26cd1e1dee1f0cf9c40fe51b20f201af1c05b95f5", size = 28453, upload-time = "2026-04-02T09:09:17.632Z" }, +] + +[[package]] +name = "sphinx-markdown-builder" +version = "0.6.10" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "docutils" }, + { name = "sphinx" }, + { name = "tabulate" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/a0/58/0b7b9a7d071140b3705885d51932e8b62f520388c2772e4952189971727b/sphinx_markdown_builder-0.6.10.tar.gz", hash = "sha256:cd5acf88d52ea0146a712fd557404f10326dff3428a78ba928e59b1727fd4a86", size = 22688, upload-time = "2026-03-11T10:56:57.639Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c2/8f/9fecf3d081d5cd49eff83a17b9fef50ed741e6223ab3bb906de4ab0068f9/sphinx_markdown_builder-0.6.10-py3-none-any.whl", hash = "sha256:16d86738b9ac69fcbc86e373c31c6402c30af1fa8d98d0f62cc5f38bfe5fc26e", size = 16700, upload-time = "2026-03-11T10:56:56.135Z" }, +] + [[package]] name = "sphinx-multiversion-scylla" -version = "0.3.4" +version = "0.3.8" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "sphinx" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/48/1d/e2b1a214b20d33cc631422e483ed1c8cf6883870940b58cc46341b65e2d7/sphinx_multiversion_scylla-0.3.4.tar.gz", hash = "sha256:8f7c94a89c794334d78ef21761a8bf455aaa7361e71037cf2ac2ca51cb47a0ba", size = 12427, upload-time = "2025-11-24T07:42:01.506Z" } +sdist = { url = "https://files.pythonhosted.org/packages/83/b7/ca070ac96cbca8b91c499827790ca4816a259b9259a961108a3fd9fa470c/sphinx_multiversion_scylla-0.3.8.tar.gz", hash = "sha256:418b563afd3c75c40f096b614cb4c595928692fb0b340762e5fd19c876567040", size = 12749, upload-time = "2026-04-13T16:45:16.119Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/fa/aa/82c27991640fe47921f74894a192d374dc1eb609d2276de4abeefe85f4aa/sphinx_multiversion_scylla-0.3.4-py3-none-any.whl", hash = "sha256:e64d49d39a8eccf06a9cb8bbe88eecb3eb2082e6b91a478b55dc7d0268d8e0b6", size = 12302, upload-time = "2025-11-24T07:42:00.403Z" }, + { url = "https://files.pythonhosted.org/packages/67/1d/c4dea80220e2cab5dc326da2369ecac60b5fc71cb0643df698ef76bb14bb/sphinx_multiversion_scylla-0.3.8-py3-none-any.whl", hash = "sha256:a3a16724eb5ec76563f12dd66efb2e7c5d9aa2ddf5e8bb755e817f9973b44ffd", size = 12675, upload-time = "2026-04-13T16:45:14.859Z" }, ] [[package]] @@ -900,7 +921,7 @@ wheels = [ [[package]] name = "sphinx-scylladb-theme" -version = "1.8.10" +version = "1.9.3" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "beautifulsoup4" }, @@ -908,14 +929,15 @@ dependencies = [ { name = "setuptools" }, { name = "sphinx-collapse" }, { name = "sphinx-copybutton" }, + { name = "sphinx-llm" }, { name = "sphinx-notfound-page" }, { name = "sphinx-substitution-extensions" }, { name = "sphinx-tabs" }, { name = "sphinxcontrib-mermaid" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/18/cd/bbd41f0d058f0ef4997cb044326f15dd28a1a17a4336e9b52cb67b8dd242/sphinx_scylladb_theme-1.8.10.tar.gz", hash = "sha256:8a78a9b692d9a946be2c4a64aa472fd82204cc8ea0b1ee7f60de6db35b356326", size = 1620675, upload-time = "2025-12-05T16:49:38.942Z" } +sdist = { url = "https://files.pythonhosted.org/packages/3d/43/2c6ca729655d99c69a7970efe56345d4bf345a345511ce4dc247aa5380df/sphinx_scylladb_theme-1.9.3.tar.gz", hash = "sha256:2a80252d6a5bb1ef8b61b6af47db4b7cbdec9c056b339ad4bc2cee97604603ad", size = 1691127, upload-time = "2026-07-16T16:44:51.404Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/4c/0e/7577d9bb6e2e7378e6c9f49263c59061a2ae9e370b806d8d1fd8c3be2a23/sphinx_scylladb_theme-1.8.10-py3-none-any.whl", hash = "sha256:8b930f33bec7308ccaa92698ebb5ad85059bcbf93a463f92917aeaf473fce632", size = 1662434, upload-time = "2025-12-05T16:49:36.265Z" }, + { url = "https://files.pythonhosted.org/packages/b8/0e/b79e97434339b4b935535709b5b20491451e5c5de5d4b90c8cafbdcc7c2f/sphinx_scylladb_theme-1.9.3-py3-none-any.whl", hash = "sha256:2b9eb999421711deb7ca0fbd5c287c668cdaee7bd41d19abf75b140e8e6982d4", size = 1674682, upload-time = "2026-07-16T16:44:49.644Z" }, ] [[package]] @@ -932,7 +954,7 @@ wheels = [ [[package]] name = "sphinx-substitution-extensions" -version = "2025.11.17" +version = "2026.1.12" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "beartype" }, @@ -940,23 +962,23 @@ dependencies = [ { name = "myst-parser" }, { name = "sphinx" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/0e/53/feccf1b607de2aef65c6411b4b4a34a91aa8daf397e77258a7774f9d1990/sphinx_substitution_extensions-2025.11.17.tar.gz", hash = "sha256:aae17f8db9efc3d454a304373ae3df763f8739e05e0b98d5381db46f6d250b27", size = 30459, upload-time = "2025-11-17T14:34:45.072Z" } +sdist = { url = "https://files.pythonhosted.org/packages/ca/3e/a82aa5fed0d06161a89dc2f6971b160f837cad44f196c467fc6b2132acaa/sphinx_substitution_extensions-2026.1.12.tar.gz", hash = "sha256:25e0c6c40fbf9e1df593883da946879044a3bf8d85652c8c58f354a53575d736", size = 31676, upload-time = "2026-01-12T06:19:35.324Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/82/df/7e9cd4775c2782c894741c9274cc4c596ad02ab31257e5a5417f0a6af893/sphinx_substitution_extensions-2025.11.17-py2.py3-none-any.whl", hash = "sha256:ac18455bdc8324b337b0fe7498c1c0d0b1cb65c74d131459be4dea9edb6abbef", size = 8741, upload-time = "2025-11-17T14:34:43.66Z" }, + { url = "https://files.pythonhosted.org/packages/9b/5e/9caa7167d2ef2b60326765150d64513be1b61b1864ad58a92683578b2776/sphinx_substitution_extensions-2026.1.12-py2.py3-none-any.whl", hash = "sha256:9152beb4f0f5cab52057681b376a473fa6b997defc85d4ac154dd12b13a3e987", size = 8766, upload-time = "2026-01-12T06:19:33.541Z" }, ] [[package]] name = "sphinx-tabs" -version = "3.4.7" +version = "3.5.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "docutils" }, { name = "pygments" }, { name = "sphinx" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/6a/53/a9a91995cb365e589f413b77fc75f1c0e9b4ac61bfa8da52a779ad855cc0/sphinx-tabs-3.4.7.tar.gz", hash = "sha256:991ad4a424ff54119799ba1491701aa8130dd43509474aef45a81c42d889784d", size = 15891, upload-time = "2024-10-08T13:37:27.887Z" } +sdist = { url = "https://files.pythonhosted.org/packages/ce/30/ca5b0de830f369968d8e3483dd45a8908fd10169c05cd9837f0bd075982e/sphinx_tabs-3.5.0.tar.gz", hash = "sha256:91dba1187e4c35fd37380a56ac228bbd54c6c649b2351829f3bf033718277537", size = 17006, upload-time = "2026-03-03T23:00:30.404Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/6b/c6/f47505b564b918a3ba60c1e99232d4942c4a7e44ecaae603e829e3d05dae/sphinx_tabs-3.4.7-py3-none-any.whl", hash = "sha256:c12d7a36fd413b369e9e9967a0a4015781b71a9c393575419834f19204bd1915", size = 9727, upload-time = "2024-10-08T13:37:26.192Z" }, + { url = "https://files.pythonhosted.org/packages/2e/45/6adc5efeb19fd5fed4027e520b5c668ce58236a2b271ade5533c4c116276/sphinx_tabs-3.5.0-py3-none-any.whl", hash = "sha256:154be49de4d5c8249ea08c5d9bf88ca8f9c31e00a178305a93cbc33e000339e5", size = 9871, upload-time = "2026-03-03T23:00:28.89Z" }, ] [[package]] @@ -997,15 +1019,16 @@ wheels = [ [[package]] name = "sphinxcontrib-mermaid" -version = "1.2.3" +version = "2.0.1" source = { registry = "https://pypi.org/simple" } dependencies = [ + { name = "jinja2" }, { name = "pyyaml" }, { name = "sphinx" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/f5/49/c6ddfe709a4ab76ac6e5a00e696f73626b2c189dc1e1965a361ec102e6cc/sphinxcontrib_mermaid-1.2.3.tar.gz", hash = "sha256:358699d0ec924ef679b41873d9edd97d0773446daf9760c75e18dc0adfd91371", size = 18885, upload-time = "2025-11-26T04:18:32.43Z" } +sdist = { url = "https://files.pythonhosted.org/packages/2b/ae/999891de292919b66ea34f2c22fc22c9be90ab3536fbc0fca95716277351/sphinxcontrib_mermaid-2.0.1.tar.gz", hash = "sha256:a21a385a059a6cafd192aa3a586b14bf5c42721e229db67b459dc825d7f0a497", size = 19839, upload-time = "2026-03-05T14:10:41.901Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/d1/39/8b54299ffa00e597d3b0b4d042241a0a0b22cb429ad007ccfb9c1745b4d1/sphinxcontrib_mermaid-1.2.3-py3-none-any.whl", hash = "sha256:5be782b27026bef97bfb15ccb2f7868b674a1afc0982b54cb149702cfc25aa02", size = 13413, upload-time = "2025-11-26T04:18:31.269Z" }, + { url = "https://files.pythonhosted.org/packages/03/46/25d64bcd7821c8d6f1080e1c43d5fcdfc442a18f759a230b5ccdc891093e/sphinxcontrib_mermaid-2.0.1-py3-none-any.whl", hash = "sha256:9dca7fbe827bad5e7e2b97c4047682cfd26e3e07398cfdc96c7a8842ae7f06e7", size = 14064, upload-time = "2026-03-05T14:10:40.533Z" }, ] [[package]] @@ -1028,57 +1051,64 @@ wheels = [ [[package]] name = "starlette" -version = "0.50.0" +version = "1.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/ba/b8/73a0e6a6e079a9d9cfa64113d771e421640b6f679a52eeb9b32f72d871a1/starlette-0.50.0.tar.gz", hash = "sha256:a2a17b22203254bcbc2e1f926d2d55f3f9497f769416b3190768befe598fa3ca", size = 2646985, upload-time = "2025-11-01T15:25:27.516Z" } +sdist = { url = "https://files.pythonhosted.org/packages/81/69/17425771797c36cded50b7fe44e850315d039f28b15901ab44839e70b593/starlette-1.0.0.tar.gz", hash = "sha256:6a4beaf1f81bb472fd19ea9b918b50dc3a77a6f2e190a12954b25e6ed5eea149", size = 2655289, upload-time = "2026-03-22T18:29:46.779Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/d9/52/1064f510b141bd54025f9b55105e26d1fa970b9be67ad766380a3c9b74b0/starlette-0.50.0-py3-none-any.whl", hash = "sha256:9e5391843ec9b6e472eed1365a78c8098cfceb7a74bfd4d6b1c0c0095efb3bca", size = 74033, upload-time = "2025-11-01T15:25:25.461Z" }, + { url = "https://files.pythonhosted.org/packages/0b/c9/584bc9651441b4ba60cc4d557d8a547b5aff901af35bda3a4ee30c819b82/starlette-1.0.0-py3-none-any.whl", hash = "sha256:d3ec55e0bb321692d275455ddfd3df75fff145d009685eb40dc91fc66b03d38b", size = 72651, upload-time = "2026-03-22T18:29:45.111Z" }, +] + +[[package]] +name = "tabulate" +version = "0.10.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/46/58/8c37dea7bbf769b20d58e7ace7e5edfe65b849442b00ffcdd56be88697c6/tabulate-0.10.0.tar.gz", hash = "sha256:e2cfde8f79420f6deeffdeda9aaec3b6bc5abce947655d17ac662b126e48a60d", size = 91754, upload-time = "2026-03-04T18:55:34.402Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/99/55/db07de81b5c630da5cbf5c7df646580ca26dfaefa593667fc6f2fe016d2e/tabulate-0.10.0-py3-none-any.whl", hash = "sha256:f0b0622e567335c8fabaaa659f1b33bcb6ddfe2e496071b743aa113f8774f2d3", size = 39814, upload-time = "2026-03-04T18:55:31.284Z" }, ] [[package]] name = "tornado" -version = "6.5.2" +version = "6.5.7" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/09/ce/1eb500eae19f4648281bb2186927bb062d2438c2e5093d1360391afd2f90/tornado-6.5.2.tar.gz", hash = "sha256:ab53c8f9a0fa351e2c0741284e06c7a45da86afb544133201c5cc8578eb076a0", size = 510821, upload-time = "2025-08-08T18:27:00.78Z" } +sdist = { url = "https://files.pythonhosted.org/packages/64/24/95ec527ad67b76d59299e5465b3935d05e4294b7e0290a3924b7487df30b/tornado-6.5.7.tar.gz", hash = "sha256:66c513a76cda70d53907bc27cf1447557699c2e95aa48ba27a442ff61c3ddfc2", size = 519252, upload-time = "2026-06-08T17:34:51.232Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/f6/48/6a7529df2c9cc12efd2e8f5dd219516184d703b34c06786809670df5b3bd/tornado-6.5.2-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:2436822940d37cde62771cff8774f4f00b3c8024fe482e16ca8387b8a2724db6", size = 442563, upload-time = "2025-08-08T18:26:42.945Z" }, - { url = "https://files.pythonhosted.org/packages/f2/b5/9b575a0ed3e50b00c40b08cbce82eb618229091d09f6d14bce80fc01cb0b/tornado-6.5.2-cp39-abi3-macosx_10_9_x86_64.whl", hash = "sha256:583a52c7aa94ee046854ba81d9ebb6c81ec0fd30386d96f7640c96dad45a03ef", size = 440729, upload-time = "2025-08-08T18:26:44.473Z" }, - { url = "https://files.pythonhosted.org/packages/1b/4e/619174f52b120efcf23633c817fd3fed867c30bff785e2cd5a53a70e483c/tornado-6.5.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b0fe179f28d597deab2842b86ed4060deec7388f1fd9c1b4a41adf8af058907e", size = 444295, upload-time = "2025-08-08T18:26:46.021Z" }, - { url = "https://files.pythonhosted.org/packages/95/fa/87b41709552bbd393c85dd18e4e3499dcd8983f66e7972926db8d96aa065/tornado-6.5.2-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b186e85d1e3536d69583d2298423744740986018e393d0321df7340e71898882", size = 443644, upload-time = "2025-08-08T18:26:47.625Z" }, - { url = "https://files.pythonhosted.org/packages/f9/41/fb15f06e33d7430ca89420283a8762a4e6b8025b800ea51796ab5e6d9559/tornado-6.5.2-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e792706668c87709709c18b353da1f7662317b563ff69f00bab83595940c7108", size = 443878, upload-time = "2025-08-08T18:26:50.599Z" }, - { url = "https://files.pythonhosted.org/packages/11/92/fe6d57da897776ad2e01e279170ea8ae726755b045fe5ac73b75357a5a3f/tornado-6.5.2-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:06ceb1300fd70cb20e43b1ad8aaee0266e69e7ced38fa910ad2e03285009ce7c", size = 444549, upload-time = "2025-08-08T18:26:51.864Z" }, - { url = "https://files.pythonhosted.org/packages/9b/02/c8f4f6c9204526daf3d760f4aa555a7a33ad0e60843eac025ccfd6ff4a93/tornado-6.5.2-cp39-abi3-musllinux_1_2_i686.whl", hash = "sha256:74db443e0f5251be86cbf37929f84d8c20c27a355dd452a5cfa2aada0d001ec4", size = 443973, upload-time = "2025-08-08T18:26:53.625Z" }, - { url = "https://files.pythonhosted.org/packages/ae/2d/f5f5707b655ce2317190183868cd0f6822a1121b4baeae509ceb9590d0bd/tornado-6.5.2-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:b5e735ab2889d7ed33b32a459cac490eda71a1ba6857b0118de476ab6c366c04", size = 443954, upload-time = "2025-08-08T18:26:55.072Z" }, - { url = "https://files.pythonhosted.org/packages/e8/59/593bd0f40f7355806bf6573b47b8c22f8e1374c9b6fd03114bd6b7a3dcfd/tornado-6.5.2-cp39-abi3-win32.whl", hash = "sha256:c6f29e94d9b37a95013bb669616352ddb82e3bfe8326fccee50583caebc8a5f0", size = 445023, upload-time = "2025-08-08T18:26:56.677Z" }, - { url = "https://files.pythonhosted.org/packages/c7/2a/f609b420c2f564a748a2d80ebfb2ee02a73ca80223af712fca591386cafb/tornado-6.5.2-cp39-abi3-win_amd64.whl", hash = "sha256:e56a5af51cc30dd2cae649429af65ca2f6571da29504a07995175df14c18f35f", size = 445427, upload-time = "2025-08-08T18:26:57.91Z" }, - { url = "https://files.pythonhosted.org/packages/5e/4f/e1f65e8f8c76d73658b33d33b81eed4322fb5085350e4328d5c956f0c8f9/tornado-6.5.2-cp39-abi3-win_arm64.whl", hash = "sha256:d6c33dc3672e3a1f3618eb63b7ef4683a7688e7b9e6e8f0d9aa5726360a004af", size = 444456, upload-time = "2025-08-08T18:26:59.207Z" }, + { url = "https://files.pythonhosted.org/packages/02/dc/c7043cab6fed8ae159fc1923ce829ada35c4dbd797d408a43858ffaf9639/tornado-6.5.7-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:148b2eb15c2c765a50796172c1e499649b35f30d2e3c3d3e15913cfa56bfb163", size = 448543, upload-time = "2026-06-08T17:34:38.052Z" }, + { url = "https://files.pythonhosted.org/packages/92/4f/090b1431e5a43df696feceffc268c5383cc079ecb5f08ce58f917109aafe/tornado-6.5.7-cp39-abi3-macosx_10_9_x86_64.whl", hash = "sha256:9da38de27f1da3b78a966f0dae12b5a1ea9afe72ca805d84ff06508272ddf100", size = 446707, upload-time = "2026-06-08T17:34:39.594Z" }, + { url = "https://files.pythonhosted.org/packages/37/d8/ef374952fd5da67d4463122c2b8e5a96536ec10b4b339254c6dcde81d01c/tornado-6.5.7-cp39-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8d759e71906ee783f8867b93bf26a265743da4c1e2f4a018464c1ba019862972", size = 449774, upload-time = "2026-06-08T17:34:41.204Z" }, + { url = "https://files.pythonhosted.org/packages/35/37/d434c73f4c6e014b745b9b37085f34f40c022f007efff3d7fe65991899f3/tornado-6.5.7-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8a46347a18f23fb92b396beebe0fb78f61dda0cc302445202c16203d8a18848b", size = 450745, upload-time = "2026-06-08T17:34:42.531Z" }, + { url = "https://files.pythonhosted.org/packages/b6/2b/56b9aff361d7f1ab728a805ec7d7ea835f8807afa9f5cc690ea0e630efb9/tornado-6.5.7-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:7778b30bef919231265e91c69963ce0f49a1e9c07ac900bbe75b19ce2575ba92", size = 450578, upload-time = "2026-06-08T17:34:43.787Z" }, + { url = "https://files.pythonhosted.org/packages/02/30/a7444fb23aa76860a14198fab96ac79f1866b0a6e19e26c4381b0938e50f/tornado-6.5.7-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:e726f0c75da7726eec023aa62751ff8878bd2737e34fbdd33b1ae5897d2200f5", size = 449985, upload-time = "2026-06-08T17:34:45.326Z" }, + { url = "https://files.pythonhosted.org/packages/5c/42/5f0e56c01e8d9d36f4e23f367b85ae6cae0c1ecddd5e6977d8388ad27488/tornado-6.5.7-cp39-abi3-win32.whl", hash = "sha256:f8de3bf12d3efdd0cbe7c8887868198f8a91415e3f29fcf258d9b8eb7b1d9ae4", size = 451047, upload-time = "2026-06-08T17:34:46.784Z" }, + { url = "https://files.pythonhosted.org/packages/c9/a4/b393076ffb21b469eec5b328a0534cf03a3b90bfc6b1f09507cdd075d938/tornado-6.5.7-cp39-abi3-win_amd64.whl", hash = "sha256:de942f843533a039ef9fa3d9c88c7cd8a7c94553fb5ad0154270989b3d99a2c4", size = 451485, upload-time = "2026-06-08T17:34:48.248Z" }, + { url = "https://files.pythonhosted.org/packages/71/2e/7b1c769803121b809112cf9a00681c472eae1d80e32d7ec0e0bd61d0d0e1/tornado-6.5.7-cp39-abi3-win_arm64.whl", hash = "sha256:ff934fce95643af5f11efdae618eaa73d469dc588641e5c8d19295a0c65c4796", size = 450506, upload-time = "2026-06-08T17:34:49.702Z" }, ] [[package]] name = "trove-classifiers" -version = "2025.12.1.14" +version = "2026.1.14.14" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/80/e1/000add3b3e0725ce7ee0ea6ea4543f1e1d9519742f3b2320de41eeefa7c7/trove_classifiers-2025.12.1.14.tar.gz", hash = "sha256:a74f0400524fc83620a9be74a07074b5cbe7594fd4d97fd4c2bfde625fdc1633", size = 16985, upload-time = "2025-12-01T14:47:11.456Z" } +sdist = { url = "https://files.pythonhosted.org/packages/d8/43/7935f8ea93fcb6680bc10a6fdbf534075c198eeead59150dd5ed68449642/trove_classifiers-2026.1.14.14.tar.gz", hash = "sha256:00492545a1402b09d4858605ba190ea33243d361e2b01c9c296ce06b5c3325f3", size = 16997, upload-time = "2026-01-14T14:54:50.526Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/4f/7e/bc19996fa86cad8801e8ffe6f1bba5836ca0160df76d0410d27432193712/trove_classifiers-2025.12.1.14-py3-none-any.whl", hash = "sha256:a8206978ede95937b9959c3aff3eb258bbf7b07dff391ddd4ea7e61f316635ab", size = 14184, upload-time = "2025-12-01T14:47:10.113Z" }, + { url = "https://files.pythonhosted.org/packages/bb/4a/2e5583e544bc437d5e8e54b47db87430df9031b29b48d17f26d129fa60c0/trove_classifiers-2026.1.14.14-py3-none-any.whl", hash = "sha256:1f9553927f18d0513d8e5ff80ab8980b8202ce37ecae0e3274ed2ef11880e74d", size = 14197, upload-time = "2026-01-14T14:54:49.067Z" }, ] [[package]] name = "typer" -version = "0.20.0" +version = "0.24.1" source = { registry = "https://pypi.org/simple" } dependencies = [ + { name = "annotated-doc" }, { name = "click" }, { name = "rich" }, { name = "shellingham" }, - { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/8f/28/7c85c8032b91dbe79725b6f17d2fffc595dff06a35c7a30a37bef73a1ab4/typer-0.20.0.tar.gz", hash = "sha256:1aaf6494031793e4876fb0bacfa6a912b551cf43c1e63c800df8b1a866720c37", size = 106492, upload-time = "2025-10-20T17:03:49.445Z" } +sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/78/64/7713ffe4b5983314e9d436a90d5bd4f63b6054e2aca783a3cfc44cb95bbf/typer-0.20.0-py3-none-any.whl", hash = "sha256:5b463df6793ec1dca6213a3cf4c0f03bc6e322ac5e16e13ddd622a889489784a", size = 47028, upload-time = "2025-10-20T17:03:47.617Z" }, + { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" }, ] [[package]] @@ -1092,24 +1122,24 @@ wheels = [ [[package]] name = "urllib3" -version = "2.6.3" +version = "2.7.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" } +sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" }, + { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" }, ] [[package]] name = "uvicorn" -version = "0.38.0" +version = "0.44.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "click" }, { name = "h11" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/cb/ce/f06b84e2697fef4688ca63bdb2fdf113ca0a3be33f94488f2cadb690b0cf/uvicorn-0.38.0.tar.gz", hash = "sha256:fd97093bdd120a2609fc0d3afe931d4d4ad688b6e75f0f929fde1bc36fe0e91d", size = 80605, upload-time = "2025-10-18T13:46:44.63Z" } +sdist = { url = "https://files.pythonhosted.org/packages/5e/da/6eee1ff8b6cbeed47eeb5229749168e81eb4b7b999a1a15a7176e51410c9/uvicorn-0.44.0.tar.gz", hash = "sha256:6c942071b68f07e178264b9152f1f16dfac5da85880c4ce06366a96d70d4f31e", size = 86947, upload-time = "2026-04-06T09:23:22.826Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/ee/d9/d88e73ca598f4f6ff671fb5fde8a32925c2e08a637303a1d12883c7305fa/uvicorn-0.38.0-py3-none-any.whl", hash = "sha256:48c0afd214ceb59340075b4a052ea1ee91c16fbc2a9b1469cca0e54566977b02", size = 68109, upload-time = "2025-10-18T13:46:42.958Z" }, + { url = "https://files.pythonhosted.org/packages/b7/23/a5bbd9600dd607411fa644c06ff4951bec3a4d82c4b852374024359c19c0/uvicorn-0.44.0-py3-none-any.whl", hash = "sha256:ce937c99a2cc70279556967274414c087888e8cec9f9c94644dfca11bd3ced89", size = 69425, upload-time = "2026-04-06T09:23:21.524Z" }, ] [[package]] @@ -1148,68 +1178,70 @@ wheels = [ [[package]] name = "websockets" -version = "15.0.1" +version = "16.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/21/e6/26d09fab466b7ca9c7737474c52be4f76a40301b08362eb2dbc19dcc16c1/websockets-15.0.1.tar.gz", hash = "sha256:82544de02076bafba038ce055ee6412d68da13ab47f0c60cab827346de828dee", size = 177016, upload-time = "2025-03-05T20:03:41.606Z" } +sdist = { url = "https://files.pythonhosted.org/packages/04/24/4b2031d72e840ce4c1ccb255f693b15c334757fc50023e4db9537080b8c4/websockets-16.0.tar.gz", hash = "sha256:5f6261a5e56e8d5c42a4497b364ea24d94d9563e8fbd44e78ac40879c60179b5", size = 179346, upload-time = "2026-01-10T09:23:47.181Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/cb/9f/51f0cf64471a9d2b4d0fc6c534f323b664e7095640c34562f5182e5a7195/websockets-15.0.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:ee443ef070bb3b6ed74514f5efaa37a252af57c90eb33b956d35c8e9c10a1931", size = 175440, upload-time = "2025-03-05T20:02:36.695Z" }, - { url = "https://files.pythonhosted.org/packages/8a/05/aa116ec9943c718905997412c5989f7ed671bc0188ee2ba89520e8765d7b/websockets-15.0.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5a939de6b7b4e18ca683218320fc67ea886038265fd1ed30173f5ce3f8e85675", size = 173098, upload-time = "2025-03-05T20:02:37.985Z" }, - { url = "https://files.pythonhosted.org/packages/ff/0b/33cef55ff24f2d92924923c99926dcce78e7bd922d649467f0eda8368923/websockets-15.0.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:746ee8dba912cd6fc889a8147168991d50ed70447bf18bcda7039f7d2e3d9151", size = 173329, upload-time = "2025-03-05T20:02:39.298Z" }, - { url = "https://files.pythonhosted.org/packages/31/1d/063b25dcc01faa8fada1469bdf769de3768b7044eac9d41f734fd7b6ad6d/websockets-15.0.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:595b6c3969023ecf9041b2936ac3827e4623bfa3ccf007575f04c5a6aa318c22", size = 183111, upload-time = "2025-03-05T20:02:40.595Z" }, - { url = "https://files.pythonhosted.org/packages/93/53/9a87ee494a51bf63e4ec9241c1ccc4f7c2f45fff85d5bde2ff74fcb68b9e/websockets-15.0.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3c714d2fc58b5ca3e285461a4cc0c9a66bd0e24c5da9911e30158286c9b5be7f", size = 182054, upload-time = "2025-03-05T20:02:41.926Z" }, - { url = "https://files.pythonhosted.org/packages/ff/b2/83a6ddf56cdcbad4e3d841fcc55d6ba7d19aeb89c50f24dd7e859ec0805f/websockets-15.0.1-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f3c1e2ab208db911594ae5b4f79addeb3501604a165019dd221c0bdcabe4db8", size = 182496, upload-time = "2025-03-05T20:02:43.304Z" }, - { url = "https://files.pythonhosted.org/packages/98/41/e7038944ed0abf34c45aa4635ba28136f06052e08fc2168520bb8b25149f/websockets-15.0.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:229cf1d3ca6c1804400b0a9790dc66528e08a6a1feec0d5040e8b9eb14422375", size = 182829, upload-time = "2025-03-05T20:02:48.812Z" }, - { url = "https://files.pythonhosted.org/packages/e0/17/de15b6158680c7623c6ef0db361da965ab25d813ae54fcfeae2e5b9ef910/websockets-15.0.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:756c56e867a90fb00177d530dca4b097dd753cde348448a1012ed6c5131f8b7d", size = 182217, upload-time = "2025-03-05T20:02:50.14Z" }, - { url = "https://files.pythonhosted.org/packages/33/2b/1f168cb6041853eef0362fb9554c3824367c5560cbdaad89ac40f8c2edfc/websockets-15.0.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:558d023b3df0bffe50a04e710bc87742de35060580a293c2a984299ed83bc4e4", size = 182195, upload-time = "2025-03-05T20:02:51.561Z" }, - { url = "https://files.pythonhosted.org/packages/86/eb/20b6cdf273913d0ad05a6a14aed4b9a85591c18a987a3d47f20fa13dcc47/websockets-15.0.1-cp313-cp313-win32.whl", hash = "sha256:ba9e56e8ceeeedb2e080147ba85ffcd5cd0711b89576b83784d8605a7df455fa", size = 176393, upload-time = "2025-03-05T20:02:53.814Z" }, - { url = "https://files.pythonhosted.org/packages/1b/6c/c65773d6cab416a64d191d6ee8a8b1c68a09970ea6909d16965d26bfed1e/websockets-15.0.1-cp313-cp313-win_amd64.whl", hash = "sha256:e09473f095a819042ecb2ab9465aee615bd9c2028e4ef7d933600a8401c79561", size = 176837, upload-time = "2025-03-05T20:02:55.237Z" }, - { url = "https://files.pythonhosted.org/packages/fa/a8/5b41e0da817d64113292ab1f8247140aac61cbf6cfd085d6a0fa77f4984f/websockets-15.0.1-py3-none-any.whl", hash = "sha256:f7a866fbc1e97b5c617ee4116daaa09b722101d4a3c170c787450ba409f9736f", size = 169743, upload-time = "2025-03-05T20:03:39.41Z" }, + { url = "https://files.pythonhosted.org/packages/cc/9c/baa8456050d1c1b08dd0ec7346026668cbc6f145ab4e314d707bb845bf0d/websockets-16.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:878b336ac47938b474c8f982ac2f7266a540adc3fa4ad74ae96fea9823a02cc9", size = 177364, upload-time = "2026-01-10T09:22:59.333Z" }, + { url = "https://files.pythonhosted.org/packages/7e/0c/8811fc53e9bcff68fe7de2bcbe75116a8d959ac699a3200f4847a8925210/websockets-16.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:52a0fec0e6c8d9a784c2c78276a48a2bdf099e4ccc2a4cad53b27718dbfd0230", size = 175039, upload-time = "2026-01-10T09:23:01.171Z" }, + { url = "https://files.pythonhosted.org/packages/aa/82/39a5f910cb99ec0b59e482971238c845af9220d3ab9fa76dd9162cda9d62/websockets-16.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e6578ed5b6981005df1860a56e3617f14a6c307e6a71b4fff8c48fdc50f3ed2c", size = 175323, upload-time = "2026-01-10T09:23:02.341Z" }, + { url = "https://files.pythonhosted.org/packages/bd/28/0a25ee5342eb5d5f297d992a77e56892ecb65e7854c7898fb7d35e9b33bd/websockets-16.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:95724e638f0f9c350bb1c2b0a7ad0e83d9cc0c9259f3ea94e40d7b02a2179ae5", size = 184975, upload-time = "2026-01-10T09:23:03.756Z" }, + { url = "https://files.pythonhosted.org/packages/f9/66/27ea52741752f5107c2e41fda05e8395a682a1e11c4e592a809a90c6a506/websockets-16.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c0204dc62a89dc9d50d682412c10b3542d748260d743500a85c13cd1ee4bde82", size = 186203, upload-time = "2026-01-10T09:23:05.01Z" }, + { url = "https://files.pythonhosted.org/packages/37/e5/8e32857371406a757816a2b471939d51c463509be73fa538216ea52b792a/websockets-16.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:52ac480f44d32970d66763115edea932f1c5b1312de36df06d6b219f6741eed8", size = 185653, upload-time = "2026-01-10T09:23:06.301Z" }, + { url = "https://files.pythonhosted.org/packages/9b/67/f926bac29882894669368dc73f4da900fcdf47955d0a0185d60103df5737/websockets-16.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6e5a82b677f8f6f59e8dfc34ec06ca6b5b48bc4fcda346acd093694cc2c24d8f", size = 184920, upload-time = "2026-01-10T09:23:07.492Z" }, + { url = "https://files.pythonhosted.org/packages/3c/a1/3d6ccdcd125b0a42a311bcd15a7f705d688f73b2a22d8cf1c0875d35d34a/websockets-16.0-cp313-cp313-win32.whl", hash = "sha256:abf050a199613f64c886ea10f38b47770a65154dc37181bfaff70c160f45315a", size = 178255, upload-time = "2026-01-10T09:23:09.245Z" }, + { url = "https://files.pythonhosted.org/packages/6b/ae/90366304d7c2ce80f9b826096a9e9048b4bb760e44d3b873bb272cba696b/websockets-16.0-cp313-cp313-win_amd64.whl", hash = "sha256:3425ac5cf448801335d6fdc7ae1eb22072055417a96cc6b31b3861f455fbc156", size = 178689, upload-time = "2026-01-10T09:23:10.483Z" }, + { url = "https://files.pythonhosted.org/packages/6f/28/258ebab549c2bf3e64d2b0217b973467394a9cea8c42f70418ca2c5d0d2e/websockets-16.0-py3-none-any.whl", hash = "sha256:1637db62fad1dc833276dded54215f2c7fa46912301a24bd94d45d46a011ceec", size = 171598, upload-time = "2026-01-10T09:23:45.395Z" }, ] [[package]] name = "yarl" -version = "1.22.0" +version = "1.23.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "idna" }, { name = "multidict" }, { name = "propcache" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/57/63/0c6ebca57330cd313f6102b16dd57ffaf3ec4c83403dcb45dbd15c6f3ea1/yarl-1.22.0.tar.gz", hash = "sha256:bebf8557577d4401ba8bd9ff33906f1376c877aa78d1fe216ad01b4d6745af71", size = 187169, upload-time = "2025-10-06T14:12:55.963Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/ea/f3/d67de7260456ee105dc1d162d43a019ecad6b91e2f51809d6cddaa56690e/yarl-1.22.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:8dee9c25c74997f6a750cd317b8ca63545169c098faee42c84aa5e506c819b53", size = 139980, upload-time = "2025-10-06T14:10:14.601Z" }, - { url = "https://files.pythonhosted.org/packages/01/88/04d98af0b47e0ef42597b9b28863b9060bb515524da0a65d5f4db160b2d5/yarl-1.22.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:01e73b85a5434f89fc4fe27dcda2aff08ddf35e4d47bbbea3bdcd25321af538a", size = 93424, upload-time = "2025-10-06T14:10:16.115Z" }, - { url = "https://files.pythonhosted.org/packages/18/91/3274b215fd8442a03975ce6bee5fe6aa57a8326b29b9d3d56234a1dca244/yarl-1.22.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:22965c2af250d20c873cdbee8ff958fb809940aeb2e74ba5f20aaf6b7ac8c70c", size = 93821, upload-time = "2025-10-06T14:10:17.993Z" }, - { url = "https://files.pythonhosted.org/packages/61/3a/caf4e25036db0f2da4ca22a353dfeb3c9d3c95d2761ebe9b14df8fc16eb0/yarl-1.22.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b4f15793aa49793ec8d1c708ab7f9eded1aa72edc5174cae703651555ed1b601", size = 373243, upload-time = "2025-10-06T14:10:19.44Z" }, - { url = "https://files.pythonhosted.org/packages/6e/9e/51a77ac7516e8e7803b06e01f74e78649c24ee1021eca3d6a739cb6ea49c/yarl-1.22.0-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e5542339dcf2747135c5c85f68680353d5cb9ffd741c0f2e8d832d054d41f35a", size = 342361, upload-time = "2025-10-06T14:10:21.124Z" }, - { url = "https://files.pythonhosted.org/packages/d4/f8/33b92454789dde8407f156c00303e9a891f1f51a0330b0fad7c909f87692/yarl-1.22.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:5c401e05ad47a75869c3ab3e35137f8468b846770587e70d71e11de797d113df", size = 387036, upload-time = "2025-10-06T14:10:22.902Z" }, - { url = "https://files.pythonhosted.org/packages/d9/9a/c5db84ea024f76838220280f732970aa4ee154015d7f5c1bfb60a267af6f/yarl-1.22.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:243dda95d901c733f5b59214d28b0120893d91777cb8aa043e6ef059d3cddfe2", size = 397671, upload-time = "2025-10-06T14:10:24.523Z" }, - { url = "https://files.pythonhosted.org/packages/11/c9/cd8538dc2e7727095e0c1d867bad1e40c98f37763e6d995c1939f5fdc7b1/yarl-1.22.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bec03d0d388060058f5d291a813f21c011041938a441c593374da6077fe21b1b", size = 377059, upload-time = "2025-10-06T14:10:26.406Z" }, - { url = "https://files.pythonhosted.org/packages/a1/b9/ab437b261702ced75122ed78a876a6dec0a1b0f5e17a4ac7a9a2482d8abe/yarl-1.22.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:b0748275abb8c1e1e09301ee3cf90c8a99678a4e92e4373705f2a2570d581273", size = 365356, upload-time = "2025-10-06T14:10:28.461Z" }, - { url = "https://files.pythonhosted.org/packages/b2/9d/8e1ae6d1d008a9567877b08f0ce4077a29974c04c062dabdb923ed98e6fe/yarl-1.22.0-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:47fdb18187e2a4e18fda2c25c05d8251a9e4a521edaed757fef033e7d8498d9a", size = 361331, upload-time = "2025-10-06T14:10:30.541Z" }, - { url = "https://files.pythonhosted.org/packages/ca/5a/09b7be3905962f145b73beb468cdd53db8aa171cf18c80400a54c5b82846/yarl-1.22.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:c7044802eec4524fde550afc28edda0dd5784c4c45f0be151a2d3ba017daca7d", size = 382590, upload-time = "2025-10-06T14:10:33.352Z" }, - { url = "https://files.pythonhosted.org/packages/aa/7f/59ec509abf90eda5048b0bc3e2d7b5099dffdb3e6b127019895ab9d5ef44/yarl-1.22.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:139718f35149ff544caba20fce6e8a2f71f1e39b92c700d8438a0b1d2a631a02", size = 385316, upload-time = "2025-10-06T14:10:35.034Z" }, - { url = "https://files.pythonhosted.org/packages/e5/84/891158426bc8036bfdfd862fabd0e0fa25df4176ec793e447f4b85cf1be4/yarl-1.22.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e1b51bebd221006d3d2f95fbe124b22b247136647ae5dcc8c7acafba66e5ee67", size = 374431, upload-time = "2025-10-06T14:10:37.76Z" }, - { url = "https://files.pythonhosted.org/packages/bb/49/03da1580665baa8bef5e8ed34c6df2c2aca0a2f28bf397ed238cc1bbc6f2/yarl-1.22.0-cp313-cp313-win32.whl", hash = "sha256:d3e32536234a95f513bd374e93d717cf6b2231a791758de6c509e3653f234c95", size = 81555, upload-time = "2025-10-06T14:10:39.649Z" }, - { url = "https://files.pythonhosted.org/packages/9a/ee/450914ae11b419eadd067c6183ae08381cfdfcb9798b90b2b713bbebddda/yarl-1.22.0-cp313-cp313-win_amd64.whl", hash = "sha256:47743b82b76d89a1d20b83e60d5c20314cbd5ba2befc9cda8f28300c4a08ed4d", size = 86965, upload-time = "2025-10-06T14:10:41.313Z" }, - { url = "https://files.pythonhosted.org/packages/98/4d/264a01eae03b6cf629ad69bae94e3b0e5344741e929073678e84bf7a3e3b/yarl-1.22.0-cp313-cp313-win_arm64.whl", hash = "sha256:5d0fcda9608875f7d052eff120c7a5da474a6796fe4d83e152e0e4d42f6d1a9b", size = 81205, upload-time = "2025-10-06T14:10:43.167Z" }, - { url = "https://files.pythonhosted.org/packages/88/fc/6908f062a2f77b5f9f6d69cecb1747260831ff206adcbc5b510aff88df91/yarl-1.22.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:719ae08b6972befcba4310e49edb1161a88cdd331e3a694b84466bd938a6ab10", size = 146209, upload-time = "2025-10-06T14:10:44.643Z" }, - { url = "https://files.pythonhosted.org/packages/65/47/76594ae8eab26210b4867be6f49129861ad33da1f1ebdf7051e98492bf62/yarl-1.22.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:47d8a5c446df1c4db9d21b49619ffdba90e77c89ec6e283f453856c74b50b9e3", size = 95966, upload-time = "2025-10-06T14:10:46.554Z" }, - { url = "https://files.pythonhosted.org/packages/ab/ce/05e9828a49271ba6b5b038b15b3934e996980dd78abdfeb52a04cfb9467e/yarl-1.22.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:cfebc0ac8333520d2d0423cbbe43ae43c8838862ddb898f5ca68565e395516e9", size = 97312, upload-time = "2025-10-06T14:10:48.007Z" }, - { url = "https://files.pythonhosted.org/packages/d1/c5/7dffad5e4f2265b29c9d7ec869c369e4223166e4f9206fc2243ee9eea727/yarl-1.22.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4398557cbf484207df000309235979c79c4356518fd5c99158c7d38203c4da4f", size = 361967, upload-time = "2025-10-06T14:10:49.997Z" }, - { url = "https://files.pythonhosted.org/packages/50/b2/375b933c93a54bff7fc041e1a6ad2c0f6f733ffb0c6e642ce56ee3b39970/yarl-1.22.0-cp313-cp313t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:2ca6fd72a8cd803be290d42f2dec5cdcd5299eeb93c2d929bf060ad9efaf5de0", size = 323949, upload-time = "2025-10-06T14:10:52.004Z" }, - { url = "https://files.pythonhosted.org/packages/66/50/bfc2a29a1d78644c5a7220ce2f304f38248dc94124a326794e677634b6cf/yarl-1.22.0-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ca1f59c4e1ab6e72f0a23c13fca5430f889634166be85dbf1013683e49e3278e", size = 361818, upload-time = "2025-10-06T14:10:54.078Z" }, - { url = "https://files.pythonhosted.org/packages/46/96/f3941a46af7d5d0f0498f86d71275696800ddcdd20426298e572b19b91ff/yarl-1.22.0-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:6c5010a52015e7c70f86eb967db0f37f3c8bd503a695a49f8d45700144667708", size = 372626, upload-time = "2025-10-06T14:10:55.767Z" }, - { url = "https://files.pythonhosted.org/packages/c1/42/8b27c83bb875cd89448e42cd627e0fb971fa1675c9ec546393d18826cb50/yarl-1.22.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d7672ecf7557476642c88497c2f8d8542f8e36596e928e9bcba0e42e1e7d71f", size = 341129, upload-time = "2025-10-06T14:10:57.985Z" }, - { url = "https://files.pythonhosted.org/packages/49/36/99ca3122201b382a3cf7cc937b95235b0ac944f7e9f2d5331d50821ed352/yarl-1.22.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:3b7c88eeef021579d600e50363e0b6ee4f7f6f728cd3486b9d0f3ee7b946398d", size = 346776, upload-time = "2025-10-06T14:10:59.633Z" }, - { url = "https://files.pythonhosted.org/packages/85/b4/47328bf996acd01a4c16ef9dcd2f59c969f495073616586f78cd5f2efb99/yarl-1.22.0-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:f4afb5c34f2c6fecdcc182dfcfc6af6cccf1aa923eed4d6a12e9d96904e1a0d8", size = 334879, upload-time = "2025-10-06T14:11:01.454Z" }, - { url = "https://files.pythonhosted.org/packages/c2/ad/b77d7b3f14a4283bffb8e92c6026496f6de49751c2f97d4352242bba3990/yarl-1.22.0-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:59c189e3e99a59cf8d83cbb31d4db02d66cda5a1a4374e8a012b51255341abf5", size = 350996, upload-time = "2025-10-06T14:11:03.452Z" }, - { url = "https://files.pythonhosted.org/packages/81/c8/06e1d69295792ba54d556f06686cbd6a7ce39c22307100e3fb4a2c0b0a1d/yarl-1.22.0-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:5a3bf7f62a289fa90f1990422dc8dff5a458469ea71d1624585ec3a4c8d6960f", size = 356047, upload-time = "2025-10-06T14:11:05.115Z" }, - { url = "https://files.pythonhosted.org/packages/4b/b8/4c0e9e9f597074b208d18cef227d83aac36184bfbc6eab204ea55783dbc5/yarl-1.22.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:de6b9a04c606978fdfe72666fa216ffcf2d1a9f6a381058d4378f8d7b1e5de62", size = 342947, upload-time = "2025-10-06T14:11:08.137Z" }, - { url = "https://files.pythonhosted.org/packages/e0/e5/11f140a58bf4c6ad7aca69a892bff0ee638c31bea4206748fc0df4ebcb3a/yarl-1.22.0-cp313-cp313t-win32.whl", hash = "sha256:1834bb90991cc2999f10f97f5f01317f99b143284766d197e43cd5b45eb18d03", size = 86943, upload-time = "2025-10-06T14:11:10.284Z" }, - { url = "https://files.pythonhosted.org/packages/31/74/8b74bae38ed7fe6793d0c15a0c8207bbb819cf287788459e5ed230996cdd/yarl-1.22.0-cp313-cp313t-win_amd64.whl", hash = "sha256:ff86011bd159a9d2dfc89c34cfd8aff12875980e3bd6a39ff097887520e60249", size = 93715, upload-time = "2025-10-06T14:11:11.739Z" }, - { url = "https://files.pythonhosted.org/packages/69/66/991858aa4b5892d57aef7ee1ba6b4d01ec3b7eb3060795d34090a3ca3278/yarl-1.22.0-cp313-cp313t-win_arm64.whl", hash = "sha256:7861058d0582b847bc4e3a4a4c46828a410bca738673f35a29ba3ca5db0b473b", size = 83857, upload-time = "2025-10-06T14:11:13.586Z" }, - { url = "https://files.pythonhosted.org/packages/73/ae/b48f95715333080afb75a4504487cbe142cae1268afc482d06692d605ae6/yarl-1.22.0-py3-none-any.whl", hash = "sha256:1380560bdba02b6b6c90de54133c81c9f2a453dee9912fe58c1dcced1edb7cff", size = 46814, upload-time = "2025-10-06T14:12:53.872Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/23/6e/beb1beec874a72f23815c1434518bfc4ed2175065173fb138c3705f658d4/yarl-1.23.0.tar.gz", hash = "sha256:53b1ea6ca88ebd4420379c330aea57e258408dd0df9af0992e5de2078dc9f5d5", size = 194676, upload-time = "2026-03-01T22:07:53.373Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9a/4b/a0a6e5d0ee8a2f3a373ddef8a4097d74ac901ac363eea1440464ccbe0898/yarl-1.23.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:16c6994ac35c3e74fb0ae93323bf8b9c2a9088d55946109489667c510a7d010e", size = 123796, upload-time = "2026-03-01T22:05:41.412Z" }, + { url = "https://files.pythonhosted.org/packages/67/b6/8925d68af039b835ae876db5838e82e76ec87b9782ecc97e192b809c4831/yarl-1.23.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:4a42e651629dafb64fd5b0286a3580613702b5809ad3f24934ea87595804f2c5", size = 86547, upload-time = "2026-03-01T22:05:42.841Z" }, + { url = "https://files.pythonhosted.org/packages/ae/50/06d511cc4b8e0360d3c94af051a768e84b755c5eb031b12adaaab6dec6e5/yarl-1.23.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:7c6b9461a2a8b47c65eef63bb1c76a4f1c119618ffa99ea79bc5bb1e46c5821b", size = 85854, upload-time = "2026-03-01T22:05:44.85Z" }, + { url = "https://files.pythonhosted.org/packages/c4/f4/4e30b250927ffdab4db70da08b9b8d2194d7c7b400167b8fbeca1e4701ca/yarl-1.23.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2569b67d616eab450d262ca7cb9f9e19d2f718c70a8b88712859359d0ab17035", size = 98351, upload-time = "2026-03-01T22:05:46.836Z" }, + { url = "https://files.pythonhosted.org/packages/86/fc/4118c5671ea948208bdb1492d8b76bdf1453d3e73df051f939f563e7dcc5/yarl-1.23.0-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e9d9a4d06d3481eab79803beb4d9bd6f6a8e781ec078ac70d7ef2dcc29d1bea5", size = 92711, upload-time = "2026-03-01T22:05:48.316Z" }, + { url = "https://files.pythonhosted.org/packages/56/11/1ed91d42bd9e73c13dc9e7eb0dd92298d75e7ac4dd7f046ad0c472e231cd/yarl-1.23.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f514f6474e04179d3d33175ed3f3e31434d3130d42ec153540d5b157deefd735", size = 106014, upload-time = "2026-03-01T22:05:50.028Z" }, + { url = "https://files.pythonhosted.org/packages/ce/c9/74e44e056a23fbc33aca71779ef450ca648a5bc472bdad7a82339918f818/yarl-1.23.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:fda207c815b253e34f7e1909840fd14299567b1c0eb4908f8c2ce01a41265401", size = 105557, upload-time = "2026-03-01T22:05:51.416Z" }, + { url = "https://files.pythonhosted.org/packages/66/fe/b1e10b08d287f518994f1e2ff9b6d26f0adeecd8dd7d533b01bab29a3eda/yarl-1.23.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:34b6cf500e61c90f305094911f9acc9c86da1a05a7a3f5be9f68817043f486e4", size = 101559, upload-time = "2026-03-01T22:05:52.872Z" }, + { url = "https://files.pythonhosted.org/packages/72/59/c5b8d94b14e3d3c2a9c20cb100119fd534ab5a14b93673ab4cc4a4141ea5/yarl-1.23.0-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:d7504f2b476d21653e4d143f44a175f7f751cd41233525312696c76aa3dbb23f", size = 100502, upload-time = "2026-03-01T22:05:54.954Z" }, + { url = "https://files.pythonhosted.org/packages/77/4f/96976cb54cbfc5c9fd73ed4c51804f92f209481d1fb190981c0f8a07a1d7/yarl-1.23.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:578110dd426f0d209d1509244e6d4a3f1a3e9077655d98c5f22583d63252a08a", size = 98027, upload-time = "2026-03-01T22:05:56.409Z" }, + { url = "https://files.pythonhosted.org/packages/63/6e/904c4f476471afdbad6b7e5b70362fb5810e35cd7466529a97322b6f5556/yarl-1.23.0-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:609d3614d78d74ebe35f54953c5bbd2ac647a7ddb9c30a5d877580f5e86b22f2", size = 95369, upload-time = "2026-03-01T22:05:58.141Z" }, + { url = "https://files.pythonhosted.org/packages/9d/40/acfcdb3b5f9d68ef499e39e04d25e141fe90661f9d54114556cf83be8353/yarl-1.23.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:4966242ec68afc74c122f8459abd597afd7d8a60dc93d695c1334c5fd25f762f", size = 105565, upload-time = "2026-03-01T22:06:00.286Z" }, + { url = "https://files.pythonhosted.org/packages/5e/c6/31e28f3a6ba2869c43d124f37ea5260cac9c9281df803c354b31f4dd1f3c/yarl-1.23.0-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:e0fd068364a6759bc794459f0a735ab151d11304346332489c7972bacbe9e72b", size = 99813, upload-time = "2026-03-01T22:06:01.712Z" }, + { url = "https://files.pythonhosted.org/packages/08/1f/6f65f59e72d54aa467119b63fc0b0b1762eff0232db1f4720cd89e2f4a17/yarl-1.23.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:39004f0ad156da43e86aa71f44e033de68a44e5a31fc53507b36dd253970054a", size = 105632, upload-time = "2026-03-01T22:06:03.188Z" }, + { url = "https://files.pythonhosted.org/packages/a3/c4/18b178a69935f9e7a338127d5b77d868fdc0f0e49becd286d51b3a18c61d/yarl-1.23.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e5723c01a56c5028c807c701aa66722916d2747ad737a046853f6c46f4875543", size = 101895, upload-time = "2026-03-01T22:06:04.651Z" }, + { url = "https://files.pythonhosted.org/packages/8f/54/f5b870b5505663911dba950a8e4776a0dbd51c9c54c0ae88e823e4b874a0/yarl-1.23.0-cp313-cp313-win32.whl", hash = "sha256:1b6b572edd95b4fa8df75de10b04bc81acc87c1c7d16bcdd2035b09d30acc957", size = 82356, upload-time = "2026-03-01T22:06:06.04Z" }, + { url = "https://files.pythonhosted.org/packages/7a/84/266e8da36879c6edcd37b02b547e2d9ecdfea776be49598e75696e3316e1/yarl-1.23.0-cp313-cp313-win_amd64.whl", hash = "sha256:baaf55442359053c7d62f6f8413a62adba3205119bcb6f49594894d8be47e5e3", size = 87515, upload-time = "2026-03-01T22:06:08.107Z" }, + { url = "https://files.pythonhosted.org/packages/00/fd/7e1c66efad35e1649114fa13f17485f62881ad58edeeb7f49f8c5e748bf9/yarl-1.23.0-cp313-cp313-win_arm64.whl", hash = "sha256:fb4948814a2a98e3912505f09c9e7493b1506226afb1f881825368d6fb776ee3", size = 81785, upload-time = "2026-03-01T22:06:10.181Z" }, + { url = "https://files.pythonhosted.org/packages/9c/fc/119dd07004f17ea43bb91e3ece6587759edd7519d6b086d16bfbd3319982/yarl-1.23.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:aecfed0b41aa72b7881712c65cf764e39ce2ec352324f5e0837c7048d9e6daaa", size = 130719, upload-time = "2026-03-01T22:06:11.708Z" }, + { url = "https://files.pythonhosted.org/packages/e6/0d/9f2348502fbb3af409e8f47730282cd6bc80dec6630c1e06374d882d6eb2/yarl-1.23.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:a41bcf68efd19073376eb8cf948b8d9be0af26256403e512bb18f3966f1f9120", size = 89690, upload-time = "2026-03-01T22:06:13.429Z" }, + { url = "https://files.pythonhosted.org/packages/50/93/e88f3c80971b42cfc83f50a51b9d165a1dbf154b97005f2994a79f212a07/yarl-1.23.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:cde9a2ecd91668bcb7f077c4966d8ceddb60af01b52e6e3e2680e4cf00ad1a59", size = 89851, upload-time = "2026-03-01T22:06:15.53Z" }, + { url = "https://files.pythonhosted.org/packages/1c/07/61c9dd8ba8f86473263b4036f70fb594c09e99c0d9737a799dfd8bc85651/yarl-1.23.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5023346c4ee7992febc0068e7593de5fa2bf611848c08404b35ebbb76b1b0512", size = 95874, upload-time = "2026-03-01T22:06:17.553Z" }, + { url = "https://files.pythonhosted.org/packages/9e/e9/f9ff8ceefba599eac6abddcfb0b3bee9b9e636e96dbf54342a8577252379/yarl-1.23.0-cp313-cp313t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:d1009abedb49ae95b136a8904a3f71b342f849ffeced2d3747bf29caeda218c4", size = 88710, upload-time = "2026-03-01T22:06:19.004Z" }, + { url = "https://files.pythonhosted.org/packages/eb/78/0231bfcc5d4c8eec220bc2f9ef82cb4566192ea867a7c5b4148f44f6cbcd/yarl-1.23.0-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a8d00f29b42f534cc8aa3931cfe773b13b23e561e10d2b26f27a8d309b0e82a1", size = 101033, upload-time = "2026-03-01T22:06:21.203Z" }, + { url = "https://files.pythonhosted.org/packages/cd/9b/30ea5239a61786f18fd25797151a17fbb3be176977187a48d541b5447dd4/yarl-1.23.0-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:95451e6ce06c3e104556d73b559f5da6c34a069b6b62946d3ad66afcd51642ea", size = 100817, upload-time = "2026-03-01T22:06:22.738Z" }, + { url = "https://files.pythonhosted.org/packages/62/e2/a4980481071791bc83bce2b7a1a1f7adcabfa366007518b4b845e92eeee3/yarl-1.23.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:531ef597132086b6cf96faa7c6c1dcd0361dd5f1694e5cc30375907b9b7d3ea9", size = 97482, upload-time = "2026-03-01T22:06:24.21Z" }, + { url = "https://files.pythonhosted.org/packages/e5/1e/304a00cf5f6100414c4b5a01fc7ff9ee724b62158a08df2f8170dfc72a2d/yarl-1.23.0-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:88f9fb0116fbfcefcab70f85cf4b74a2b6ce5d199c41345296f49d974ddb4123", size = 95949, upload-time = "2026-03-01T22:06:25.697Z" }, + { url = "https://files.pythonhosted.org/packages/68/03/093f4055ed4cae649ac53bca3d180bd37102e9e11d048588e9ab0c0108d0/yarl-1.23.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:e7b0460976dc75cb87ad9cc1f9899a4b97751e7d4e77ab840fc9b6d377b8fd24", size = 95839, upload-time = "2026-03-01T22:06:27.309Z" }, + { url = "https://files.pythonhosted.org/packages/b9/28/4c75ebb108f322aa8f917ae10a8ffa4f07cae10a8a627b64e578617df6a0/yarl-1.23.0-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:115136c4a426f9da976187d238e84139ff6b51a20839aa6e3720cd1026d768de", size = 90696, upload-time = "2026-03-01T22:06:29.048Z" }, + { url = "https://files.pythonhosted.org/packages/23/9c/42c2e2dd91c1a570402f51bdf066bfdb1241c2240ba001967bad778e77b7/yarl-1.23.0-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:ead11956716a940c1abc816b7df3fa2b84d06eaed8832ca32f5c5e058c65506b", size = 100865, upload-time = "2026-03-01T22:06:30.525Z" }, + { url = "https://files.pythonhosted.org/packages/74/05/1bcd60a8a0a914d462c305137246b6f9d167628d73568505fce3f1cb2e65/yarl-1.23.0-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:fe8f8f5e70e6dbdfca9882cd9deaac058729bcf323cf7a58660901e55c9c94f6", size = 96234, upload-time = "2026-03-01T22:06:32.692Z" }, + { url = "https://files.pythonhosted.org/packages/90/b2/f52381aac396d6778ce516b7bc149c79e65bfc068b5de2857ab69eeea3b7/yarl-1.23.0-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:a0e317df055958a0c1e79e5d2aa5a5eaa4a6d05a20d4b0c9c3f48918139c9fc6", size = 100295, upload-time = "2026-03-01T22:06:34.268Z" }, + { url = "https://files.pythonhosted.org/packages/e5/e8/638bae5bbf1113a659b2435d8895474598afe38b4a837103764f603aba56/yarl-1.23.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:6f0fd84de0c957b2d280143522c4f91a73aada1923caee763e24a2b3fda9f8a5", size = 97784, upload-time = "2026-03-01T22:06:35.864Z" }, + { url = "https://files.pythonhosted.org/packages/80/25/a3892b46182c586c202629fc2159aa13975d3741d52ebd7347fd501d48d5/yarl-1.23.0-cp313-cp313t-win32.whl", hash = "sha256:93a784271881035ab4406a172edb0faecb6e7d00f4b53dc2f55919d6c9688595", size = 88313, upload-time = "2026-03-01T22:06:37.39Z" }, + { url = "https://files.pythonhosted.org/packages/43/68/8c5b36aa5178900b37387937bc2c2fe0e9505537f713495472dcf6f6fccc/yarl-1.23.0-cp313-cp313t-win_amd64.whl", hash = "sha256:dd00607bffbf30250fe108065f07453ec124dbf223420f57f5e749b04295e090", size = 94932, upload-time = "2026-03-01T22:06:39.579Z" }, + { url = "https://files.pythonhosted.org/packages/c6/cc/d79ba8292f51f81f4dc533a8ccfb9fc6992cabf0998ed3245de7589dc07c/yarl-1.23.0-cp313-cp313t-win_arm64.whl", hash = "sha256:ac09d42f48f80c9ee1635b2fcaa819496a44502737660d3c0f2ade7526d29144", size = 84786, upload-time = "2026-03-01T22:06:41.988Z" }, + { url = "https://files.pythonhosted.org/packages/69/68/c8739671f5699c7dc470580a4f821ef37c32c4cb0b047ce223a7f115757f/yarl-1.23.0-py3-none-any.whl", hash = "sha256:a2df6afe50dea8ae15fa34c9f824a3ee958d785fd5d089063d960bae1daa0a3f", size = 48288, upload-time = "2026-03-01T22:07:51.388Z" }, ] [[package]] @@ -1223,14 +1255,14 @@ wheels = [ [[package]] name = "zope-interface" -version = "8.1.1" +version = "8.3" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/71/c9/5ec8679a04d37c797d343f650c51ad67d178f0001c363e44b6ac5f97a9da/zope_interface-8.1.1.tar.gz", hash = "sha256:51b10e6e8e238d719636a401f44f1e366146912407b58453936b781a19be19ec", size = 254748, upload-time = "2025-11-15T08:32:52.404Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c9/04/0b1d92e7d31507c5fbe203d9cc1ae80fb0645688c7af751ea0ec18c2223e/zope_interface-8.3.tar.gz", hash = "sha256:e1a9de7d0b5b5c249a73b91aebf4598ce05e334303af6aa94865893283e9ff10", size = 256822, upload-time = "2026-04-10T06:12:35.036Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/85/81/3c3b5386ce4fba4612fd82ffb8a90d76bcfea33ca2b6399f21e94d38484f/zope_interface-8.1.1-cp313-cp313-macosx_10_9_x86_64.whl", hash = "sha256:84f9be6d959640de9da5d14ac1f6a89148b16da766e88db37ed17e936160b0b1", size = 209046, upload-time = "2025-11-15T08:37:01.473Z" }, - { url = "https://files.pythonhosted.org/packages/4a/e3/32b7cb950c4c4326b3760a8e28e5d6f70ad15f852bfd8f9364b58634f74b/zope_interface-8.1.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:531fba91dcb97538f70cf4642a19d6574269460274e3f6004bba6fe684449c51", size = 209104, upload-time = "2025-11-15T08:37:02.887Z" }, - { url = "https://files.pythonhosted.org/packages/a3/3d/c4c68e1752a5f5effa2c1f5eaa4fea4399433c9b058fb7000a34bfb1c447/zope_interface-8.1.1-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:fc65f5633d5a9583ee8d88d1f5de6b46cd42c62e47757cfe86be36fb7c8c4c9b", size = 259277, upload-time = "2025-11-15T08:37:04.389Z" }, - { url = "https://files.pythonhosted.org/packages/fd/5b/cf4437b174af7591ee29bbad728f620cab5f47bd6e9c02f87d59f31a0dda/zope_interface-8.1.1-cp313-cp313-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:efef80ddec4d7d99618ef71bc93b88859248075ca2e1ae1c78636654d3d55533", size = 264742, upload-time = "2025-11-15T08:37:05.613Z" }, - { url = "https://files.pythonhosted.org/packages/0b/0e/0cf77356862852d3d3e62db9aadae5419a1a7d89bf963b219745283ab5ca/zope_interface-8.1.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:49aad83525eca3b4747ef51117d302e891f0042b06f32aa1c7023c62642f962b", size = 264252, upload-time = "2025-11-15T08:37:07.035Z" }, - { url = "https://files.pythonhosted.org/packages/8a/10/2af54aa88b2fa172d12364116cc40d325fedbb1877c3bb031b0da6052855/zope_interface-8.1.1-cp313-cp313-win_amd64.whl", hash = "sha256:71cf329a21f98cb2bd9077340a589e316ac8a415cac900575a32544b3dffcb98", size = 212330, upload-time = "2025-11-15T08:37:08.14Z" }, + { url = "https://files.pythonhosted.org/packages/27/da/ff205c5463e52ad64cc40be667fdff2b01b9754a385c6b95bac01645fa4f/zope_interface-8.3-cp313-cp313-macosx_10_9_x86_64.whl", hash = "sha256:1aa0e1d72212cedc38b2156bbca08cf24625c057135a7947ef6b19bc732b2772", size = 211889, upload-time = "2026-04-10T06:22:27.612Z" }, + { url = "https://files.pythonhosted.org/packages/c7/21/0cc848e22769b1cf4c0cd636ec2e60ea05cfb958423435ea526d5a291fe8/zope_interface-8.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:54ab83218a8f6947ba4b6cb1a121f1e1abe2e418b838ccdac71639d0f97e734e", size = 211961, upload-time = "2026-04-10T06:22:29.575Z" }, + { url = "https://files.pythonhosted.org/packages/e3/54/815c9dbb90336c50694b4c7ef7ced06bc389e5597200c77457b557a0221c/zope_interface-8.3-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:34d6c10fa790005487c471e0e4ab537b0fa9a70e55a96994e51ffeef92205fa4", size = 264409, upload-time = "2026-04-10T06:22:31.426Z" }, + { url = "https://files.pythonhosted.org/packages/3a/69/2e5c30adde0e94552d934971fa6eba107449d3d11fa086cfcfeb8ea6354d/zope_interface-8.3-cp313-cp313-manylinux1_x86_64.manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:93108d5f8dee20177a637438bf4df4c6faf8a317c9d4a8b1d5e78123854e3317", size = 269592, upload-time = "2026-04-10T06:22:33.393Z" }, + { url = "https://files.pythonhosted.org/packages/23/8a/fbb1dceb5c5400b2b27934aa102d29fe4cb06732122e7f409efebeb6e097/zope_interface-8.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:8f81d90f80b9fbf36602549e2f187861c9d7139837f8c9dd685ce3b933c6360f", size = 269548, upload-time = "2026-04-10T06:22:35.339Z" }, + { url = "https://files.pythonhosted.org/packages/a2/70/abd0bb9cc9b1a9a718f30c81f46a184a2e751dd80cf57db142ffa42730da/zope_interface-8.3-cp313-cp313-win_amd64.whl", hash = "sha256:96106a5f609bb355e1aec6ab0361213c8af0843ca1e1ba9c42eacfbd0910914e", size = 214391, upload-time = "2026-04-10T06:22:36.969Z" }, ] diff --git a/examples/concurrent_executions/execute_async_with_queue.py b/examples/concurrent_executions/execute_async_with_queue.py index 72d2c101cb..794ac78818 100644 --- a/examples/concurrent_executions/execute_async_with_queue.py +++ b/examples/concurrent_executions/execute_async_with_queue.py @@ -31,7 +31,7 @@ session = cluster.connect() session.execute(("CREATE KEYSPACE IF NOT EXISTS examples " - "WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1' }")) + "WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1' }")) session.execute("USE examples") session.execute("CREATE TABLE IF NOT EXISTS tbl_sample_kv (id uuid, value text, PRIMARY KEY (id))") prepared_insert = session.prepare("INSERT INTO tbl_sample_kv (id, value) VALUES (?, ?)") diff --git a/examples/concurrent_executions/execute_with_threads.py b/examples/concurrent_executions/execute_with_threads.py index e3c80f5d6b..70893bd5be 100644 --- a/examples/concurrent_executions/execute_with_threads.py +++ b/examples/concurrent_executions/execute_with_threads.py @@ -34,7 +34,7 @@ session = cluster.connect() session.execute(("CREATE KEYSPACE IF NOT EXISTS examples " - "WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1' }")) + "WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1' }")) session.execute("USE examples") session.execute("CREATE TABLE IF NOT EXISTS tbl_sample_kv (id uuid, value text, PRIMARY KEY (id))") prepared_insert = session.prepare("INSERT INTO tbl_sample_kv (id, value) VALUES (?, ?)") diff --git a/examples/example_core.py b/examples/example_core.py index 01c766e109..ec41ca7fd5 100644 --- a/examples/example_core.py +++ b/examples/example_core.py @@ -36,7 +36,7 @@ def main(): log.info("creating keyspace...") session.execute(""" CREATE KEYSPACE IF NOT EXISTS %s - WITH replication = { 'class': 'SimpleStrategy', 'replication_factor': '2' } + WITH replication = { 'class': 'NetworkTopologyStrategy', 'replication_factor': '2' } """ % KEYSPACE) log.info("setting keyspace...") diff --git a/pyproject.toml b/pyproject.toml index 7f60ed0b2a..698ff4c37b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,7 +21,7 @@ classifiers = [ ] dependencies = ['geomet>=1.1', 'pyyaml > 5.0'] dynamic = ["version", "readme"] -license = "Apache-2.0" +license = {text = "Apache-2.0"} requires-python = ">=3.9" [project.urls] @@ -49,6 +49,7 @@ dev = [ "gevent", "eventlet>=0.33.3", "cython>=3.2", + "setuptools", "packaging>=25.0", "futurist", "pyyaml", @@ -121,6 +122,9 @@ log_level = "DEBUG" log_date_format = "%Y-%m-%d %H:%M:%S" xfail_strict = true addopts = "-rf" +markers = [ + "last: mark test to run last within its module group", +] [tool.setuptools_scm] version_file = "cassandra/_version.py" @@ -139,6 +143,7 @@ skip = [ "cp3*t-*", "pp3*t-*", "*i686", + "*win32", "*musllinux*", ] build = ["cp3*", "pp3*"] @@ -153,22 +158,71 @@ enable = ["pypy"] [tool.cibuildwheel.linux] before-build = "rm -rf ~/.pyxbld && rpm --import https://repo.almalinux.org/almalinux/RPM-GPG-KEY-AlmaLinux && yum install -y libffi-devel libev libev-devel openssl openssl-devel" +# Install the optional lz4 compression dependency so the lz4 segment tests run +# (and fail loudly under CASS_DRIVER_NO_SKIP) instead of skipping silently. +test-extras = ["compress-lz4"] +# Extensions are mandatory on Linux (CASS_DRIVER_BUILD_EXTENSIONS_ARE_MUST=yes), +# so skipping is disabled (CASS_DRIVER_NO_SKIP=1): a missing dependency such as +# libev fails loudly instead of being silently skipped. Tests that cannot run in +# the default configuration are listed explicitly: +# * event-loop reactor tests are run separately with the matching +# EVENT_LOOP_MANAGER (gevent/eventlet/asyncio); +# * asyncore is deprecated and unavailable on modern Python, so it is ignored; +# * column_encryption is disabled upstream (scylladb/python-driver#365); +# * test_deserialize_date_range_month is disabled upstream (PYTHON-912). +# PyPy uses the pp* override below. All Linux CPython reactor commands run with +# CASS_DRIVER_NO_SKIP=1 so unexpected skips fail loudly. test-command = [ - "pytest {package}/tests/unit", - "EVENT_LOOP_MANAGER=gevent pytest {package}/tests/unit/io/test_geventreactor.py", + "CASS_DRIVER_NO_SKIP=1 pytest --import-mode=append {package}/tests/unit -v --ignore={package}/tests/unit/column_encryption --ignore={package}/tests/unit/io/test_geventreactor.py --ignore={package}/tests/unit/io/test_eventletreactor.py --ignore={package}/tests/unit/io/test_asyncioreactor.py --ignore={package}/tests/unit/io/test_asyncorereactor.py -k 'not test_deserialize_date_range_month'", + "EVENT_LOOP_MANAGER=gevent CASS_DRIVER_NO_SKIP=1 pytest --import-mode=append {package}/tests/unit/io/test_geventreactor.py -v", + "EVENT_LOOP_MANAGER=asyncio CASS_DRIVER_NO_SKIP=1 pytest --import-mode=append {package}/tests/unit/io/test_asyncioreactor.py -v", + "EVENT_LOOP_MANAGER=eventlet CASS_DRIVER_NO_SKIP=1 pytest --import-mode=append {package}/tests/unit/io/test_eventletreactor.py -v", ] [tool.cibuildwheel.macos] build-frontend = "build" +# Install lz4 so the lz4 segment tests run instead of skipping (see Linux note). +test-extras = ["compress-lz4"] +# Same policy as Linux (extensions are mandatory here too, libev comes from +# Homebrew). The extra -k exclusions are timing-sensitive tests that are flaky +# on macOS runners. The gevent/eventlet/asyncio reactor test files only contain +# those timing-sensitive timer tests, so they are not run separately here. test-command = [ - "pytest {project}/tests/unit -k 'not (test_multi_timer_validation or test_empty_connections or test_timer_cancellation)'", + "CASS_DRIVER_NO_SKIP=1 pytest --import-mode=append {project}/tests/unit -v --ignore={project}/tests/unit/column_encryption --ignore={project}/tests/unit/io/test_geventreactor.py --ignore={project}/tests/unit/io/test_eventletreactor.py --ignore={project}/tests/unit/io/test_asyncioreactor.py --ignore={project}/tests/unit/io/test_asyncorereactor.py -k 'not (test_multi_timer_validation or test_empty_connections or test_timer_cancellation or test_deserialize_date_range_month)'", ] [tool.cibuildwheel.windows] build-frontend = "build" +# On Windows the C extensions are optional (CASS_DRIVER_BUILD_EXTENSIONS_ARE_MUST +# is overridden to "no" below), so extension-dependent tests (e.g. libev) are +# legitimately skipped here. CASS_DRIVER_NO_SKIP is therefore NOT enabled on +# Windows; we only add -v so skips are visible in the log. test-command = [ - "pytest {project}/tests/unit -k \"not (test_deserialize_date_range_year or test_datetype or test_libevreactor)\"", + "pytest --import-mode=append {project}/tests/unit -v -k \"not (test_deserialize_date_range_year or test_datetype or test_libevreactor)\"", ] # TODO: set CASS_DRIVER_BUILD_EXTENSIONS_ARE_MUST to yes when https://github.com/scylladb/python-driver/issues/429 is fixed environment = { CASS_DRIVER_BUILD_CONCURRENCY = "2", CASS_DRIVER_BUILD_EXTENSIONS_ARE_MUST = "no" } + +# PyPy never builds the libev/cmurmur3/Cython C extensions (setup.py forces +# is_pypy to skip them even when CASS_DRIVER_BUILD_EXTENSIONS_ARE_MUST=yes), so +# the tests that depend on those extensions legitimately skip. Enforcing +# CASS_DRIVER_NO_SKIP would turn those expected skips into failures, so it is +# NOT enabled for PyPy (same reasoning as Windows). The reactor tests are not +# run separately here because eventlet is unsupported on PyPy (@notpypy) and the +# extension-backed reactors are unavailable; with no-skip off they simply skip. +# test-extras is cleared (no compress-lz4): PyPy has no prebuilt lz4 wheel, so +# pip would try to compile it from source and fail. The lz4 tests just skip here. +# test_deserialize_date_range_year and test_datetype are excluded because they +# fail on Windows (the C runtime's gmtime rejects the far-future timestamps they +# use); the CPython Windows command excludes them for the same reason. The +# timer tests (test_multi_timer_validation, test_empty_connections, +# test_timer_cancellation) are timing-sensitive and flaky on macOS, matching the +# CPython macOS exclusions. The override matches PyPy on all OSes, so these are +# deselected everywhere here (they are still covered by the CPython runs). +[[tool.cibuildwheel.overrides]] +select = "pp*" +test-extras = [] +test-command = [ + "pytest --import-mode=append {package}/tests/unit -v --ignore={package}/tests/unit/column_encryption -k \"not (test_deserialize_date_range_month or test_deserialize_date_range_year or test_datetype or test_multi_timer_validation or test_empty_connections or test_timer_cancellation)\"", +] diff --git a/renovate.json b/renovate.json index 5db72dd6a9..d85ac38c01 100644 --- a/renovate.json +++ b/renovate.json @@ -2,5 +2,12 @@ "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": [ "config:recommended" + ], + "packageRules": [ + { + "matchManagers": ["github-actions"], + "pinDigests": true, + "minimumReleaseAge": "90 days" + } ] } diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000000..8eed388549 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,103 @@ +# Copyright ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import importlib.machinery +import os +import warnings + +import pytest + +# Directory containing the Cython-compiled driver modules. +_CASSANDRA_DIR = os.path.join(os.path.dirname(__file__), os.pardir, "cassandra") + +# When set (e.g. in CI) a skipped test is turned into a failure. Tests skip +# themselves when their requirements are missing (a library is not installed, +# the wrong event loop is selected, ...). That is convenient locally, but in CI +# it is a footgun: a test may be silently skipped because we forgot to install +# something. Enabling this forces every skip to be explicit on the command line +# (via -k / --ignore / --deselect) instead of being hidden in the output. +_NO_SKIP = bool(os.environ.get("CASS_DRIVER_NO_SKIP")) + + +@pytest.hookimpl(hookwrapper=True) +def pytest_runtest_makereport(item, call): + """Turn skips into failures when CASS_DRIVER_NO_SKIP is set. + + xfailed tests (which are reported as skipped) are left untouched so that + ``xfail_strict`` keeps working as configured. + """ + outcome = yield + if not _NO_SKIP: + return + report = outcome.get_result() + if report.skipped and not hasattr(report, "wasxfail"): + reason = "" + if isinstance(report.longrepr, tuple) and len(report.longrepr) == 3: + reason = report.longrepr[2] + elif report.longrepr: + reason = str(report.longrepr) + report.outcome = "failed" + report.longrepr = ( + "Test was skipped but skipping is disabled in this environment " + "(CASS_DRIVER_NO_SKIP is set). Run it in a suitable configuration " + "or deselect it explicitly on the command line. " + "Original skip reason: {!r}".format(reason) + ) + + +def pytest_configure(config): + """Warn when a compiled Cython extension is older than its .py source. + + Python's import system prefers compiled extensions (.so / .pyd) over pure + Python (.py) files. If a developer edits a .py file without rebuilding + the Cython extensions, the tests + will silently run the *old* compiled code, masking any regressions in the + Python source. + + This hook detects such staleness at test-session startup so the developer + is alerted immediately. + """ + stale = [] + # Iterate over .py sources and, for each module, look for the first + # existing compiled extension in EXTENSION_SUFFIXES order. This mirrors + # how Python's import machinery selects an extension module, and avoids + # globbing patterns like "*{suffix}" that can pick up ABI-tagged + # extensions built for other Python versions. + if os.path.isdir(_CASSANDRA_DIR): + for entry in os.listdir(_CASSANDRA_DIR): + if not entry.endswith(".py"): + continue + module_name, _ = os.path.splitext(entry) + py_path = os.path.join(_CASSANDRA_DIR, entry) + # For this module, find the first extension file Python would load. + for suffix in importlib.machinery.EXTENSION_SUFFIXES: + ext_path = os.path.join(_CASSANDRA_DIR, module_name + suffix) + if not os.path.exists(ext_path): + continue + if os.path.getmtime(py_path) > os.path.getmtime(ext_path): + stale.append((module_name, ext_path, py_path)) + # Only consider the first matching suffix; this is the one + # the import system would actually use. + break + + if stale: + names = ", ".join(m for m, _, _ in stale) + warnings.warn( + f"Stale Cython extension(s) detected: {names}. " + f"The .py source is newer than the compiled extension — tests " + f"will run the OLD compiled code, not your latest changes. " + f"Rebuild with: uv sync --reinstall-package scylla-driver\n" + f"Or use 'uv run pytest' which handles rebuilds automatically.", + stacklevel=1, + ) diff --git a/tests/integration/__init__.py b/tests/integration/__init__.py index dfac2dc1d9..6118d961da 100644 --- a/tests/integration/__init__.py +++ b/tests/integration/__init__.py @@ -122,7 +122,6 @@ def cmd_line_args_to_dict(env_var): args[cmd_arg.lstrip('-')] = cmd_arg_value return args -USE_CASS_EXTERNAL = bool(os.getenv('USE_CASS_EXTERNAL', False)) KEEP_TEST_CLUSTER = bool(os.getenv('KEEP_TEST_CLUSTER', False)) SIMULACRON_JAR = os.getenv('SIMULACRON_JAR', None) @@ -250,7 +249,7 @@ def get_unsupported_upper_protocol(): def local_decorator_creator(): - if USE_CASS_EXTERNAL or not CASSANDRA_IP.startswith("127.0.0."): + if not CASSANDRA_IP.startswith("127.0.0."): return unittest.skip('Tests only runs against local C*') def _id_and_mark(f): @@ -373,7 +372,7 @@ def check_log_error(): def remove_cluster(): - if USE_CASS_EXTERNAL or KEEP_TEST_CLUSTER: + if KEEP_TEST_CLUSTER: return global CCM_CLUSTER @@ -430,21 +429,6 @@ def use_cluster(cluster_name, nodes, ipformat=None, start=True, workloads=None, cassandra_version = ccm_options.get('version', CCM_VERSION) global CCM_CLUSTER - if USE_CASS_EXTERNAL: - if CCM_CLUSTER: - log.debug("Using external CCM cluster {0}".format(CCM_CLUSTER.name)) - else: - ccm_path = os.getenv("CCM_PATH", None) - ccm_name = os.getenv("CCM_NAME", None) - if ccm_path and ccm_name: - CCM_CLUSTER = CCMClusterFactory.load(ccm_path, ccm_name) - log.debug("Using external CCM cluster {0}".format(CCM_CLUSTER.name)) - else: - log.debug("Using unnamed external cluster") - if set_keyspace and start: - setup_keyspace(ipformat=ipformat, wait=False) - return - if is_current_cluster(cluster_name, nodes, workloads): log.debug("Using existing cluster, matching topology: {0}".format(cluster_name)) else: @@ -549,7 +533,7 @@ def use_cluster(cluster_name, nodes, ipformat=None, start=True, workloads=None, def teardown_package(): - if USE_CASS_EXTERNAL or KEEP_TEST_CLUSTER: + if KEEP_TEST_CLUSTER: return # when multiple modules are run explicitly, this runs between them # need to make sure CCM_CLUSTER is properly cleared for that case @@ -600,7 +584,7 @@ def execute_with_long_wait_retry(session, query, timeout=30): del tb tries += 1 - raise RuntimeError("Failed to execute query after 100 attempts: {0}".format(query)) + raise RuntimeError("Failed to execute query after 10 attempts: {0}".format(query)) def execute_with_retry_tolerant(session, query, retry_exceptions, escape_exception): @@ -632,11 +616,7 @@ def drop_keyspace_shutdown_cluster(keyspace_name, session, cluster): cluster.shutdown() -def setup_keyspace(ipformat=None, wait=True, protocol_version=None, port=9042): - # wait for nodes to startup - if wait: - time.sleep(10) - +def setup_keyspace(ipformat=None, protocol_version=None, port=9042): if protocol_version: _protocol_version = protocol_version else: @@ -655,17 +635,17 @@ def setup_keyspace(ipformat=None, wait=True, protocol_version=None, port=9042): ddl = ''' CREATE KEYSPACE test3rf - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3'}''' + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '3'}''' execute_with_long_wait_retry(session, ddl) ddl = ''' CREATE KEYSPACE test2rf - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '2'}''' + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '2'}''' execute_with_long_wait_retry(session, ddl) ddl = ''' CREATE KEYSPACE test1rf - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}''' + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'}''' execute_with_long_wait_retry(session, ddl) ddl_3f = ''' @@ -691,29 +671,56 @@ def is_scylla_enterprise(version: Version) -> bool: return version > Version('2000.1.1') -def xfail_scylla_version_lt(reason, oss_scylla_version, ent_scylla_version, *args, **kwargs): +def xfail_scylla_version_lt(reason, scylla_version, *args, **kwargs): """ It is used to mark tests that are going to fail on certain scylla versions. :param reason: message to fail test with - :param oss_scylla_version: str, oss version from which test supposed to succeed - :param ent_scylla_version: str, enterprise version from which test supposed to succeed + :param scylla_version: str, version from which test supposed to succeed + """ + if not (reason.startswith("scylladb/scylladb#") or reason.startswith("scylladb/scylla-enterprise#")): + raise ValueError('reason should start with scylladb/scylladb# or scylladb/scylla-enterprise# to reference issue in scylla repo') + + if not isinstance(scylla_version, str): + raise ValueError('scylla_version should be a str') + + if SCYLLA_VERSION is None: + return pytest.mark.skipif(False, reason="It is just a NoOP Decor, should not skip anything") + + current_version = Version(get_scylla_version(SCYLLA_VERSION)) + + return pytest.mark.xfail(current_version < Version(scylla_version), reason=reason, *args, **kwargs) + + +def get_tablets_disabled_ddl_suffix(scylla_version='2026.1'): + """ + Returns DDL option string for disabling tablets on ScyllaDB versions older than scylla_version. + Used to work around features not yet supported with tablets (e.g. MVs, secondary indexes, counters). + :param scylla_version: str, version from which tablets support the feature + """ + if SCYLLA_VERSION is not None and Version(get_scylla_version(SCYLLA_VERSION)) < Version(scylla_version): + return " AND tablets = {'enabled': false}" + return "" + + +def skip_scylla_version_lt(reason, scylla_version): + """ + Skip tests on scylla versions older than the specified thresholds. + :param reason: message explaining why the test is skipped + :param scylla_version: str, version from which test supposed to work """ if not (reason.startswith("scylladb/scylladb#") or reason.startswith("scylladb/scylla-enterprise#")): raise ValueError('reason should start with scylladb/scylladb# or scylladb/scylla-enterprise# to reference issue in scylla repo') - if not isinstance(ent_scylla_version, str): - raise ValueError('ent_scylla_version should be a str') + if not isinstance(scylla_version, str): + raise ValueError('scylla_version should be a str') if SCYLLA_VERSION is None: return pytest.mark.skipif(False, reason="It is just a NoOP Decor, should not skip anything") current_version = Version(get_scylla_version(SCYLLA_VERSION)) - if is_scylla_enterprise(current_version): - return pytest.mark.xfail(current_version < Version(ent_scylla_version), - reason=reason, *args, **kwargs) + return pytest.mark.skipif(current_version < Version(scylla_version), reason=reason) - return pytest.mark.xfail(current_version < Version(oss_scylla_version), reason=reason, *args, **kwargs) class UpDownWaiter(object): @@ -762,7 +769,7 @@ def drop_keyspace(cls): @classmethod def create_keyspace(cls, rf): - ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'SimpleStrategy', 'replication_factor': '{1}'}}".format(cls.ks_name, rf) + ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}".format(cls.ks_name, rf) execute_with_long_wait_retry(cls.session, ddl) @classmethod @@ -969,9 +976,9 @@ def __new__(cls, **kwargs): # introduced by CASSANDRA-15234 class Cassandra41CCMCluster(CCMCluster): __test__ = False - IN_MS_REGEX = re.compile('^(\w+)_in_ms$') - IN_KB_REGEX = re.compile('^(\w+)_in_kb$') - ENABLE_REGEX = re.compile('^enable_(\w+)$') + IN_MS_REGEX = re.compile(r'^(\w+)_in_ms$') + IN_KB_REGEX = re.compile(r'^(\w+)_in_kb$') + ENABLE_REGEX = re.compile(r'^enable_(\w+)$') def _get_config_key(self, k, v): if "." in k: diff --git a/tests/integration/conftest.py b/tests/integration/conftest.py index a682bcb608..826ba80729 100644 --- a/tests/integration/conftest.py +++ b/tests/integration/conftest.py @@ -17,10 +17,10 @@ def cleanup_clusters(): if not os.environ.get('DISABLE_CLUSTER_CLEANUP'): for cluster_name in [CLUSTER_NAME, SINGLE_NODE_CLUSTER_NAME, MULTIDC_CLUSTER_NAME, - 'shared_aware', 'sni_proxy', 'test_ip_change']: + 'cluster_tests', 'shared_aware', 'sni_proxy', 'test_ip_change', 'test_client_routes_replacement']: try: cluster = CCMClusterFactory.load(ccm_path, cluster_name) - logging.debug("Using external CCM cluster {0}".format(cluster.name)) + logging.debug("Clearing CCM cluster {0}".format(cluster.name)) cluster.clear() except FileNotFoundError: pass diff --git a/tests/integration/cqlengine/__init__.py b/tests/integration/cqlengine/__init__.py index 7fae437370..802bf77d19 100644 --- a/tests/integration/cqlengine/__init__.py +++ b/tests/integration/cqlengine/__init__.py @@ -13,7 +13,6 @@ # limitations under the License. import os -import unittest from cassandra import ConsistencyLevel from cassandra.cqlengine import connection diff --git a/tests/integration/cqlengine/base.py b/tests/integration/cqlengine/base.py index c65554b974..29297720da 100644 --- a/tests/integration/cqlengine/base.py +++ b/tests/integration/cqlengine/base.py @@ -13,7 +13,6 @@ # limitations under the License. import unittest -import sys from cassandra.cqlengine.connection import get_session from cassandra.cqlengine.models import Model diff --git a/tests/integration/cqlengine/connections/test_connection.py b/tests/integration/cqlengine/connections/test_connection.py index 78d5133e63..957acaa417 100644 --- a/tests/integration/cqlengine/connections/test_connection.py +++ b/tests/integration/cqlengine/connections/test_connection.py @@ -23,7 +23,7 @@ from cassandra.policies import RoundRobinPolicy from cassandra.query import dict_factory -from tests.integration import CASSANDRA_IP, PROTOCOL_VERSION, execute_with_long_wait_retry, local, TestCluster +from tests.integration import CASSANDRA_IP, execute_with_long_wait_retry, local, TestCluster from tests.integration.cqlengine.base import BaseCassEngTestCase from tests.integration.cqlengine import DEFAULT_KEYSPACE, setup_connection @@ -76,9 +76,9 @@ def setUpClass(cls): super(SeveralConnectionsTest, cls).setUpClass() cls.setup_cluster = TestCluster() cls.setup_session = cls.setup_cluster.connect() - ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'SimpleStrategy', 'replication_factor': '{1}'}}".format(cls.keyspace1, 1) + ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}".format(cls.keyspace1, 1) execute_with_long_wait_retry(cls.setup_session, ddl) - ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'SimpleStrategy', 'replication_factor': '{1}'}}".format(cls.keyspace2, 1) + ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}".format(cls.keyspace2, 1) execute_with_long_wait_retry(cls.setup_session, ddl) @classmethod diff --git a/tests/integration/cqlengine/management/test_management.py b/tests/integration/cqlengine/management/test_management.py index 1332680cef..23ddefb639 100644 --- a/tests/integration/cqlengine/management/test_management.py +++ b/tests/integration/cqlengine/management/test_management.py @@ -14,7 +14,6 @@ import unittest from unittest import mock -import logging from packaging.version import Version from cassandra.cqlengine.connection import get_session, get_cluster from cassandra.cqlengine import CQLEngineException diff --git a/tests/integration/cqlengine/model/test_model.py b/tests/integration/cqlengine/model/test_model.py index cafe6ae9c9..1bdd373c28 100644 --- a/tests/integration/cqlengine/model/test_model.py +++ b/tests/integration/cqlengine/model/test_model.py @@ -20,7 +20,6 @@ from cassandra.cqlengine import models from cassandra.cqlengine.models import Model, ModelDefinitionException from uuid import uuid1 -from tests.integration import pypy from tests.integration.cqlengine.base import TestQueryUpdateModel import pytest @@ -259,10 +258,8 @@ class SensitiveModel(Model): rows[-1] rows[-1:] - # ignore DeprecationWarning('The loop argument is deprecated since Python 3.8, and scheduled for removal in Python 3.10.') - relevant_warnings = [warn for warn in w if "The loop argument is deprecated" not in str(warn.message)] + warning_messages = [str(warn.message) for warn in w] - assert "__table_name_case_sensitive__ will be removed in 4.0." in str(relevant_warnings[0].message) - assert "__table_name_case_sensitive__ will be removed in 4.0." in str(relevant_warnings[1].message) - assert "ModelQuerySet indexing with negative indices support will be removed in 4.0." in str(relevant_warnings[2].message) - assert "ModelQuerySet slicing with negative indices support will be removed in 4.0." in str(relevant_warnings[3].message) + assert sum("__table_name_case_sensitive__ will be removed in 4.0." in message for message in warning_messages) == 2 + assert sum("ModelQuerySet indexing with negative indices support will be removed in 4.0." in message for message in warning_messages) == 1 + assert sum("ModelQuerySet slicing with negative indices support will be removed in 4.0." in message for message in warning_messages) == 1 diff --git a/tests/integration/cqlengine/model/test_model_io.py b/tests/integration/cqlengine/model/test_model_io.py index f55815310a..a575e86cf8 100644 --- a/tests/integration/cqlengine/model/test_model_io.py +++ b/tests/integration/cqlengine/model/test_model_io.py @@ -19,7 +19,6 @@ from decimal import Decimal from operator import itemgetter -import cassandra from cassandra.cqlengine import columns from cassandra.cqlengine import CQLEngineException from cassandra.cqlengine.management import sync_table diff --git a/tests/integration/cqlengine/query/test_named.py b/tests/integration/cqlengine/query/test_named.py index 24a6802b47..70df912428 100644 --- a/tests/integration/cqlengine/query/test_named.py +++ b/tests/integration/cqlengine/query/test_named.py @@ -12,7 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -import unittest from cassandra import ConsistencyLevel from cassandra.cqlengine import operators @@ -22,12 +21,12 @@ from cassandra.concurrent import execute_concurrent_with_args from cassandra.cqlengine import models -from tests.integration.cqlengine import setup_connection, execute_count +from tests.integration.cqlengine import execute_count from tests.integration.cqlengine.base import BaseCassEngTestCase from tests.integration.cqlengine.query.test_queryset import BaseQuerySetUsage -from tests.integration import BasicSharedKeyspaceUnitTestCase, greaterthanorequalcass30, requires_collection_indexes +from tests.integration import BasicSharedKeyspaceUnitTestCase, greaterthanorequalcass30, requires_collection_indexes, get_tablets_disabled_ddl_suffix, execute_with_long_wait_retry import pytest @@ -280,6 +279,12 @@ def test_get_multipleobjects_exception(self): class TestNamedWithMV(BasicSharedKeyspaceUnitTestCase): + @classmethod + def create_keyspace(cls, rf): + ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}{2}".format( + cls.ks_name, rf, get_tablets_disabled_ddl_suffix()) + execute_with_long_wait_retry(cls.session, ddl) + @classmethod def setUpClass(cls): super(TestNamedWithMV, cls).setUpClass() diff --git a/tests/integration/cqlengine/query/test_queryset.py b/tests/integration/cqlengine/query/test_queryset.py index 34b4ab5964..a4420e8283 100644 --- a/tests/integration/cqlengine/query/test_queryset.py +++ b/tests/integration/cqlengine/query/test_queryset.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import import unittest diff --git a/tests/integration/cqlengine/statements/test_select_statement.py b/tests/integration/cqlengine/statements/test_select_statement.py index b4bada1eb0..f1108b0bbc 100644 --- a/tests/integration/cqlengine/statements/test_select_statement.py +++ b/tests/integration/cqlengine/statements/test_select_statement.py @@ -14,7 +14,7 @@ import unittest from cassandra.cqlengine.columns import Column -from cassandra.cqlengine.statements import SelectStatement, WhereClause +from cassandra.cqlengine.statements import SelectStatement from cassandra.cqlengine.operators import * class SelectStatementTests(unittest.TestCase): diff --git a/tests/integration/cqlengine/statements/test_update_statement.py b/tests/integration/cqlengine/statements/test_update_statement.py index 6529b73558..5832002a26 100644 --- a/tests/integration/cqlengine/statements/test_update_statement.py +++ b/tests/integration/cqlengine/statements/test_update_statement.py @@ -15,9 +15,7 @@ from cassandra.cqlengine.columns import Column, Set, List, Text from cassandra.cqlengine.operators import * -from cassandra.cqlengine.statements import (UpdateStatement, WhereClause, - AssignmentClause, SetUpdateClause, - ListUpdateClause) +from cassandra.cqlengine.statements import (UpdateStatement) class UpdateStatementTests(unittest.TestCase): diff --git a/tests/integration/cqlengine/test_connections.py b/tests/integration/cqlengine/test_connections.py index 612255bdc5..a628195877 100644 --- a/tests/integration/cqlengine/test_connections.py +++ b/tests/integration/cqlengine/test_connections.py @@ -17,12 +17,12 @@ from cassandra.cqlengine import columns, CQLEngineException from cassandra.cqlengine import connection as conn from cassandra.cqlengine.management import drop_keyspace, sync_table, drop_table, create_keyspace_simple -from cassandra.cqlengine.models import Model, QuerySetDescriptor +from cassandra.cqlengine.models import Model from cassandra.cqlengine.query import ContextQuery, BatchQuery, ModelQuerySet from tests.integration.cqlengine import setup_connection, DEFAULT_KEYSPACE from tests.integration.cqlengine.base import BaseCassEngTestCase from tests.integration.cqlengine.query import test_queryset -from tests.integration import local, CASSANDRA_IP, TestCluster +from tests.integration import CASSANDRA_IP, TestCluster import pytest diff --git a/tests/integration/cqlengine/test_ifexists.py b/tests/integration/cqlengine/test_ifexists.py index 6c2ff437ab..26b0ba287b 100644 --- a/tests/integration/cqlengine/test_ifexists.py +++ b/tests/integration/cqlengine/test_ifexists.py @@ -18,7 +18,7 @@ from cassandra.cqlengine import columns from cassandra.cqlengine.management import sync_table, drop_table from cassandra.cqlengine.models import Model -from cassandra.cqlengine.query import BatchQuery, BatchType, LWTException, IfExistsWithCounterColumn +from cassandra.cqlengine.query import BatchQuery, LWTException, IfExistsWithCounterColumn from tests.integration.cqlengine.base import BaseCassEngTestCase from tests.integration import PROTOCOL_VERSION diff --git a/tests/integration/cqlengine/test_ttl.py b/tests/integration/cqlengine/test_ttl.py index df1afb6bf0..2d83fab6e3 100644 --- a/tests/integration/cqlengine/test_ttl.py +++ b/tests/integration/cqlengine/test_ttl.py @@ -13,7 +13,6 @@ # limitations under the License. -import unittest from packaging.version import Version @@ -25,7 +24,7 @@ from cassandra.cqlengine import columns from unittest import mock from cassandra.cqlengine.connection import get_session -from tests.integration import CASSANDRA_VERSION, greaterthancass20 +from tests.integration import CASSANDRA_VERSION class TestTTLModel(Model): diff --git a/tests/integration/long/test_failure_types.py b/tests/integration/long/test_failure_types.py index beb10f02c0..04d75555f5 100644 --- a/tests/integration/long/test_failure_types.py +++ b/tests/integration/long/test_failure_types.py @@ -187,7 +187,7 @@ def test_write_failures_from_coordinator(self): self._perform_cql_statement( """ CREATE KEYSPACE testksfail - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3'} + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '3'} """, consistency_level=ConsistencyLevel.ALL, expected_exception=None) # create table diff --git a/tests/integration/long/test_large_data.py b/tests/integration/long/test_large_data.py index 0a1b368bf0..c6ddaea709 100644 --- a/tests/integration/long/test_large_data.py +++ b/tests/integration/long/test_large_data.py @@ -21,7 +21,7 @@ from cassandra.cluster import ExecutionProfile, EXEC_PROFILE_DEFAULT from cassandra.query import dict_factory from cassandra.query import SimpleStatement -from tests.integration import use_singledc, PROTOCOL_VERSION, TestCluster +from tests.integration import use_singledc, TestCluster from tests.integration.long.utils import create_schema import unittest diff --git a/tests/integration/long/test_loadbalancingpolicies.py b/tests/integration/long/test_loadbalancingpolicies.py index fd8edde14c..072786dc23 100644 --- a/tests/integration/long/test_loadbalancingpolicies.py +++ b/tests/integration/long/test_loadbalancingpolicies.py @@ -45,7 +45,6 @@ class LoadBalancingPolicyTests(unittest.TestCase): def setUp(self): - remove_cluster() # clear ahead of test so it doesn't use one left in unknown state self.coordinator_stats = CoordinatorStats() self.prepared = None self.probe_cluster = None @@ -191,6 +190,7 @@ def test_token_aware_is_used_by_default(self): assert isinstance(cluster.profile_manager.default.load_balancing_policy, DCAwareRoundRobinPolicy) def test_roundrobin(self): + remove_cluster() use_singledc() keyspace = 'test_roundrobin' cluster, session = self._cluster_session_with_lbp(RoundRobinPolicy()) @@ -228,6 +228,7 @@ def test_roundrobin(self): self.coordinator_stats.assert_query_count_equals(3, 6) def test_roundrobin_two_dcs(self): + remove_cluster() use_multidc([2, 2]) keyspace = 'test_roundrobin_two_dcs' cluster, session = self._cluster_session_with_lbp(RoundRobinPolicy()) @@ -261,6 +262,7 @@ def test_roundrobin_two_dcs(self): self.coordinator_stats.assert_query_count_equals(5, 3) def test_roundrobin_two_dcs_2(self): + remove_cluster() use_multidc([2, 2]) keyspace = 'test_roundrobin_two_dcs_2' cluster, session = self._cluster_session_with_lbp(RoundRobinPolicy()) @@ -294,6 +296,7 @@ def test_roundrobin_two_dcs_2(self): self.coordinator_stats.assert_query_count_equals(5, 3) def test_dc_aware_roundrobin_two_dcs(self): + remove_cluster() use_multidc([3, 2]) keyspace = 'test_dc_aware_roundrobin_two_dcs' cluster, session = self._cluster_session_with_lbp(DCAwareRoundRobinPolicy('dc1')) @@ -311,6 +314,7 @@ def test_dc_aware_roundrobin_two_dcs(self): self.coordinator_stats.assert_query_count_equals(5, 0) def test_dc_aware_roundrobin_two_dcs_2(self): + remove_cluster() use_multidc([3, 2]) keyspace = 'test_dc_aware_roundrobin_two_dcs_2' cluster, session = self._cluster_session_with_lbp(DCAwareRoundRobinPolicy('dc2')) @@ -328,6 +332,7 @@ def test_dc_aware_roundrobin_two_dcs_2(self): self.coordinator_stats.assert_query_count_equals(5, 6) def test_dc_aware_roundrobin_one_remote_host(self): + remove_cluster() use_multidc([2, 2]) keyspace = 'test_dc_aware_roundrobin_one_remote_host' cluster, session = self._cluster_session_with_lbp(DCAwareRoundRobinPolicy('dc2', used_hosts_per_remote_dc=1)) @@ -410,6 +415,7 @@ def test_token_aware_prepared(self): self.token_aware(keyspace, True) def token_aware(self, keyspace, use_prepared=False): + remove_cluster() use_singledc() cluster, session = self._cluster_session_with_lbp(TokenAwarePolicy(RoundRobinPolicy())) self.addCleanup(cluster.shutdown) @@ -505,6 +511,7 @@ def test_token_aware_composite_key(self): assert results[0].i def test_token_aware_with_rf_2(self, use_prepared=False): + remove_cluster() use_singledc() keyspace = 'test_token_aware_with_rf_2' cluster, session = self._cluster_session_with_lbp(TokenAwarePolicy(RoundRobinPolicy())) @@ -617,6 +624,7 @@ def test_token_aware_with_transient_replication(self): @test_category policy """ + remove_cluster() # We can test this with a single dc when CASSANDRA-15670 is fixed use_multidc([3, 3]) @@ -647,6 +655,7 @@ def test_token_aware_with_transient_replication(self): def _set_up_shuffle_test(self, keyspace, replication_factor): + remove_cluster() use_singledc() cluster, session = self._cluster_session_with_lbp( TokenAwarePolicy(RoundRobinPolicy(), shuffle_replicas=True) @@ -678,6 +687,7 @@ def _check_query_order_changes(self, session, keyspace): self.coordinator_stats.reset_counts() def test_white_list(self): + remove_cluster() use_singledc() keyspace = 'test_white_list' @@ -723,6 +733,7 @@ def test_black_list_with_host_filter_policy(self): @test_category policy """ + remove_cluster() use_singledc() keyspace = 'test_black_list_with_hfp' ignored_address = (IP_FORMAT % 2) diff --git a/tests/integration/long/test_policies.py b/tests/integration/long/test_policies.py index ab8d125ab1..5cada34d8b 100644 --- a/tests/integration/long/test_policies.py +++ b/tests/integration/long/test_policies.py @@ -48,7 +48,7 @@ def test_should_rethrow_on_unvailable_with_default_policy_if_cas(self): cluster = TestCluster(execution_profiles={EXEC_PROFILE_DEFAULT: ep}) session = cluster.connect() - session.execute("CREATE KEYSPACE test_retry_policy_cas WITH replication = {'class':'SimpleStrategy','replication_factor': 3};") + session.execute("CREATE KEYSPACE test_retry_policy_cas WITH replication = {'class':'NetworkTopologyStrategy','replication_factor': 3};") session.execute("CREATE TABLE test_retry_policy_cas.t (id int PRIMARY KEY, data text);") session.execute('INSERT INTO test_retry_policy_cas.t ("id", "data") VALUES (%(0)s, %(1)s)', {'0': 42, '1': 'testing'}) diff --git a/tests/integration/long/test_schema.py b/tests/integration/long/test_schema.py index f892acba52..d60ff775c4 100644 --- a/tests/integration/long/test_schema.py +++ b/tests/integration/long/test_schema.py @@ -57,7 +57,7 @@ def test_recreates(self): log.debug(drop) execute_until_pass(session, drop) - create = "CREATE KEYSPACE {0} WITH replication = {{'class': 'SimpleStrategy', 'replication_factor': 3}}".format(keyspace) + create = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': 3}}".format(keyspace) log.debug(create) execute_until_pass(session, create) @@ -82,7 +82,7 @@ def test_for_schema_disagreements_different_keyspaces(self): session = self.session for i in range(30): - execute_until_pass(session, "CREATE KEYSPACE test_{0} WITH replication = {{'class': 'SimpleStrategy', 'replication_factor': 1}}".format(i)) + execute_until_pass(session, "CREATE KEYSPACE test_{0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': 1}}".format(i)) execute_until_pass(session, "CREATE TABLE test_{0}.cf (key int PRIMARY KEY, value int)".format(i)) for j in range(100): @@ -100,10 +100,10 @@ def test_for_schema_disagreements_same_keyspace(self): for i in range(30): try: - execute_until_pass(session, "CREATE KEYSPACE test WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}") + execute_until_pass(session, "CREATE KEYSPACE test WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 1}") except AlreadyExists: execute_until_pass(session, "DROP KEYSPACE test") - execute_until_pass(session, "CREATE KEYSPACE test WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}") + execute_until_pass(session, "CREATE KEYSPACE test WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 1}") execute_until_pass(session, "CREATE TABLE test.cf (key int PRIMARY KEY, value int)") @@ -132,7 +132,7 @@ def test_for_schema_disagreement_attribute(self): cluster = TestCluster(max_schema_agreement_wait=0.001) session = cluster.connect(wait_for_all_pools=True) - rs = session.execute("CREATE KEYSPACE test_schema_disagreement WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3}") + rs = session.execute("CREATE KEYSPACE test_schema_disagreement WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 3}") self.check_and_wait_for_agreement(session, rs, False) rs = session.execute(SimpleStatement("CREATE TABLE test_schema_disagreement.cf (key int PRIMARY KEY, value int)", consistency_level=ConsistencyLevel.ALL)) @@ -144,7 +144,7 @@ def test_for_schema_disagreement_attribute(self): # These should have schema agreement cluster = TestCluster(max_schema_agreement_wait=100) session = cluster.connect() - rs = session.execute("CREATE KEYSPACE test_schema_disagreement WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3}") + rs = session.execute("CREATE KEYSPACE test_schema_disagreement WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 3}") self.check_and_wait_for_agreement(session, rs, True) rs = session.execute(SimpleStatement("CREATE TABLE test_schema_disagreement.cf (key int PRIMARY KEY, value int)", consistency_level=ConsistencyLevel.ALL)) @@ -158,4 +158,4 @@ def check_and_wait_for_agreement(self, session, rs, exepected): time.sleep(1) assert rs.response_future.is_schema_agreed == exepected if not rs.response_future.is_schema_agreed: - session.cluster.control_connection.wait_for_schema_agreement(wait_time=1000) + session.wait_for_schema_agreement(wait_time=1000) diff --git a/tests/integration/long/test_ssl.py b/tests/integration/long/test_ssl.py index 56dc6a5c2d..0170f56fa1 100644 --- a/tests/integration/long/test_ssl.py +++ b/tests/integration/long/test_ssl.py @@ -116,7 +116,7 @@ def validate_ssl_options(**kwargs): # attempt a few simple commands. insert_keyspace = """CREATE KEYSPACE ssltest - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3'} + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '3'} """ statement = SimpleStatement(insert_keyspace) statement.consistency_level = 3 @@ -369,7 +369,7 @@ def test_ssl_want_write_errors_are_retried(self): except: pass session.execute( - "CREATE KEYSPACE ssl_error_test WITH replication = {'class':'SimpleStrategy','replication_factor':1};") + "CREATE KEYSPACE ssl_error_test WITH replication = {'class':'NetworkTopologyStrategy','replication_factor':1};") session.execute("CREATE TABLE ssl_error_test.big_text (id uuid PRIMARY KEY, data text);") params = { diff --git a/tests/integration/long/utils.py b/tests/integration/long/utils.py index 93464df8ff..ba9351828e 100644 --- a/tests/integration/long/utils.py +++ b/tests/integration/long/utils.py @@ -63,7 +63,7 @@ def create_schema(cluster, session, keyspace, simple_strategy=True, if simple_strategy: ddl = "CREATE KEYSPACE %s WITH replication" \ - " = {'class': 'SimpleStrategy', 'replication_factor': '%s'}" + " = {'class': 'NetworkTopologyStrategy', 'replication_factor': '%s'}" session.execute(ddl % (keyspace, replication_factor), timeout=10) else: if not replication_strategy: diff --git a/tests/integration/simulacron/__init__.py b/tests/integration/simulacron/__init__.py index b75b67c540..671a862bab 100644 --- a/tests/integration/simulacron/__init__.py +++ b/tests/integration/simulacron/__init__.py @@ -18,7 +18,6 @@ clear_queries, start_and_prime_singledc, stop_simulacron, - start_and_prime_cluster_defaults, ) from cassandra.cluster import Cluster diff --git a/tests/integration/simulacron/test_cluster.py b/tests/integration/simulacron/test_cluster.py index 898734c416..b8b908e3bb 100644 --- a/tests/integration/simulacron/test_cluster.py +++ b/tests/integration/simulacron/test_cluster.py @@ -11,15 +11,12 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -import unittest -import logging -from packaging.version import Version import cassandra -from tests.integration.simulacron import SimulacronCluster, SimulacronBase +from tests.integration.simulacron import SimulacronCluster from tests.integration import (requiressimulacron, PROTOCOL_VERSION, MockLoggingHandler) -from tests.integration.simulacron.utils import prime_query, start_and_prime_singledc +from tests.integration.simulacron.utils import prime_query from cassandra import (WriteTimeout, WriteType, ConsistencyLevel, UnresolvableContactPoints) diff --git a/tests/integration/simulacron/test_connection.py b/tests/integration/simulacron/test_connection.py index 818d0b46b9..574f153edf 100644 --- a/tests/integration/simulacron/test_connection.py +++ b/tests/integration/simulacron/test_connection.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -import unittest import logging import time @@ -23,7 +22,7 @@ from cassandra.policies import HostStateListener, RoundRobinPolicy, WhiteListRoundRobinPolicy from tests import connection_class, thread_pool_executor_class -from tests.util import late +from tests.util import late, wait_until_not_raised from tests.integration import requiressimulacron, libevtest from tests.integration.util import assert_quiescent_pool_state # important to import the patch PROTOCOL_VERSION from the simulacron module @@ -356,13 +355,15 @@ def test_retry_after_defunct(self): for _ in range(10): session.execute(query_to_prime) - # Might take some time to close the previous connections and reconnect - time.sleep(10) - assert_quiescent_pool_state(cluster) + # Wait for previous connections to close and pool to stabilize + wait_until_not_raised( + lambda: assert_quiescent_pool_state(cluster), + delay=1, max_attempts=30) clear_queries() - time.sleep(10) - assert_quiescent_pool_state(cluster) + wait_until_not_raised( + lambda: assert_quiescent_pool_state(cluster), + delay=1, max_attempts=30) def test_idle_connection_is_not_closed(self): """ diff --git a/tests/integration/simulacron/test_empty_column.py b/tests/integration/simulacron/test_empty_column.py index 2dbf3985ad..015f303d56 100644 --- a/tests/integration/simulacron/test_empty_column.py +++ b/tests/integration/simulacron/test_empty_column.py @@ -11,11 +11,9 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -import unittest from collections import namedtuple, OrderedDict -from cassandra import ProtocolVersion from cassandra.cluster import Cluster, EXEC_PROFILE_DEFAULT from cassandra.query import (named_tuple_factory, tuple_factory, dict_factory, ordered_dict_factory) @@ -140,9 +138,9 @@ def test_empty_columns_in_system_schema(self): 'delay_in_ms': 0, 'rows': [ { - "strategy_class": "SimpleStrategy", # C* 2.2 + "strategy_class": "NetworkTopologyStrategy", # C* 2.2 "strategy_options": '{}', # C* 2.2 - "replication": {'strategy': 'SimpleStrategy', 'replication_factor': 1}, + "replication": {'strategy': 'NetworkTopologyStrategy', 'replication_factor': 1}, "durable_writes": True, "keyspace_name": "testks" } diff --git a/tests/integration/simulacron/test_endpoint.py b/tests/integration/simulacron/test_endpoint.py index 5af38a9f6b..005d15a422 100644 --- a/tests/integration/simulacron/test_endpoint.py +++ b/tests/integration/simulacron/test_endpoint.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -import unittest from functools import total_ordering diff --git a/tests/integration/simulacron/utils.py b/tests/integration/simulacron/utils.py index b6136e247a..9f6791be30 100644 --- a/tests/integration/simulacron/utils.py +++ b/tests/integration/simulacron/utils.py @@ -14,7 +14,6 @@ import json import subprocess -import time from urllib.request import build_opener, Request, HTTPHandler from cassandra.metadata import SchemaParserV4, SchemaParserDSE68 @@ -89,8 +88,13 @@ def start_simulacron(): SERVER_SIMULACRON.start() - # TODO improve this sleep, maybe check the logs like ccm - time.sleep(5) + # Poll the admin endpoint until simulacron is ready + def _check_simulacron_ready(): + opener = build_opener(HTTPHandler) + request = Request("http://127.0.0.1:8187/cluster") + opener.open(request, timeout=2) + + wait_until_not_raised(_check_simulacron_ready, delay=0.5, max_attempts=30) def stop_simulacron(): diff --git a/tests/integration/standard/column_encryption/test_policies.py b/tests/integration/standard/column_encryption/test_policies.py index 9a1d186895..4b12fa135a 100644 --- a/tests/integration/standard/column_encryption/test_policies.py +++ b/tests/integration/standard/column_encryption/test_policies.py @@ -30,7 +30,7 @@ class ColumnEncryptionPolicyTest(unittest.TestCase): def _recreate_keyspace(self, session): session.execute("drop keyspace if exists foo") - session.execute("CREATE KEYSPACE foo WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}") + session.execute("CREATE KEYSPACE foo WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'}") session.execute("CREATE TABLE foo.bar(encrypted blob, unencrypted int, primary key(unencrypted))") def _create_policy(self, key, iv = None): diff --git a/tests/integration/standard/conftest.py b/tests/integration/standard/conftest.py index 6028c2a06d..ce73a10433 100644 --- a/tests/integration/standard/conftest.py +++ b/tests/integration/standard/conftest.py @@ -1,6 +1,69 @@ -import pytest import logging +# Cluster topology groups for test ordering. +# Tests are sorted so that modules sharing the same CCM cluster run +# together, minimising expensive cluster teardown/restart cycles. +# Lower number = runs first. Modules not listed get a high default. +_MODULE_CLUSTER_ORDER = { + # Group 0: default 3-node singledc (CLUSTER_NAME = 'test_cluster') + "test_metadata": 0, + "test_policies": 0, + "test_control_connection": 0, + "test_routing": 0, + "test_prepared_statements": 0, + "test_metrics": 0, + "test_connection": 0, + "test_concurrent": 0, + "test_custom_payload": 0, + "test_query_paging": 0, + "test_single_interface": 0, + "test_rate_limit_exceeded": 0, + # Group 1: 'cluster_tests' (--smp 2, 3 nodes) + "test_cluster": 1, + "test_shard_aware": 1, + # Group 2: 'shared_aware' (--smp 2 --memory 2048M, 3 nodes) + "test_use_keyspace": 2, + "test_client_routes": 2, + # Group 3: single-node cluster + "test_types": 3, + "test_cython_protocol_handlers": 3, + "test_custom_protocol_handler": 3, + "test_row_factories": 3, + "test_udts": 3, + "test_client_warnings": 3, + "test_application_info": 3, + # Group 4: destructive / special clusters (run last) + "test_ip_change": 4, + "test_authentication": 4, + "test_authentication_misconfiguration": 4, + "test_control_connection_query_fallback": 4, + "test_custom_cluster": 4, + "test_query": 4, + # Group 5: tablets (destructive — decommissions a node) + "test_tablets": 5, + # Group 6: schema change + node kill (destructive — kills node2) + "test_concurrent_schema_change_and_node_kill": 6, + # Group 7: multi-dc (7 nodes — most expensive to create) + "test_rack_aware_policy": 7, +} + + +def pytest_collection_modifyitems(items): + """Sort tests so modules with the same cluster topology are adjacent. + + Uses the original collection index as tie-breaker so that the + definition order inside each file is preserved (important for tests + that depend on running order, e.g. destructive tablet tests). + """ + orig_order = {id(item): idx for idx, item in enumerate(items)} + + def _sort_key(item): + module_name = item.module.__name__.rsplit(".", 1)[-1] + return (_MODULE_CLUSTER_ORDER.get(module_name, 99), item.fspath, orig_order[id(item)]) + + items[:] = sorted(items, key=_sort_key) + + # from https://github.com/streamlit/streamlit/pull/5047/files def pytest_sessionfinish(): # We're not waiting for scriptrunner threads to cleanly close before ending the PyTest, @@ -10,4 +73,4 @@ def pytest_sessionfinish(): # * https://github.com/pytest-dev/pytest/issues/5282 # To prevent the exception from being raised on pytest_sessionfinish # we disable exception raising in logging module - logging.raiseExceptions = False \ No newline at end of file + logging.raiseExceptions = False diff --git a/tests/integration/standard/test_application_info.py b/tests/integration/standard/test_application_info.py index 719f37843a..5d4b679fc8 100644 --- a/tests/integration/standard/test_application_info.py +++ b/tests/integration/standard/test_application_info.py @@ -27,7 +27,7 @@ def teardown_module(): @xfail_scylla_version_lt(reason='scylladb/scylla-enterprise#5467 - system.client_options is not yet supported', - oss_scylla_version="7.0", ent_scylla_version="2026.1.0") + scylla_version="2026.1.0") class ApplicationInfoTest(unittest.TestCase): attribute_to_startup_key = { 'application_name': 'APPLICATION_NAME', diff --git a/tests/integration/standard/test_authentication.py b/tests/integration/standard/test_authentication.py index eb8019bf65..f23cc324b1 100644 --- a/tests/integration/standard/test_authentication.py +++ b/tests/integration/standard/test_authentication.py @@ -12,6 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. +import os + from packaging.version import Version import logging import time @@ -20,7 +22,7 @@ from cassandra.auth import PlainTextAuthProvider, SASLClient, SaslAuthProvider from tests.integration import use_singledc, get_cluster, remove_cluster, PROTOCOL_VERSION, \ - CASSANDRA_IP, CASSANDRA_VERSION, USE_CASS_EXTERNAL, start_cluster_wait_for_up, TestCluster + CASSANDRA_IP, CASSANDRA_VERSION, start_cluster_wait_for_up, TestCluster from tests.integration.util import assert_quiescent_pool_state import unittest @@ -32,27 +34,51 @@ #This can be tested for remote hosts, but the cluster has to be configured accordingly #@local +_saved_scylla_ext_opts = None + def setup_module(): - if CASSANDRA_IP.startswith("127.0.0.") and not USE_CASS_EXTERNAL: + global _saved_scylla_ext_opts + _saved_scylla_ext_opts = os.environ.get('SCYLLA_EXT_OPTS') + if CASSANDRA_IP.startswith("127.0.0."): use_singledc(start=False) ccm_cluster = get_cluster() ccm_cluster.stop() - config_options = {'authenticator': 'PasswordAuthenticator', - 'authorizer': 'CassandraAuthorizer'} + config_options = { + 'authenticator': 'PasswordAuthenticator', + 'authorizer': 'CassandraAuthorizer', + 'auth_superuser_name': 'cassandra', + 'auth_superuser_salted_password': '$6$x7IFjiX5VCpvNiFk$2IfjTvSyGL7zerpV.wbY7mJjaRCrJ/68dtT3UpT.sSmNYz1bPjtn3mH.kJKFvaZ2T4SbVeBijjmwGjcb83LlV/' + } ccm_cluster.set_configuration_options(config_options) log.debug("Starting ccm test cluster with %s", config_options) start_cluster_wait_for_up(ccm_cluster) # PYTHON-1328 # - # Give the cluster enough time to startup (and perform necessary initialization) - # before executing the test. + # Wait for PasswordAuthenticator to finish initializing (creating the + # default superuser). Poll by attempting to authenticate rather than + # using a fixed sleep. if CASSANDRA_VERSION > Version('4.0-a'): - time.sleep(10) + from tests.util import wait_until_not_raised + + def _check_auth_ready(): + cluster = TestCluster(protocol_version=PROTOCOL_VERSION, + auth_provider=PlainTextAuthProvider('cassandra', 'cassandra')) + try: + session = cluster.connect() + session.execute("SELECT * FROM system.local WHERE key='local'") + finally: + cluster.shutdown() + + wait_until_not_raised(_check_auth_ready, delay=1, max_attempts=30) def teardown_module(): remove_cluster() # this test messes with config + if _saved_scylla_ext_opts is None: + os.environ.pop('SCYLLA_EXT_OPTS', None) + else: + os.environ['SCYLLA_EXT_OPTS'] = _saved_scylla_ext_opts class AuthenticationTests(unittest.TestCase): diff --git a/tests/integration/standard/test_authentication_misconfiguration.py b/tests/integration/standard/test_authentication_misconfiguration.py index 9ad4ad997d..12397e4a8d 100644 --- a/tests/integration/standard/test_authentication_misconfiguration.py +++ b/tests/integration/standard/test_authentication_misconfiguration.py @@ -15,7 +15,7 @@ import unittest import pytest -from tests.integration import USE_CASS_EXTERNAL, use_cluster, TestCluster +from tests.integration import use_cluster, TestCluster @pytest.mark.skip(reason="Flaky test - needs investigation whether its Scylla's or driver's fault." @@ -24,16 +24,15 @@ class MisconfiguredAuthenticationTests(unittest.TestCase): """ One node (not the contact point) has password auth. The rest of the nodes have no auth """ @classmethod def setUpClass(cls): - if not USE_CASS_EXTERNAL: - ccm_cluster = use_cluster(cls.__name__, [3], start=False) - node3 = ccm_cluster.nodes['node3'] - node3.set_configuration_options(values={ - 'authenticator': 'PasswordAuthenticator', - 'authorizer': 'CassandraAuthorizer', - }) - ccm_cluster.start(wait_for_binary_proto=True, wait_other_notice=True) + ccm_cluster = use_cluster(cls.__name__, [3], start=False) + node3 = ccm_cluster.nodes['node3'] + node3.set_configuration_options(values={ + 'authenticator': 'PasswordAuthenticator', + 'authorizer': 'CassandraAuthorizer', + }) + ccm_cluster.start(wait_for_binary_proto=True, wait_other_notice=True) - cls.ccm_cluster = ccm_cluster + cls.ccm_cluster = ccm_cluster def test_connect_no_auth_provider(self): cluster = TestCluster() @@ -45,5 +44,4 @@ def test_connect_no_auth_provider(self): @classmethod def tearDownClass(cls): - if not USE_CASS_EXTERNAL: - cls.ccm_cluster.stop() + cls.ccm_cluster.stop() diff --git a/tests/integration/standard/test_client_routes.py b/tests/integration/standard/test_client_routes.py new file mode 100644 index 0000000000..f365a628f8 --- /dev/null +++ b/tests/integration/standard/test_client_routes.py @@ -0,0 +1,1214 @@ +# Copyright 2026 ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Comprehensive integration tests for Client Routes (Private Link) support. + +Includes: +- TCP proxy and NLB emulator for simulating private link infrastructure +- Tests verifying all connections go exclusively through the proxy +- Tests for dynamic route updates and topology changes +- Tests for query_routes filtering +""" + +import logging +import os +import shutil +import ssl +import subprocess +import tempfile +import threading +import time +import unittest +import uuid + +import json as _json +import urllib.request + +from cassandra.cluster import Cluster +from cassandra.client_routes import ClientRoutesConfig, ClientRouteProxy +from cassandra.connection import ClientRoutesEndPoint +from cassandra.policies import RoundRobinPolicy +from tests.integration import ( + TestCluster, + get_cluster, + get_node, + use_cluster, + wait_for_node_socket, + skip_scylla_version_lt, +) +from tests.tcp_proxy import TcpProxy +from tests.util import wait_until_not_raised + +log = logging.getLogger(__name__) + +class NLBEmulator: + """ + Emulates a Network Load Balancer for a CCM cluster. + + Provides: + - One *discovery port* (round-robin across all live nodes, used as the + driver's ``contact_points``). + - One *per-node port* for each node (dedicated proxy to that node's + native transport port). + + All proxies listen on ``LISTEN_HOST`` (127.254.254.101), an address + outside the CCM node range, simulating a real NLB endpoint. + + Port layout (all ports are OS-assigned by default): + LISTEN_HOST:discovery_port -> round-robin to all live nodes + LISTEN_HOST: -> node1 (127.0.0.1:9042) + LISTEN_HOST: -> node2 (127.0.0.2:9042) + ... + + Automatically creates/removes per-node proxies when nodes are + added/removed so CCM cluster operations are reflected seamlessly. + """ + + LISTEN_HOST = "127.254.254.101" + + def __init__(self, discovery_port=0, + per_node_base=0, + native_port=9042, + node_addresses=None): + self.discovery_port = discovery_port + self.per_node_base = per_node_base + self.native_port = native_port + self._deferred_node_addresses = node_addresses + + self._node_proxies = {} + self._discovery_proxy = None + self._rr_index = 0 + # RLock: add_node() holds it while _add_node_proxy() re-acquires it. + self._lock = threading.RLock() + self._running = False + + def start(self, node_addresses): + """ + Start the NLB with an initial set of node addresses. + + :param node_addresses: dict of node_id -> ip_address, e.g. + {1: "127.0.0.1", 2: "127.0.0.2"} + """ + self._running = True + try: + for node_id, addr in node_addresses.items(): + self._add_node_proxy(node_id, addr) + + first_addr = list(node_addresses.values())[0] + self._discovery_proxy = TcpProxy( + self.LISTEN_HOST, self.discovery_port, + first_addr, self.native_port, + ) + self._discovery_proxy.start() + self.discovery_port = self._discovery_proxy.listen_port + except Exception: + self.stop() + raise + original_handler = self._discovery_proxy._handle_new_connection + + def rr_handler(client_sock): + addrs = self._live_addresses() + if not addrs: + client_sock.close() + return + idx = self._rr_index % len(addrs) + self._rr_index += 1 + addr = addrs[idx] + original_handler(client_sock, target_host=addr, target_port=self.native_port) + + self._discovery_proxy._handle_new_connection = rr_handler + + log.info("NLB started: discovery=%s:%d, %d node proxies", + self.LISTEN_HOST, self.discovery_port, len(self._node_proxies)) + return self + + def __enter__(self): + if not self._running and self._deferred_node_addresses is not None: + self.start(self._deferred_node_addresses) + return self + + def __exit__(self, *args): + self.stop() + + def stop(self): + self._running = False + if self._discovery_proxy: + self._discovery_proxy.stop() + for proxy in self._node_proxies.values(): + proxy.stop() + self._node_proxies.clear() + log.info("NLB stopped") + + def add_node(self, node_id, addr): + # Serialize against remove_node(): TcpProxy.stop() blocks until + # joined, so by the time we get the lock any freed fds are reaped. + with self._lock: + self._add_node_proxy(node_id, addr) + + def remove_node(self, node_id): + with self._lock: + proxy = self._node_proxies.pop(node_id, None) + if proxy: + proxy.stop() + if proxy: + log.info("NLB removed node %d", node_id) + + def node_port(self, node_id): + proxy = self._node_proxies.get(node_id) + if proxy: + return proxy.listen_port + return self.per_node_base + node_id + + def get_node_proxy(self, node_id): + return self._node_proxies.get(node_id) + + def total_proxy_connections(self): + return sum(p.total_connections for p in self._node_proxies.values()) + + def active_proxy_connections(self): + return sum(p.active_connections for p in self._node_proxies.values()) + + def drop_all_connections(self): + for proxy in self._node_proxies.values(): + proxy.drop_connections() + if self._discovery_proxy: + self._discovery_proxy.drop_connections() + + def _add_node_proxy(self, node_id, addr): + port = 0 + proxy = TcpProxy(self.LISTEN_HOST, port, addr, self.native_port) + proxy.start() + with self._lock: + self._node_proxies[node_id] = proxy + log.info("NLB added node %d: %s:%d -> %s:%d", + node_id, self.LISTEN_HOST, port, addr, self.native_port) + + def _live_addresses(self): + """ + IPs of nodes with active proxies. + + Snapshots under _lock: rr_handler() (the discovery port's accept + handler) calls this from the discovery TcpProxy's own accept-loop + thread, concurrently with add_node()/remove_node() mutating + _node_proxies from other threads. Without the lock, a node being + added/removed mid-iteration can raise "RuntimeError: dictionary + changed size during iteration". + """ + with self._lock: + return [p.target_host for p in self._node_proxies.values()] + +def post_client_routes(contact_point, routes): + """ + Post client routes to Scylla's REST API. + + :param contact_point: IP/hostname of a Scylla node (e.g. "127.0.0.1") + :param routes: List of route dicts with keys: connection_id, host_id, address, port + and optionally tls_port + """ + payload = [] + for route in routes: + entry = { + "connection_id": str(route["connection_id"]), + "host_id": str(route["host_id"]), + "address": route["address"], + "port": route["port"], + } + if route.get("tls_port") is not None: + entry["tls_port"] = route["tls_port"] + payload.append(entry) + + url = "http://%s:10000/v2/client-routes" % contact_point + log.info("Posting %d routes to %s", len(payload), url) + data = _json.dumps(payload).encode("utf-8") + req = urllib.request.Request( + url, + data=data, + headers={ + "Content-Type": "application/json", + "Accept": "application/json", + }, + method="POST", + ) + response = urllib.request.urlopen(req) + log.info("Routes posted successfully (status %d)", response.status) + + +def get_host_ids_from_cluster(session): + """ + Build a mapping of rpc_address -> host_id for all nodes in the cluster. + + Uses the driver's metadata rather than querying system.local / system.peers + directly, because those queries can be routed to different coordinators + (system.local returns the coordinator's own info while system.peers omits + the coordinator), leading to a node being missing from the map. + """ + host_id_map = {} + for host in session.cluster.metadata.all_hosts(): + host_id_map[host.address] = host.host_id + return host_id_map + + +def build_routes_for_nlb(connection_id, host_id_map, nlb): + """ + Build routes that direct each host_id through the NLB per-node proxy. + + :param connection_id: Connection ID string + :param host_id_map: dict ip -> uuid host_id (from get_host_ids_from_cluster) + :param nlb: NLBEmulator instance + :return: list of route dicts + """ + routes = [] + for ip, host_id in host_id_map.items(): + node_id = int(ip.split(".")[-1]) + port = nlb.node_port(node_id) + routes.append({ + "connection_id": connection_id, + "host_id": host_id, + "address": NLBEmulator.LISTEN_HOST, + "port": port, + }) + return routes + + +def post_routes_for_nlb(contact_point, connection_id, host_id_map, nlb): + """Build routes for the NLB and POST them via the REST API.""" + routes = build_routes_for_nlb(connection_id, host_id_map, nlb) + post_client_routes(contact_point, routes) + return routes + +def wait_for_routes_visible(session, connection_id, expected_count, timeout=10, poll_interval=0.1): + """ + Poll system.client_routes on **every** node until each one sees at + least *expected_count* rows for *connection_id*. + + ``system.client_routes`` is a node-local table, so routes posted via + the REST API to one node are not guaranteed to be visible on the + others at the same time. This helper ensures they have propagated + everywhere before the test proceeds. + + :param session: an active driver Session (direct, not through NLB) + :param connection_id: the connection_id string to filter on + :param expected_count: how many rows we expect to see per node + :param timeout: maximum seconds to wait + :param poll_interval: seconds between polls + """ + all_hosts = list(session.cluster.metadata.all_hosts()) + deadline = time.time() + timeout + while True: + pending_hosts = [] + for host in all_hosts: + rows = list(session.execute( + "SELECT * FROM system.client_routes WHERE connection_id = %s", + (connection_id,), + host=host, + )) + if len(rows) < expected_count: + pending_hosts.append((host, len(rows))) + if not pending_hosts: + return + if time.time() >= deadline: + details = ", ".join( + "%s: %d" % (h.address, count) for h, count in pending_hosts + ) + raise RuntimeError( + "Timed out waiting for %d routes (connection_id=%s) to appear " + "in system.client_routes on all nodes; pending: %s" + % (expected_count, connection_id, details) + ) + time.sleep(poll_interval) + + +def node_id_from_ip(ip): + """Extract node_id from an IP like '127.0.0.3' -> 3.""" + return int(ip.split(".")[-1]) + + +def assert_routes_via_nlb(test, cluster, nlb, expected_node_ids): + """ + Assert that every host in *expected_node_ids* has its endpoint + resolving through the NLB (correct address and per-node port). + """ + nlb_listen_host = NLBEmulator.LISTEN_HOST + expected_node_ids = set(expected_node_ids) + + seen_node_ids = set() + for host in cluster.metadata.all_hosts(): + ep = host.endpoint + if not isinstance(ep, ClientRoutesEndPoint): + continue + node_id = node_id_from_ip(ep.address) + if node_id not in expected_node_ids: + continue + resolved_addr, resolved_port = ep.resolve() + test.assertEqual( + resolved_addr, nlb_listen_host, + "Node %d endpoint should resolve to NLB address %s, got %s" + % (node_id, nlb_listen_host, resolved_addr), + ) + test.assertEqual( + resolved_port, nlb.node_port(node_id), + "Node %d endpoint should resolve to NLB port %d, got %d" + % (node_id, nlb.node_port(node_id), resolved_port), + ) + seen_node_ids.add(node_id) + test.assertEqual( + seen_node_ids, expected_node_ids, + "Not all expected nodes found in metadata endpoints", + ) + + +def assert_routes_direct(test, cluster, expected_node_ids, direct_port=9042): + """ + Assert that every host in *expected_node_ids* has its endpoint + resolving to the node's own IP on *direct_port*. + """ + expected_node_ids = set(expected_node_ids) + + for host in cluster.metadata.all_hosts(): + ep = host.endpoint + if not isinstance(ep, ClientRoutesEndPoint): + continue + node_id = node_id_from_ip(ep.address) + if node_id not in expected_node_ids: + continue + resolved_addr, resolved_port = ep.resolve() + expected_ip = "127.0.0.%d" % node_id + test.assertEqual( + resolved_addr, expected_ip, + "Node %d endpoint should resolve to direct address %s, got %s" + % (node_id, expected_ip, resolved_addr), + ) + test.assertEqual( + resolved_port, direct_port, + "Node %d endpoint should resolve to direct port %d, got %d" + % (node_id, direct_port, resolved_port), + ) + + +_saved_scylla_ext_opts = None + + +def setup_module(): + global _saved_scylla_ext_opts + _saved_scylla_ext_opts = os.environ.get('SCYLLA_EXT_OPTS') + os.environ['SCYLLA_EXT_OPTS'] = "--smp 2 --memory 2048M" + use_cluster('shared_aware', [3], start=True) + + +def teardown_module(): + if _saved_scylla_ext_opts is None: + os.environ.pop('SCYLLA_EXT_OPTS', None) + else: + os.environ['SCYLLA_EXT_OPTS'] = _saved_scylla_ext_opts + +@skip_scylla_version_lt(reason='scylladb/scylladb#26992 - system.client_routes is not yet supported', + scylla_version="2026.1.0") +class TestGetHostPortMapping(unittest.TestCase): + """ + Test _query_all_routes_for_connections and _query_routes_for_change_event + methods with different filtering scenarios. + """ + + @classmethod + def setUpClass(cls): + cls.cluster = TestCluster(client_routes_config=ClientRoutesConfig( + proxies=[ClientRouteProxy("conn_id", "127.0.0.1")])) + cls.session = cls.cluster.connect() + + cls.host_ids = [uuid.uuid4() for _ in range(3)] + cls.connection_ids = [str(uuid.uuid4()) for _ in range(3)] + cls.expected = [] + + for idx, host_id in enumerate(cls.host_ids): + ip = f"127.0.0.{idx + 1}" + for connection_id in cls.connection_ids: + cls.expected.append({ + 'connection_id': connection_id, + 'host_id': host_id, + 'address': ip, + 'port': 9042, + 'tls_port': 9142, + }) + + cls._sort_routes(cls.expected) + post_client_routes(cls.cluster.contact_points[0], cls.expected) + + @classmethod + def tearDownClass(cls): + cls.cluster.shutdown() + + @staticmethod + def _sort_routes(routes): + routes.sort(key=lambda r: (str(r['connection_id']), str(r['host_id']))) + + def _routes_to_dicts(self, routes): + """Convert _Route objects to comparable dicts, adjusting port for ssl_enabled.""" + return [ + { + 'connection_id': route.connection_id, + 'host_id': route.host_id, + 'address': route.address, + 'port': route.port, + } + for route in routes + ] + + def _expected_dicts(self, expected): + """Build expected dicts with tls_port or port based on ssl_enabled.""" + port_key = 'tls_port' if self.cluster._client_routes_handler.ssl_enabled else 'port' + return [ + { + 'connection_id': e['connection_id'], + 'host_id': e['host_id'], + 'address': e['address'], + 'port': e[port_key], + } + for e in expected + ] + + def test_get_all_routes_for_all_connections(self): + """Querying all connection IDs returns every route.""" + cc = self.cluster.control_connection + routes = self.cluster._client_routes_handler._query_all_routes_for_connections( + cc._connection, cc._timeout, self.connection_ids, + ) + got = self._routes_to_dicts(routes) + self._sort_routes(got) + expected = self._expected_dicts(self.expected) + self._sort_routes(expected) + self.assertEqual(got, expected) + + def test_get_routes_for_single_connection(self): + """Querying a single connection ID returns only its routes.""" + cc = self.cluster.control_connection + routes = self.cluster._client_routes_handler._query_all_routes_for_connections( + cc._connection, cc._timeout, [self.connection_ids[0]], + ) + got = self._routes_to_dicts(routes) + self._sort_routes(got) + filtered = [r for r in self.expected + if r['connection_id'] == self.connection_ids[0]] + expected = self._expected_dicts(filtered) + self._sort_routes(expected) + self.assertEqual(got, expected) + + def test_get_routes_for_change_event_all_pairs(self): + """Querying all (connection_id, host_id) pairs returns every route.""" + cc = self.cluster.control_connection + pairs = [(r['connection_id'], r['host_id']) for r in self.expected] + routes = self.cluster._client_routes_handler._query_routes_for_change_event( + cc._connection, cc._timeout, pairs, + ) + got = self._routes_to_dicts(routes) + self._sort_routes(got) + expected = self._expected_dicts(self.expected) + self._sort_routes(expected) + self.assertEqual(got, expected) + + def test_get_routes_for_change_event_single_pair(self): + """Querying a single (connection_id, host_id) pair returns one route.""" + cc = self.cluster.control_connection + target_conn_id = self.connection_ids[0] + target_host_id = self.host_ids[0] + routes = self.cluster._client_routes_handler._query_routes_for_change_event( + cc._connection, cc._timeout, [(target_conn_id, target_host_id)], + ) + got = self._routes_to_dicts(routes) + self._sort_routes(got) + filtered = [r for r in self.expected + if r['connection_id'] == target_conn_id + and r['host_id'] == target_host_id] + expected = self._expected_dicts(filtered) + self._sort_routes(expected) + self.assertEqual(got, expected) + +@skip_scylla_version_lt(reason='scylladb/scylladb#26992 - system.client_routes is not yet supported', + scylla_version="2026.1.0") +class TestPrivateLinkConnectivity(unittest.TestCase): + """ + Verifies the driver connects to all cluster nodes exclusively through + the NLB proxy, never directly. + + Setup: + 1. Start a 3-node CCM cluster (done by setup_module). + 2. Start an NLB emulator with per-node proxies. + 3. Use a direct session to read host_ids, then POST client routes + pointing each host_id at the NLB proxy port. + 4. Create a client-routes-enabled session using the NLB discovery + port as the contact point. + 5. Verify all driver connections go through proxy ports. + """ + + @classmethod + def setUpClass(cls): + cls.direct_cluster = TestCluster() + cls.direct_session = cls.direct_cluster.connect() + cls.host_id_map = get_host_ids_from_cluster(cls.direct_session) + log.info("Host ID map: %s", cls.host_id_map) + + cls.node_addrs = {} + for ip in cls.host_id_map: + node_id = int(ip.split(".")[-1]) + cls.node_addrs[node_id] = ip + + cls.nlb = NLBEmulator() + cls.nlb.start(cls.node_addrs) + + cls.connection_id = str(uuid.uuid4()) + post_routes_for_nlb("127.0.0.1", cls.connection_id, cls.host_id_map, cls.nlb) + wait_for_routes_visible(cls.direct_session, cls.connection_id, len(cls.host_id_map)) + + @classmethod + def tearDownClass(cls): + cls.direct_cluster.shutdown() + cls.nlb.stop() + + def _make_client_routes_cluster(self, **extra_kwargs): + """Create a Cluster configured with client-routes pointing at the NLB.""" + return Cluster( + contact_points=[NLBEmulator.LISTEN_HOST], + port=self.nlb.discovery_port, + client_routes_config=ClientRoutesConfig( + proxies=[ClientRouteProxy(self.connection_id, NLBEmulator.LISTEN_HOST)], + ), + load_balancing_policy=RoundRobinPolicy(), + **extra_kwargs, + ) + + def test_all_connections_through_proxy(self): + """Every pool connection must go through the NLB proxy, not directly.""" + with self._make_client_routes_cluster() as cluster: + session = cluster.connect(wait_for_all_pools=True) + + for _ in range(50): + session.execute("SELECT key FROM system.local") + + pool_state = session.get_pool_state() + self.assertEqual(len(pool_state), len(self.node_addrs), + "Driver should have pools for all nodes") + + for host, state in pool_state.items(): + node_id = node_id_from_ip(host.address) + proxy = self.nlb.get_node_proxy(node_id) + self.assertIsNotNone(proxy, f"No proxy for node {node_id}") + open_count = state['open_count'] + self.assertGreaterEqual( + proxy.total_connections, open_count, + f"Node {node_id} proxy saw {proxy.total_connections} " + f"connections but pool has {open_count} open — " + f"some connections bypassed the proxy") + + assert_routes_via_nlb(self, cluster, self.nlb, + self.node_addrs.keys()) + + def test_queries_succeed_through_proxy(self): + """Queries should work normally through the proxy.""" + with self._make_client_routes_cluster() as cluster: + session = cluster.connect() + session.execute( + "CREATE KEYSPACE IF NOT EXISTS test_cr_ks " + "WITH replication = {'class':'NetworkTopologyStrategy', 'replication_factor': 3}" + ) + session.execute( + "CREATE TABLE IF NOT EXISTS test_cr_ks.t (k int PRIMARY KEY, v text)" + ) + session.execute("INSERT INTO test_cr_ks.t (k, v) VALUES (1, 'hello')") + row = session.execute("SELECT v FROM test_cr_ks.t WHERE k = 1").one() + self.assertEqual(row.v, "hello") + + assert_routes_via_nlb(self, cluster, self.nlb, + self.node_addrs.keys()) + + def test_connection_recovery_after_proxy_drop(self): + """ + After the proxy drops all connections, the driver should reconnect + (still through the proxy). + """ + with self._make_client_routes_cluster() as cluster: + session = cluster.connect(wait_for_all_pools=True) + session.execute("SELECT key FROM system.local") + + assert_routes_via_nlb(self, cluster, self.nlb, + self.node_addrs.keys()) + + self.nlb.drop_all_connections() + + def query_ok(): + session.execute("SELECT key FROM system.local") + + wait_until_not_raised(query_ok, 1, 30) + + assert_routes_via_nlb(self, cluster, self.nlb, + self.node_addrs.keys()) + +@skip_scylla_version_lt(reason='scylladb/scylladb#26992 - system.client_routes is not yet supported', + scylla_version="2026.1.0") +class TestDynamicRouteUpdates(unittest.TestCase): + """ + Verify that when routes are updated (e.g. port changes), the driver + picks up the new routes and reconnects through the new proxy ports + after existing connections are dropped. + """ + + @classmethod + def setUpClass(cls): + cls.direct_cluster = TestCluster() + cls.direct_session = cls.direct_cluster.connect() + cls.host_id_map = get_host_ids_from_cluster(cls.direct_session) + + cls.node_addrs = {} + for ip in cls.host_id_map: + node_id = int(ip.split(".")[-1]) + cls.node_addrs[node_id] = ip + + cls.connection_id = str(uuid.uuid4()) + + @classmethod + def tearDownClass(cls): + cls.direct_cluster.shutdown() + + def test_route_update_causes_reconnect_to_new_port(self): + """ + 1. Start NLB v1, post routes -> driver connects through v1 ports. + 2. Start NLB v2 on different ports, post new routes. + 3. Drop v1 connections. + 4. Driver should reconnect through v2 ports. + """ + with NLBEmulator( + node_addresses=self.node_addrs, + ) as nlb_v1, NLBEmulator( + node_addresses=self.node_addrs, + ) as nlb_v2: + post_routes_for_nlb("127.0.0.1", self.connection_id, + self.host_id_map, nlb_v1) + wait_for_routes_visible(self.direct_session, self.connection_id, len(self.host_id_map)) + + with Cluster( + contact_points=[NLBEmulator.LISTEN_HOST], + port=nlb_v1.discovery_port, + client_routes_config=ClientRoutesConfig( + proxies=[ClientRouteProxy(self.connection_id, NLBEmulator.LISTEN_HOST)], + ), + load_balancing_policy=RoundRobinPolicy(), + ) as cluster: + session = cluster.connect(wait_for_all_pools=True) + session.execute("SELECT key FROM system.local") + + for node_id in self.node_addrs: + self.assertGreater( + nlb_v1.get_node_proxy(node_id).total_connections, 0) + assert_routes_via_nlb(self, cluster, nlb_v1, + self.node_addrs.keys()) + + post_routes_for_nlb("127.0.0.1", self.connection_id, + self.host_id_map, nlb_v2) + time.sleep(2) # let CLIENT_ROUTES_CHANGE propagate + + # Stop v1 per-node proxies entirely so v1 ports become + # unreachable, forcing the driver to reconnect through v2. + # (Merely dropping connections is insufficient because v1 + # proxies would still accept new connections before the + # route update propagates.) + for node_id in list(self.node_addrs.keys()): + nlb_v1.remove_node(node_id) + + def all_nodes_via_v2(): + session.execute("SELECT key FROM system.local") + for nid in self.node_addrs: + assert nlb_v2.get_node_proxy(nid).total_connections > 0, \ + "NLB v2 node %d proxy has no connections yet" % nid + + wait_until_not_raised(all_nodes_via_v2, 1, 30) + + assert_routes_via_nlb(self, cluster, nlb_v2, + self.node_addrs.keys()) + + +def _generate_ssl_certs(cert_dir, node_ips): + """ + Generate test SSL certificates with SANs covering the given node IPs. + + File names follow CCM's ``ScyllaCluster.enable_ssl()`` convention so the + resulting directory can be passed directly to ``enable_ssl(cert_dir, ...)``. + + Creates: + - ca.key / ca.crt: self-signed CA + - ccm_node.key / ccm_node.pem: server cert signed by CA with SANs for all node_ips + + :param cert_dir: directory to write files into (must exist) + :param node_ips: list of IP strings to include as SANs (e.g. ["127.0.0.1", "127.0.0.2"]) + """ + if shutil.which("openssl") is None: + raise unittest.SkipTest("openssl not found on PATH; skipping SSL cert generation") + + san_cnf = os.path.join(cert_dir, "san.cnf") + san_value = ",".join("IP:%s" % ip for ip in node_ips) + with open(san_cnf, "w") as f: + f.write("subjectAltName=%s\n" % san_value) + + def _run(cmd): + result = subprocess.run(cmd, cwd=cert_dir, capture_output=True, text=True) + if result.returncode != 0: + raise RuntimeError("Command failed: %s\n%s" % (" ".join(cmd), result.stderr)) + + _run(["openssl", "req", "-x509", "-newkey", "rsa:2048", + "-keyout", "ca.key", "-out", "ca.crt", + "-days", "1", "-nodes", "-subj", "/CN=Test CA"]) + + _run(["openssl", "req", "-newkey", "rsa:2048", + "-keyout", "ccm_node.key", "-out", "ccm_node.csr", + "-nodes", "-subj", "/CN=Test Server"]) + + _run(["openssl", "x509", "-req", + "-in", "ccm_node.csr", "-CA", "ca.crt", "-CAkey", "ca.key", + "-CAcreateserial", "-out", "ccm_node.pem", + "-days", "1", "-extfile", "san.cnf"]) + + log.info("Generated SSL certs in %s with SANs: %s", cert_dir, san_value) + + +@skip_scylla_version_lt(reason='scylladb/scylladb#26992 - system.client_routes is not yet supported', + scylla_version="2026.1.0") +class TestMixedDirectAndNlbConnections(unittest.TestCase): + """ + Verify the cluster works when some nodes are accessed through the NLB + proxy and others are accessed directly (no route posted, falls back + to the default endpoint). + """ + + @classmethod + def setUpClass(cls): + cls.direct_cluster = TestCluster() + cls.direct_session = cls.direct_cluster.connect() + cls.host_id_map = get_host_ids_from_cluster(cls.direct_session) + + cls.node_addrs = {} + for ip in cls.host_id_map: + node_id = int(ip.split(".")[-1]) + cls.node_addrs[node_id] = ip + + cls.connection_id = str(uuid.uuid4()) + + @classmethod + def tearDownClass(cls): + cls.direct_cluster.shutdown() + + def test_mixed_direct_and_nlb_connections(self): + """ + Post routes for only a subset of nodes (through NLB proxy). + Remaining nodes have no route and fall back to direct connections. + Queries should work through both paths. + """ + proxied_node_id = min(self.node_addrs.keys()) + proxied_ip = self.node_addrs[proxied_node_id] + + with NLBEmulator( + node_addresses={proxied_node_id: proxied_ip}, + ) as nlb: + proxied_host_id = self.host_id_map[proxied_ip] + routes = [{ + "connection_id": self.connection_id, + "host_id": proxied_host_id, + "address": NLBEmulator.LISTEN_HOST, + "port": nlb.node_port(proxied_node_id), + }] + post_client_routes("127.0.0.1", routes) + time.sleep(1) + + with Cluster( + contact_points=["127.0.0.1"], + client_routes_config=ClientRoutesConfig( + proxies=[ClientRouteProxy(self.connection_id, NLBEmulator.LISTEN_HOST)], + ), + load_balancing_policy=RoundRobinPolicy(), + ) as cluster: + session = cluster.connect(wait_for_all_pools=True) + + for _ in range(50): + session.execute("SELECT key FROM system.local") + + assert_routes_via_nlb(self, cluster, nlb, + [proxied_node_id]) + + direct_node_ids = set(self.node_addrs.keys()) - {proxied_node_id} + assert_routes_direct(self, cluster, direct_node_ids) + + proxy = nlb.get_node_proxy(proxied_node_id) + self.assertGreater(proxy.total_connections, 0, + "Proxied node should have connections through NLB") + + +@skip_scylla_version_lt(reason='scylladb/scylladb#26992 - system.client_routes is not yet supported', + scylla_version="2026.1.0") +class TestSslThroughNlb(unittest.TestCase): + """ + Verify SSL with check_hostname=False works through the NLB proxy. + + When using client routes, connections go through NLB proxies whose + addresses won't match server certificates, so hostname verification + must be disabled. Certificate chain validation (verify_mode=CERT_REQUIRED) + is still active — only hostname matching is skipped. + + The driver raises ValueError at Cluster init time if check_hostname=True + is used with client_routes_config. + """ + + @classmethod + def setUpClass(cls): + cls.direct_cluster = TestCluster() + cls.direct_session = cls.direct_cluster.connect() + cls.host_id_map = get_host_ids_from_cluster(cls.direct_session) + cls.direct_cluster.shutdown() + + cls.node_addrs = {} + for ip in cls.host_id_map: + node_id = int(ip.split(".")[-1]) + cls.node_addrs[node_id] = ip + + cls.connection_id = str(uuid.uuid4()) + + cls.cert_dir = tempfile.mkdtemp(prefix="client-routes-ssl-") + cert_ips = list(cls.node_addrs.values()) + _generate_ssl_certs(cls.cert_dir, cert_ips) + + cls.ccm_cluster = get_cluster() + cls.ccm_cluster.stop() + cls.ccm_cluster.set_configuration_options({ + 'client_encryption_options': { + 'enabled': True, + 'certificate': os.path.join(cls.cert_dir, "ccm_node.pem"), + 'keyfile': os.path.join(cls.cert_dir, "ccm_node.key"), + } + }) + cls.ccm_cluster.start(wait_for_binary_proto=True) + + @classmethod + def tearDownClass(cls): + cls.ccm_cluster.stop() + cls.ccm_cluster.set_configuration_options({ + 'client_encryption_options': { + 'enabled': False, + } + }) + cls.ccm_cluster.start(wait_for_binary_proto=True) + + shutil.rmtree(cls.cert_dir, ignore_errors=True) + + def test_ssl_without_hostname_verification_through_nlb(self): + """ + Connect through NLB with SSL but check_hostname=False. + + When using client routes, connections go through NLB proxies + whose addresses won't match server certificates, so hostname + verification must be disabled. Certificate chain validation + (verify_mode=CERT_REQUIRED) is still active. + """ + with NLBEmulator( + node_addresses=self.node_addrs, + ) as nlb: + routes = build_routes_for_nlb( + self.connection_id, self.host_id_map, nlb, + ) + for route in routes: + route["tls_port"] = route["port"] + post_client_routes("127.0.0.1", routes) + + ssl_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) + ssl_ctx.check_hostname = False + ssl_ctx.load_verify_locations(os.path.join(self.cert_dir, 'ca.crt')) + + self.assertFalse(ssl_ctx.check_hostname, + "check_hostname must be False for this test") + self.assertEqual(ssl_ctx.verify_mode, ssl.CERT_REQUIRED, + "verify_mode must be CERT_REQUIRED") + + def routes_visible(): + with TestCluster( + contact_points=["127.0.0.1"], + ssl_context=ssl_ctx, connect_timeout=30, + ) as c: + session = c.connect() + rs = session.execute( + "SELECT * FROM system.client_routes " + "WHERE connection_id = %s ALLOW FILTERING", + (self.connection_id,) + ) + return len(list(rs)) >= len(self.host_id_map) + + wait_until_not_raised( + lambda: self.assertTrue(routes_visible()), + 1, 30, + ) + + with Cluster( + contact_points=[NLBEmulator.LISTEN_HOST], + port=nlb.discovery_port, + ssl_context=ssl_ctx, + client_routes_config=ClientRoutesConfig( + proxies=[ClientRouteProxy(self.connection_id, NLBEmulator.LISTEN_HOST)], + ), + load_balancing_policy=RoundRobinPolicy(), + ) as cluster: + session = cluster.connect(wait_for_all_pools=True) + + for _ in range(20): + row = session.execute( + "SELECT release_version FROM system.local" + ).one() + self.assertIsNotNone(row) + + assert_routes_via_nlb(self, cluster, nlb, + self.node_addrs.keys()) + + def test_ssl_with_hostname_verification_raises_error(self): + """ + Verify that Cluster raises ValueError when client_routes_config + is used with SSL hostname verification enabled. + """ + ssl_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) + ssl_ctx.load_verify_locations(os.path.join(self.cert_dir, 'ca.crt')) + self.assertTrue(ssl_ctx.check_hostname) + + with self.assertRaises(ValueError) as cm: + Cluster( + contact_points=[NLBEmulator.LISTEN_HOST], + ssl_context=ssl_ctx, + client_routes_config=ClientRoutesConfig( + proxies=[ClientRouteProxy("test-id", NLBEmulator.LISTEN_HOST)], + ), + ) + self.assertIn("check_hostname", str(cm.exception)) + +@skip_scylla_version_lt(reason='scylladb/scylladb#26992 - system.client_routes is not yet supported', + scylla_version="2026.1.0") +class TestFullNodeReplacementThroughNlb(unittest.TestCase): + """ + End-to-end test: creates a session through an NLB proxy with client routes, + scales the cluster up, then decommissions original nodes, verifying the + session survives the full node replacement. + + This test is destructive — it modifies the CCM cluster topology by + bootstrapping new nodes and decommissioning original ones. It uses + its own CCM cluster so it cannot interfere with other tests. + """ + + @classmethod + def setUpClass(cls): + cls._saved_scylla_ext_opts = os.environ.get('SCYLLA_EXT_OPTS') + os.environ['SCYLLA_EXT_OPTS'] = "--smp 2 --memory 2048M" + use_cluster('test_client_routes_replacement', [3], start=True) + + cls.direct_cluster = TestCluster() + cls.direct_session = cls.direct_cluster.connect() + cls.host_id_map = get_host_ids_from_cluster(cls.direct_session) + + cls.node_addrs = {} + for ip in cls.host_id_map: + node_id = int(ip.split(".")[-1]) + cls.node_addrs[node_id] = ip + + cls.connection_id = str(uuid.uuid4()) + + @classmethod + def tearDownClass(cls): + cls.direct_cluster.shutdown() + if cls._saved_scylla_ext_opts is None: + os.environ.pop('SCYLLA_EXT_OPTS', None) + else: + os.environ['SCYLLA_EXT_OPTS'] = cls._saved_scylla_ext_opts + + def test_should_survive_full_node_replacement_through_nlb(self): + """ + 1. Start with 3 nodes behind the NLB + 2. Bootstrap 3 new nodes, add to NLB, update routes + 3. Decommission the original 3 nodes one-by-one, updating NLB/routes + 4. Verify the session survives with only new nodes + """ + original_node_ids = sorted(self.node_addrs.keys()) + with NLBEmulator( + node_addresses=self.node_addrs, + ) as nlb: + # ---- Stage 1: Set up NLB for initial nodes ---- + log.info("Stage 1: Setting up NLB for %d initial nodes", len(original_node_ids)) + + post_routes_for_nlb("127.0.0.1", self.connection_id, self.host_id_map, nlb) + wait_for_routes_visible(self.direct_session, self.connection_id, len(self.host_id_map)) + + # ---- Stage 2: Create session through NLB ---- + log.info("Stage 2: Creating session through NLB") + with Cluster( + contact_points=[NLBEmulator.LISTEN_HOST], + port=nlb.discovery_port, + client_routes_config=ClientRoutesConfig( + proxies=[ClientRouteProxy(self.connection_id, NLBEmulator.LISTEN_HOST)], + ), + load_balancing_policy=RoundRobinPolicy(), + ) as cluster: + session = cluster.connect(wait_for_all_pools=True) + self._assert_query_works(session) + + handler = cluster._client_routes_handler + self.assertIsNotNone(handler) + + assert_routes_via_nlb(self, cluster, nlb, + original_node_ids) + log.info("Stage 2: Session created, all %d nodes via NLB", + len(original_node_ids)) + + # ---- Stage 3: Bootstrap new nodes ---- + new_node_ids = [max(original_node_ids) + 1, max(original_node_ids) + 2, max(original_node_ids) + 3] + log.info("Stage 3: Adding nodes %s", new_node_ids) + ccm_cluster = get_cluster() + + for node_id in new_node_ids: + self._bootstrap_node(ccm_cluster, node_id, data_center='dc1') + + expected_total = len(original_node_ids) + len(new_node_ids) + self._wait_for_condition( + lambda: len(cluster.metadata.all_hosts()) >= expected_total, + timeout_seconds=60, + description="%d nodes in metadata" % expected_total, + ) + + for node_id in new_node_ids: + nlb.add_node(node_id, "127.0.0.%d" % node_id) + + all_host_ids = get_host_ids_from_cluster(session) + log.info("All host IDs after expansion: %s", all_host_ids) + post_routes_for_nlb("127.0.0.1", self.connection_id, all_host_ids, nlb) + + handler.initialize( + cluster.control_connection._connection, + cluster.control_connection._timeout) + + self._wait_for_condition( + lambda: sum(1 for h in cluster.metadata.all_hosts() if h.is_up) >= expected_total, + timeout_seconds=60, + description="all %d nodes up" % expected_total, + ) + + self._assert_query_works(session) + + all_node_ids = set(original_node_ids) | set(new_node_ids) + assert_routes_via_nlb(self, cluster, nlb, all_node_ids) + log.info("Stage 3: All %d nodes via NLB after expansion", + len(all_node_ids)) + + # ---- Stage 4: Decommission original nodes ---- + log.info("Stage 4: Decommissioning original nodes %s", original_node_ids) + + remaining_node_ids = set(all_node_ids) + remaining_host_ids = dict(all_host_ids) + for node_id in original_node_ids: + log.info("Decommissioning node %d", node_id) + get_node(node_id).decommission() + nlb.remove_node(node_id) + remaining_node_ids.discard(node_id) + + ip = "127.0.0.%d" % node_id + remaining_host_ids.pop(ip, None) + + surviving_ips = list(remaining_host_ids.keys()) + if surviving_ips: + post_routes_for_nlb( + surviving_ips[0], self.connection_id, + remaining_host_ids, nlb, + ) + + expected_remaining = expected_total - (original_node_ids.index(node_id) + 1) + self._wait_for_condition( + lambda er=expected_remaining: ( + len(cluster.metadata.all_hosts()) <= er + and self._query_succeeds(session) + ), + timeout_seconds=60, + description="node %d decommissioned" % node_id, + ) + + # Reload routes after the control connection has + # re-established itself (the decommission may have + # killed the old control connection). + handler.initialize( + cluster.control_connection._connection, + cluster.control_connection._timeout) + + assert_routes_via_nlb(self, cluster, nlb, + remaining_node_ids) + log.info("Node %d decommissioned, %d nodes still via NLB", + node_id, len(remaining_node_ids)) + + # ---- Stage 5: Verify with only new nodes ---- + log.info("Stage 5: Verifying session works with only new nodes %s", new_node_ids) + self._assert_query_works(session) + + hosts = cluster.metadata.all_hosts() + self.assertEqual( + len(hosts), len(new_node_ids), + "Expected %d hosts, got %d" % (len(new_node_ids), len(hosts)) + ) + + for _ in range(10): + self._assert_query_works(session) + + assert_routes_via_nlb(self, cluster, nlb, new_node_ids) + log.info("PASS: Full node replacement, all %d new nodes via NLB", + len(new_node_ids)) + + def _assert_query_works(self, session): + rs = session.execute("SELECT release_version FROM system.local WHERE key='local'") + row = rs.one() + self.assertIsNotNone(row, "Query via NLB should return a result") + + def _query_succeeds(self, session): + try: + self._assert_query_works(session) + return True + except Exception: + return False + + def _bootstrap_node(self, ccm_cluster, node_id, data_center=None, rack=None): + node_type = type(next(iter(ccm_cluster.nodes.values()))) + ip = "127.0.0.%d" % node_id + node_instance = node_type( + 'node%s' % node_id, + ccm_cluster, + auto_bootstrap=True, + thrift_interface=(ip, 9160), + storage_interface=(ip, 7000), + binary_interface=(ip, 9042), + jmx_port=str(7000 + 100 * node_id), + remote_debug_port=0, + initial_token=None, + ) + # CCM requires explicit data_center/rack when adding a node so that + # cassandra-rackdc.properties is written correctly. Without this the + # snitch fails to parse the empty properties file and the node crashes + # on startup. + ccm_cluster.add(node_instance, is_seed=False, + data_center=data_center, rack=rack) + node_instance.start(wait_for_binary_proto=True, wait_other_notice=True) + wait_for_node_socket(node_instance, 120) + log.info("Node %d bootstrapped successfully", node_id) + + @staticmethod + def _wait_for_condition(predicate, timeout_seconds, poll_interval=2, description="condition"): + deadline = time.time() + timeout_seconds + while time.time() < deadline: + if predicate(): + return True + time.sleep(poll_interval) + raise AssertionError( + "Timed out waiting for %s after %d seconds" % (description, timeout_seconds) + ) diff --git a/tests/integration/standard/test_client_warnings.py b/tests/integration/standard/test_client_warnings.py index 781b5b7860..c18fa8cb1f 100644 --- a/tests/integration/standard/test_client_warnings.py +++ b/tests/integration/standard/test_client_warnings.py @@ -17,13 +17,13 @@ from cassandra.query import BatchStatement -from tests.integration import (use_singledc, PROTOCOL_VERSION, local, TestCluster, +from tests.integration import (use_single_node, PROTOCOL_VERSION, local, TestCluster, requires_custom_payload, xfail_scylla) from tests.util import assertRegex, assertDictEqual def setup_module(): - use_singledc() + use_single_node() @xfail_scylla('scylladb/scylladb#10196 - scylla does not report warnings') class ClientWarningTests(unittest.TestCase): diff --git a/tests/integration/standard/test_cluster.py b/tests/integration/standard/test_cluster.py index bf62f5df48..9db4fede9e 100644 --- a/tests/integration/standard/test_cluster.py +++ b/tests/integration/standard/test_cluster.py @@ -27,10 +27,10 @@ import pytest import cassandra -from cassandra.cluster import NoHostAvailable, ExecutionProfile, EXEC_PROFILE_DEFAULT, ControlConnection, Cluster +from cassandra.cluster import NoHostAvailable, ExecutionProfile, EXEC_PROFILE_DEFAULT, Cluster from cassandra.concurrent import execute_concurrent from cassandra.policies import (RoundRobinPolicy, ExponentialReconnectionPolicy, - RetryPolicy, SimpleConvictionPolicy, HostDistance, + SimpleConvictionPolicy, HostDistance, AddressTranslator, TokenAwarePolicy, HostFilterPolicy) from cassandra import ConsistencyLevel @@ -43,7 +43,7 @@ from tests.integration import use_cluster, get_server_versions, CASSANDRA_VERSION, \ execute_until_pass, execute_with_long_wait_retry, get_node, MockLoggingHandler, get_unsupported_lower_protocol, \ get_unsupported_upper_protocol, local, CASSANDRA_IP, greaterthanorequalcass30, \ - lessthanorequalcass40, TestCluster, PROTOCOL_VERSION, xfail_scylla, incorrect_test + lessthanorequalcass40, TestCluster, PROTOCOL_VERSION, incorrect_test from tests.integration.util import assert_quiescent_pool_state from tests.util import assertListEqual import sys @@ -51,12 +51,24 @@ log = logging.getLogger(__name__) +_saved_scylla_ext_opts = None + + def setup_module(): - os.environ['SCYLLA_EXT_OPTS'] = "--smp 1" + global _saved_scylla_ext_opts + _saved_scylla_ext_opts = os.environ.get('SCYLLA_EXT_OPTS') + os.environ['SCYLLA_EXT_OPTS'] = "--smp 2" use_cluster("cluster_tests", [3], start=True, workloads=None) warnings.simplefilter("always") +def teardown_module(): + if _saved_scylla_ext_opts is None: + os.environ.pop('SCYLLA_EXT_OPTS', None) + else: + os.environ['SCYLLA_EXT_OPTS'] = _saved_scylla_ext_opts + + class IgnoredHostPolicy(RoundRobinPolicy): def __init__(self, ignored_hosts): @@ -168,7 +180,7 @@ def test_basic(self): result = execute_until_pass(session, """ CREATE KEYSPACE clustertests - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'} """) assert not result @@ -720,10 +732,13 @@ def _warning_are_issued_when_auth(self, auth_provider): session = cluster.connect() assert session.execute("SELECT * from system.local WHERE key='local'") is not None - # Three conenctions to nodes plus the control connection + # Verify that auth warnings are issued for connections where + # auth is configured but the server does not send a challenge. + # At minimum one warning per node connection (3 for a 3-node + # cluster). The control connection and shard-aware connections + # may add more, so we only assert a lower bound. auth_warning = mock_handler.get_message_count('warning', "An authentication challenge was not sent") - assert auth_warning >= 4 - assert auth_warning == mock_handler.get_message_count("debug", "Got ReadyMessage on new connection") + assert auth_warning >= 3 def _wait_for_all_shard_connections(self, cluster, timeout=30): """Wait until all shard-aware connections are fully established.""" @@ -1121,8 +1136,7 @@ def test_stale_connections_after_shutdown(self): """ for _ in range(10): with TestCluster(protocol_version=3) as cluster: - cluster.connect().execute("SELECT * FROM system_schema.keyspaces") - time.sleep(1) + cluster.connect(wait_for_all_pools=True).execute("SELECT * FROM system_schema.keyspaces") with TestCluster(protocol_version=3) as cluster: session = cluster.connect() @@ -1181,27 +1195,35 @@ def test_replicas_are_queried(self): Then using HostFilterPolicy the replica is excluded from the considered hosts. By checking the trace we verify that there are no more replicas. + Requires tablets feature disabled. + @since 3.5 @jira_ticket PYTHON-653 @expected_result the replicas are queried for HostFilterPolicy @test_category metadata """ + ks_name = 'test_replicas_queried_ks' queried_hosts = set() tap_profile = ExecutionProfile( load_balancing_policy=TokenAwarePolicy(RoundRobinPolicy()) ) with TestCluster(execution_profiles={EXEC_PROFILE_DEFAULT: tap_profile}) as cluster: session = cluster.connect(wait_for_all_pools=True) + session.execute("DROP KEYSPACE IF EXISTS {}".format(ks_name)) + session.execute( + "CREATE KEYSPACE {} WITH replication = {{'class': 'NetworkTopologyStrategy', " + "'replication_factor': '1'}} AND tablets = {{'enabled': false}}".format(ks_name) + ) session.execute(''' - CREATE TABLE test1rf.table_with_big_key ( + CREATE TABLE {}.table_with_big_key ( k1 int, k2 int, k3 int, k4 int, - PRIMARY KEY((k1, k2, k3), k4))''') - prepared = session.prepare("""SELECT * from test1rf.table_with_big_key - WHERE k1 = ? AND k2 = ? AND k3 = ? AND k4 = ?""") + PRIMARY KEY((k1, k2, k3), k4))'''.format(ks_name)) + prepared = session.prepare("""SELECT * from {}.table_with_big_key + WHERE k1 = ? AND k2 = ? AND k3 = ? AND k4 = ?""".format(ks_name)) for i in range(10): result = session.execute(prepared, (i, i, i, i), trace=True) trace = result.response_future.get_query_trace(query_cl=ConsistencyLevel.ALL) @@ -1220,14 +1242,14 @@ def test_replicas_are_queried(self): execution_profiles={EXEC_PROFILE_DEFAULT: hfp_profile}) as cluster: session = cluster.connect(wait_for_all_pools=True) - prepared = session.prepare("""SELECT * from test1rf.table_with_big_key - WHERE k1 = ? AND k2 = ? AND k3 = ? AND k4 = ?""") + prepared = session.prepare("""SELECT * from {}.table_with_big_key + WHERE k1 = ? AND k2 = ? AND k3 = ? AND k4 = ?""".format(ks_name)) for _ in range(10): result = session.execute(prepared, (last_i, last_i, last_i, last_i), trace=True) trace = result.response_future.get_query_trace(query_cl=ConsistencyLevel.ALL) self._assert_replica_queried(trace, only_replicas=False) - session.execute('''DROP TABLE test1rf.table_with_big_key''') + session.execute('DROP KEYSPACE {}'.format(ks_name)) @greaterthanorequalcass30 @lessthanorequalcass40 @@ -1492,7 +1514,7 @@ def test_prepare_on_ignored_hosts(self): hosts = cluster.metadata.all_hosts() session.execute("CREATE KEYSPACE clustertests " "WITH replication = " - "{'class': 'SimpleStrategy', 'replication_factor': '1'}") + "{'class': 'NetworkTopologyStrategy', 'replication_factor': '1'}") session.execute("CREATE TABLE clustertests.tab (a text, PRIMARY KEY (a))") # assign to an unused variable so cluster._prepared_statements retains # reference diff --git a/tests/integration/standard/test_concurrent.py b/tests/integration/standard/test_concurrent.py index 5e6b1ffd59..267869b943 100644 --- a/tests/integration/standard/test_concurrent.py +++ b/tests/integration/standard/test_concurrent.py @@ -19,7 +19,6 @@ ReadFailure, WriteFailure from cassandra.cluster import ExecutionProfile, EXEC_PROFILE_DEFAULT from cassandra.concurrent import execute_concurrent, execute_concurrent_with_args, ExecutionResult -from cassandra.policies import HostDistance from cassandra.query import dict_factory, tuple_factory, SimpleStatement from tests.integration import use_singledc, PROTOCOL_VERSION, TestCluster diff --git a/tests/integration/standard/test_concurrent_schema_change_and_node_kill.py b/tests/integration/standard/test_concurrent_schema_change_and_node_kill.py index aeda381c0d..87b75144d8 100644 --- a/tests/integration/standard/test_concurrent_schema_change_and_node_kill.py +++ b/tests/integration/standard/test_concurrent_schema_change_and_node_kill.py @@ -1,4 +1,3 @@ -import os import logging import unittest @@ -8,7 +7,7 @@ def setup_module(): - use_cluster('test_concurrent_schema_change_and_node_kill', [3], start=True) + use_cluster('test_schema_kill', [3], start=True) @local class TestConcurrentSchemaChangeAndNodeKill(unittest.TestCase): @@ -27,7 +26,7 @@ def test_schema_change_after_node_kill(self): "DROP KEYSPACE IF EXISTS ks_deadlock;") self.session.execute( "CREATE KEYSPACE IF NOT EXISTS ks_deadlock " - "WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '2' };") + "WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '2' };") self.session.set_keyspace('ks_deadlock') self.session.execute("CREATE TABLE IF NOT EXISTS some_table(k int, c int, v int, PRIMARY KEY (k, v));") self.session.execute("INSERT INTO some_table (k, c, v) VALUES (1, 2, 3);") diff --git a/tests/integration/standard/test_connection.py b/tests/integration/standard/test_connection.py index 630e5e6ba0..df0f568c2c 100644 --- a/tests/integration/standard/test_connection.py +++ b/tests/integration/standard/test_connection.py @@ -32,6 +32,7 @@ from tests import is_monkey_patched from tests.integration import use_singledc, get_node, CASSANDRA_IP, local, \ requiresmallclockgranularity, greaterthancass20, TestCluster +from tests.util import wait_until try: import cassandra.io.asyncorereactor @@ -140,9 +141,10 @@ def test_heart_beat_timeout(self): # Wait for connections associated with this host go away self.wait_for_no_connections(host, self.cluster) - # Wait to seconds for the driver to be notified - time.sleep(2) - assert test_listener.host_down + # Wait for the driver to detect the host is down + wait_until( + lambda: test_listener.host_down, + delay=0.5, max_attempts=20) # Resume paused node finally: node.resume() diff --git a/tests/integration/standard/test_control_connection.py b/tests/integration/standard/test_control_connection.py index 2788a1d837..f0c41dde14 100644 --- a/tests/integration/standard/test_control_connection.py +++ b/tests/integration/standard/test_control_connection.py @@ -68,7 +68,7 @@ def test_drop_keyspace(self): self.session = self.cluster.connect() self.session.execute(""" CREATE KEYSPACE keyspacetodrop - WITH replication = { 'class' : 'SimpleStrategy', 'replication_factor': '1' } + WITH replication = { 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1' } """) self.session.set_keyspace("keyspacetodrop") self.session.execute("CREATE TYPE user (age int, name text)") @@ -135,7 +135,7 @@ def test_control_connection_port_discovery(self): assert 7000 == host.broadcast_port @xfail_scylla_version_lt(reason='scylladb/scylladb#26992 - system.client_routes is not yet supported', - oss_scylla_version="7.0", ent_scylla_version="2026.1.0") + scylla_version="2026.1.0") def test_client_routes_change_event(self): cluster = TestCluster() diff --git a/tests/integration/standard/test_control_connection_query_fallback.py b/tests/integration/standard/test_control_connection_query_fallback.py new file mode 100644 index 0000000000..a9154f681e --- /dev/null +++ b/tests/integration/standard/test_control_connection_query_fallback.py @@ -0,0 +1,109 @@ +# Copyright DataStax, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import unittest + +import pytest + +from cassandra.cluster import ControlConnectionQueryFallback, NoHostAvailable + +from tests.integration import TestCluster, local, remove_cluster, use_cluster + + +_CLUSTER_NAME = "control_connection_query_fallback" +_UNREACHABLE_BROADCAST_RPC_ADDRESS = "127.255.255.1" + + +def setup_module(): + remove_cluster() + + ccm_cluster = use_cluster(_CLUSTER_NAME, [1], start=False) + ccm_cluster.nodes["node1"].set_configuration_options(values={ + "broadcast_rpc_address": _UNREACHABLE_BROADCAST_RPC_ADDRESS, + }) + ccm_cluster.start(wait_for_binary_proto=True, wait_other_notice=True) + + +def teardown_module(): + remove_cluster() + + +@local +class ControlConnectionQueryFallbackIntegrationTests(unittest.TestCase): + + def setUp(self): + self.cluster = None + + def tearDown(self): + if self.cluster is not None: + self.cluster.shutdown() + + def _assert_unreachable_broadcast_rpc_metadata(self): + hosts = self.cluster.metadata.all_hosts() + assert len(hosts) == 1 + + host = hosts[0] + assert host.broadcast_rpc_address == _UNREACHABLE_BROADCAST_RPC_ADDRESS + assert host.endpoint.address == _UNREACHABLE_BROADCAST_RPC_ADDRESS + return host + + def test_disabled_raises_when_broadcast_rpc_address_is_unreachable(self): + self.cluster = TestCluster( + allow_control_connection_query_fallback=ControlConnectionQueryFallback.Disabled, + connect_timeout=1, + monitor_reporting_enabled=False, + ) + + with pytest.raises(NoHostAvailable): + self.cluster.connect() + + self._assert_unreachable_broadcast_rpc_metadata() + assert self.cluster.control_connection._connection is not None + assert self.cluster.get_all_pools() == [] + + def test_fallback_executes_queries_when_broadcast_rpc_address_is_unreachable(self): + self.cluster = TestCluster( + allow_control_connection_query_fallback=ControlConnectionQueryFallback.Fallback, + connect_timeout=1, + monitor_reporting_enabled=False, + ) + + session = self.cluster.connect() + + self._assert_unreachable_broadcast_rpc_metadata() + assert session._initial_connect_futures + assert list(session.get_pools()) == [] + + row = session.execute( + "SELECT release_version, rpc_address FROM system.local WHERE key='local'").one() + assert str(row.rpc_address) == _UNREACHABLE_BROADCAST_RPC_ADDRESS + assert row.release_version + + def test_no_node_pool_fallback_executes_queries_without_creating_pools(self): + self.cluster = TestCluster( + allow_control_connection_query_fallback=ControlConnectionQueryFallback.SkipPoolCreation, + connect_timeout=1, + monitor_reporting_enabled=False, + ) + + session = self.cluster.connect() + + self._assert_unreachable_broadcast_rpc_metadata() + assert session._initial_connect_futures == set() + assert list(session.get_pools()) == [] + + row = session.execute( + "SELECT release_version, rpc_address FROM system.local WHERE key='local'").one() + assert str(row.rpc_address) == _UNREACHABLE_BROADCAST_RPC_ADDRESS + assert row.release_version diff --git a/tests/integration/standard/test_custom_cluster.py b/tests/integration/standard/test_custom_cluster.py index 4eb62e43bc..db6eef0be4 100644 --- a/tests/integration/standard/test_custom_cluster.py +++ b/tests/integration/standard/test_custom_cluster.py @@ -14,7 +14,7 @@ from cassandra.cluster import NoHostAvailable from tests.integration import use_singledc, get_cluster, remove_cluster, local, TestCluster -from tests.util import wait_until, wait_until_not_raised +from tests.util import wait_until import unittest import pytest diff --git a/tests/integration/standard/test_custom_payload.py b/tests/integration/standard/test_custom_payload.py index fc58081070..2179c4225d 100644 --- a/tests/integration/standard/test_custom_payload.py +++ b/tests/integration/standard/test_custom_payload.py @@ -17,7 +17,7 @@ from cassandra.query import (SimpleStatement, BatchStatement, BatchType) -from tests.integration import (use_singledc, PROTOCOL_VERSION, local, TestCluster, +from tests.integration import (use_singledc, local, TestCluster, requires_custom_payload) import pytest diff --git a/tests/integration/standard/test_custom_protocol_handler.py b/tests/integration/standard/test_custom_protocol_handler.py index 239f7e7336..59283a3b33 100644 --- a/tests/integration/standard/test_custom_protocol_handler.py +++ b/tests/integration/standard/test_custom_protocol_handler.py @@ -16,23 +16,20 @@ from cassandra.protocol import ProtocolHandler, ResultMessage, QueryMessage, UUIDType, read_int from cassandra.query import tuple_factory, SimpleStatement -from cassandra.cluster import (ResponseFuture, ExecutionProfile, EXEC_PROFILE_DEFAULT, - ContinuousPagingOptions, NoHostAvailable) +from cassandra.cluster import (ResponseFuture, ExecutionProfile, EXEC_PROFILE_DEFAULT) from cassandra import ProtocolVersion, ConsistencyLevel -from tests.integration import use_singledc, drop_keyspace_shutdown_cluster, \ - greaterthanorequalcass30, execute_with_long_wait_retry, greaterthanorequalcass3_10, \ - TestCluster, greaterthanorequalcass40 +from tests.integration import use_single_node, drop_keyspace_shutdown_cluster, \ + greaterthanorequalcass30, execute_with_long_wait_retry, TestCluster, greaterthanorequalcass40 from tests.integration.datatype_utils import update_datatypes, PRIMITIVE_DATATYPES from tests.integration.standard.utils import create_table_with_all_types, get_all_primitive_params import uuid from unittest import mock -import pytest def setup_module(): - use_singledc() + use_single_node() update_datatypes() @@ -42,8 +39,9 @@ class CustomProtocolHandlerTest(unittest.TestCase): def setUpClass(cls): cls.cluster = TestCluster() cls.session = cls.cluster.connect() - cls.session.execute("CREATE KEYSPACE custserdes WITH replication = { 'class' : 'SimpleStrategy', 'replication_factor': '1'}") + cls.session.execute("CREATE KEYSPACE custserdes WITH replication = { 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1'}") cls.session.set_keyspace("custserdes") + cls.session.execute("CREATE TABLE IF NOT EXISTS custserdes.test (k int PRIMARY KEY, v int)") @classmethod def tearDownClass(cls): @@ -165,7 +163,7 @@ def test_protocol_divergence_v5_fail_by_flag_uses_int(self): int_flag=False) def _send_query_message(self, session, timeout, **kwargs): - query = "SELECT * FROM test3rf.test" + query = "SELECT * FROM custserdes.test" message = QueryMessage(query=query, **kwargs) future = ResponseFuture(session, message, query=None, timeout=timeout) future.send_request() @@ -175,8 +173,8 @@ def _protocol_divergence_fail_by_flag_uses_int(self, version, uses_int_query_fla cluster = TestCluster(protocol_version=version, allow_beta_protocol_version=beta) session = cluster.connect() - query_one = SimpleStatement("INSERT INTO test3rf.test (k, v) VALUES (1, 1)") - query_two = SimpleStatement("INSERT INTO test3rf.test (k, v) VALUES (2, 2)") + query_one = SimpleStatement("INSERT INTO custserdes.test (k, v) VALUES (1, 1)") + query_two = SimpleStatement("INSERT INTO custserdes.test (k, v) VALUES (2, 2)") execute_with_long_wait_retry(session, query_one) execute_with_long_wait_retry(session, query_two) @@ -190,7 +188,7 @@ def _protocol_divergence_fail_by_flag_uses_int(self, version, uses_int_query_fla # This means the flag are not handled as they are meant by the server if uses_int=False assert response.has_more_pages == uses_int_query_flag - execute_with_long_wait_retry(session, SimpleStatement("TRUNCATE test3rf.test")) + execute_with_long_wait_retry(session, SimpleStatement("TRUNCATE custserdes.test")) cluster.shutdown() diff --git a/tests/integration/standard/test_cython_protocol_handlers.py b/tests/integration/standard/test_cython_protocol_handlers.py index f44d613c64..49a13ac23a 100644 --- a/tests/integration/standard/test_cython_protocol_handlers.py +++ b/tests/integration/standard/test_cython_protocol_handlers.py @@ -12,7 +12,7 @@ from cassandra.protocol import ProtocolHandler, LazyProtocolHandler, NumpyProtocolHandler from cassandra.query import tuple_factory from tests import VERIFY_CYTHON -from tests.integration import use_singledc, notprotocolv1, \ +from tests.integration import use_single_node, notprotocolv1, \ drop_keyspace_shutdown_cluster, BasicSharedKeyspaceUnitTestCase, greaterthancass21, TestCluster from tests.integration.datatype_utils import update_datatypes from tests.integration.standard.utils import ( @@ -21,7 +21,7 @@ def setup_module(): - use_singledc() + use_single_node() update_datatypes() @@ -34,7 +34,7 @@ def setUpClass(cls): cls.cluster = TestCluster() cls.session = cls.cluster.connect() cls.session.execute("CREATE KEYSPACE testspace WITH replication = " - "{ 'class' : 'SimpleStrategy', 'replication_factor': '1'}") + "{ 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1'}") cls.session.set_keyspace("testspace") cls.colnames = create_table_with_all_types("test_table", cls.session, cls.N_ITEMS) @@ -225,7 +225,7 @@ def setUpClass(cls): cls.cluster = TestCluster() cls.session = cls.cluster.connect() cls.session.execute("CREATE KEYSPACE IF NOT EXISTS test_wide_table WITH replication = " - "{ 'class' : 'SimpleStrategy', 'replication_factor': '1'}") + "{ 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1'}") cls.session.set_keyspace("test_wide_table") # Create a wide table with many int columns diff --git a/tests/integration/standard/test_ip_change.py b/tests/integration/standard/test_ip_change.py index 6d23d30e04..53debfa1f5 100644 --- a/tests/integration/standard/test_ip_change.py +++ b/tests/integration/standard/test_ip_change.py @@ -10,11 +10,22 @@ LOGGER = logging.getLogger(__name__) +_saved_scylla_ext_opts = None + def setup_module(): + global _saved_scylla_ext_opts + _saved_scylla_ext_opts = os.environ.get('SCYLLA_EXT_OPTS') os.environ['SCYLLA_EXT_OPTS'] = "--smp 2 --memory 2048M" use_cluster('test_ip_change', [3], start=True) + +def teardown_module(): + if _saved_scylla_ext_opts is None: + os.environ.pop('SCYLLA_EXT_OPTS', None) + else: + os.environ['SCYLLA_EXT_OPTS'] = _saved_scylla_ext_opts + @local class TestIpAddressChange(unittest.TestCase): @classmethod diff --git a/tests/integration/standard/test_metadata.py b/tests/integration/standard/test_metadata.py index c30e369d83..562f457a32 100644 --- a/tests/integration/standard/test_metadata.py +++ b/tests/integration/standard/test_metadata.py @@ -14,38 +14,31 @@ import unittest -from collections import defaultdict -import difflib import logging import sys import time import os -from typing import Optional from packaging.version import Version from unittest.mock import Mock, patch import pytest from cassandra import AlreadyExists, SignatureDescriptor, UserFunctionDescriptor, UserAggregateDescriptor -from cassandra.connection import Connection from cassandra.encoder import Encoder from cassandra.metadata import (IndexMetadata, Token, murmur3, Function, Aggregate, protect_name, protect_names, RegisteredTableExtension, _RegisteredExtensionType, get_schema_parser, group_keys_by_replica, NO_VALID_REPLICA) from cassandra.protocol import QueryMessage, ProtocolHandler -from cassandra.util import SortedSet from tests.integration import (get_cluster, use_singledc, PROTOCOL_VERSION, execute_until_pass, BasicSegregatedKeyspaceUnitTestCase, BasicSharedKeyspaceUnitTestCase, BasicExistingKeyspaceUnitTestCase, drop_keyspace_shutdown_cluster, CASSANDRA_VERSION, greaterthanorequalcass30, lessthancass30, local, get_supported_protocol_versions, greaterthancass20, - greaterthancass21, greaterthanorequalcass40, - lessthancass40, + greaterthancass21, lessthancass40, TestCluster, requires_java_udf, requires_composite_type, - requires_collection_indexes, SCYLLA_VERSION, xfail_scylla, xfail_scylla_version_lt, - requirescompactstorage) + requires_collection_indexes, SCYLLA_VERSION, xfail_scylla, requirescompactstorage, get_tablets_disabled_ddl_suffix, execute_with_long_wait_retry) from tests.util import wait_until, assertRegex, assertDictEqual, assertListEqual, assert_startswith_diff @@ -141,6 +134,12 @@ def test_bad_contact_point(self): class SchemaMetadataTests(BasicSegregatedKeyspaceUnitTestCase): + @classmethod + def create_keyspace(cls, rf): + ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}{2}".format( + cls.ks_name, rf, get_tablets_disabled_ddl_suffix()) + execute_with_long_wait_retry(cls.session, ddl) + def test_schema_metadata_disable(self): """ Checks to ensure that schema metadata_enabled, and token_metadata_enabled @@ -230,8 +229,8 @@ def test_basic_table_meta_properties(self): assert ksmeta.name == self.keyspace_name assert ksmeta.durable_writes - assert ksmeta.replication_strategy.name == 'SimpleStrategy' - assert ksmeta.replication_strategy.replication_factor == 1 + assert ksmeta.replication_strategy.name == 'NetworkTopologyStrategy' + assert ksmeta.replication_strategy.dc_replication_factors["dc1"] == 1 assert self.function_table_name in ksmeta.tables tablemeta = ksmeta.tables[self.function_table_name] @@ -601,7 +600,7 @@ def test_refresh_schema_metadata(self): assert "new_keyspace" not in cluster2.metadata.keyspaces # Cluster metadata modification - self.session.execute("CREATE KEYSPACE new_keyspace WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}") + self.session.execute("CREATE KEYSPACE new_keyspace WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'}") assert "new_keyspace" not in cluster2.metadata.keyspaces cluster2.refresh_schema_metadata() @@ -1077,7 +1076,7 @@ def test_metadata_pagination_keyspaces(self): for ks in keyspaces: self.session.execute( - f"CREATE KEYSPACE IF NOT EXISTS {ks} WITH REPLICATION = {{ 'class' : 'SimpleStrategy', 'replication_factor' : 3 }}" + f"CREATE KEYSPACE IF NOT EXISTS {ks} WITH REPLICATION = {{ 'class' : 'NetworkTopologyStrategy', 'replication_factor' : 3 }}" ) self.cluster.schema_metadata_page_size = 2000 @@ -1138,7 +1137,7 @@ def test_export_keyspace_schema_udts(self): session.execute(""" CREATE KEYSPACE export_udts - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'} AND durable_writes = true; """) session.execute(""" @@ -1162,7 +1161,7 @@ def test_export_keyspace_schema_udts(self): addresses map>) """) - expected_prefix = """CREATE KEYSPACE export_udts WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} AND durable_writes = true; + expected_prefix = """CREATE KEYSPACE export_udts WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'} AND durable_writes = true; CREATE TYPE export_udts.street ( street_number int, @@ -1196,8 +1195,6 @@ def test_export_keyspace_schema_udts(self): cluster.shutdown() @greaterthancass21 - @xfail_scylla_version_lt(reason='scylladb/scylladb#10707 - Column name in CREATE INDEX is not quoted', - oss_scylla_version="5.2", ent_scylla_version="2023.1.1") def test_case_sensitivity(self): """ Test that names that need to be escaped in CREATE statements are @@ -1210,10 +1207,9 @@ def test_case_sensitivity(self): cfname = 'AnInterestingTable' session.execute("DROP KEYSPACE IF EXISTS {0}".format(ksname)) - session.execute(""" - CREATE KEYSPACE "%s" - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} - """ % (ksname,)) + session.execute( + ("CREATE KEYSPACE \"%s\" WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'}" + + get_tablets_disabled_ddl_suffix()) % (ksname,)) session.execute(""" CREATE TABLE "%s"."%s" ( k int, @@ -1256,7 +1252,7 @@ def test_already_exists_exceptions(self): ddl = ''' CREATE KEYSPACE %s - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3'}''' + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '3'}''' with pytest.raises(AlreadyExists): session.execute(ddl % ksname) @@ -1387,7 +1383,7 @@ def setUp(self): self.session = self.cluster.connect() name = self._testMethodName.lower() crt_ks = ''' - CREATE KEYSPACE %s WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1} AND durable_writes = true''' % name + CREATE KEYSPACE %s WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 1} AND durable_writes = true''' % name self.session.execute(crt_ks) def tearDown(self): @@ -1434,11 +1430,9 @@ def setup_class(cls): if cls.keyspace_name in cls.cluster.metadata.keyspaces: cls.session.execute("DROP KEYSPACE %s" % cls.keyspace_name) - cls.session.execute( - """ - CREATE KEYSPACE %s - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}; - """ % cls.keyspace_name) + ddl = ("CREATE KEYSPACE %s WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'}" + + get_tablets_disabled_ddl_suffix()) + cls.session.execute(ddl % cls.keyspace_name) cls.session.set_keyspace(cls.keyspace_name) except Exception: cls.cluster.shutdown() @@ -1540,7 +1534,7 @@ def setup_class(cls): cls.cluster = TestCluster() cls.keyspace_name = cls.__name__.lower() cls.session = cls.cluster.connect() - cls.session.execute("CREATE KEYSPACE IF NOT EXISTS %s WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}" % cls.keyspace_name) + cls.session.execute("CREATE KEYSPACE IF NOT EXISTS %s WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 1}" % cls.keyspace_name) cls.session.set_keyspace(cls.keyspace_name) cls.keyspace_function_meta = cls.cluster.metadata.keyspaces[cls.keyspace_name].functions cls.keyspace_aggregate_meta = cls.cluster.metadata.keyspaces[cls.keyspace_name].aggregates @@ -2007,7 +2001,8 @@ def setup_class(cls): cls.cluster = TestCluster() cls.keyspace_name = cls.__name__.lower() cls.session = cls.cluster.connect() - cls.session.execute("CREATE KEYSPACE %s WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}" % cls.keyspace_name) + ddl = "CREATE KEYSPACE %s WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'}" + get_tablets_disabled_ddl_suffix() + cls.session.execute(ddl % cls.keyspace_name) cls.session.set_keyspace(cls.keyspace_name) connection = cls.cluster.control_connection._connection @@ -2132,6 +2127,13 @@ def test_dct_alias(self): @greaterthanorequalcass30 class MaterializedViewMetadataTestSimple(BasicSharedKeyspaceUnitTestCase): + @classmethod + def create_keyspace(cls, rf): + ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}{2}".format( + cls.ks_name, rf, get_tablets_disabled_ddl_suffix()) + execute_with_long_wait_retry(cls.session, ddl) + + def setUp(self): self.session.execute("CREATE TABLE {0}.{1} (pk int PRIMARY KEY, c int)".format(self.keyspace_name, self.function_table_name)) self.session.execute( @@ -2219,6 +2221,13 @@ def test_materialized_view_metadata_drop(self): @greaterthanorequalcass30 class MaterializedViewMetadataTestComplex(BasicSegregatedKeyspaceUnitTestCase): + + @classmethod + def create_keyspace(cls, rf): + ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}{2}".format( + cls.ks_name, rf, get_tablets_disabled_ddl_suffix()) + execute_with_long_wait_retry(cls.session, ddl) + def test_create_view_metadata(self): """ test to ensure that materialized view metadata is properly constructed diff --git a/tests/integration/standard/test_metrics.py b/tests/integration/standard/test_metrics.py index 7b502d91c3..7ebdded141 100644 --- a/tests/integration/standard/test_metrics.py +++ b/tests/integration/standard/test_metrics.py @@ -25,6 +25,7 @@ from cassandra.cluster import NoHostAvailable, ExecutionProfile, EXEC_PROFILE_DEFAULT from tests.integration import get_cluster, get_node, use_singledc, execute_until_pass, TestCluster +from tests.util import wait_until, wait_until_not_raised from cassandra import metrics from tests.integration import BasicSharedKeyspaceUnitTestCaseRF3WM, BasicExistingKeyspaceUnitTestCase, local @@ -75,8 +76,10 @@ def test_connection_error(self): self.session.execute(query) finally: get_cluster().start(wait_for_binary_proto=True, wait_other_notice=True) - # Give some time for the cluster to come back up, for the next test - time.sleep(5) + # Wait for the cluster to come back up for the next test + wait_until_not_raised( + lambda: self.session.execute("SELECT key FROM system.local WHERE key='local'"), + delay=0.5, max_attempts=30) assert self.cluster.metrics.stats.connection_errors > 0 @@ -156,7 +159,10 @@ def test_unavailable(self): # Sometimes this commands continues with the other nodes having not noticed # 1 is down, and a Timeout error is returned instead of an Unavailable get_node(1).stop(wait=True, wait_other_notice=True) - time.sleep(5) + wait_until( + lambda: not self.cluster.metadata.get_host('127.0.0.1') or + not self.cluster.metadata.get_host('127.0.0.1').is_up, + delay=0.5, max_attempts=30) try: # Test write query = SimpleStatement("INSERT INTO test (k, v) VALUES (2, 2)", consistency_level=ConsistencyLevel.ALL) @@ -171,8 +177,10 @@ def test_unavailable(self): assert self.cluster.metrics.stats.unavailables == 2 finally: get_node(1).start(wait_other_notice=True, wait_for_binary_proto=True) - # Give some time for the cluster to come back up, for the next test - time.sleep(5) + # Wait for the cluster to come back up for the next test + wait_until_not_raised( + lambda: self.session.execute("SELECT key FROM system.local WHERE key='local'"), + delay=0.5, max_attempts=30) self.cluster.shutdown() diff --git a/tests/integration/standard/test_policies.py b/tests/integration/standard/test_policies.py index 2de12f7b7f..c67eb1cf3a 100644 --- a/tests/integration/standard/test_policies.py +++ b/tests/integration/standard/test_policies.py @@ -15,9 +15,7 @@ import unittest from cassandra.cluster import ExecutionProfile, EXEC_PROFILE_DEFAULT -from cassandra.policies import HostFilterPolicy, RoundRobinPolicy, SimpleConvictionPolicy, \ - WhiteListRoundRobinPolicy, ExponentialBackoffRetryPolicy, ColDesc -from cassandra.pool import Host +from cassandra.policies import HostFilterPolicy, RoundRobinPolicy, WhiteListRoundRobinPolicy, ExponentialBackoffRetryPolicy from cassandra.connection import DefaultEndPoint from tests.integration import local, use_singledc, TestCluster @@ -104,5 +102,5 @@ def test_exponential_retries(self): self.session.execute( """ CREATE KEYSPACE preparedtests - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'} """) diff --git a/tests/integration/standard/test_prepared_statements.py b/tests/integration/standard/test_prepared_statements.py index 3f63b881ef..98faf6a5bc 100644 --- a/tests/integration/standard/test_prepared_statements.py +++ b/tests/integration/standard/test_prepared_statements.py @@ -62,7 +62,7 @@ def test_basic(self): self.session.execute( """ CREATE KEYSPACE preparedtests - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '1'} """) self.session.set_keyspace("preparedtests") @@ -437,7 +437,7 @@ def test_fail_if_different_query_id_on_reprepare(self): keyspace = "test_fail_if_different_query_id_on_reprepare" self.session.execute( "CREATE KEYSPACE IF NOT EXISTS {} WITH replication = " - "{{'class': 'SimpleStrategy', 'replication_factor': 1}}".format(keyspace) + "{{'class': 'NetworkTopologyStrategy', 'replication_factor': 1}}".format(keyspace) ) self.session.execute("CREATE TABLE IF NOT EXISTS {}.foo(k int PRIMARY KEY)".format(keyspace)) prepared = self.session.prepare("SELECT * FROM {}.foo WHERE k=?".format(keyspace)) @@ -614,13 +614,15 @@ def _test_updated_conditional(self, session, value): prepared_statement = session.prepare( "INSERT INTO {}(a, b, d) VALUES " "(?, ? , ?) IF NOT EXISTS".format(self.table_name)) - first_id = prepared_statement.result_metadata_id - LOG.debug('initial result_metadata_id: {}'.format(first_id)) + LOG.debug('initial result_metadata_id: {}'.format(prepared_statement.result_metadata_id)) + # The cached (result_metadata, result_metadata_id) pair is not asserted on: + # a METADATA_CHANGED response refreshes it for a conditional statement like + # for any other, so its contents are the server's business. What must hold + # is that each result is decoded against the metadata describing it, whether + # the conditional update applied (narrow shape) or not (whole row). def check_result_and_metadata(expected): assert session.execute(prepared_statement, (value, value, value)).one() == expected - assert prepared_statement.result_metadata_id == first_id - assert prepared_statement.result_metadata is None # Successful conditional update check_result_and_metadata((True,)) diff --git a/tests/integration/standard/test_query.py b/tests/integration/standard/test_query.py index 9cebc22b05..5f1d5bfc19 100644 --- a/tests/integration/standard/test_query.py +++ b/tests/integration/standard/test_query.py @@ -23,13 +23,14 @@ from cassandra.query import (PreparedStatement, BoundStatement, SimpleStatement, BatchStatement, BatchType, dict_factory, TraceUnavailable) from cassandra.cluster import NoHostAvailable, ExecutionProfile, EXEC_PROFILE_DEFAULT, Cluster -from cassandra.policies import HostDistance, RoundRobinPolicy, WhiteListRoundRobinPolicy +from cassandra.policies import RoundRobinPolicy, WhiteListRoundRobinPolicy from tests.integration import use_singledc, PROTOCOL_VERSION, BasicSharedKeyspaceUnitTestCase, \ greaterthanprotocolv3, MockLoggingHandler, get_supported_protocol_versions, local, get_cluster, setup_keyspace, \ - USE_CASS_EXTERNAL, greaterthanorequalcass40, TestCluster, xfail_scylla + greaterthanorequalcass40, TestCluster, xfail_scylla, xfail_scylla_version_lt, \ + get_tablets_disabled_ddl_suffix, execute_with_long_wait_retry from tests import notwindows from tests.integration import greaterthanorequalcass30, get_node -from tests.util import assertListEqual +from tests.util import assertListEqual, wait_until import time import random @@ -42,15 +43,14 @@ def setup_module(): - if not USE_CASS_EXTERNAL: - use_singledc(start=False) - ccm_cluster = get_cluster() - ccm_cluster.stop() - # This is necessary because test_too_many_statements may - # timeout otherwise - config_options = {'write_request_timeout_in_ms': '20000'} - ccm_cluster.set_configuration_options(config_options) - ccm_cluster.start(wait_for_binary_proto=True, wait_other_notice=True) + use_singledc(start=False) + ccm_cluster = get_cluster() + ccm_cluster.stop() + # This is necessary because test_too_many_statements may + # timeout otherwise + config_options = {'write_request_timeout_in_ms': '20000'} + ccm_cluster.set_configuration_options(config_options) + ccm_cluster.start(wait_for_binary_proto=True, wait_other_notice=True) setup_keyspace() @@ -804,6 +804,9 @@ def setUp(self): def tearDown(self): self.cluster.shutdown() + @xfail_scylla_version_lt(reason='scylladb/scylladb#18068 - LWT is not yet supported with tablets', + scylla_version='2025.4', + raises=InvalidRequest) def test_conditional_update(self): self.session.execute("INSERT INTO test3rf.test (k, v) VALUES (0, 0)") statement = SimpleStatement( @@ -828,6 +831,9 @@ def test_conditional_update(self): assert result assert result.one().applied + @xfail_scylla_version_lt(reason='scylladb/scylladb#18068 - LWT is not yet supported with tablets', + scylla_version='2025.4', + raises=InvalidRequest) def test_conditional_update_with_prepared_statements(self): self.session.execute("INSERT INTO test3rf.test (k, v) VALUES (0, 0)") statement = self.session.prepare( @@ -850,6 +856,9 @@ def test_conditional_update_with_prepared_statements(self): assert result assert result.one().applied + @xfail_scylla_version_lt(reason='scylladb/scylladb#18068 - LWT is not yet supported with tablets', + scylla_version='2025.4', + raises=InvalidRequest) def test_conditional_update_with_batch_statements(self): self.session.execute("INSERT INTO test3rf.test (k, v) VALUES (0, 0)") statement = BatchStatement(serial_consistency_level=ConsistencyLevel.SERIAL) @@ -915,6 +924,9 @@ def tearDown(self): self.session.execute("DROP TABLE test3rf.lwt_clustering") self.cluster.shutdown() + @xfail_scylla_version_lt(reason='scylladb/scylladb#18068 - LWT is not yet supported with tablets', + scylla_version='2025.4', + raises=AttributeError) def test_no_connection_refused_on_timeout(self): """ Test for PYTHON-91 "Connection closed after LWT timeout" @@ -1156,6 +1168,12 @@ def test_inherit_first_rk_prepared_param(self): @greaterthanorequalcass30 class MaterializedViewQueryTest(BasicSharedKeyspaceUnitTestCase): + @classmethod + def create_keyspace(cls, rf): + ddl = "CREATE KEYSPACE {0} WITH replication = {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}{2}".format( + cls.ks_name, rf, get_tablets_disabled_ddl_suffix()) + execute_with_long_wait_retry(cls.session, ddl) + def test_mv_filtering(self): """ Test to ensure that cql filtering where clauses are properly supported in the python driver. @@ -1359,12 +1377,12 @@ def setUpClass(cls): cls.table_name = "table_query_keyspace_tests" ddl = """CREATE KEYSPACE {0} WITH replication = - {{'class': 'SimpleStrategy', + {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}""".format(cls.ks_name, 1) cls.session.execute(ddl) ddl = """CREATE KEYSPACE {0} WITH replication = - {{'class': 'SimpleStrategy', + {{'class': 'NetworkTopologyStrategy', 'replication_factor': '{1}'}}""".format(cls.alternative_ks, 1) cls.session.execute(ddl) @@ -1571,9 +1589,10 @@ def test_reprepare_after_host_is_down(self): get_node(1).start(wait_for_binary_proto=True, wait_other_notice=True) - # We wait for cluster._prepare_all_queries to be called - time.sleep(5) - assert 1 == mock_handler.get_message_count('debug', 'Preparing all known prepared statements') + # Wait for cluster._prepare_all_queries to be called + wait_until( + lambda: mock_handler.get_message_count('debug', 'Preparing all known prepared statements') >= 1, + delay=0.5, max_attempts=20) results = self.session.execute(prepared_statement, (1,), execution_profile="only_first") assert results.one() == (1, ) diff --git a/tests/integration/standard/test_query_paging.py b/tests/integration/standard/test_query_paging.py index e0c67cd309..0dca7ffd41 100644 --- a/tests/integration/standard/test_query_paging.py +++ b/tests/integration/standard/test_query_paging.py @@ -25,7 +25,6 @@ from cassandra import ConsistencyLevel from cassandra.cluster import EXEC_PROFILE_DEFAULT, ExecutionProfile from cassandra.concurrent import execute_concurrent, execute_concurrent_with_args -from cassandra.policies import HostDistance from cassandra.query import SimpleStatement from tests.util import assertSequenceEqual diff --git a/tests/integration/standard/test_rate_limit_exceeded.py b/tests/integration/standard/test_rate_limit_exceeded.py index 211f0c9930..5a7fc5dc74 100644 --- a/tests/integration/standard/test_rate_limit_exceeded.py +++ b/tests/integration/standard/test_rate_limit_exceeded.py @@ -4,13 +4,13 @@ from cassandra.cluster import Cluster from cassandra.policies import ConstantReconnectionPolicy, RoundRobinPolicy, TokenAwarePolicy -from tests.integration import PROTOCOL_VERSION, use_cluster +from tests.integration import PROTOCOL_VERSION, use_singledc import pytest LOGGER = logging.getLogger(__name__) def setup_module(): - use_cluster('rate_limit', [3], start=True) + use_singledc() class TestRateLimitExceededException(unittest.TestCase): @classmethod @@ -33,7 +33,7 @@ def test_rate_limit_exceeded(self): self.session.execute( """ CREATE KEYSPACE IF NOT EXISTS ratetests - WITH REPLICATION = {'class' : 'SimpleStrategy', 'replication_factor' : 1} + WITH REPLICATION = {'class' : 'NetworkTopologyStrategy', 'replication_factor' : 1} """) self.session.execute("USE ratetests") diff --git a/tests/integration/standard/test_row_factories.py b/tests/integration/standard/test_row_factories.py index 187f35704a..818f11c061 100644 --- a/tests/integration/standard/test_row_factories.py +++ b/tests/integration/standard/test_row_factories.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -from tests.integration import get_server_versions, use_singledc, \ +from tests.integration import get_server_versions, use_single_node, \ BasicSharedKeyspaceUnitTestCaseWFunctionTable, BasicSharedKeyspaceUnitTestCase, execute_until_pass, TestCluster import unittest @@ -24,7 +24,7 @@ def setup_module(): - use_singledc() + use_single_node() class NameTupleFactory(BasicSharedKeyspaceUnitTestCase): diff --git a/tests/integration/standard/test_scylla_metadata_id.py b/tests/integration/standard/test_scylla_metadata_id.py new file mode 100644 index 0000000000..24511bee3a --- /dev/null +++ b/tests/integration/standard/test_scylla_metadata_id.py @@ -0,0 +1,166 @@ +# Copyright 2026 ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import unittest +from unittest.mock import patch + +import pytest + +from cassandra.cluster import ResponseFuture +from tests.integration import use_singledc, SCYLLA_VERSION, BasicSharedKeyspaceUnitTestCase, \ + drop_keyspace_shutdown_cluster + +pytestmark = pytest.mark.skipif(SCYLLA_VERSION is None, reason="SCYLLA_USE_METADATA_ID is a Scylla-only protocol extension") + + +def setup_module(): + use_singledc() + + +class ScyllaMetadataIdTests(BasicSharedKeyspaceUnitTestCase): + """ + Live-server coverage for the SCYLLA_USE_METADATA_ID protocol extension (DRIVER-153). + """ + + @classmethod + def setUpClass(cls): + cls.common_setup(1) + # Skip the whole class if this Scylla build does not advertise the + # extension (e.g. a version predating scylladb#23292). Without this the + # tests below would error out instead of skipping on an unsupporting node. + try: + if not cls._negotiated_use_metadata_id(): + raise unittest.SkipTest( + "Scylla node does not advertise SCYLLA_USE_METADATA_ID") + except Exception: + # setUpClass raising means unittest never calls tearDownClass, so the + # cluster and keyspace created above are torn down here explicitly. + drop_keyspace_shutdown_cluster(cls.ks_name, cls.session, cls.cluster) + raise + + @classmethod + def _negotiated_use_metadata_id(cls): + """Whether this class's data-path connections negotiated SCYLLA_USE_METADATA_ID. + + Reads the pool's existing connection rather than borrowing one: + borrow_connection() pops a stream id that only Connection.process_msg gives + back, so borrowing without sending a message would leak it. + """ + pool = next(iter(cls.session.get_pools())) + return next(iter(pool._connections.values())).features.use_metadata_id + + def setUp(self): + self.table_name = "{}.{}".format(self.keyspace_name, self.function_table_name) + self.session.execute("CREATE TABLE {} (a int PRIMARY KEY, b int, c int)".format(self.table_name)) + self.session.execute("INSERT INTO {} (a, b, c) VALUES (1, 1, 1)".format(self.table_name)) + + def tearDown(self): + self.session.execute("DROP TABLE {}".format(self.table_name)) + + def test_extension_is_negotiated(self): + """ + Sanity check that SCYLLA_USE_METADATA_ID was actually negotiated on this + connection. Without this, the tests below could pass vacuously if + negotiation silently failed. + """ + assert self._negotiated_use_metadata_id() is True + + def test_metadata_changed_recovers_after_schema_change(self): + """ + Normal METADATA_CHANGED path: after ALTER TABLE, the next EXECUTE must + come back with a fresh result_metadata_id and updated column metadata, + picked up automatically without re-preparing. + """ + prepared = self.session.prepare("SELECT * FROM {} WHERE a = ?".format(self.table_name)) + id_before = prepared.result_metadata_id + assert id_before is not None + assert len(prepared.result_metadata) == 3 + + self.session.execute(prepared.bind((1,))) + + self.session.execute("ALTER TABLE {} ADD d int".format(self.table_name)) + self.session.execute(prepared.bind((1,))) + + assert prepared.result_metadata_id is not None + assert prepared.result_metadata_id != id_before + assert len(prepared.result_metadata) == 4 + + def test_empty_sentinel_id_triggers_metadata_changed(self): + """ + Statements prepared before the extension was negotiated (e.g. mid rolling + upgrade) start with result_metadata_id=None and must send the empty b'' + sentinel on their first EXECUTE. This must not be treated as a protocol + error by the server: it must be treated as a mismatch, causing Scylla to + respond with METADATA_CHANGED (fresh id + full metadata), which the + driver then caches. + """ + prepared = self.session.prepare("SELECT * FROM {} WHERE a = ?".format(self.table_name)) + assert prepared.result_metadata_id is not None + + # Simulate "prepared before the extension was known" by dropping the + # cached id while keeping the cached metadata (mirrors the java-driver's + # should_handle_empty_metadata_id_when_executing_statement_when_supported). + prepared.update_result_metadata(prepared.result_metadata, None) + assert prepared.result_metadata_id is None + + # The table was not altered, so the statement is still valid server-side and + # nothing should re-prepare it. Spying on _reprepare keeps this test honest: + # if the id came back via an UNPREPARED/reprepare round trip instead, the + # METADATA_CHANGED-on-ROWS path in ResponseFuture._set_result would not + # actually be under test here. + with patch.object(ResponseFuture, '_reprepare', autospec=True, + side_effect=ResponseFuture._reprepare) as reprepare_spy: + result = self.session.execute(prepared.bind((1,))) + + assert reprepare_spy.call_count == 0 + assert list(result) == [(1, 1, 1)] + assert prepared.result_metadata_id is not None + + def test_conditional_statement_metadata_is_stable_across_outcomes(self): + """ + Conditional (LWT) statements get no special handling, and this pins the + server behaviour that makes that correct. + + Cassandra returns NO_METADATA for a conditional statement at PREPARE and + then varies the result shape per execution — ``(True,)`` when applied, the + conflicting row when not — which is what PYTHON-847 is about. Scylla + instead describes the result up front as ``[applied]`` plus every column of + the row, filling nulls when the update applied. The shape does not + alternate, so the cached metadata id stays valid across both outcomes and + ``skip_meta`` is exactly as safe here as for any other statement. A schema + change still changes the id, and the driver must pick that up. + """ + prepared = self.session.prepare( + "INSERT INTO {} (a, b, c) VALUES (?, ?, ?) IF NOT EXISTS".format(self.table_name)) + id_before = prepared.result_metadata_id + assert id_before is not None + assert len(prepared.result_metadata) == 4 # [applied], a, b, c + + # a=2 is free, so the insert applies; the row columns come back null. + assert self.session.execute(prepared.bind((2, 2, 2))).one() == (True, None, None, None) + + # a=1 exists (setUp), so this one does not apply and the conflicting row is + # returned — same metadata, so the cached pair is still the right one. + assert self.session.execute(prepared.bind((1, 9, 9))).one() == (False, 1, 1, 1) + assert prepared.result_metadata_id == id_before + + self.session.execute("ALTER TABLE {} ADD d int".format(self.table_name)) + + # The result gained a column, so the server must report a new id and the + # driver must adopt it — for a conditional statement like for any other. + assert self.session.execute(prepared.bind((1, 9, 9))).one() == (False, 1, 1, 1, None) + assert prepared.result_metadata_id != id_before + assert len(prepared.result_metadata) == 5 + + assert self.session.execute(prepared.bind((3, 3, 3))).one() == (True, None, None, None, None) diff --git a/tests/integration/standard/test_shard_aware.py b/tests/integration/standard/test_shard_aware.py index 48d1aa3609..6daba6e26f 100644 --- a/tests/integration/standard/test_shard_aware.py +++ b/tests/integration/standard/test_shard_aware.py @@ -12,7 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. import os -import time import random from subprocess import run import logging @@ -24,16 +23,29 @@ from cassandra.cluster import Cluster from cassandra.policies import TokenAwarePolicy, RoundRobinPolicy, ConstantReconnectionPolicy -from cassandra import OperationTimedOut, ConsistencyLevel +from cassandra import OperationTimedOut from tests.integration import use_cluster, get_node, PROTOCOL_VERSION +from tests.util import wait_until_not_raised LOGGER = logging.getLogger(__name__) +_saved_scylla_ext_opts = None + + def setup_module(): + global _saved_scylla_ext_opts + _saved_scylla_ext_opts = os.environ.get('SCYLLA_EXT_OPTS') os.environ['SCYLLA_EXT_OPTS'] = "--smp 2" - use_cluster('shard_aware', [3], start=True) + use_cluster('cluster_tests', [3], start=True) + + +def teardown_module(): + if _saved_scylla_ext_opts is None: + os.environ.pop('SCYLLA_EXT_OPTS', None) + else: + os.environ['SCYLLA_EXT_OPTS'] = _saved_scylla_ext_opts class TestShardAwareIntegration(unittest.TestCase): @@ -77,7 +89,7 @@ def create_ks_and_cf(self): self.session.execute( """ CREATE KEYSPACE preparedtests - WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3'} + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': '3'} AND tablets = {'enabled': false} """) self.session.execute("USE preparedtests") @@ -131,12 +143,39 @@ def query_data(self, session, verify_in_tracing=True): if verify_in_tracing: self.verify_same_shard_in_tracing(results, "shard 0") + def _assert_blocked_node_disconnected(self, node_ip_address, node_port): + control_connection = self.cluster.control_connection + active_control_connection = control_connection._connection if control_connection else None + if active_control_connection and \ + active_control_connection.endpoint.address == node_ip_address and \ + active_control_connection.endpoint.port == node_port: + assert active_control_connection.is_closed or active_control_connection.is_defunct + + pools = getattr(self.session, '_pools', None) or {} + for host, pool in pools.items(): + if host.endpoint.address != node_ip_address or host.endpoint.port != node_port: + continue + + open_connections = [ + connection for connection in pool._connections.values() + if not (connection.is_closed or connection.is_defunct) + ] + assert not open_connections + + pending_connections = [ + connection for connection in pool._pending_connections + if not (connection.is_closed or connection.is_defunct) + ] + assert not pending_connections + def test_all_tracing_coming_one_shard(self): """ Testing that shard aware driver is sending the requests to the correct shards using the traces to validate that all the action been executed on the the same shard. this test is using prepared SELECT statements for this validation + + Requires tablets to be disabled to ensure shard consistency. """ self.create_ks_and_cf() @@ -178,11 +217,13 @@ def test_closing_connections(self): continue shard_id = random.choice(list(pool._connections.keys())) pool._connections.get(shard_id).close() - time.sleep(5) - self.query_data(self.session, verify_in_tracing=False) + wait_until_not_raised( + lambda: self.query_data(self.session, verify_in_tracing=False), + delay=0.5, max_attempts=30) - time.sleep(10) - self.query_data(self.session) + wait_until_not_raised( + lambda: self.query_data(self.session), + delay=0.5, max_attempts=60) @pytest.mark.skip def test_blocking_connections(self): @@ -212,13 +253,18 @@ def remove_iptables(): '--destination {node1_ip_address}/32 -j REJECT --reject-with icmp-port-unreachable' ).format(node1_ip_address=node1_ip_address, node1_port=node1_port).split(' ') ) - time.sleep(5) + + wait_until_not_raised( + lambda: self._assert_blocked_node_disconnected(node1_ip_address, node1_port), + delay=0.1, + max_attempts=50) try: self.query_data(self.session, verify_in_tracing=False) except OperationTimedOut: pass remove_iptables() - time.sleep(5) - self.query_data(self.session, verify_in_tracing=False) + wait_until_not_raised( + lambda: self.query_data(self.session, verify_in_tracing=False), + delay=0.5, max_attempts=30) self.query_data(self.session) diff --git a/tests/integration/standard/test_single_interface.py b/tests/integration/standard/test_single_interface.py index 5fd9ef45d3..ad31821a7e 100644 --- a/tests/integration/standard/test_single_interface.py +++ b/tests/integration/standard/test_single_interface.py @@ -13,14 +13,12 @@ # limitations under the License. import unittest -import pytest from cassandra import ConsistencyLevel from cassandra.query import SimpleStatement from packaging.version import Version -from tests.integration import use_singledc, PROTOCOL_VERSION, \ - remove_cluster, greaterthanorequalcass40, \ +from tests.integration import use_singledc, remove_cluster, greaterthanorequalcass40, \ CASSANDRA_VERSION, TestCluster, DEFAULT_SINGLE_INTERFACE_PORT diff --git a/tests/integration/standard/test_tablets.py b/tests/integration/standard/test_tablets.py index d9439e5c2c..45e8a807ea 100644 --- a/tests/integration/standard/test_tablets.py +++ b/tests/integration/standard/test_tablets.py @@ -1,16 +1,15 @@ -import time - import pytest from cassandra.cluster import Cluster, EXEC_PROFILE_DEFAULT, ExecutionProfile from cassandra.policies import ConstantReconnectionPolicy, RoundRobinPolicy, TokenAwarePolicy from tests.integration import PROTOCOL_VERSION, use_cluster, get_cluster +from tests.util import wait_until from tests.unit.test_host_connection_pool import LOGGER def setup_module(): - use_cluster('tablets', [3], start=True) + use_cluster('tablets', [3], start=True, set_keyspace=False) class TestTabletsIntegration: @@ -28,7 +27,7 @@ def teardown_class(cls): cls.cluster.shutdown() def verify_hosts_in_tracing(self, results, expected): - traces = results.get_query_trace() + traces = results.get_query_trace(max_wait_sec=10) events = traces.events host_set = set() for event in events: @@ -54,7 +53,7 @@ def get_tablet_record(self, query): return metadata._tablets.get_tablet_for_key(query.keyspace, query.table, metadata.token_map.token_class.from_key(query.routing_key)) def verify_same_shard_in_tracing(self, results): - traces = results.get_query_trace() + traces = results.get_query_trace(max_wait_sec=10) events = traces.events shard_set = set() for event in events: @@ -212,7 +211,10 @@ def test_tablets_invalidation_drop_ks(self): def drop_ks(_): # Drop and recreate ks and table to trigger tablets invalidation self.create_ks_and_cf(self.cluster.connect()) - time.sleep(3) + # Wait for tablet metadata to be refreshed + wait_until( + lambda: 'test1' in self.cluster.metadata.keyspaces, + delay=0.5, max_attempts=20) self.run_tablets_invalidation_test(drop_ks) @@ -233,7 +235,12 @@ def decommission_non_cc_node(rec): break else: assert False, "failed to find node to decommission" - time.sleep(10) + # Wait for decommission to complete and metadata to update + wait_until( + lambda: len([h for h in self.cluster.metadata.all_hosts() if h.is_up]) < 3, + delay=1, max_attempts=60) + # Tablet metadata invalidation may take additional time to propagate; + # run_tablets_invalidation_test will poll for the expected result. self.run_tablets_invalidation_test(decommission_non_cc_node) @@ -257,5 +264,7 @@ def run_tablets_invalidation_test(self, invalidate): invalidate(rec) - # Check if tablets information was purged - assert self.get_tablet_record(bound) is None, "tablet was not deleted, invalidation did not work" + # Wait for tablets information to be purged (invalidation is async) + wait_until( + lambda: self.get_tablet_record(bound) is None, + delay=0.5, max_attempts=20) diff --git a/tests/integration/standard/test_tablets_routing_v2.py b/tests/integration/standard/test_tablets_routing_v2.py new file mode 100644 index 0000000000..9edcdcd64e --- /dev/null +++ b/tests/integration/standard/test_tablets_routing_v2.py @@ -0,0 +1,548 @@ +""" +End-to-end tests for TABLETS_ROUTING_V2 against a V2-capable Scylla build. + +Unlike the unit tests in tests/unit/test_tablets.py and tests/unit/test_policies.py, +these tests cross the driver<->server boundary: they validate that the driver +negotiates the extension, parses the server's `tablets-routing-v2` payload with +the correct field layout, and that the tablet_version_block it sends actually +matches the server's encoding. + +The whole module is opt-in: the server only advertises the extension when started +with the `strongly-consistent-tables` experimental feature, and it is exchanged on +the wire under the name `TABLETS_ROUTING_V2_EXPERIMENTAL`. When run against a +server that does not advertise it (e.g. a released Scylla), every test is skipped. +""" + +from contextlib import contextmanager + +import pytest + +import cassandra.cqltypes as types +from cassandra import ConsistencyLevel +from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT +from cassandra.metadata import _ConsistencyMode +from cassandra.policies import ConstantReconnectionPolicy, RoundRobinPolicy, TokenAwarePolicy +from cassandra.protocol import ExecuteMessage +from cassandra.protocol_features import ( + ProtocolFeatures, TABLETS_ROUTING_V1, TABLETS_ROUTING_V2, +) + +from tests.integration import PROTOCOL_VERSION, use_cluster + + +def setup_module(module): + try: + # Use a single DC with three racks. + use_cluster('tablets_routing_v2', {"dc1": [1, 1, 1]}, start=True, set_keyspace=False, + configuration_options={ + # `strongly-consistent-tables` is what gates the server's + # advertisement of TABLETS_ROUTING_V2_EXPERIMENTAL. + 'experimental_features': ['udf', 'strongly-consistent-tables'], + }) + except Exception as exc: + pytest.skip("Could not start a Scylla cluster with the " + f"'strongly-consistent-tables' experimental feature: {exc}", + allow_module_level=True) + + +_add_startup_options = ProtocolFeatures.add_startup_options + + +def _startup_with_both_extensions(self, options): + """ + Drop-in replacement for ProtocolFeatures.add_startup_options that negotiates + BOTH tablets_routing_v1 and tablets_routing_v2 on the same connection. + + The real driver makes the two mutually exclusive (V2 wins). Forcing both lets + us prove the server-side precedence rules: scylla checks V2 first and only + falls back to V1 when V2 is not set. + + Every other extension must be negotiated exactly as the driver would, so this + delegates to the real implementation and only adds V1 on top of the V2 it + already requested. Enumerating the options here instead would silently stop + requesting any extension added later, while ProtocolFeatures still reports it + as negotiated (it is parsed from SUPPORTED, not from what STARTUP asked for) -- + and an extension that changes the frame layout, such as + SCYLLA_USE_METADATA_ID, then desynchronizes every request on the connection. + """ + _add_startup_options(self, options) + if self.tablets_routing_v1: + options[TABLETS_ROUTING_V1] = "" + + +class TestTabletsRoutingV2Integration: + @classmethod + def setup_class(cls): + cls.cluster = Cluster(contact_points=["127.0.0.1", "127.0.0.2", "127.0.0.3"], + protocol_version=PROTOCOL_VERSION, + execution_profiles={ + EXEC_PROFILE_DEFAULT: ExecutionProfile( + load_balancing_policy=TokenAwarePolicy(RoundRobinPolicy())) + }, + reconnection_policy=ConstantReconnectionPolicy(1)) + # pytest does not call teardown_class when setup_class raises, so any exit + # from here must shut the Cluster down explicitly or it leaks threads and + # sockets into later test modules. + try: + cls.session = cls.cluster.connect() + # A server without the 'strongly-consistent-tables' experimental + # feature (e.g. a released Scylla) still starts and connects, but it + # neither advertises TABLETS_ROUTING_V2 nor accepts the + # `consistency = 'global'` keyspace that _create_schema needs. Detect + # that here and skip the whole class, instead of letting _create_schema + # fail and erroring every test. + v2_negotiated = cls._v2_negotiated() + if v2_negotiated: + cls._create_schema(cls.session) + except Exception: + cls.cluster.shutdown() + raise + if not v2_negotiated: + cls.cluster.shutdown() + pytest.skip("Server does not support TABLETS_ROUTING_V2_EXPERIMENTAL. " + "It must be started with the 'strongly-consistent-tables' feature " + "and offer support for the protocol extension.") + + @classmethod + def teardown_class(cls): + cls.cluster.shutdown() + + @classmethod + def _create_schema(cls, session): + session.execute("DROP KEYSPACE IF EXISTS test_v2") + session.execute( + """ + CREATE KEYSPACE test_v2 + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 2} + AND tablets = {'initial': 8} + """) + session.execute("CREATE TABLE test_v2.t (pk int PRIMARY KEY, v int)") + prepared = session.prepare("INSERT INTO test_v2.t (pk, v) VALUES (?, ?)") + for i in range(50): + session.execute(prepared.bind((i, i))) + + session.execute("DROP KEYSPACE IF EXISTS test_v2_sc") + session.execute( + """ + CREATE KEYSPACE test_v2_sc + WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 2} + AND tablets = {'initial': 8} + AND consistency = 'global' + """) + session.execute("CREATE TABLE test_v2_sc.t (pk int PRIMARY KEY, v int)") + prepared_sc = session.prepare("INSERT INTO test_v2_sc.t (pk, v) VALUES (?, ?)") + # Writes to a strongly-consistent (Raft) table are rejected unless they + # use QUORUM/LOCAL_QUORUM. The session default is LOCAL_ONE, so request + # LOCAL_QUORUM for these inserts; it propagates to every statement bound + # from this prepared one. + prepared_sc.consistency_level = ConsistencyLevel.LOCAL_QUORUM + for i in range(50): + session.execute(prepared_sc.bind((i, i))) + + # -- helpers ---------------------------------------------------------------- + + @classmethod + def _v2_negotiated(cls): + connection = cls.session.cluster.control_connection._connection + return bool(connection and connection.features.tablets_routing_v2) + + def _cached_tablet(self, bound): + md = self.session.cluster.metadata + token = md.token_map.token_class.from_key(bound.routing_key) + tablet = md._tablets.get_tablet_for_key(bound.keyspace, bound.table, token) + return tablet, token + + def _ensure_cached(self, bound, attempts=30): + """ + Drive requests until the V2 routing cache is populated for `bound`. + + On a cold start the driver sends a *random* tablet_version_block, which + only matches the server ~1/16 of the time; on a mismatch the server + returns routing info and the cache is filled. We retry until that happens. + """ + for _ in range(attempts): + self.session.execute(bound) + tablet, _token = self._cached_tablet(bound) + if tablet is not None and tablet.tablet_version is not None: + return tablet + raise AssertionError("V2 routing cache was never populated; the server " + "never returned a 'tablets-routing-v2' payload") + + # -- tests ------------------------------------------------------------------ + + def test_v2_is_negotiated(self): + # Every per-host pool must report tablet-routing support, and every live + # connection in it must have negotiated V2 -- V2 gates the per-connection + # EXECUTE framing. + for pool in self.session._pools.values(): + assert pool.supports_tablet_routing is True + for conn in pool._connections.values(): + assert conn.features.tablets_routing_v2 is True + + def test_v2_payload_populates_cache_with_valid_fields(self): + """Test guarding against the payload tuple being decoded out of order.""" + select = self.session.prepare("SELECT v FROM test_v2.t WHERE pk = ?") + bound = select.bind([2]) + + tablet = self._ensure_cached(bound) + _, token = self._cached_tablet(bound) + + # If the tuple were decoded in the wrong order, first_token/last_token + # would actually carry the version / replica list and these invariants + # would not hold. + assert tablet.tablet_version is not None + # tablet_version is an unsigned 64-bit value; a signedness bug in the + # decode path would surface here as a negative or out-of-range number. + assert 0 <= tablet.tablet_version <= 2 ** 64 - 1 + assert tablet.first_token <= tablet.last_token + # get_tablet_for_key matches first_token < token <= last_token. + assert tablet.first_token < token.value and token.value <= tablet.last_token + + # Replicas must be real hosts known to the cluster with sane shard ids. + known_host_ids = {h.host_id for h in self.session.cluster.metadata.all_hosts()} + assert tablet.replicas, "tablet has no replicas" + for host_id, shard in tablet.replicas: + assert host_id in known_host_ids, \ + f"replica host_id {host_id} is not a known host (corrupt payload?)" + assert isinstance(shard, int) and shard >= 0 + + def test_matching_block_yields_no_payload(self): + """Test guarding against a wrong tablet_version_block bit-shift.""" + select = self.session.prepare("SELECT v FROM test_v2.t WHERE pk = ?") + bound = select.bind([7]) + + # Populate the cache so the driver knows the current tablet_version. + self._ensure_cached(bound) + + # The next request carries a block derived from the cached version. If the + # driver's encoding agrees with the server, the versions match and NO + # routing payload is returned. A wrong shift would mismatch and the server + # would keep returning routing info. + result = self.session.execute(bound) + assert result.one() is not None + payload = result.response_future.custom_payload + assert not (payload and 'tablets-routing-v2' in payload), ( + "Server returned routing info despite a cached, up-to-date " + "tablet_version; the driver's tablet_version_block encoding likely " + "disagrees with the server (locator::compare_tablet_version_block)") + + # -- low-level helpers ------------------------------------------------------ + + @staticmethod + def _right_block(version, idx=0): + """ + Build a tablet_version_block that the server will accept as a match for + block `idx` of `version` (high nibble = index, low nibble = that nibble + of the version). + """ + idx &= 0xF + return (idx << 4) | ((version >> (idx * 4)) & 0xF) + + def _send_raw_execute(self, conn, bound, tablet_version_block): + """ + Send an EXECUTE directly on a specific shard connection with a chosen + tablet_version_block (or None to omit the byte entirely, i.e. behave like + the pre-V2 protocol), and return the decoded response message. + + This bypasses ResponseFuture/load balancing so we control exactly which + node+shard the request hits and which byte is on the wire; it also avoids + polluting the driver's tablet cache. + """ + ps = bound.prepared_statement + msg = ExecuteMessage( + ps.query_id, bound.values, ConsistencyLevel.LOCAL_ONE, + serial_consistency_level=None, fetch_size=None, paging_state=None, + timestamp=None, skip_meta=False, + result_metadata_id=ps.result_metadata_id, + tablet_version_block=tablet_version_block) + return conn.wait_for_response(msg, timeout=30) + + def _decode_v2_payload(self, payload): + ctype = types.lookup_casstype( + 'TupleType(LongType, LongType, ListType(TupleType(UUIDType, Int32Type)), LongType)') + info = ctype.from_binary(payload['tablets-routing-v2'], self.cluster.protocol_version) + # LongType decodes as signed, but tablet_version is an unsigned 64-bit + # value; mask it the same way Tablet.from_row does so the decoded value + # matches what the driver cached. + return {'first_token': info[0], 'last_token': info[1], + 'replicas': info[2], + 'tablet_version': info[3] & 0xFFFFFFFFFFFFFFFF} + + def _any_connection(self): + for pool in self.session._pools.values(): + for conn in pool._connections.values(): + return conn + raise AssertionError("no shard connections available") + + @staticmethod + def _all_shard_connections(session): + for host, pool in session._pools.items(): + for shard, conn in pool._connections.items(): + yield host, shard, conn + + @staticmethod + def _wait_for_shard_connections(session, timeout=15): + """Wait until each pool has filled its shard-aware connections (background).""" + import time + deadline = time.time() + timeout + while time.time() < deadline: + if all( + len(pool._connections) >= (min(host.sharding_info.shards_count, 2) + if host.sharding_info else 1) + for host, pool in session._pools.items() + ): + return + time.sleep(0.05) + raise AssertionError(f"Shard-aware connection pools did not fill within {timeout}s") + + @contextmanager + def _cluster_with_v1_and_v2(self): + """ + Yield a (cluster, session) whose connections negotiated BOTH V1 and V2. + Restores the original startup behavior and shuts the cluster down on exit. + """ + original = ProtocolFeatures.add_startup_options + ProtocolFeatures.add_startup_options = _startup_with_both_extensions + + cluster = None + try: + cluster = Cluster(contact_points=["127.0.0.1", "127.0.0.2", "127.0.0.3"], + protocol_version=PROTOCOL_VERSION, + execution_profiles={ + EXEC_PROFILE_DEFAULT: ExecutionProfile( + load_balancing_policy=TokenAwarePolicy(RoundRobinPolicy())) + }, + reconnection_policy=ConstantReconnectionPolicy(1)) + session = cluster.connect('test_v2') + self._wait_for_shard_connections(session) + yield cluster, session + finally: + ProtocolFeatures.add_startup_options = original + if cluster is not None: + cluster.shutdown() + + @staticmethod + def _find_replica_wrong_shard(session, tablet): + """ + Find a connection to a host that *is* a replica of `tablet` but on a shard + that the host does NOT own for it ("right node, wrong shard"). Returns + (host, owner_shard, wrong_shard, conn) or None if no host has >=2 shards. + """ + replica_shard = {host_id: shard for host_id, shard in tablet.replicas} + for host, pool in session._pools.items(): + owner = replica_shard.get(host.host_id) + if owner is None: + continue + for shard, conn in pool._connections.items(): + if shard != owner: + return host, owner, shard, conn + return None + + # -- scenario tests --------------------------------------------------------- + + def test_index0_all_block_values_exactly_one_match(self): + """ + Scenario 1: for block index 0, exactly one of the 16 possible values + matches the server's tablet_version; every other value is reported as a + mismatch carrying that same tablet_version, whose nibble 0 equals the + value that matched. + """ + select = self.session.prepare("SELECT v FROM test_v2.t WHERE pk = ?") + bound = select.bind([11]) + tablet = self._ensure_cached(bound) + version = tablet.tablet_version + + conn = self._any_connection() + + matched_values = [] + reported_versions = [] + for value in range(16): + block = value # index 0 -> high nibble 0, low nibble = value + resp = self._send_raw_execute(conn, bound, block) + payload = resp.custom_payload or {} + if 'tablets-routing-v2' in payload: + reported_versions.append(self._decode_v2_payload(payload)['tablet_version']) + else: + matched_values.append(value) + + # Exactly one value matches: the low nibble of the version. + assert matched_values == [version & 0xF], \ + f"expected exactly one matching block value, got {matched_values}" + # All 15 mismatches report the same tablet_version ... + assert len(reported_versions) == 15 + assert set(reported_versions) == {version} + # ... and that version's block-0 nibble is the value that matched. + assert (version & 0xF) == matched_values[0] + + def test_right_block_to_all_nodes_and_shards_never_returns_payload(self): + """ + Scenario 2: a correct tablet_version_block matches on every node and every + shard (the server's V2 check ignores shard), so no routing payload is ever + returned. + """ + select = self.session.prepare("SELECT v FROM test_v2.t WHERE pk = ?") + bound = select.bind([13]) + tablet = self._ensure_cached(bound) + version = tablet.tablet_version + + sent = 0 + for host, shard, conn in self._all_shard_connections(self.session): + # Vary the block index per shard to also exercise non-zero indices. + block = self._right_block(version, idx=shard) + resp = self._send_raw_execute(conn, bound, block) + payload = resp.custom_payload or {} + assert 'tablets-routing-v2' not in payload, ( + f"host {host} shard {shard} returned a routing payload for a correct " + "tablet_version_block") + sent += 1 + assert sent >= 1, "no shard connections were exercised" + + def test_v2_takes_precedence_over_v1_no_v1_payload_on_wrong_shard(self): + """ + Scenario 3: with BOTH V1 and V2 negotiated, send a correct V2 block to the + wrong shard. The server checks V2 first; since the block matches there is + no payload at all -- crucially no `tablets-routing-v1`, which V1 would have + emitted for a wrong-shard request. + """ + select = self.session.prepare("SELECT v FROM test_v2.t WHERE pk = ?") + bound = select.bind([17]) + tablet = self._ensure_cached(bound) + version = tablet.tablet_version + + with self._cluster_with_v1_and_v2() as (_cluster, session): + target = self._find_replica_wrong_shard(session, tablet) + if target is None: + pytest.skip("need a replica host with >=2 shards to target a wrong shard") + _host, _owner_shard, _wrong_shard, conn = target + assert conn.features.tablets_routing_v1 and conn.features.tablets_routing_v2, \ + "test setup failed: connection did not negotiate both V1 and V2" + + resp = self._send_raw_execute(conn, bound, self._right_block(version)) + payload = resp.custom_payload or {} + assert 'tablets-routing-v1' not in payload, ( + "server emitted V1 routing info despite V2 being negotiated; " + "V2 must take precedence (select_statement.cc)") + # The correct V2 block also means no V2 payload. + assert 'tablets-routing-v2' not in payload + + # -- strongly-consistent (leader-aware) routing ----------------------------- + + def test_strongly_consistent_keyspace_metadata(self): + """ + The driver must learn from system_schema.scylla_keyspaces which keyspaces + are strongly consistent: test_v2_sc (consistency='global') reports GLOBAL, + test_v2 (no consistency clause) reports EVENTUAL. A GLOBAL mode is the + precondition for leader-aware routing in + TokenAwarePolicy.make_query_plan. + """ + self.session.cluster.refresh_schema_metadata() + keyspaces = self.session.cluster.metadata.keyspaces + assert keyspaces['test_v2_sc']._consistency_mode is _ConsistencyMode.GLOBAL + assert keyspaces['test_v2']._consistency_mode is _ConsistencyMode.EVENTUAL + + def test_consistency_mode_tracks_dynamic_keyspace_changes(self): + """ + The driver reads system_schema.scylla_keyspaces on every schema refresh + and sets KeyspaceMetadata._consistency_mode for each keyspace. + + The mode is not a one-off computed at connect time -- it has to track the + live schema. Because the driver refreshes its metadata synchronously in + response to a DDL it executes (ResponseFuture handles + RESULT_KIND_SCHEMA_CHANGE by refreshing before returning), a keyspace + created or dropped *after* connecting is immediately reflected in + cluster.metadata.keyspaces, with no sleep or manual refresh required. A + keyspace created by some *other* client is picked up through the very same + refresh path, driven by the control connection's schema-change events + (subject to the schema refresh window); this test drives the changes + through the connected session so the assertions stay deterministic. + """ + metadata = self.session.cluster.metadata + ec_ks = "dyn_ec_ks" # eventually consistent (no consistency clause) + sc_ks = "dyn_sc_ks" # strongly consistent (Raft, consistency='global') + + # Start from a known-clean slate so the test is repeatable. + self.session.execute("DROP KEYSPACE IF EXISTS {0}".format(ec_ks)) + self.session.execute("DROP KEYSPACE IF EXISTS {0}".format(sc_ks)) + try: + assert ec_ks not in metadata.keyspaces + assert sc_ks not in metadata.keyspaces + + # Create an eventually-consistent keyspace after connecting: it shows + # up in the map as EVENTUAL. This exercises the + # "absent from scylla_keyspaces -> eventual" path. + self.session.execute( + "CREATE KEYSPACE {0} WITH replication = " + "{{'class': 'NetworkTopologyStrategy', 'replication_factor': 1}} " + "AND tablets = {{'initial': 1}}".format(ec_ks)) + assert ec_ks in metadata.keyspaces + assert metadata.keyspaces[ec_ks]._consistency_mode is _ConsistencyMode.EVENTUAL + + # Create a strongly-consistent keyspace: same map, mode now GLOBAL. + # (RF is irrelevant here -- the mode only tracks the consistency option.) + self.session.execute( + "CREATE KEYSPACE {0} WITH replication = " + "{{'class': 'NetworkTopologyStrategy', 'replication_factor': 1}} " + "AND tablets = {{'initial': 1}} AND consistency = 'global'".format(sc_ks)) + assert sc_ks in metadata.keyspaces + assert metadata.keyspaces[sc_ks]._consistency_mode is _ConsistencyMode.GLOBAL + # The previously-created keyspace keeps its EVENTUAL mode. + assert metadata.keyspaces[ec_ks]._consistency_mode is _ConsistencyMode.EVENTUAL + + # A full refresh (the bulk get_all_keyspaces path, as opposed to the + # single-keyspace get_keyspace path the DDL above exercised) agrees. + self.session.cluster.refresh_schema_metadata() + assert metadata.keyspaces[ec_ks]._consistency_mode is _ConsistencyMode.EVENTUAL + assert metadata.keyspaces[sc_ks]._consistency_mode is _ConsistencyMode.GLOBAL + + # Dropping a keyspace removes it from the map and leaves the other + # keyspace's mode untouched. + self.session.execute("DROP KEYSPACE {0}".format(sc_ks)) + assert sc_ks not in metadata.keyspaces + assert metadata.keyspaces[ec_ks]._consistency_mode is _ConsistencyMode.EVENTUAL + + self.session.execute("DROP KEYSPACE {0}".format(ec_ks)) + assert ec_ks not in metadata.keyspaces + finally: + self.session.execute("DROP KEYSPACE IF EXISTS {0}".format(ec_ks)) + self.session.execute("DROP KEYSPACE IF EXISTS {0}".format(sc_ks)) + + def test_leader_aware_routing_targets_the_raft_leader(self): + """ + For a strongly-consistent table, the server orders the replica list with + the Raft leader first. Once that payload is cached, a TokenAwarePolicy + must route every leader-requiring request (here a LOCAL_QUORUM read) for + the tablet to replicas[0] (the leader), saving the extra + coordinator->leader hop. This is the strongly-consistent counterpart to + the eventually consistent test_v2 tests above, which never assert *which* + replica is hit. + + A read at ONE/LOCAL_ONE is intentionally *not* pinned to the leader (any + single replica satisfies it); that carve-out is covered by the policy + unit tests. + """ + select = self.session.prepare("SELECT v FROM test_v2_sc.t WHERE pk = ?") + bound = select.bind([2]) + # Leader-first routing only applies to requests that actually need the + # leader, so request LOCAL_QUORUM (a strong read). The session default is + # LOCAL_ONE, which the policy would deliberately spread across replicas. + bound.consistency_level = ConsistencyLevel.LOCAL_QUORUM + + tablet = self._ensure_cached(bound) + assert tablet.replicas, "strongly-consistent tablet has no replicas" + leader_host_id = tablet.replicas[0][0] + + # Leader-first routing only triggers when the keyspace is known to be + # strongly consistent, i.e. when its consistency mode is GLOBAL. + ks_meta = self.session.cluster.metadata.keyspaces['test_v2_sc'] + assert ks_meta._consistency_mode is _ConsistencyMode.GLOBAL + + # With an up-to-date cache the block always matches, so the server returns + # no further payload and replicas[0] stays the leader; every request must + # therefore be coordinated by that leader. + for _ in range(10): + result = self.session.execute(bound) + coordinator = result.response_future.coordinator_host + assert coordinator is not None and coordinator.host_id == leader_host_id, ( + "request coordinated by {} but the Raft leader is replicas[0]={}; " + "leader-aware routing did not target the leader".format( + getattr(coordinator, 'host_id', None), leader_host_id)) diff --git a/tests/integration/standard/test_types.py b/tests/integration/standard/test_types.py index 1d66ce1ed9..cc946bf0d5 100644 --- a/tests/integration/standard/test_types.py +++ b/tests/integration/standard/test_types.py @@ -21,15 +21,13 @@ import socket import uuid -from datetime import datetime, date, time, timedelta +from datetime import datetime, timedelta from decimal import Decimal from functools import partial -from packaging.version import Version import cassandra from cassandra import InvalidRequest -from cassandra import util from cassandra.cluster import ExecutionProfile, EXEC_PROFILE_DEFAULT from cassandra.concurrent import execute_concurrent_with_args from cassandra.cqltypes import Int32Type, EMPTY @@ -38,7 +36,7 @@ from tests.unit.cython.utils import cythontest from tests.util import assertEqual -from tests.integration import use_singledc, execute_until_pass, notprotocolv1, \ +from tests.integration import use_single_node, execute_until_pass, notprotocolv1, \ BasicSharedKeyspaceUnitTestCase, greaterthancass21, lessthancass30, \ greaterthanorequalcass3_10, TestCluster, requires_composite_type, \ requires_vector_type @@ -48,7 +46,7 @@ def setup_module(): - use_singledc() + use_single_node() update_datatypes() @@ -663,18 +661,22 @@ def test_can_insert_nested_tuples(self): s.encoder.mapping[tuple] = s.encoder.cql_encode_tuple # create a table with multiple sizes of nested tuples + # Note: Scylla limits CQL expression nesting depth to 12 (every + # recursive `term` counts, including the innermost scalar value), so a + # nested tuple literal can be at most 11 levels deep before the server + # rejects it with "expression nested too deeply". s.execute("CREATE TABLE nested_tuples (" "k int PRIMARY KEY, " "v_1 frozen<%s>," "v_2 frozen<%s>," "v_3 frozen<%s>," - "v_32 frozen<%s>" + "v_11 frozen<%s>" ")" % (self.nested_tuples_schema_helper(1), self.nested_tuples_schema_helper(2), self.nested_tuples_schema_helper(3), - self.nested_tuples_schema_helper(32))) + self.nested_tuples_schema_helper(11))) - for i in (1, 2, 3, 32): + for i in (1, 2, 3, 11): # create tuple created_tuple = self.nested_tuples_creator_helper(i) diff --git a/tests/integration/standard/test_udts.py b/tests/integration/standard/test_udts.py index dd696ea0e9..520df49413 100644 --- a/tests/integration/standard/test_udts.py +++ b/tests/integration/standard/test_udts.py @@ -21,7 +21,7 @@ from cassandra.query import dict_factory from cassandra.util import OrderedMap -from tests.integration import use_singledc, execute_until_pass, \ +from tests.integration import use_single_node, execute_until_pass, \ BasicSegregatedKeyspaceUnitTestCase, greaterthancass20, lessthancass30, greaterthanorequalcass36, TestCluster from tests.integration.datatype_utils import update_datatypes, PRIMITIVE_DATATYPES, PRIMITIVE_DATATYPES_KEYS, \ COLLECTION_TYPES, get_sample, get_collection_sample @@ -32,7 +32,7 @@ def setup_module(): - use_singledc() + use_single_node() update_datatypes() @@ -94,7 +94,7 @@ def test_can_insert_unprepared_registered_udts(self): # use the same UDT name in a different keyspace s.execute(""" CREATE KEYSPACE udt_test_unprepared_registered2 - WITH replication = { 'class' : 'SimpleStrategy', 'replication_factor': '1' } + WITH replication = { 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1' } """) s.set_keyspace("udt_test_unprepared_registered2") s.execute("CREATE TYPE user (state text, is_cool boolean)") @@ -124,14 +124,14 @@ def test_can_register_udt_before_connecting(self): s.execute(""" CREATE KEYSPACE udt_test_register_before_connecting - WITH replication = { 'class' : 'SimpleStrategy', 'replication_factor': '1' } + WITH replication = { 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1' } """) s.execute("CREATE TYPE udt_test_register_before_connecting.user (age int, name text)") s.execute("CREATE TABLE udt_test_register_before_connecting.mytable (a int PRIMARY KEY, b frozen)") s.execute(""" CREATE KEYSPACE udt_test_register_before_connecting2 - WITH replication = { 'class' : 'SimpleStrategy', 'replication_factor': '1' } + WITH replication = { 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1' } """) s.execute("CREATE TYPE udt_test_register_before_connecting2.user (state text, is_cool boolean)") s.execute("CREATE TABLE udt_test_register_before_connecting2.mytable (a int PRIMARY KEY, b frozen)") @@ -147,7 +147,7 @@ def test_can_register_udt_before_connecting(self): c.register_user_type("udt_test_register_before_connecting2", "user", User2) s = c.connect(wait_for_all_pools=True) - c.control_connection.wait_for_schema_agreement() + s.wait_for_schema_agreement() s.execute("INSERT INTO udt_test_register_before_connecting.mytable (a, b) VALUES (%s, %s)", (0, User1(42, 'bob'))) result = s.execute("SELECT b FROM udt_test_register_before_connecting.mytable WHERE a=0") @@ -193,7 +193,7 @@ def test_can_insert_prepared_unregistered_udts(self): # use the same UDT name in a different keyspace s.execute(""" CREATE KEYSPACE udt_test_prepared_unregistered2 - WITH replication = { 'class' : 'SimpleStrategy', 'replication_factor': '1' } + WITH replication = { 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1' } """) s.set_keyspace("udt_test_prepared_unregistered2") s.execute("CREATE TYPE user (state text, is_cool boolean)") @@ -240,7 +240,7 @@ def test_can_insert_prepared_registered_udts(self): # use the same UDT name in a different keyspace s.execute(""" CREATE KEYSPACE udt_test_prepared_registered2 - WITH replication = { 'class' : 'SimpleStrategy', 'replication_factor': '1' } + WITH replication = { 'class' : 'NetworkTopologyStrategy', 'replication_factor': '1' } """) s.set_keyspace("udt_test_prepared_registered2") s.execute("CREATE TYPE user (state text, is_cool boolean)") @@ -389,7 +389,12 @@ def test_can_insert_nested_registered_udts(self): with self._cluster_default_dict_factory() as c: s = c.connect(self.keyspace_name, wait_for_all_pools=True) - max_nesting_depth = 16 + # Scylla caps CQL expression nesting depth at 12 (every recursive + # `term` counts). A UDT literal `{value: ...}` adds two term levels + # per nesting, so a UDT literal inserted via a simple statement can + # be at most 10 levels deep before the server rejects it with + # "expression nested too deeply". + max_nesting_depth = 10 # create the schema self.nested_udt_schema_helper(s, max_nesting_depth) @@ -417,7 +422,7 @@ def test_can_insert_nested_unregistered_udts(self): with self._cluster_default_dict_factory() as c: s = c.connect(self.keyspace_name, wait_for_all_pools=True) - max_nesting_depth = 16 + max_nesting_depth = 12 # create the schema self.nested_udt_schema_helper(s, max_nesting_depth) @@ -454,7 +459,12 @@ def test_can_insert_nested_registered_udts_with_different_namedtuples(self): with self._cluster_default_dict_factory() as c: s = c.connect(self.keyspace_name, wait_for_all_pools=True) - max_nesting_depth = 16 + # Scylla caps CQL expression nesting depth at 12 (every recursive + # `term` counts). A UDT literal `{value: ...}` adds two term levels + # per nesting, so a UDT literal inserted via a simple statement can + # be at most 10 levels deep before the server rejects it with + # "expression nested too deeply". + max_nesting_depth = 10 # create the schema self.nested_udt_schema_helper(s, max_nesting_depth) diff --git a/tests/integration/standard/test_use_keyspace.py b/tests/integration/standard/test_use_keyspace.py index 25e954b956..9eb3f5be36 100644 --- a/tests/integration/standard/test_use_keyspace.py +++ b/tests/integration/standard/test_use_keyspace.py @@ -14,12 +14,23 @@ LOGGER = logging.getLogger(__name__) +_saved_scylla_ext_opts = None + def setup_module(): + global _saved_scylla_ext_opts + _saved_scylla_ext_opts = os.environ.get('SCYLLA_EXT_OPTS') os.environ['SCYLLA_EXT_OPTS'] = "--smp 2 --memory 2048M" use_cluster('shared_aware', [3], start=True) +def teardown_module(): + if _saved_scylla_ext_opts is None: + os.environ.pop('SCYLLA_EXT_OPTS', None) + else: + os.environ['SCYLLA_EXT_OPTS'] = _saved_scylla_ext_opts + + @local class TestUseKeyspace(unittest.TestCase): @classmethod @@ -54,7 +65,7 @@ def patched_set_keyspace_blocking(*args, **kwargs): return original_set_keyspace_blocking(*args, **kwargs) with patch.object(Connection, "set_keyspace_blocking", patched_set_keyspace_blocking): - self.session.execute("CREATE KEYSPACE test_set_keyspace WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}") + self.session.execute("CREATE KEYSPACE test_set_keyspace WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 1}") self.session.execute("CREATE TABLE test_set_keyspace.set_keyspace_slow_connection(pk int, PRIMARY KEY(pk))") session2 = self.cluster.connect() diff --git a/tests/integration/upgrade/__init__.py b/tests/integration/upgrade/__init__.py index a1c751bcbd..42588f1608 100644 --- a/tests/integration/upgrade/__init__.py +++ b/tests/integration/upgrade/__init__.py @@ -13,7 +13,7 @@ # limitations under the License. -from tests.integration import CCM_KWARGS, use_cluster, remove_cluster, MockLoggingHandler +from tests.integration import use_cluster, remove_cluster, MockLoggingHandler from tests.integration import setup_keyspace from cassandra.cluster import Cluster @@ -182,9 +182,21 @@ class UpgradeBaseAuth(UpgradeBase): def _upgrade_step_setup(self): """ - We sleep here for the same reason as we do in test_authentication.py: - there seems to be some race, with some versions of C* taking longer to - get the auth (and default user) setup. Sleep here to give it a chance + Wait for PasswordAuthenticator to finish initializing (creating the + default superuser). Poll by attempting to authenticate rather than + using a fixed sleep. """ super(UpgradeBaseAuth, self)._upgrade_step_setup() - time.sleep(10) + + from cassandra.auth import PlainTextAuthProvider + from tests.util import wait_until_not_raised + + def _check_auth_ready(): + c = Cluster(auth_provider=PlainTextAuthProvider('cassandra', 'cassandra')) + try: + s = c.connect() + s.execute("SELECT * FROM system.local WHERE key='local'") + finally: + c.shutdown() + + wait_until_not_raised(_check_auth_ready, delay=1, max_attempts=30) diff --git a/tests/integration/upgrade/test_upgrade.py b/tests/integration/upgrade/test_upgrade.py index fec9a38604..1eccf12712 100644 --- a/tests/integration/upgrade/test_upgrade.py +++ b/tests/integration/upgrade/test_upgrade.py @@ -19,11 +19,21 @@ from cassandra.cluster import ConsistencyLevel, Cluster, DriverException, ExecutionProfile from cassandra.policies import ConstantSpeculativeExecutionPolicy from tests.integration.upgrade import UpgradeBase, UpgradeBaseAuth, UpgradePath, upgrade_paths +from tests.util import wait_until -import unittest import pytest +def _wait_for_control_connection(cluster_driver, timeout=60): + """Wait for the driver's control connection to be established.""" + wait_until( + lambda: cluster_driver.control_connection._connection is not None + and not cluster_driver.control_connection._connection.is_closed, + delay=1, + max_attempts=timeout, + ) + + # Previous Cassandra upgrade two_to_three_path = upgrade_paths([ UpgradePath("2.2.9-3.11", {"version": "2.2.9"}, {"version": "3.11.4"}, {}), @@ -142,14 +152,14 @@ def test_schema_metadata_gets_refreshed(self): for node in nodes[1:]: self.upgrade_node(node) # Wait for the control connection to reconnect - time.sleep(20) + _wait_for_control_connection(self.cluster_driver) with pytest.raises(DriverException): self.cluster_driver.refresh_schema_metadata(max_schema_agreement_wait=10) self.upgrade_node(nodes[0]) # Wait for the control connection to reconnect - time.sleep(20) + _wait_for_control_connection(self.cluster_driver) self.cluster_driver.refresh_schema_metadata(max_schema_agreement_wait=40) assert original_meta != self.cluster_driver.metadata.keyspaces @@ -171,7 +181,7 @@ def test_schema_nodes_gets_refreshed(self): token_map = self.cluster_driver.metadata.token_map self.upgrade_node(node) # Wait for the control connection to reconnect - time.sleep(20) + _wait_for_control_connection(self.cluster_driver) self.cluster_driver.refresh_nodes(force_token_rebuild=True) self._assert_same_token_map(token_map, self.cluster_driver.metadata.token_map) diff --git a/tests/stress_tests/test_load.py b/tests/stress_tests/test_load.py index 3492ff2923..7bf7a2d374 100644 --- a/tests/stress_tests/test_load.py +++ b/tests/stress_tests/test_load.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -import unittest import gc diff --git a/tests/tcp_proxy.py b/tests/tcp_proxy.py new file mode 100644 index 0000000000..e87df3b430 --- /dev/null +++ b/tests/tcp_proxy.py @@ -0,0 +1,224 @@ +# Copyright 2026 ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Socket-level ``TcpProxy`` test helper. + +It backs the Client Routes / NLB integration tests +(``tests/integration/standard/test_client_routes.py``), but has no +dependency on CCM or a running Cassandra/Scylla cluster, so it lives here +rather than in ``tests.integration`` -- that lets the unit test suite +(``tests/unit/test_tcp_proxy.py``) exercise it without importing +``tests.integration``, whose module-level code requires ``ccmlib`` and +CASSANDRA_VERSION/SCYLLA_VERSION to be set. +""" + +import logging +import select +import socket +import threading + +log = logging.getLogger(__name__) + + +class TcpProxy: + """ + A simple TCP proxy that forwards connections from a local listen port + to a target (host, port). Tracks active connections so tests can + verify that traffic flows through the proxy. + """ + + BUF_SIZE = 65536 + + def __init__(self, listen_host, listen_port, target_host, target_port): + self.listen_host = listen_host + self.listen_port = listen_port + self.target_host = target_host + self.target_port = target_port + + self._server_sock = None + self._running = False + self._thread = None + self._lock = threading.Lock() + self._connections = {} # (client_sock, target_sock) -> forwarder thread + self.total_connections = 0 + + def start(self): + self._server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + self._server_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + self._server_sock.bind((self.listen_host, self.listen_port)) + self.listen_port = self._server_sock.getsockname()[1] + self._server_sock.listen(128) + self._server_sock.setblocking(False) + self._running = True + self._thread = threading.Thread(target=self._run, daemon=True, + name="proxy-%s:%d" % (self.listen_host, self.listen_port)) + self._thread.start() + log.info("TcpProxy started %s:%d -> %s:%d", + self.listen_host, self.listen_port, + self.target_host, self.target_port) + + def stop(self): + if self._server_sock: + try: + self._server_sock.close() + except Exception: + pass + self._shutdown_and_join_connections(stopping=True) + if self._thread: + self._thread.join(timeout=5) + log.info("TcpProxy stopped %s:%d", self.listen_host, self.listen_port) + + @property + def active_connections(self): + with self._lock: + return len(self._connections) + + def retarget(self, new_host, new_port): + """Change the backend target for new connections (existing ones keep the old target).""" + self.target_host = new_host + self.target_port = new_port + log.info("TcpProxy %s:%d retargeted to %s:%d", + self.listen_host, self.listen_port, new_host, new_port) + + def drop_connections(self): + """Forcibly close all active connections.""" + self._shutdown_and_join_connections() + log.info("TcpProxy %s:%d dropped all connections", self.listen_host, self.listen_port) + + def _shutdown_and_join_connections(self, stopping=False): + """ + Shut down (not close) each connection's sockets to unblock its + forwarder thread, then join it. Only the forwarder thread itself + closes its sockets, avoiding a close-vs-still-in-use fd-reuse race. + + stopping=True (stop() only) flips _running to False under the same + lock as the connections snapshot, so no connection registered by + _handle_new_connection can be missed. + """ + with self._lock: + if stopping: + self._running = False + connections = list(self._connections.items()) + for (csock, tsock), _thread in connections: + self._shutdown_pair(csock, tsock) + finished_keys = [] + for (csock, tsock), thread in connections: + thread.join(timeout=5) + if thread.is_alive(): + # Do NOT drop this entry from self._connections: it is + # still a live thread owning open fds. Leaving it tracked + # lets active_connections reflect reality and lets a + # subsequent stop()/drop_connections() retry the shutdown + # and join. _forward_loop() removes its own entry (under + # _lock) once it actually exits, so there's no leak here. + log.warning( + "TcpProxy %s:%d: forwarder thread %s did not exit " + "within timeout; leaked fds are possible", + self.listen_host, self.listen_port, thread.name) + else: + finished_keys.append((csock, tsock)) + with self._lock: + for key in finished_keys: + self._connections.pop(key, None) + + def _run(self): + while self._running: + try: + readable, _, _ = select.select([self._server_sock], [], [], 0.2) + except (ValueError, OSError): + break + for sock in readable: + if sock is self._server_sock: + try: + client_sock, _ = self._server_sock.accept() + except OSError: + continue + self._handle_new_connection(client_sock) + + def _handle_new_connection(self, client_sock, target_host=None, target_port=None): + target_host = target_host or self.target_host + target_port = target_port or self.target_port + try: + target_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + target_sock.connect((target_host, target_port)) + except Exception as e: + log.warning("TcpProxy %s:%d failed to connect to target %s:%d: %s", + self.listen_host, self.listen_port, + target_host, target_port, e) + client_sock.close() + return + + t = threading.Thread(target=self._forward_loop, + args=(client_sock, target_sock), + daemon=True) + # Register then start() atomically under _lock, in that order: + # otherwise a short-lived thread could finish (and clean up) + # before being registered, leaking the entry, or run unseen by + # a concurrent stop()/drop_connections(). Also re-check + # _running, to reject connections after shutdown has begun. + with self._lock: + if not self._running: + target_sock.close() + client_sock.close() + return + self._connections[(client_sock, target_sock)] = t + self.total_connections += 1 + try: + t.start() + except Exception as e: + # Undo registration: join()-ing an unstarted thread later + # would raise RuntimeError. + self._connections.pop((client_sock, target_sock), None) + self.total_connections -= 1 + log.warning("TcpProxy %s:%d failed to start forwarder thread: %s", + self.listen_host, self.listen_port, e) + client_sock.close() + target_sock.close() + + def _forward_loop(self, client_sock, target_sock): + try: + while self._running: + readable, _, _ = select.select([client_sock, target_sock], [], [], 0.5) + for sock in readable: + data = sock.recv(self.BUF_SIZE) + if not data: + return + if sock is client_sock: + target_sock.sendall(data) + else: + client_sock.sendall(data) + except (OSError, ConnectionResetError, BrokenPipeError): + pass + finally: + with self._lock: + self._connections.pop((client_sock, target_sock), None) + self._close_pair(client_sock, target_sock) + + @staticmethod + def _close_pair(csock, tsock): + for s in (csock, tsock): + try: + s.close() + except Exception: + pass + + @staticmethod + def _shutdown_pair(csock, tsock): + """Best-effort shutdown (not close) to interrupt a thread blocked in select()/recv().""" + for s in (csock, tsock): + try: + s.shutdown(socket.SHUT_RDWR) + except OSError: + pass diff --git a/tests/unit/advanced/test_graph.py b/tests/unit/advanced/test_graph.py index 5b82def245..6939f1217c 100644 --- a/tests/unit/advanced/test_graph.py +++ b/tests/unit/advanced/test_graph.py @@ -19,7 +19,7 @@ from cassandra import ConsistencyLevel from cassandra.policies import RetryPolicy -from cassandra.graph import (SimpleGraphStatement, GraphOptions, GraphProtocol, Result, +from cassandra.graph import (SimpleGraphStatement, GraphOptions, Result, graph_result_row_factory, single_object_row_factory, Vertex, Edge, Path, VertexProperty) from cassandra.datastax.graph.query import _graph_options diff --git a/tests/unit/advanced/test_insights.py b/tests/unit/advanced/test_insights.py index ec9b918866..2050439804 100644 --- a/tests/unit/advanced/test_insights.py +++ b/tests/unit/advanced/test_insights.py @@ -21,18 +21,12 @@ from cassandra import ConsistencyLevel from cassandra.cluster import ( - ExecutionProfile, GraphExecutionProfile, ProfileManager, - GraphAnalyticsExecutionProfile, - EXEC_PROFILE_DEFAULT, EXEC_PROFILE_GRAPH_DEFAULT, - EXEC_PROFILE_GRAPH_ANALYTICS_DEFAULT, - EXEC_PROFILE_GRAPH_SYSTEM_DEFAULT + ExecutionProfile, GraphExecutionProfile, GraphAnalyticsExecutionProfile ) from cassandra.datastax.graph.query import GraphOptions from cassandra.datastax.insights.registry import insights_registry from cassandra.datastax.insights.serializers import initialize_registry -from cassandra.datastax.insights.util import namespace from cassandra.policies import ( - RoundRobinPolicy, LoadBalancingPolicy, DCAwareRoundRobinPolicy, TokenAwarePolicy, diff --git a/tests/unit/advanced/test_metadata.py b/tests/unit/advanced/test_metadata.py index 5ccfa5e477..1503759372 100644 --- a/tests/unit/advanced/test_metadata.py +++ b/tests/unit/advanced/test_metadata.py @@ -16,7 +16,7 @@ from cassandra.metadata import ( KeyspaceMetadata, TableMetadataDSE68, - VertexMetadata, EdgeMetadata, SchemaParserV22, _SchemaParser + VertexMetadata, EdgeMetadata, _SchemaParser ) from cassandra.protocol import ResultMessage, RESULT_KIND_ROWS @@ -34,8 +34,8 @@ def _create_vertex_metadata(self, label_name='label'): def _create_keyspace_metadata(self, graph_engine): return KeyspaceMetadata( - 'keyspace', True, 'org.apache.cassandra.locator.SimpleStrategy', - {'replication_factor': 1}, graph_engine=graph_engine) + 'keyspace', True, 'org.apache.cassandra.locator.NetworkTopologyStrategy', + {'dc1': 1}, graph_engine=graph_engine) def _create_table_metadata(self, with_vertex=False, with_edge=False): tm = TableMetadataDSE68('keyspace', 'table') diff --git a/tests/unit/cqlengine/test_management.py b/tests/unit/cqlengine/test_management.py new file mode 100644 index 0000000000..660117f437 --- /dev/null +++ b/tests/unit/cqlengine/test_management.py @@ -0,0 +1,204 @@ +# Copyright 2025 ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Unit tests for cassandra.cqlengine.management module. +""" + +import unittest +from unittest.mock import patch, MagicMock, PropertyMock + +from cassandra import DriverException +from cassandra.cqlengine import CQLEngineException +from cassandra.cqlengine.management import _get_table_metadata, _sync_table + + +class MockTableMeta: + """Minimal stand-in for TableMetadata.""" + + def __init__(self): + self.columns = {} + self.options = {} + self.partition_key = [] + self.clustering_key = [] + + +class TestGetTableMetadataRetry(unittest.TestCase): + """Tests for _get_table_metadata retry on KeyError.""" + + def _make_model(self, ks="test_ks", table="test_table"): + model = MagicMock() + model._get_keyspace.return_value = ks + model._raw_column_family_name.return_value = table + return model + + @patch("cassandra.cqlengine.management.get_cluster") + def test_returns_table_when_present(self, mock_get_cluster): + """Table metadata is found on first lookup -- no refresh needed.""" + table_meta = MockTableMeta() + cluster = MagicMock() + cluster.metadata.keyspaces = { + "test_ks": MagicMock(tables={"test_table": table_meta}) + } + mock_get_cluster.return_value = cluster + model = self._make_model() + + result = _get_table_metadata(model) + self.assertIs(result, table_meta) + cluster.refresh_table_metadata.assert_not_called() + + @patch("cassandra.cqlengine.management.get_cluster") + def test_retries_after_refresh_on_missing_table(self, mock_get_cluster): + """Table missing initially, but available after refresh.""" + table_meta = MockTableMeta() + cluster = MagicMock() + + # First lookup: table not in tables dict. After refresh: table is there. + tables_first = {} + tables_after = {"test_table": table_meta} + ks_meta = MagicMock() + type(ks_meta).tables = PropertyMock(side_effect=[tables_first, tables_after]) + cluster.metadata.keyspaces = {"test_ks": ks_meta} + mock_get_cluster.return_value = cluster + + model = self._make_model() + result = _get_table_metadata(model) + + self.assertIs(result, table_meta) + cluster.refresh_table_metadata.assert_called_once_with("test_ks", "test_table") + + @patch("cassandra.cqlengine.management.get_cluster") + def test_raises_after_failed_refresh(self, mock_get_cluster): + """Table missing even after refresh -- raises CQLEngineException.""" + cluster = MagicMock() + ks_meta = MagicMock() + type(ks_meta).tables = PropertyMock(return_value={}) + cluster.metadata.keyspaces = {"test_ks": ks_meta} + mock_get_cluster.return_value = cluster + + model = self._make_model() + + with self.assertRaises(CQLEngineException) as ctx: + _get_table_metadata(model) + + self.assertIn("not available after refresh", str(ctx.exception)) + cluster.refresh_table_metadata.assert_called_once_with("test_ks", "test_table") + + @patch("cassandra.cqlengine.management.get_cluster") + def test_raises_cqlengineexception_when_refresh_raises_driver_exception( + self, mock_get_cluster + ): + """Table missing initially and refresh_table_metadata() itself raises + a DriverException -- a contextual CQLEngineException is raised + instead of letting the driver error escape uncaught.""" + cluster = MagicMock() + ks_meta = MagicMock() + type(ks_meta).tables = PropertyMock(return_value={}) + cluster.metadata.keyspaces = {"test_ks": ks_meta} + cluster.refresh_table_metadata.side_effect = DriverException("refresh failed") + mock_get_cluster.return_value = cluster + + model = self._make_model() + + with self.assertRaises(CQLEngineException) as ctx: + _get_table_metadata(model) + + self.assertIsInstance(ctx.exception.__cause__, DriverException) + cluster.refresh_table_metadata.assert_called_once_with("test_ks", "test_table") + + +class TestSyncTableMetadataLookup(unittest.TestCase): + """Tests that _sync_table delegates metadata lookup to _get_table_metadata.""" + + def _make_model(self, ks="test_ks", table="test_table"): + """Create a mock model that passes _sync_table's precondition checks.""" + model = MagicMock() + model.__abstract__ = False + model.column_family_name.return_value = '"test_ks"."test_table"' + model._raw_column_family_name.return_value = table + model._get_keyspace.return_value = ks + model._get_connection.return_value = None + model._columns = {} + return model + + @patch("cassandra.cqlengine.management._get_table_metadata") + @patch( + "cassandra.cqlengine.management._get_create_table", + return_value="CREATE TABLE test", + ) + @patch("cassandra.cqlengine.management.execute") + @patch("cassandra.cqlengine.management.get_cluster") + @patch( + "cassandra.cqlengine.management._allow_schema_modification", return_value=True + ) + @patch("cassandra.cqlengine.management.issubclass", return_value=True) + def test_calls_get_table_metadata_after_create( + self, + mock_issubclass, + mock_allow, + mock_get_cluster, + mock_execute, + mock_create, + mock_get_meta, + ): + """After creating a new table, _sync_table calls _get_table_metadata.""" + table_meta = MockTableMeta() + mock_get_meta.return_value = table_meta + + cluster = MagicMock() + ks_meta = MagicMock() + ks_meta.tables = {} # table not in tables -> triggers CREATE TABLE + cluster.metadata.keyspaces = {"test_ks": ks_meta} + mock_get_cluster.return_value = cluster + + model = self._make_model() + _sync_table(model) + + mock_get_meta.assert_called_once_with(model, None) + + @patch("cassandra.cqlengine.management._get_table_metadata") + @patch( + "cassandra.cqlengine.management._get_create_table", + return_value="CREATE TABLE test", + ) + @patch("cassandra.cqlengine.management.execute") + @patch("cassandra.cqlengine.management.get_cluster") + @patch( + "cassandra.cqlengine.management._allow_schema_modification", return_value=True + ) + @patch("cassandra.cqlengine.management.issubclass", return_value=True) + def test_propagates_exception_from_get_table_metadata( + self, + mock_issubclass, + mock_allow, + mock_get_cluster, + mock_execute, + mock_create, + mock_get_meta, + ): + """CQLEngineException from _get_table_metadata propagates out of _sync_table.""" + mock_get_meta.side_effect = CQLEngineException("Table metadata not available") + + cluster = MagicMock() + ks_meta = MagicMock() + ks_meta.tables = {} + cluster.metadata.keyspaces = {"test_ks": ks_meta} + mock_get_cluster.return_value = cluster + + model = self._make_model() + + with self.assertRaises(CQLEngineException) as ctx: + _sync_table(model) + + self.assertIn("not available", str(ctx.exception)) diff --git a/tests/unit/io/test_asyncorereactor.py b/tests/unit/io/test_asyncorereactor.py index d614a856d1..c8f979bdb9 100644 --- a/tests/unit/io/test_asyncorereactor.py +++ b/tests/unit/io/test_asyncorereactor.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -import platform import unittest from unittest.mock import patch diff --git a/tests/unit/io/test_libevreactor.py b/tests/unit/io/test_libevreactor.py index cf7e7caf77..a228a71de8 100644 --- a/tests/unit/io/test_libevreactor.py +++ b/tests/unit/io/test_libevreactor.py @@ -69,24 +69,33 @@ def test_watchers_are_finished(self): @test_category connection """ from cassandra.io.libevreactor import _global_loop - with patch.object(_global_loop, "_thread"),\ - patch.object(_global_loop, "notify"): - - self.make_connection() - - # We have to make a copy because the connections shouldn't - # be alive when we verify them - live_connections = set(_global_loop._live_conns) - - # This simulates the process ending without cluster.shutdown() - # being called, then with atexit _cleanup for libevreactor would - # be called - libev__cleanup(_global_loop) - for conn in live_connections: - assert conn._write_watcher.stop.mock_calls - assert conn._read_watcher.stop.mock_calls - - _global_loop._shutdown = False + reactor_needs_restore = False + try: + with patch.object(_global_loop, "_thread"),\ + patch.object(_global_loop, "notify"): + + self.make_connection() + + # We have to make a copy because the connections shouldn't + # be alive when we verify them + live_connections = set(_global_loop._live_conns) + + # This simulates the process ending without cluster.shutdown() + # being called, then with atexit _cleanup for libevreactor would + # be called + reactor_needs_restore = True + libev__cleanup(_global_loop) + for conn in live_connections: + assert conn._write_watcher.stop.mock_calls + assert conn._read_watcher.stop.mock_calls + + finally: + if reactor_needs_restore: + _global_loop._shutdown = False + # _cleanup stopped the prepare watcher; restart it so the shared + # singleton loop is left in a working state for subsequent tests + # (otherwise timers would never be scheduled and tests would hang). + _global_loop._preparer.start() class LibevTimerPatcher(unittest.TestCase): diff --git a/tests/unit/io/test_libevreactor_shutdown.py b/tests/unit/io/test_libevreactor_shutdown.py new file mode 100644 index 0000000000..e2f76f8a3e --- /dev/null +++ b/tests/unit/io/test_libevreactor_shutdown.py @@ -0,0 +1,248 @@ +# Copyright ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Test to demonstrate the libevwrapper atexit cleanup issue. + +This test demonstrates the problem where the atexit callback is registered +with _global_loop=None at import time, causing it to receive None during +shutdown instead of the actual loop instance. +""" + +import unittest +import sys +import subprocess +import tempfile +import os +from pathlib import Path + +from cassandra import DependencyException + +try: + from cassandra.io.libevreactor import LibevConnection +except (ImportError, DependencyException): + LibevConnection = None + +from tests import is_monkey_patched + + +class LibevAtexitCleanupTest(unittest.TestCase): + """ + Test case to demonstrate the atexit cleanup bug in libevreactor. + + The bug: atexit.register(partial(_cleanup, _global_loop)) is called when + _global_loop is None, so the cleanup function receives None at shutdown + instead of the actual LibevLoop instance that was created later. + """ + + def setUp(self): + if is_monkey_patched(): + raise unittest.SkipTest("Can't test libev with monkey patching") + if LibevConnection is None: + raise unittest.SkipTest('libev does not appear to be installed correctly') + + def test_atexit_callback_uses_current_global_loop(self): + """ + Test that verifies the atexit callback fix. + + The fix uses a wrapper function _atexit_cleanup() that looks up the + current value of _global_loop at shutdown time, instead of capturing + it at import time with partial(). + + @since 3.29 + @jira_ticket PYTHON-XXX + @expected_result The atexit handler calls cleanup with the actual loop + + @test_category connection + """ + from cassandra.io import libevreactor + + # Verify the fix: _atexit_cleanup should exist as a module-level function + self.assertTrue(hasattr(libevreactor, '_atexit_cleanup'), + "Module should have _atexit_cleanup function") + + # Verify it's not a partial (the old buggy implementation) + from functools import partial + self.assertNotIsInstance(libevreactor._atexit_cleanup, partial, + "The _atexit_cleanup should NOT be a partial function") + + # Verify it's actually a function + self.assertTrue(callable(libevreactor._atexit_cleanup), + "_atexit_cleanup should be callable") + + # Initialize the reactor + LibevConnection.initialize_reactor() + + # At this point, libevreactor._global_loop is not None + self.assertIsNotNone(libevreactor._global_loop, + "Global loop should be initialized") + + # The fix: _atexit_cleanup is a function that will look up + # _global_loop when it's called, not a partial with captured args + self.assertEqual(libevreactor._atexit_cleanup.__name__, '_atexit_cleanup', + "The function should have the correct name") + + def test_shutdown_cleanup_works_with_fix(self): + """ + Test that verifies the atexit cleanup fix works in a subprocess. + + This test creates a minimal script that: + 1. Imports the driver + 2. Initializes the reactor (creates the global loop) + 3. Verifies the _atexit_cleanup function is available + 4. Exits without explicit cleanup + + With the fix, atexit should properly clean up the loop using the + wrapper function that looks up _global_loop at shutdown time. + + @since 3.29 + @jira_ticket PYTHON-XXX + @expected_result The subprocess shows the fix is working + + @test_category connection + """ + # Create a test script that verifies the fix + test_script = ''' +import sys +import os + +# Add the driver path as a fallback only. Append (not insert at 0) so that an +# installed build of the driver (e.g. the compiled wheel under cibuildwheel) +# takes precedence over the in-tree pure-Python source, which lacks the libev +# C extension and would make the import fail. +sys.path.append({driver_path!r}) + +# Import and setup +from cassandra.io import libevreactor +from cassandra.io.libevreactor import LibevConnection +import atexit + +# Initialize the reactor (creates the global loop) +LibevConnection.initialize_reactor() + +print("Global loop initialized:", libevreactor._global_loop is not None) + +# Verify the fix is in place: _atexit_cleanup should be a module-level function +if hasattr(libevreactor, '_atexit_cleanup'): + print("FIXED: Module has _atexit_cleanup function") + print("This function will look up _global_loop at shutdown time") + # Verify it's not using partial with None + import inspect + source = inspect.getsource(libevreactor._atexit_cleanup) + if "global _global_loop" in source and "_global_loop is not None" in source: + print("Verified: _atexit_cleanup uses current _global_loop value") +else: + print("BUG: No _atexit_cleanup function found") + +# Exit without explicit cleanup - atexit should handle it properly with the fix! +print("Exiting with proper cleanup...") +''' + + driver_path = str(Path(__file__).parent.parent.parent.parent) + script_content = test_script.format(driver_path=driver_path) + + with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f: + f.write(script_content) + script_path = f.name + + try: + result = subprocess.run( + [sys.executable, script_path], + capture_output=True, + text=True, + timeout=5 + ) + + output = result.stdout + error_output = result.stderr + print("\n=== Subprocess Output ===") + print(output) + print("=== End Output ===\n") + print("\n=== Subprocess Error Output ===") + print(error_output) + print("=== End Error Output ===\n") + + self.assertEqual( + result.returncode, 0, + "Subprocess failed\nstdout:\n{}\nstderr:\n{}".format(output, error_output) + ) + + # Verify the output shows the fix is working + self.assertIn("Global loop initialized: True", output) + self.assertIn("FIXED: Module has _atexit_cleanup function", output) + self.assertIn("Verified: _atexit_cleanup uses current _global_loop value", output) + self.assertNotIn("BUG", output.replace("BUG STILL PRESENT", "").replace("DEBUG", "")) # Allow "BUG" only in success message + + finally: + os.unlink(script_path) + + +class LibevShutdownRaceConditionTest(unittest.TestCase): + """ + Tests to analyze potential race conditions and crashes during shutdown. + """ + + def setUp(self): + if is_monkey_patched(): + raise unittest.SkipTest("Can't test libev with monkey patching") + if LibevConnection is None: + raise unittest.SkipTest('libev does not appear to be installed correctly') + + def test_cleanup_with_fix_properly_shuts_down(self): + """ + Test to verify the fix properly shuts down the event loop. + + With the fix in place, the atexit cleanup will: + 1. Look up the current _global_loop value (not None) + 2. Call _cleanup with the actual loop instance + 3. Properly shut down the loop and its watchers + + This prevents the crash scenario where: + - Various modules are being torn down during Python shutdown + - The libev event loop is still running + - Callbacks fire and try to access deallocated Python objects + + @since 3.29 + @jira_ticket PYTHON-XXX + @expected_result Cleanup properly shuts down the loop with the fix + + @test_category connection + """ + from cassandra.io import libevreactor + from cassandra.io.libevreactor import _cleanup, _atexit_cleanup + + LibevConnection.initialize_reactor() + + # Verify the loop exists + self.assertIsNotNone(libevreactor._global_loop) + + # Before cleanup, the loop should not be shut down + self.assertFalse(libevreactor._global_loop._shutdown, + "Loop should not be shut down initially") + + # Simulate what the OLD buggy code would do + _cleanup(None) # This does nothing + self.assertFalse(libevreactor._global_loop._shutdown, + "Loop should NOT be shut down when cleanup receives None") + + # Now test the FIX: call the wrapper that looks up _global_loop + _atexit_cleanup() # This is what atexit will actually call + + # With the fix, the loop should be properly shut down + self.assertTrue(libevreactor._global_loop._shutdown, + "Loop should be shut down when _atexit_cleanup is called") + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/unit/io/test_twistedreactor.py b/tests/unit/io/test_twistedreactor.py index 54abe884ae..23d9148e97 100644 --- a/tests/unit/io/test_twistedreactor.py +++ b/tests/unit/io/test_twistedreactor.py @@ -19,7 +19,6 @@ try: from twisted.test import proto_helpers - from twisted.python.failure import Failure from cassandra.io import twistedreactor from cassandra.io.twistedreactor import TwistedConnection except ImportError: @@ -99,21 +98,40 @@ def setUp(self): self.reactor_cft_patcher = patch( 'twisted.internet.reactor.callFromThread') self.reactor_run_patcher = patch('twisted.internet.reactor.run') + self.thread_patcher = patch('cassandra.io.twistedreactor.Thread') + # Patch reactor.running to False so maybe_start() always enters + # the branch that spawns the reactor thread. Without this, leaked + # reactor state from prior tests can cause reactor.running to be + # True, making maybe_start() a no-op and the reactor.run mock + # never called — leading to a flaky test_connection_initialization. + self.reactor_running_patcher = patch( + 'twisted.internet.reactor.running', new=False) self.mock_reactor_cft = self.reactor_cft_patcher.start() self.mock_reactor_run = self.reactor_run_patcher.start() + self.mock_thread_class = self.thread_patcher.start() + self.mock_thread = self.mock_thread_class.return_value + self.mock_thread.is_alive.return_value = False + self.reactor_running_patcher.start() self.obj_ut = twistedreactor.TwistedConnection(DefaultEndPoint('1.2.3.4'), cql_version='3.0.1') def tearDown(self): self.reactor_cft_patcher.stop() self.reactor_run_patcher.stop() + self.thread_patcher.stop() + self.reactor_running_patcher.stop() def test_connection_initialization(self): """ Verify that __init__() works correctly. """ self.mock_reactor_cft.assert_called_with(self.obj_ut.add_connection) - self.mock_reactor_run.assert_called_with(installSignalHandlers=False) + self.mock_thread_class.assert_called_once_with( + target=self.mock_reactor_run, + name="cassandra_driver_twisted_event_loop", + kwargs={'installSignalHandlers': False}) + self.assertIs(self.mock_thread.daemon, True) + self.mock_thread.start.assert_called_once_with() def test_client_connection_made(self): """ diff --git a/tests/unit/io/utils.py b/tests/unit/io/utils.py index f43224058c..b821ee1897 100644 --- a/tests/unit/io/utils.py +++ b/tests/unit/io/utils.py @@ -120,7 +120,7 @@ def submit_and_wait_for_completion(unit_test, create_timer, start, end, incremen pending_callbacks.append(callback) # wait for all the callbacks associated with the timers to be invoked - while len(pending_callbacks) is not 0: + while len(pending_callbacks) != 0: for callback in pending_callbacks: if callback.was_invoked(): pending_callbacks.remove(callback) diff --git a/tests/unit/test_client_routes.py b/tests/unit/test_client_routes.py new file mode 100644 index 0000000000..0aa82fc76a --- /dev/null +++ b/tests/unit/test_client_routes.py @@ -0,0 +1,482 @@ +# Copyright 2026 ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import socket +import ssl +import unittest +import uuid +from unittest.mock import Mock, patch + +from cassandra.client_routes import ( + ClientRouteProxy, + ClientRoutesChangeType, + ClientRoutesConfig, + _RouteStore, + _Route, + _ClientRoutesHandler +) +from cassandra.connection import ClientRoutesEndPoint, ClientRoutesEndPointFactory +from cassandra.cluster import Cluster + + +class TestClientRouteProxy(unittest.TestCase): + + def test_endpoint_none_connection_id(self): + with self.assertRaises(ValueError): + ClientRouteProxy(None) + + +class TestClientRoutesConfig(unittest.TestCase): + + def test_config_with_proxies(self): + ep1 = ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1") + ep2 = ClientRouteProxy(str(uuid.uuid4()), "10.0.0.2") + config = ClientRoutesConfig([ep1, ep2]) + self.assertEqual(len(config.proxies), 2) + + def test_config_empty_proxies(self): + with self.assertRaises(ValueError): + ClientRoutesConfig([]) + + def test_config_invalid_proxy_type(self): + with self.assertRaises(TypeError): + ClientRoutesConfig(["not-a-proxy"]) + + + +class TestRouteStore(unittest.TestCase): + + def test_get_by_host_id(self): + routes = _RouteStore() + host_id = uuid.uuid4() + route = _Route( + connection_id=str(uuid.uuid4()), + host_id=host_id, + address="example.com", + port=9042, + ) + + routes.update([route]) + + retrieved = routes.get_by_host_id(host_id) + self.assertEqual(retrieved.host_id, host_id) + self.assertEqual(retrieved.address, "example.com") + + def test_merge_routes(self): + routes = _RouteStore() + host_id1 = uuid.uuid4() + host_id2 = uuid.uuid4() + + route1 = _Route( + connection_id=str(uuid.uuid4()), host_id=host_id1, + address="host1.com", port=9042, + ) + + route2 = _Route( + connection_id=str(uuid.uuid4()), host_id=host_id2, + address="host2.com", port=9042, + ) + + routes.update([route1]) + routes.merge([route2], affected_host_ids={host_id2}) + + self.assertIsNotNone(routes.get_by_host_id(host_id1)) + self.assertIsNotNone(routes.get_by_host_id(host_id2)) + + def test_merge_deletes_affected_host_with_no_new_route(self): + """When an affected host_id has no corresponding new route, it should be removed.""" + store = _RouteStore() + host_id1 = uuid.uuid4() + host_id2 = uuid.uuid4() + conn_id = str(uuid.uuid4()) + + store.update([ + _Route(connection_id=conn_id, host_id=host_id1, address="a.com", port=9042), + _Route(connection_id=conn_id, host_id=host_id2, address="b.com", port=9042), + ]) + self.assertIsNotNone(store.get_by_host_id(host_id1)) + self.assertIsNotNone(store.get_by_host_id(host_id2)) + + # Merge with host_id2 affected but no new route for it → deletion + store.merge([], affected_host_ids={host_id2}) + + self.assertIsNotNone(store.get_by_host_id(host_id1)) + self.assertIsNone(store.get_by_host_id(host_id2)) + + def test_select_preferred_routes_keeps_existing_connection_id(self): + """When multiple connection_ids provide routes for the same host_id, + the one already in use should be preferred.""" + store = _RouteStore() + host_id = uuid.uuid4() + conn_a = "conn-a" + conn_b = "conn-b" + + # Populate store with conn_a for host_id + store.update([_Route(connection_id=conn_a, host_id=host_id, address="a.com", port=9042)]) + self.assertEqual(store.get_by_host_id(host_id).connection_id, conn_a) + + # Update with both conn_a and conn_b for the same host_id + store.update([ + _Route(connection_id=conn_b, host_id=host_id, address="b.com", port=9042), + _Route(connection_id=conn_a, host_id=host_id, address="a-new.com", port=9042), + ]) + # conn_a should be preferred since it was already in use + result = store.get_by_host_id(host_id) + self.assertEqual(result.connection_id, conn_a) + self.assertEqual(result.address, "a-new.com") + + def test_select_preferred_routes_falls_back_when_existing_gone(self): + """When the existing connection_id is no longer among candidates, + the first candidate should be selected.""" + store = _RouteStore() + host_id = uuid.uuid4() + + store.update([_Route(connection_id="old-conn", host_id=host_id, address="old.com", port=9042)]) + + # Update only has new connection_ids + store.update([ + _Route(connection_id="new-a", host_id=host_id, address="a.com", port=9042), + _Route(connection_id="new-b", host_id=host_id, address="b.com", port=9042), + ]) + result = store.get_by_host_id(host_id) + self.assertEqual(result.connection_id, "new-a") + + +class TestClientRoutesHandler(unittest.TestCase): + + def setUp(self): + self.conn_id = uuid.uuid4() + self.proxy = ClientRouteProxy(str(self.conn_id), "10.0.0.1") + self.config = ClientRoutesConfig([self.proxy]) + + def test_handler_initialization(self): + handler = _ClientRoutesHandler(self.config, ssl_enabled=False) + self.assertIsNotNone(handler) + self.assertEqual(handler.ssl_enabled, False) + + @patch.object(_ClientRoutesHandler, '_query_all_routes_for_connections') + def test_initialize(self, mock_query): + host_id = uuid.uuid4() + mock_query.return_value = [ + _Route( + connection_id=self.conn_id, + host_id=host_id, + address="node1.example.com", + port=9042, + ) + ] + + handler = _ClientRoutesHandler(self.config) + mock_conn = Mock() + + handler.initialize(mock_conn, timeout=5.0) + + mock_query.assert_called_once() + route = handler._routes.get_by_host_id(host_id) + self.assertIsNotNone(route) + self.assertEqual(route.address, "node1.example.com") + + @patch.object(_ClientRoutesHandler, '_query_routes_for_change_event') + def test_handle_change_filters_by_configured_connection_ids(self, mock_query): + """Events with unrelated connection_ids should be ignored.""" + handler = _ClientRoutesHandler(self.config) + mock_conn = Mock() + host_id = str(uuid.uuid4()) + + # Event with a connection_id NOT in our config → should return early + handler.handle_client_routes_change( + mock_conn, 5.0, + ClientRoutesChangeType.UPDATE_NODES, + connection_ids=["unrelated-conn-id"], + host_ids=[host_id], + ) + mock_query.assert_not_called() + + @patch.object(_ClientRoutesHandler, '_query_routes_for_change_event') + def test_handle_change_merges_when_host_ids_present(self, mock_query): + """When host_ids are provided, routes should be merged (not full replace).""" + handler = _ClientRoutesHandler(self.config) + mock_conn = Mock() + + existing_host = uuid.uuid4() + new_host = uuid.uuid4() + conn_id = str(self.conn_id) + + # Pre-populate a route + handler._routes.update([ + _Route(connection_id=conn_id, host_id=existing_host, address="old.com", port=9042), + ]) + + mock_query.return_value = [ + _Route(connection_id=conn_id, host_id=new_host, address="new.com", port=9042), + ] + + handler.handle_client_routes_change( + mock_conn, 5.0, + ClientRoutesChangeType.UPDATE_NODES, + connection_ids=[conn_id], + host_ids=[str(new_host)], + ) + + # Existing route should still be there (merge, not replace) + self.assertIsNotNone(handler._routes.get_by_host_id(existing_host)) + self.assertIsNotNone(handler._routes.get_by_host_id(new_host)) + + @patch.object(_ClientRoutesHandler, '_query_all_routes_for_connections') + def test_handle_change_updates_when_no_host_ids(self, mock_query): + """When no host_ids are provided, routes should be fully replaced.""" + handler = _ClientRoutesHandler(self.config) + mock_conn = Mock() + conn_id = str(self.conn_id) + + old_host = uuid.uuid4() + handler._routes.update([ + _Route(connection_id=conn_id, host_id=old_host, address="old.com", port=9042), + ]) + + new_host = uuid.uuid4() + mock_query.return_value = [ + _Route(connection_id=conn_id, host_id=new_host, address="new.com", port=9042), + ] + + handler.handle_client_routes_change( + mock_conn, 5.0, + ClientRoutesChangeType.UPDATE_NODES, + connection_ids=None, + host_ids=None, + ) + + # Full replace: old_host gone, new_host present + self.assertIsNone(handler._routes.get_by_host_id(old_host)) + self.assertIsNotNone(handler._routes.get_by_host_id(new_host)) + + @patch.object(_ClientRoutesHandler, '_query_routes_for_change_event') + def test_handle_change_propagates_query_failure(self, mock_query): + """If _query_routes raises, handle_client_routes_change should propagate.""" + handler = _ClientRoutesHandler(self.config) + mock_conn = Mock() + mock_query.side_effect = Exception("network error") + + conn_id = self.proxy.connection_id + host_id = str(uuid.uuid4()) + with self.assertRaises(Exception) as cm: + handler.handle_client_routes_change( + mock_conn, 5.0, + ClientRoutesChangeType.UPDATE_NODES, + connection_ids=[conn_id], + host_ids=[host_id], + ) + self.assertIn("network error", str(cm.exception)) + + @patch.object(_ClientRoutesHandler, '_query_all_routes_for_connections') + def test_initialize_propagates_exception_on_failure(self, mock_query): + """initialize should propagate exceptions to caller.""" + handler = _ClientRoutesHandler(self.config) + mock_conn = Mock() + mock_query.side_effect = Exception("query failed") + + with self.assertRaises(Exception) as ctx: + handler.initialize(mock_conn, 5.0) + self.assertIn("query failed", str(ctx.exception)) + self.assertEqual(mock_query.call_count, 1) + + @patch.object(_ClientRoutesHandler, '_query_all_routes_for_connections') + def test_initialize_keeps_old_routes_on_failure(self, mock_query): + """On failure, existing routes must be preserved (critical for PL clusters).""" + handler = _ClientRoutesHandler(self.config) + mock_conn = Mock() + host_id = uuid.uuid4() + + # Pre-populate a route + handler._routes.update([ + _Route(connection_id=str(self.conn_id), host_id=host_id, address="old.com", port=9042), + ]) + + mock_query.side_effect = Exception("query failed") + with self.assertRaises(Exception): + handler.initialize(mock_conn, 5.0) + + # Old route must still be there + self.assertIsNotNone(handler._routes.get_by_host_id(host_id)) + + @patch.object(_ClientRoutesHandler, '_query_all_routes_for_connections') + def test_initialize_updates_routes_on_success(self, mock_query): + """initialize should update routes on success.""" + handler = _ClientRoutesHandler(self.config) + mock_conn = Mock() + host_id = uuid.uuid4() + + mock_query.return_value = [ + _Route(connection_id=str(self.conn_id), host_id=host_id, address="new.com", port=9042), + ] + + handler.initialize(mock_conn, 5.0) + + self.assertEqual(mock_query.call_count, 1) + route = handler._routes.get_by_host_id(host_id) + self.assertIsNotNone(route) + self.assertEqual(route.address, "new.com") + +class TestClientRoutesEndPoint(unittest.TestCase): + + def setUp(self): + self.conn_id = uuid.uuid4() + self.proxy = ClientRouteProxy(str(self.conn_id), "10.0.0.1") + self.config = ClientRoutesConfig([self.proxy]) + self.handler = _ClientRoutesHandler(self.config, ssl_enabled=False) + + def test_resolve_falls_back_when_no_mapping(self): + """resolve() should return original address/port when no route mapping exists.""" + host_id = uuid.uuid4() + ep = ClientRoutesEndPoint( + host_id=host_id, + handler=self.handler, + original_address="10.0.0.1", + original_port=9042, + ) + self.assertEqual(ep.resolve(), ("10.0.0.1", 9042)) + + @patch('cassandra.client_routes.socket.getaddrinfo', + return_value=[(socket.AF_INET, socket.SOCK_STREAM, 0, '', ("192.168.1.100", 9042))]) + def test_resolve_returns_address_when_route_exists(self, _mock_getaddrinfo): + """resolve() should return the DNS-resolved address and port when a route exists.""" + host_id = uuid.uuid4() + self.handler._routes.update([ + _Route(connection_id=str(self.conn_id), host_id=host_id, + address="nlb.example.com", port=9042), + ]) + ep = ClientRoutesEndPoint( + host_id=host_id, + handler=self.handler, + original_address="10.0.0.1", + original_port=9042, + ) + self.assertEqual(ep.resolve(), ("192.168.1.100", 9042)) + _mock_getaddrinfo.assert_called_once_with( + "nlb.example.com", 9042, socket.AF_UNSPEC, socket.SOCK_STREAM) + + @patch('cassandra.client_routes.socket.getaddrinfo', + side_effect=socket.gaierror("DNS resolution failed")) + def test_resolve_host_dns_failure_raises(self, _mock_getaddrinfo): + """resolve_host should propagate socket.gaierror on DNS failure.""" + host_id = uuid.uuid4() + self.handler._routes.update([ + _Route(connection_id=str(self.conn_id), host_id=host_id, + address="nonexistent.example.com", port=9042), + ]) + with self.assertRaises(socket.gaierror): + self.handler.resolve_host(host_id) + + def test_resolve_host_missing_port_raises(self): + """resolve_host should raise ValueError when route has no port.""" + host_id = uuid.uuid4() + self.handler._routes.update([ + _Route(connection_id=str(self.conn_id), host_id=host_id, + address="host.com", port=0), + ]) + with self.assertRaises(ValueError): + self.handler.resolve_host(host_id) + + +class TestClientRoutesEndPointFactory(unittest.TestCase): + + def setUp(self): + self.conn_id = uuid.uuid4() + proxy = ClientRouteProxy(str(self.conn_id), "10.0.0.1") + self.config = ClientRoutesConfig([proxy]) + self.handler = _ClientRoutesHandler(self.config, ssl_enabled=False) + self.factory = ClientRoutesEndPointFactory(self.handler, default_port=9042) + + def test_create_from_row(self): + """Factory should create a ClientRoutesEndPoint from a peers row.""" + host_id = uuid.uuid4() + row = { + "host_id": host_id, + "rpc_address": "10.0.0.5", + "native_transport_port": 9042, + "peer": "10.0.0.5", + } + ep = self.factory.create(row) + self.assertIsInstance(ep, ClientRoutesEndPoint) + self.assertEqual(ep.host_id, host_id) + self.assertEqual(ep.address, "10.0.0.5") + + def test_create_missing_host_id_raises(self): + """Factory should raise ValueError when row has no host_id.""" + row = {"rpc_address": "10.0.0.5", "native_transport_port": 9042} + with self.assertRaises(ValueError): + self.factory.create(row) + +class TestClientRoutesSSLValidation(unittest.TestCase): + + def test_check_hostname_with_ssl_context_raises(self): + """Cluster should reject check_hostname=True with client_routes_config.""" + ssl_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) + self.assertTrue(ssl_ctx.check_hostname) + + config = ClientRoutesConfig( + proxies=[ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")] + ) + with self.assertRaises(ValueError) as cm: + Cluster( + contact_points=["10.0.0.1"], + ssl_context=ssl_ctx, + client_routes_config=config, + ) + self.assertIn("check_hostname", str(cm.exception)) + + def test_check_hostname_with_ssl_options_raises(self): + """Cluster should reject check_hostname=True in ssl_options with client_routes_config.""" + config = ClientRoutesConfig( + proxies=[ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")] + ) + with self.assertRaises(ValueError) as cm: + Cluster( + contact_points=["10.0.0.1"], + ssl_options={'check_hostname': True}, + client_routes_config=config, + ) + self.assertIn("check_hostname", str(cm.exception)) + + def test_disabled_check_hostname_with_client_routes_ok(self): + """Cluster should allow check_hostname=False with client_routes_config.""" + ssl_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) + ssl_ctx.check_hostname = False + + config = ClientRoutesConfig( + proxies=[ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")] + ) + # Should not raise + cluster = Cluster( + contact_points=["10.0.0.1"], + ssl_context=ssl_ctx, + client_routes_config=config, + ) + cluster.shutdown() + + def test_no_ssl_with_client_routes_ok(self): + """Cluster should allow client_routes_config without SSL.""" + config = ClientRoutesConfig( + proxies=[ClientRouteProxy(str(uuid.uuid4()), "10.0.0.1")] + ) + # Should not raise + cluster = Cluster( + contact_points=["10.0.0.1"], + client_routes_config=config, + ) + cluster.shutdown() + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/unit/test_cluster.py b/tests/unit/test_cluster.py index 49208ac53e..3d55bc1860 100644 --- a/tests/unit/test_cluster.py +++ b/tests/unit/test_cluster.py @@ -13,16 +13,19 @@ # limitations under the License. import unittest +from concurrent.futures import Future import logging import socket +from types import SimpleNamespace from unittest.mock import patch, Mock import uuid from cassandra import ConsistencyLevel, DriverException, Timeout, Unavailable, RequestExecutionException, ReadTimeout, WriteTimeout, CoordinationFailure, ReadFailure, WriteFailure, FunctionFailure, AlreadyExists,\ InvalidRequest, Unauthorized, AuthenticationFailed, OperationTimedOut, UnsupportedOperation, RequestValidationException, ConfigurationException, ProtocolVersion -from cassandra.cluster import _Scheduler, Session, Cluster, default_lbp_factory, \ +from cassandra.cluster import _Scheduler, Session, Cluster, ResultSet, SchemaAgreementScope, ControlConnectionQueryFallback, default_lbp_factory, \ ExecutionProfile, _ConfigMode, EXEC_PROFILE_DEFAULT +from cassandra.connection import ConnectionBusy, ConnectionException from cassandra.pool import Host from cassandra.policies import HostDistance, RetryPolicy, RoundRobinPolicy, DowngradingConsistencyRetryPolicy, SimpleConvictionPolicy from cassandra.query import SimpleStatement, named_tuple_factory, tuple_factory @@ -87,11 +90,72 @@ def test_exception_types(self): assert issubclass(UnsupportedOperation, DriverException) +class OperationTimedOutTest(unittest.TestCase): + + def test_message_without_timeout(self): + """Default message format when no timeout info is provided.""" + exc = OperationTimedOut(errors={'host1': 'some error'}, last_host='host1') + msg = str(exc) + assert "errors={'host1': 'some error'}" in msg + assert "last_host=host1" in msg + assert "timeout=" not in msg + assert "in_flight=" not in msg + + def test_message_with_timeout_and_in_flight(self): + """Message includes timeout and in_flight when both are provided.""" + exc = OperationTimedOut(errors={'host1': 'err'}, last_host='host1', + timeout=10.0, in_flight=42) + msg = str(exc) + assert "(timeout=10.0s, in_flight=42)" in msg + + def test_message_with_timeout_no_in_flight(self): + """Message includes timeout but not in_flight when only timeout is set.""" + exc = OperationTimedOut(timeout=5.0) + msg = str(exc) + assert "(timeout=5.0s)" in msg + assert "in_flight=" not in msg + + def test_message_no_args(self): + """No-argument form should not crash and should have clean message.""" + exc = OperationTimedOut() + msg = str(exc) + assert "errors=None, last_host=None" in msg + assert "timeout=" not in msg + + def test_attributes_accessible(self): + """New and existing attributes should be readable.""" + exc = OperationTimedOut(errors={'h': 'e'}, last_host='h', + timeout=10.0, in_flight=42) + assert exc.errors == {'h': 'e'} + assert exc.last_host == 'h' + assert exc.timeout == 10.0 + assert exc.in_flight == 42 + + def test_attributes_default_none(self): + """New attributes should default to None when not provided.""" + exc = OperationTimedOut() + assert exc.timeout is None + assert exc.in_flight is None + assert exc.errors is None + assert exc.last_host is None + + def test_backward_compat_positional(self): + """Existing two-positional-arg form should still work.""" + exc = OperationTimedOut({'h': 'err'}, 'host1') + assert exc.errors == {'h': 'err'} + assert exc.last_host == 'host1' + assert exc.timeout is None + assert exc.in_flight is None + + class ClusterTest(unittest.TestCase): def test_tuple_for_contact_points(self): cluster = Cluster(contact_points=[('localhost', 9045), ('127.0.0.2', 9046), '127.0.0.3'], port=9999) - localhost_addr = set([addr[0] for addr in [t for (_,_,_,_,t) in socket.getaddrinfo("localhost",80)]]) + # Refactored for clarity + addr_info = socket.getaddrinfo("localhost", 80) + sockaddr_tuples = [info[4] for info in addr_info] # info[4] is sockaddr + localhost_addr = set([sockaddr[0] for sockaddr in sockaddr_tuples]) for cp in cluster.endpoints_resolved: if cp.address in localhost_addr: assert cp.port == 9045 @@ -108,7 +172,7 @@ def test_invalid_contact_point_types(self): Cluster(contact_points="not a sequence", protocol_version=4, connect_timeout=1) def test_port_str(self): - """Check port passed as tring is converted and checked properly""" + """Check port passed as string is converted and checked properly""" cluster = Cluster(contact_points=['127.0.0.1'], port='1111') for cp in cluster.endpoints_resolved: if cp.address in ('::1', '127.0.0.1'): @@ -123,6 +187,52 @@ def test_port_range(self): with pytest.raises(ValueError): cluster = Cluster(contact_points=['127.0.0.1'], port=invalid_port) + def test_control_connection_query_fallback_modes(self): + assert Cluster().allow_control_connection_query_fallback is ControlConnectionQueryFallback.Disabled + with pytest.raises(TypeError): + Cluster(allow_control_connection_query_fallback=False) + with pytest.raises(TypeError): + Cluster(allow_control_connection_query_fallback=True) + assert ( + Cluster(allow_control_connection_query_fallback=ControlConnectionQueryFallback.Fallback) + .allow_control_connection_query_fallback + is ControlConnectionQueryFallback.Fallback + ) + assert Cluster( + allow_control_connection_query_fallback=ControlConnectionQueryFallback.SkipPoolCreation + ).allow_control_connection_query_fallback is ControlConnectionQueryFallback.SkipPoolCreation + + def test_control_connection_query_fallback_no_node_pool_mode_skips_pool_creation(self): + cluster = Cluster( + allow_control_connection_query_fallback=ControlConnectionQueryFallback.SkipPoolCreation, + monitor_reporting_enabled=False, + ) + host = Host("127.0.0.1", SimpleConvictionPolicy, host_id=uuid.uuid4()) + + with patch.object(Session, "add_or_renew_pool") as mocked_add_or_renew_pool: + session = Session(cluster, [host]) + + mocked_add_or_renew_pool.assert_not_called() + assert session._initial_connect_futures == set() + assert session._pools == {} + assert session.update_created_pools() == set() + + def test_control_connection_query_fallback_fallback_tolerates_empty_initial_pools(self): + cluster = Cluster( + allow_control_connection_query_fallback=ControlConnectionQueryFallback.Fallback, + monitor_reporting_enabled=False, + ) + host = Host("127.0.0.1", SimpleConvictionPolicy, host_id=uuid.uuid4()) + future = Future() + future.set_result(False) + + with patch.object(Session, "add_or_renew_pool", return_value=future) as mocked_add_or_renew_pool: + session = Session(cluster, [host]) + + mocked_add_or_renew_pool.assert_called_once_with(host, is_host_addition=False) + assert session._initial_connect_futures == {future} + assert session._pools == {} + def test_compression_autodisabled_without_libraries(self): with patch.dict('cassandra.cluster.locally_supported_compressions', {}, clear=True): with patch('cassandra.cluster.log') as patched_logger: @@ -182,15 +292,127 @@ def test_event_delay_timing(self, *_): """ sched = _Scheduler(None) sched.schedule(0, lambda: None) - sched.schedule(0, lambda: None) # pre-473: "TypeError: unorderable types: function() < function()"t + sched.schedule(0, lambda: None) # pre-473: "TypeError: unorderable types: function() < function()" class SessionTest(unittest.TestCase): + class FakeTime(object): + + def __init__(self): + self.clock = 0 + + def time(self): + return self.clock + + def sleep(self, amount): + self.clock += amount + + class MockPool(object): + + def __init__(self, host, connection): + self.host = host + self.host_distance = HostDistance.LOCAL + self.is_shutdown = False + self.connection = connection + + def _get_connection_for_routing_key(self): + return self.connection + + class MockSchemaVersionFuture(object): + + def __init__(self, outcome, auto_complete=True): + self._outcome = outcome + self._auto_complete = auto_complete + self._delivered = False + self._callback_state = None + self._col_names = ("schema_version",) + self._col_types = None + self.has_more_pages = False + self._continuous_paging_session = None + + def _deliver(self): + if self._delivered or self._callback_state is None: + return + + self._delivered = True + callback, errback, callback_args, callback_kwargs, errback_args, errback_kwargs = self._callback_state + if isinstance(self._outcome, Exception): + errback(self._outcome, *errback_args, **errback_kwargs) + else: + row = SimpleNamespace(schema_version=self._outcome) + callback([row], *callback_args, **callback_kwargs) + + def add_callbacks(self, callback, errback, + callback_args=(), callback_kwargs=None, + errback_args=(), errback_kwargs=None): + self._callback_state = ( + callback, + errback, + callback_args, + callback_kwargs or {}, + errback_args, + errback_kwargs or {}, + ) + if self._auto_complete: + self._deliver() + return self + + def complete(self): + self._deliver() + + def result(self): + if isinstance(self._outcome, Exception): + raise self._outcome + return ResultSet(self, [SimpleNamespace(schema_version=self._outcome)]) + def setUp(self): if connection_class is None: raise unittest.SkipTest('libev does not appear to be installed correctly') connection_class.initialize_reactor() + def _mock_schema_future(self, outcome): + return self.MockSchemaVersionFuture(outcome) + + def _host_query_count(self, session, target_host): + return sum(1 for call in session.execute_async.call_args_list if call.kwargs.get('host') is target_host) + + def _new_schema_agreement_session(self, schema_versions, distances=None): + hosts = [] + connections = {} + distance_map = {} + if distances is None: + distances = [HostDistance.LOCAL] * len(schema_versions) + + for index, schema_version in enumerate(schema_versions): + host = Host("127.0.0.%d" % (index + 1), SimpleConvictionPolicy, host_id=uuid.uuid4()) + host.set_up() + hosts.append(host) + distance_map[host] = distances[index] + + cluster = Cluster(protocol_version=4) + for host in hosts: + cluster.metadata.add_or_return_host(host) + + session = Session(cluster, hosts) + session._profile_manager.distance = Mock(side_effect=lambda host: distance_map.get(host, HostDistance.LOCAL)) + session._pools = {} + for host, schema_version in zip(hosts, schema_versions): + connection = Mock(endpoint=host.endpoint) + connection.future_outcomes = [schema_version] + session._pools[host] = self.MockPool(host, connection) + connections[host] = connection + + def execute_async(query, parameters=None, trace=False, + custom_payload=None, execution_profile=None, + paging_state=None, timeout=None, host=None, execute_as=None): + connection = connections[host] + outcome = connection.future_outcomes.pop(0) if len(connection.future_outcomes) > 1 else connection.future_outcomes[0] + return self._mock_schema_future(outcome) + + session.execute_async = Mock(side_effect=execute_async) + + return session, hosts, connections + # TODO: this suite could be expanded; for now just adding a test covering a PR @mock_session_pools def test_default_serial_consistency_level_ep(self, *_): @@ -251,6 +473,157 @@ def test_default_serial_consistency_level_legacy(self, *_): assert f.message.serial_consistency_level == cl_override + + @mock_session_pools + def test_set_keyspace_escapes_quotes(self, *_): + """ + Test that Session.set_keyspace properly escapes double quotes in + keyspace names to prevent CQL injection. + Requested in review of PR #758. + """ + c = Cluster(protocol_version=4) + s = Session(c, [Host("127.0.0.1", SimpleConvictionPolicy, host_id=uuid.uuid4())]) + c.connection_class.initialize_reactor() + + s.execute = Mock() + + s.set_keyspace('my"ks') + query = s.execute.call_args[0][0] + assert query == 'USE "my""ks"', ( + "Double quotes in keyspace name must be escaped as double-double quotes, " + "got: %r" % query) + + # Also verify a simple keyspace name doesn't get unnecessarily quoted + s.execute.reset_mock() + s.set_keyspace('simple_ks') + query = s.execute.call_args[0][0] + assert query == 'USE simple_ks', ( + "Simple keyspace names should not be quoted, got: %r" % query) + + @mock_session_pools + def test_wait_for_schema_agreement_default_scope_queries_all_connected_hosts(self, *_): + session, hosts, _ = self._new_schema_agreement_session( + ["a", "a"], + distances=[HostDistance.LOCAL_RACK, HostDistance.REMOTE]) + + assert session.wait_for_schema_agreement(wait_time=1) + + for host in hosts: + assert self._host_query_count(session, host) == 1 + + @mock_session_pools + def test_wait_for_schema_agreement_retries_until_local_hosts_match(self, *_): + session, hosts, connections = self._new_schema_agreement_session(["a", "b"]) + clock = self.FakeTime() + connections[hosts[1]].future_outcomes = ["b", "a"] + + with patch('cassandra.cluster.time', new=clock): + assert session.wait_for_schema_agreement(wait_time=1) + for host in hosts: + assert self._host_query_count(session, host) == 2 + assert clock.clock == 0.2 + + @mock_session_pools + def test_wait_for_schema_agreement_retries_when_local_connection_is_busy(self, *_): + session, hosts, connections = self._new_schema_agreement_session(["a", "a"]) + clock = self.FakeTime() + connections[hosts[1]].future_outcomes = [ + ConnectionBusy("connection overloaded"), + "a"] + + with patch('cassandra.cluster.time', new=clock): + assert session.wait_for_schema_agreement(wait_time=1) + for host in hosts: + assert self._host_query_count(session, host) == 2 + assert clock.clock == 0.2 + + @mock_session_pools + def test_wait_for_schema_agreement_ignores_local_hosts_without_session_pool(self, *_): + session, hosts, _ = self._new_schema_agreement_session(["a"]) + + unconnected_host = Host("127.0.0.2", SimpleConvictionPolicy, host_id=uuid.uuid4()) + unconnected_host.set_up() + session.cluster.metadata.add_or_return_host(unconnected_host) + + assert session.wait_for_schema_agreement(wait_time=1) + assert self._host_query_count(session, hosts[0]) == 1 + + @mock_session_pools + def test_wait_for_schema_agreement_queries_hosts_in_order(self, *_): + session, hosts, _ = self._new_schema_agreement_session(["a"] * 11) + + assert session.wait_for_schema_agreement(wait_time=1) + assert [call.kwargs['host'] for call in session.execute_async.call_args_list] == list(hosts) + + @mock_session_pools + def test_wait_for_schema_agreement_rack_scope_only_queries_local_rack_connections(self, *_): + session, hosts, _ = self._new_schema_agreement_session( + ["a", "a", "a"], + distances=[HostDistance.LOCAL_RACK, HostDistance.LOCAL, HostDistance.REMOTE]) + + assert session.wait_for_schema_agreement(wait_time=1, scope=SchemaAgreementScope.RACK) + + assert self._host_query_count(session, hosts[0]) == 1 + assert self._host_query_count(session, hosts[1]) == 0 + assert self._host_query_count(session, hosts[2]) == 0 + + @mock_session_pools + def test_wait_for_schema_agreement_cluster_scope_skips_ignored_hosts(self, *_): + session, hosts, _ = self._new_schema_agreement_session( + ["a", "a"], + distances=[HostDistance.IGNORED, HostDistance.LOCAL]) + + assert session.wait_for_schema_agreement(wait_time=1, scope=SchemaAgreementScope.CLUSTER) + + assert self._host_query_count(session, hosts[0]) == 0 + assert self._host_query_count(session, hosts[1]) == 1 + + @mock_session_pools + def test_wait_for_schema_agreement_cluster_scope_excludes_hosts_with_unknown_status(self, *_): + session, hosts, _ = self._new_schema_agreement_session( + ["a", "a"], + distances=[HostDistance.LOCAL_RACK, HostDistance.LOCAL]) + + hosts[0].is_up = None + + assert session.wait_for_schema_agreement(wait_time=1, scope=SchemaAgreementScope.CLUSTER) + + assert self._host_query_count(session, hosts[0]) == 0 + assert self._host_query_count(session, hosts[1]) == 1 + + @mock_session_pools + def test_wait_for_schema_agreement_rejects_unknown_scope(self, *_): + session, _, _ = self._new_schema_agreement_session(["a"]) + + with pytest.raises(ValueError): + session.wait_for_schema_agreement(wait_time=1, scope='planet') + + @mock_session_pools + def test_set_keyspace_for_all_pools_reports_all_errors(self, *_): + cluster = Cluster() + session = Session( + cluster, + [Host("127.0.0.1", SimpleConvictionPolicy, host_id=uuid.uuid4())], + ) + + pool1 = Mock(host='host1') + pool2 = Mock(host='host2') + keyspace_error = ConnectionException("boom") + + pool1._set_keyspace_for_all_conns.side_effect = ( + lambda keyspace, callback: callback(pool1, [keyspace_error]) + ) + pool2._set_keyspace_for_all_conns.side_effect = ( + lambda keyspace, callback: callback(pool2, []) + ) + session._pools = {'host1': pool1, 'host2': pool2} + + callback = Mock() + session._set_keyspace_for_all_pools('ks', callback) + + callback.assert_called_once() + assert callback.call_args.args[0] == {'host1': [keyspace_error]} + class ProtocolVersionTests(unittest.TestCase): def test_protocol_downgrade_test(self): @@ -292,8 +665,8 @@ def test_default_exec_parameters(self): assert cluster.profile_manager.default.request_timeout == 10.0 assert session.default_consistency_level == ConsistencyLevel.LOCAL_ONE assert cluster.profile_manager.default.consistency_level == ConsistencyLevel.LOCAL_ONE - assert session.default_serial_consistency_level == None - assert cluster.profile_manager.default.serial_consistency_level == None + assert session.default_serial_consistency_level is None + assert cluster.profile_manager.default.serial_consistency_level is None assert session.row_factory == named_tuple_factory assert cluster.profile_manager.default.row_factory == named_tuple_factory diff --git a/tests/unit/test_connection.py b/tests/unit/test_connection.py index 6ac63ff761..8fdedd723f 100644 --- a/tests/unit/test_connection.py +++ b/tests/unit/test_connection.py @@ -21,11 +21,12 @@ from cassandra import OperationTimedOut from cassandra.cluster import Cluster from cassandra.connection import (Connection, HEADER_DIRECTION_TO_CLIENT, ProtocolError, - locally_supported_compressions, ConnectionHeartbeat, _Frame, Timer, TimerManager, + locally_supported_compressions, ConnectionHeartbeat, HeartbeatFuture, _Frame, Timer, TimerManager, ConnectionException, ConnectionShutdown, DefaultEndPoint, ShardAwarePortGenerator) from cassandra.marshal import uint8_pack, uint32_pack, int32_pack from cassandra.protocol import (write_stringmultimap, write_int, write_string, - SupportedMessage, ProtocolHandler) + SupportedMessage, ProtocolHandler, ResultMessage, + RESULT_KIND_SET_KEYSPACE) from tests.util import wait_until, assertRegex import pytest @@ -256,6 +257,60 @@ def test_set_keyspace_blocking(self): c.set_keyspace_blocking('ks') assert c.keyspace == 'ks' + def test_set_keyspace_blocking_escapes_quotes(self): + """ + Test that set_keyspace_blocking properly escapes double quotes in + keyspace names to prevent CQL injection. This is the Python equivalent + of the vulnerability fixed in the Go driver: + https://github.com/scylladb/gocql/pull/783 + """ + c = self.make_connection() + c.wait_for_response = Mock(return_value=ResultMessage(kind=RESULT_KIND_SET_KEYSPACE)) + + c.set_keyspace_blocking('my"ks') + query_msg = c.wait_for_response.call_args[0][0] + assert query_msg.query == 'USE "my""ks"', ( + "Double quotes in keyspace name must be escaped as double-double quotes") + + def test_set_keyspace_async_escapes_quotes(self): + """ + Test that set_keyspace_async properly escapes double quotes in + keyspace names to prevent CQL injection. + """ + c = self.make_connection() + c.lock = Lock() + c.in_flight = 0 + c.max_request_id = 100 + c.get_request_id = Mock(return_value=1) + c.send_msg = Mock() + + callback = Mock() + c.set_keyspace_async('my"ks', callback) + + query_msg = c.send_msg.call_args[0][0] + assert query_msg.query == 'USE "my""ks"', ( + "Double quotes in keyspace name must be escaped as double-double quotes") + + def test_send_msg_passes_negotiated_features_to_encoder(self): + """ + send_msg must hand the connection's negotiated ProtocolFeatures to the + encoder, so message serialization can emit fields belonging to protocol + extensions exactly on the connections that negotiated them. + """ + c = self.make_connection() + c.push = Mock() + captured = {} + + def encoder(msg, stream_id, protocol_version, compressor, allow_beta_protocol_version, + protocol_features=None): + captured['protocol_features'] = protocol_features + return b'encoded-frame' + + c.send_msg(Mock(), 1, cb=Mock(), encoder=encoder, decoder=Mock()) + + assert captured['protocol_features'] is c.features + c.push.assert_called_once_with(b'encoded-frame') + def test_set_connection_class(self): cluster = Cluster(connection_class='test') assert 'test' == cluster.connection_class @@ -428,6 +483,31 @@ def test_no_req_ids(self, *args): holder.return_connection.assert_has_calls( [call(max_connection)] * get_holders.call_count) + def test_heartbeat_future_releases_request_id_when_send_fails(self, *args): + connection = Connection(DefaultEndPoint('1.2.3.4')) + connection.push = Mock(side_effect=ConnectionException("write failed")) + owner = Mock() + initial_in_flight = connection.in_flight + initial_request_ids = len(connection.request_ids) + + # HostConnection.return_connection releases the heartbeat's in-flight slot. + def return_connection(conn): + with conn.lock: + conn.in_flight -= 1 + + owner.return_connection.side_effect = return_connection + + future = HeartbeatFuture(connection, owner) + + with pytest.raises(ConnectionException): + future.wait(timeout=0, original_timeout=0) + + owner.return_connection(connection) + + assert connection.in_flight == initial_in_flight + assert len(connection.request_ids) == initial_request_ids + assert not connection._requests + def test_unexpected_response(self, *args): request_id = 999 @@ -483,8 +563,10 @@ def send_msg(msg, req_id, msg_callback): connection.defunct.assert_has_calls([call(ANY)] * get_holders.call_count) exc = connection.defunct.call_args_list[0][0][0] assert isinstance(exc, OperationTimedOut) - assert exc.errors == 'Connection heartbeat timeout after 0.05 seconds' + assert exc.errors == 'Connection heartbeat timeout (total wait=0.05 seconds, this wait call=0.05 seconds)' assert exc.last_host == DefaultEndPoint('localhost') + assert exc.timeout == 0.05 + assert isinstance(exc.in_flight, int) holder.return_connection.assert_has_calls( [call(connection)] * get_holders.call_count) diff --git a/tests/unit/test_control_connection.py b/tests/unit/test_control_connection.py index d759e12332..fd62323f33 100644 --- a/tests/unit/test_control_connection.py +++ b/tests/unit/test_control_connection.py @@ -15,7 +15,7 @@ import unittest from concurrent.futures import ThreadPoolExecutor -from unittest.mock import Mock, ANY, call +from unittest.mock import Mock, ANY, call, patch from cassandra import OperationTimedOut, SchemaTargetType, SchemaChangeType from cassandra.protocol import ResultMessage, RESULT_KIND_ROWS @@ -210,16 +210,27 @@ def test_wait_for_schema_agreement(self): """ Basic test with all schema versions agreeing """ - assert self.control_connection.wait_for_schema_agreement() + assert self.control_connection._wait_for_schema_agreement() # the control connection should not have slept at all assert self.time.clock == 0 + @patch('cassandra.cluster.warn') + def test_wait_for_schema_agreement_warns_about_deprecation(self, mocked_warn): + assert self.control_connection.wait_for_schema_agreement() + + mocked_warn.assert_called_once() + warning_args, warning_kwargs = mocked_warn.call_args + assert 'ControlConnection.wait_for_schema_agreement is deprecated' in str(warning_args[0]) + assert 'Use Session.wait_for_schema_agreement instead.' in str(warning_args[0]) + assert warning_args[1] is DeprecationWarning + assert warning_kwargs['stacklevel'] == 2 + def test_wait_for_schema_agreement_uses_preloaded_results_if_given(self): """ wait_for_schema_agreement uses preloaded results if given for shared table queries """ preloaded_results = self._matching_schema_preloaded_results - assert self.control_connection.wait_for_schema_agreement(preloaded_results=preloaded_results) + assert self.control_connection._wait_for_schema_agreement(preloaded_results=preloaded_results) # the control connection should not have slept at all assert self.time.clock == 0 # the connection should not have made any queries if given preloaded results @@ -230,7 +241,7 @@ def test_wait_for_schema_agreement_falls_back_to_querying_if_schemas_dont_match_ wait_for_schema_agreement requery if schema does not match using preloaded results """ preloaded_results = self._nonmatching_schema_preloaded_results - assert self.control_connection.wait_for_schema_agreement(preloaded_results=preloaded_results) + assert self.control_connection._wait_for_schema_agreement(preloaded_results=preloaded_results) # the control connection should not have slept at all assert self.time.clock == 0 assert self.connection.wait_for_responses.call_count == 1 @@ -241,7 +252,7 @@ def test_wait_for_schema_agreement_fails(self): """ # change the schema version on one node self.connection.peer_results[1][1][2] = 'b' - assert not self.control_connection.wait_for_schema_agreement() + assert not self.control_connection._wait_for_schema_agreement() # the control connection should have slept until it hit the limit assert self.time.clock >= self.cluster.max_schema_agreement_wait @@ -262,7 +273,7 @@ def test_wait_for_schema_agreement_skipping(self): self.connection.peer_results[1][1][3] = 'c' self.cluster.metadata.get_host(DefaultEndPoint('192.168.1.1')).is_up = False - assert self.control_connection.wait_for_schema_agreement() + assert self.control_connection._wait_for_schema_agreement() assert self.time.clock == 0 def test_wait_for_schema_agreement_rpc_lookup(self): @@ -279,14 +290,28 @@ def test_wait_for_schema_agreement_rpc_lookup(self): # even though the new host has a different schema version, it's # marked as down, so the control connection shouldn't care - assert self.control_connection.wait_for_schema_agreement() + assert self.control_connection._wait_for_schema_agreement() assert self.time.clock == 0 # but once we mark it up, the control connection will care host.is_up = True - assert not self.control_connection.wait_for_schema_agreement() + assert not self.control_connection._wait_for_schema_agreement() assert self.time.clock >= self.cluster.max_schema_agreement_wait + + def test_wait_for_schema_agreement_none_timeout(self): + """ + When control_connection_timeout is None, wait_for_schema_agreement + should not raise a TypeError on the min() call. + """ + cc = ControlConnection(self.cluster, timeout=None, + schema_event_refresh_window=0, + topology_event_refresh_window=0, + status_event_refresh_window=0) + cc._connection = self.connection + cc._time = self.time + assert cc._wait_for_schema_agreement() + def test_refresh_nodes_and_tokens(self): self.control_connection.refresh_node_list_and_token_map() meta = self.cluster.metadata @@ -427,7 +452,8 @@ def bad_wait_for_responses(*args, **kwargs): self.control_connection.refresh_node_list_and_token_map() self.cluster.executor.submit.assert_called_with(self.control_connection._reconnect) - def test_refresh_schema_timeout(self): + @patch('cassandra.cluster.warn') + def test_refresh_schema_timeout(self, mocked_warn): def bad_wait_for_responses(*args, **kwargs): self.time.sleep(kwargs['timeout']) @@ -437,6 +463,7 @@ def bad_wait_for_responses(*args, **kwargs): self.control_connection.refresh_schema() assert self.connection.wait_for_responses.call_count == self.cluster.max_schema_agreement_wait / self.control_connection._timeout assert self.connection.wait_for_responses.call_args[1]['timeout'] == self.control_connection._timeout + mocked_warn.assert_not_called() def test_handle_topology_change(self): event = { diff --git a/tests/unit/test_endpoints.py b/tests/unit/test_endpoints.py index 14fb8b5806..1b6367dc2d 100644 --- a/tests/unit/test_endpoints.py +++ b/tests/unit/test_endpoints.py @@ -10,7 +10,7 @@ import itertools -from cassandra.connection import DefaultEndPoint, SniEndPoint, SniEndPointFactory +from cassandra.connection import DefaultEndPoint, SniEndPointFactory from unittest.mock import patch diff --git a/tests/unit/test_exception.py b/tests/unit/test_exception.py index 6bddd96a4b..0ac4052a63 100644 --- a/tests/unit/test_exception.py +++ b/tests/unit/test_exception.py @@ -29,7 +29,7 @@ def extract_consistency(self, msg): :param msg: message with consistency value :return: String representing consistency value """ - match = re.search("'consistency':\s+'([\w\s]+)'", msg) + match = re.search(r"'consistency':\s+'([\w\s]+)'", msg) return match and match.group(1) def test_timeout_consistency(self): diff --git a/tests/unit/test_host_connection_pool.py b/tests/unit/test_host_connection_pool.py index f92bb53785..8bb57d0dc0 100644 --- a/tests/unit/test_host_connection_pool.py +++ b/tests/unit/test_host_connection_pool.py @@ -13,7 +13,6 @@ # limitations under the License. from concurrent.futures import ThreadPoolExecutor import logging -import time import uuid from cassandra.protocol_features import ProtocolFeatures diff --git a/tests/unit/test_marshalling.py b/tests/unit/test_marshalling.py index e4b415ac69..02ca901abc 100644 --- a/tests/unit/test_marshalling.py +++ b/tests/unit/test_marshalling.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -import sys from cassandra import ProtocolVersion diff --git a/tests/unit/test_metadata.py b/tests/unit/test_metadata.py index dcbb840447..a058f73c61 100644 --- a/tests/unit/test_metadata.py +++ b/tests/unit/test_metadata.py @@ -25,17 +25,19 @@ from cassandra.marshal import uint16_unpack, uint16_pack from cassandra.metadata import (Murmur3Token, MD5Token, BytesToken, ReplicationStrategy, - NetworkTopologyStrategy, SimpleStrategy, + NetworkTopologyStrategy, LocalStrategy, protect_name, protect_names, protect_value, is_valid_name, UserType, KeyspaceMetadata, get_schema_parser, _UnknownStrategy, ColumnMetadata, TableMetadata, IndexMetadata, Function, Aggregate, Metadata, TokenMap, ReplicationFactor, - SchemaParserDSE68) + SchemaParserDSE68, SchemaParserV3, + _ConsistencyMode, _consistency_mode_from_string) from cassandra.policies import SimpleConvictionPolicy from cassandra.pool import Host from cassandra.protocol import QueryMessage +from cassandra.tablets import Tablet from tests.util import assertCountEqual import pytest @@ -96,14 +98,14 @@ def test_replication_strategy(self): assert rs.create('NetworkTopologyStrategy', fake_options_map).dc_replication_factors == NetworkTopologyStrategy(fake_options_map).dc_replication_factors fake_options_map = {'options': 'map'} - assert rs.create('SimpleStrategy', fake_options_map) is None + assert rs.create('NetworkTopologyStrategy', fake_options_map) is None fake_options_map = {'options': 'map'} assert isinstance(rs.create('LocalStrategy', fake_options_map), LocalStrategy) - fake_options_map = {'options': 'map', 'replication_factor': 3} - assert isinstance(rs.create('SimpleStrategy', fake_options_map), SimpleStrategy) - assert rs.create('SimpleStrategy', fake_options_map).replication_factor == SimpleStrategy(fake_options_map).replication_factor + fake_options_map = {'dc1': 3} + assert isinstance(rs.create('NetworkTopologyStrategy', fake_options_map), NetworkTopologyStrategy) + assert rs.create('NetworkTopologyStrategy', fake_options_map).dc_replication_factors == NetworkTopologyStrategy(fake_options_map).dc_replication_factors assert rs.create('xxxxxxxx', fake_options_map) == _UnknownStrategy('xxxxxxxx', fake_options_map) @@ -113,38 +115,38 @@ def test_replication_strategy(self): rs.export_for_schema() def test_simple_replication_type_parsing(self): - """ Test equality between passing numeric and string replication factor for simple strategy """ + """ Test equality between passing numeric and string replication factor for NTS """ rs = ReplicationStrategy() - simple_int = rs.create('SimpleStrategy', {'replication_factor': 3}) - simple_str = rs.create('SimpleStrategy', {'replication_factor': '3'}) + nts_int = rs.create('NetworkTopologyStrategy', {'dc1': 3}) + nts_str = rs.create('NetworkTopologyStrategy', {'dc1': '3'}) - assert simple_int.export_for_schema() == simple_str.export_for_schema() - assert simple_int == simple_str + assert nts_int.export_for_schema() == nts_str.export_for_schema() + assert nts_int == nts_str # make token replica map ring = [MD5Token(0), MD5Token(1), MD5Token(2)] - hosts = [Host('dc1.{}'.format(host), SimpleConvictionPolicy, host_id=uuid.uuid4()) for host in range(3)] + hosts = [Host('dc1.{}'.format(host), SimpleConvictionPolicy, datacenter='dc1', rack='rack1', host_id=uuid.uuid4()) for host in range(3)] token_to_host = dict(zip(ring, hosts)) - assert simple_int.make_token_replica_map(token_to_host, ring) == simple_str.make_token_replica_map(token_to_host, ring) + assert nts_int.make_token_replica_map(token_to_host, ring) == nts_str.make_token_replica_map(token_to_host, ring) def test_transient_replication_parsing(self): - """ Test that we can PARSE a transient replication factor for SimpleStrategy """ + """ Test that we can PARSE a transient replication factor for NetworkTopologyStrategy """ rs = ReplicationStrategy() - simple_transient = rs.create('SimpleStrategy', {'replication_factor': '3/1'}) - assert simple_transient.replication_factor_info == ReplicationFactor(3, 1) - assert simple_transient.replication_factor == 2 - assert "'replication_factor': '3/1'" in simple_transient.export_for_schema() + nts_transient = rs.create('NetworkTopologyStrategy', {'dc1': '3/1'}) + assert nts_transient.dc_replication_factors_info['dc1'] == ReplicationFactor(3, 1) + assert nts_transient.dc_replication_factors['dc1'] == 2 + assert "'dc1': '3/1'" in nts_transient.export_for_schema() - simple_str = rs.create('SimpleStrategy', {'replication_factor': '2'}) - assert simple_transient != simple_str + nts_str = rs.create('NetworkTopologyStrategy', {'dc1': '2'}) + assert nts_transient != nts_str # make token replica map ring = [MD5Token(0), MD5Token(1), MD5Token(2)] - hosts = [Host('dc1.{}'.format(host), SimpleConvictionPolicy, host_id=uuid.uuid4()) for host in range(3)] + hosts = [Host('dc1.{}'.format(host), SimpleConvictionPolicy, datacenter='dc1', rack='rack1', host_id=uuid.uuid4()) for host in range(3)] token_to_host = dict(zip(ring, hosts)) - assert simple_transient.make_token_replica_map(token_to_host, ring) == simple_str.make_token_replica_map(token_to_host, ring) + assert nts_transient.make_token_replica_map(token_to_host, ring) == nts_str.make_token_replica_map(token_to_host, ring) def test_nts_replication_parsing(self): """ Test equality between passing numeric and string replication factor for NTS """ @@ -318,9 +320,9 @@ def test_nts_export_for_schema(self): assert "{'class': 'NetworkTopologyStrategy', 'dc1': '1', 'dc2': '2'}" == strategy.export_for_schema() def test_simple_strategy_make_token_replica_map(self): - host1 = Host('1', SimpleConvictionPolicy, host_id=uuid.uuid4()) - host2 = Host('2', SimpleConvictionPolicy, host_id=uuid.uuid4()) - host3 = Host('3', SimpleConvictionPolicy, host_id=uuid.uuid4()) + host1 = Host('1', SimpleConvictionPolicy, datacenter='dc1', rack='rack1', host_id=uuid.uuid4()) + host2 = Host('2', SimpleConvictionPolicy, datacenter='dc1', rack='rack1', host_id=uuid.uuid4()) + host3 = Host('3', SimpleConvictionPolicy, datacenter='dc1', rack='rack1', host_id=uuid.uuid4()) token_to_host_owner = { MD5Token(0): host1, MD5Token(100): host2, @@ -328,23 +330,23 @@ def test_simple_strategy_make_token_replica_map(self): } ring = [MD5Token(0), MD5Token(100), MD5Token(200)] - rf1_replicas = SimpleStrategy({'replication_factor': '1'}).make_token_replica_map(token_to_host_owner, ring) + rf1_replicas = NetworkTopologyStrategy({'dc1': '1'}).make_token_replica_map(token_to_host_owner, ring) assertCountEqual(rf1_replicas[MD5Token(0)], [host1]) assertCountEqual(rf1_replicas[MD5Token(100)], [host2]) assertCountEqual(rf1_replicas[MD5Token(200)], [host3]) - rf2_replicas = SimpleStrategy({'replication_factor': '2'}).make_token_replica_map(token_to_host_owner, ring) + rf2_replicas = NetworkTopologyStrategy({'dc1': '2'}).make_token_replica_map(token_to_host_owner, ring) assertCountEqual(rf2_replicas[MD5Token(0)], [host1, host2]) assertCountEqual(rf2_replicas[MD5Token(100)], [host2, host3]) assertCountEqual(rf2_replicas[MD5Token(200)], [host3, host1]) - rf3_replicas = SimpleStrategy({'replication_factor': '3'}).make_token_replica_map(token_to_host_owner, ring) + rf3_replicas = NetworkTopologyStrategy({'dc1': '3'}).make_token_replica_map(token_to_host_owner, ring) assertCountEqual(rf3_replicas[MD5Token(0)], [host1, host2, host3]) assertCountEqual(rf3_replicas[MD5Token(100)], [host2, host3, host1]) assertCountEqual(rf3_replicas[MD5Token(200)], [host3, host1, host2]) def test_ss_equals(self): - assert SimpleStrategy({'replication_factor': '1'}) != NetworkTopologyStrategy({'dc1': 2}) + assert NetworkTopologyStrategy({'dc1': '1'}) != NetworkTopologyStrategy({'dc1': 2}) class NameEscapingTest(unittest.TestCase): @@ -409,9 +411,9 @@ def test_is_valid_name(self): class GetReplicasTest(unittest.TestCase): def _get_replicas(self, token_klass): tokens = [token_klass(i) for i in range(0, (2 ** 127 - 1), 2 ** 125)] - hosts = [Host("ip%d" % i, SimpleConvictionPolicy, host_id=uuid.uuid4()) for i in range(len(tokens))] + hosts = [Host("ip%d" % i, SimpleConvictionPolicy, datacenter="dc1", rack="rack1", host_id=uuid.uuid4()) for i in range(len(tokens))] token_to_primary_replica = dict(zip(tokens, hosts)) - keyspace = KeyspaceMetadata("ks", True, "SimpleStrategy", {"replication_factor": "1"}) + keyspace = KeyspaceMetadata("ks", True, "NetworkTopologyStrategy", {"dc1": "1"}) metadata = Mock(spec=Metadata, keyspaces={'ks': keyspace}) token_map = TokenMap(token_klass, token_to_primary_replica, tokens, metadata) @@ -522,15 +524,47 @@ def test_comparison_unicode(self): class KeyspaceMetadataTest(unittest.TestCase): + @staticmethod + def _keyspace(consistency_mode=None): + keyspace = KeyspaceMetadata('test', True, 'NetworkTopologyStrategy', dict(dc1=3)) + if consistency_mode is not None: + keyspace._consistency_mode = consistency_mode + return keyspace + + def test_as_cql_query_omits_eventual_consistency(self): + # Eventual consistency is the server's default, so it must not be + # spelled out -- including for a keyspace whose mode was never set, + # which is every keyspace on a non-Scylla cluster. + assert 'consistency' not in self._keyspace().as_cql_query() + assert 'consistency' not in self._keyspace(_ConsistencyMode.EVENTUAL).as_cql_query() + + def test_as_cql_query_includes_consistency_mode(self): + # A recreated keyspace has to keep its consistency mode, or the copy + # silently loses strong consistency. + assert self._keyspace(_ConsistencyMode.GLOBAL).as_cql_query() == ( + "CREATE KEYSPACE test WITH replication = " + "{'class': 'NetworkTopologyStrategy', 'dc1': '3'} " + " AND consistency = 'global' AND durable_writes = true") + assert self._keyspace(_ConsistencyMode.LOCAL).as_cql_query() == ( + "CREATE KEYSPACE test WITH replication = " + "{'class': 'NetworkTopologyStrategy', 'dc1': '3'} " + " AND consistency = 'local' AND durable_writes = true") + + def test_export_as_string_includes_consistency_mode(self): + # export_as_string() appends the statement terminator and is what a + # schema dump goes through, so the option has to survive that path too. + exported = self._keyspace(_ConsistencyMode.GLOBAL).export_as_string() + assert "AND consistency = 'global' AND durable_writes = true;" in exported + def test_export_as_string_user_types(self): keyspace_name = 'test' - keyspace = KeyspaceMetadata(keyspace_name, True, 'SimpleStrategy', dict(replication_factor=3)) + keyspace = KeyspaceMetadata(keyspace_name, True, 'NetworkTopologyStrategy', dict(dc1=3)) keyspace.user_types['a'] = UserType(keyspace_name, 'a', ['one', 'two'], ['c', 'int']) keyspace.user_types['b'] = UserType(keyspace_name, 'b', ['one', 'two', 'three'], ['d', 'int', 'a']) keyspace.user_types['c'] = UserType(keyspace_name, 'c', ['one'], ['int']) keyspace.user_types['d'] = UserType(keyspace_name, 'd', ['one'], ['c']) - assert """CREATE KEYSPACE test WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3'} AND durable_writes = true; + assert """CREATE KEYSPACE test WITH replication = {'class': 'NetworkTopologyStrategy', 'dc1': '3'} AND durable_writes = true; CREATE TYPE test.c ( one int @@ -552,6 +586,150 @@ def test_export_as_string_user_types(self): );""" == keyspace.export_as_string() +class KeyspaceConsistencyTabletInvalidationTest(unittest.TestCase): + """ + Metadata._update_keyspace must drop cached tablets when a keyspace's + strong-consistency mode changes, not only when its replication strategy + changes. A tablet cached while the keyspace was eventually consistent has no + leader ordering, so it must not survive an eventual->global flip and then be + misread as a leader hint by TokenAwarePolicy.make_query_plan. + """ + + def _ks_meta(self, strongly_consistent): + meta = KeyspaceMetadata('ks', True, 'NetworkTopologyStrategy', {'replication_factor': '1'}) + meta._consistency_mode = _ConsistencyMode.GLOBAL if strongly_consistent else _ConsistencyMode.EVENTUAL + return meta + + def _add_cached_tablet(self, metadata): + tablet = Tablet(first_token=-100, last_token=100, + replicas=[(uuid.uuid4(), 0)], tablet_version=1) + metadata._tablets.add_tablet('ks', 'tbl', tablet) + + def test_consistency_flip_drops_tablets(self): + metadata = Metadata() + metadata._update_keyspace(self._ks_meta(strongly_consistent=False)) + self._add_cached_tablet(metadata) + assert metadata._tablets.table_has_tablets('ks', 'tbl') + + # Same replication strategy, consistency flips False -> True: the stale + # tablet cache must be dropped. + metadata._update_keyspace(self._ks_meta(strongly_consistent=True)) + assert not metadata._tablets.table_has_tablets('ks', 'tbl') + + def test_no_consistency_change_keeps_tablets(self): + metadata = Metadata() + metadata._update_keyspace(self._ks_meta(strongly_consistent=False)) + self._add_cached_tablet(metadata) + assert metadata._tablets.table_has_tablets('ks', 'tbl') + + # No replication change and no consistency change: cache is preserved. + metadata._update_keyspace(self._ks_meta(strongly_consistent=False)) + assert metadata._tablets.table_has_tablets('ks', 'tbl') + + +class ScyllaKeyspaceConsistencyParsingTest(unittest.TestCase): + """ + SchemaParserV3 maps the server's per-keyspace consistency option to + KeyspaceMetadata._consistency_mode, on the bulk path (rows collected by + _query_all, folded into a map by _aggregate_results) and on the + single-keyspace path (a filtered read). A transient failure reading the + consistency table propagates so the schema refresh aborts and the previously + known metadata is retried, rather than being reset to eventual. + + Which modes actually get leader-aware routing is TokenAwarePolicy's business + and is covered in tests/unit/test_policies.py. + """ + + def _parser_with_rows(self, rows): + # Build the parser without a connection and drive only the aggregation + # step; _query_all's batching is exercised by the integration tests. + parser = SchemaParserV3.__new__(SchemaParserV3) + parser.scylla_keyspaces_result = rows + return parser + + def test_consistency_modes_are_mapped_from_rows(self): + # The mode the server reported is kept verbatim, so 'local' stays + # distinguishable from 'eventual' even though ScyllaDB does not implement + # it yet and the driver treats the two alike. + parser = self._parser_with_rows([ + {'keyspace_name': 'g', 'consistency': 'global'}, + {'keyspace_name': 'l', 'consistency': 'local'}, + {'keyspace_name': 'e', 'consistency': 'eventual'}, + {'keyspace_name': 'n', 'consistency': None}, + ]) + modes = {row["keyspace_name"]: _consistency_mode_from_string(row.get("consistency")) + for row in parser.scylla_keyspaces_result} + assert modes['g'] == _ConsistencyMode.GLOBAL + assert modes['l'] == _ConsistencyMode.LOCAL + assert modes['e'] == _ConsistencyMode.EVENTUAL + assert modes['n'] == _ConsistencyMode.EVENTUAL + + def test_keyspace_absent_from_the_map_is_eventual(self): + # Covers the whole-cluster fallbacks too: no rows is what a skipped read + # (no TABLETS_ROUTING_V2) and a missing table/column both produce. + parser = SchemaParserV3.__new__(SchemaParserV3) + parser.keyspace_consistency_modes = {'g': _ConsistencyMode.GLOBAL} + assert parser.keyspace_consistency_modes.get( + 'absent', _ConsistencyMode.EVENTUAL) == _ConsistencyMode.EVENTUAL + + def test_single_keyspace_read_is_filtered_and_mapped(self): + # The single-keyspace refresh path must not read the whole table; it + # restricts the query to the keyspace being refreshed. + parser = SchemaParserV3.__new__(SchemaParserV3) + parser.connection = Mock(features=Mock(tablets_routing_v2=True)) + queries = [] + + def _fake_query_build_row(query_string, build_func): + queries.append(query_string) + return {'keyspace_name': 'g', 'consistency': 'global'} + parser._query_build_row = _fake_query_build_row + + assert parser._query_keyspace_consistency_mode('g') == _ConsistencyMode.GLOBAL + assert len(queries) == 1 + assert "WHERE keyspace_name = 'g'" in queries[0] + + def test_single_keyspace_read_is_skipped_without_v2(self): + # Without the extension there is nothing to route for, so the query is + # not issued at all and the keyspace is eventually consistent. + parser = SchemaParserV3.__new__(SchemaParserV3) + parser.connection = Mock(features=Mock(tablets_routing_v2=False)) + + def _fail(*args, **kwargs): + raise AssertionError("scylla_keyspaces must not be queried without V2") + parser._query_build_row = _fail + + assert parser._query_keyspace_consistency_mode('g') == _ConsistencyMode.EVENTUAL + + def test_consistency_string_mapping_is_case_insensitive(self): + # The option is a free-form string on the wire, so the mapping must not + # depend on the case the server happens to use. Anything unrecognized -- + # including a null, which is how an eventually-consistent keyspace is + # reported -- falls back to eventual rather than failing the refresh. + assert _consistency_mode_from_string('GLOBAL') == _ConsistencyMode.GLOBAL + assert _consistency_mode_from_string('Global') == _ConsistencyMode.GLOBAL + assert _consistency_mode_from_string('global') == _ConsistencyMode.GLOBAL + assert _consistency_mode_from_string('LOCAL') == _ConsistencyMode.LOCAL + assert _consistency_mode_from_string('eventual') == _ConsistencyMode.EVENTUAL + assert _consistency_mode_from_string(None) == _ConsistencyMode.EVENTUAL + assert _consistency_mode_from_string('something-new') == _ConsistencyMode.EVENTUAL + + def test_read_failure_propagates(self): + # A transient failure reading system_schema.scylla_keyspaces must + # propagate (not be swallowed into "eventual"), so the schema refresh + # aborts and the previously known consistency modes are retried. + parser = SchemaParserV3.__new__(SchemaParserV3) + # The control connection must have negotiated V2 to reach the read; + # otherwise the query is skipped and no failure could propagate. + parser.connection = Mock(features=Mock(tablets_routing_v2=True)) + + def _raise_timeout(*args, **kwargs): + raise cassandra.OperationTimedOut("scylla_keyspaces read timed out") + parser._query_build_row = _raise_timeout + + with pytest.raises(cassandra.OperationTimedOut): + parser._query_keyspace_consistency_mode('g') + + class UserTypesTest(unittest.TestCase): def test_as_cql_query(self): @@ -662,7 +840,7 @@ class UnicodeIdentifiersTests(unittest.TestCase): name = b'\'_-()"\xc2\xac'.decode('utf-8') def test_keyspace_name(self): - km = KeyspaceMetadata(self.name, False, 'SimpleStrategy', {'replication_factor': 1}) + km = KeyspaceMetadata(self.name, False, 'NetworkTopologyStrategy', {'dc1': 1}) km.export_as_string() def test_table_name(self): diff --git a/tests/unit/test_policies.py b/tests/unit/test_policies.py index 6142af1aa1..35c1a96f87 100644 --- a/tests/unit/test_policies.py +++ b/tests/unit/test_policies.py @@ -26,7 +26,7 @@ from cassandra import ConsistencyLevel from cassandra.cluster import Cluster, ControlConnection -from cassandra.metadata import Metadata +from cassandra.metadata import Metadata, _ConsistencyMode from cassandra.policies import (RackAwareRoundRobinPolicy, RoundRobinPolicy, WhiteListRoundRobinPolicy, DCAwareRoundRobinPolicy, TokenAwarePolicy, SimpleConvictionPolicy, HostDistance, ExponentialReconnectionPolicy, @@ -943,6 +943,456 @@ def _assert_shuffle(self, patched_shuffle, cluster, keyspace, routing_key): child_policy.make_query_plan.assert_called_once_with(keyspace, query) assert patched_shuffle.call_count == 1 + def test_leader_aware_routing_with_tablet_version(self): + """ + For a strongly-consistent keyspace, the leader (first replica in the + tablet's replica list) must be yielded first in the query plan, even + when it is not the closest replica. + """ + hosts = [Host(DefaultEndPoint(str(i)), SimpleConvictionPolicy, host_id=uuid.uuid4()) for i in range(4)] + for i, host in enumerate(hosts): + host.set_up() + host.set_location_info("dc1", f"rack{i + 1}") + + # The leader is hosts[2] (first in tablet.replicas). + leader = hosts[2] + other_replica = hosts[3] + tablet = Tablet( + first_token=-100, last_token=100, + replicas=[(leader.host_id, 0), (other_replica.host_id, 1)], + tablet_version=0xDEADBEEF12345678 + ) + + cluster = Mock(spec=Cluster) + cluster.metadata = Mock(spec=Metadata) + cluster.metadata._tablets = Mock(spec=Tablets) + cluster.metadata._tablets.get_tablet_for_key.return_value = tablet + cluster.metadata.get_replicas.return_value = [leader, other_replica] + cluster.metadata.keyspaces = {'ks': Mock(_consistency_mode=_ConsistencyMode.GLOBAL)} + + child_policy = Mock() + # Put the leader last in the child plan and make it the farther replica + # by distance (LOCAL vs LOCAL_RACK). Without leader-first routing, + # other_replica would be yielded before the leader. + child_policy.make_query_plan.return_value = [hosts[0], hosts[1], other_replica, leader] + distances = { + leader: HostDistance.LOCAL, + other_replica: HostDistance.LOCAL_RACK, + hosts[0]: HostDistance.LOCAL, + hosts[1]: HostDistance.LOCAL, + } + child_policy.distance.side_effect = lambda host: distances.get(host, HostDistance.LOCAL) + + # shuffle_replicas=False keeps replica ordering deterministic so the only + # thing that can pull the leader to the front is the leader-first logic. + policy = TokenAwarePolicy(child_policy, shuffle_replicas=False) + policy.populate(cluster, hosts) + + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + # A non-weak consistency level requires the leader; ONE/LOCAL_ONE would + # instead spread the request across replicas (covered separately). + query.consistency_level = ConsistencyLevel.LOCAL_QUORUM + qplan = list(policy.make_query_plan(None, query)) + + # Leader must be first, even though other_replica is closer (LOCAL_RACK + # vs LOCAL) and the leader is last in the child plan. + self.assertEqual(qplan[0], leader) + # The closer replica follows, and the leader appears exactly once. + self.assertEqual(qplan[1], other_replica) + self.assertEqual(qplan.count(leader), 1) + + def test_leader_fallback_when_leader_is_down(self): + """ + When the leader host is down, the driver should fall back to other + replicas without crashing. The leader should NOT appear in the plan. + """ + hosts = [Host(DefaultEndPoint(str(i)), SimpleConvictionPolicy, host_id=uuid.uuid4()) for i in range(4)] + for i, host in enumerate(hosts): + host.set_up() + host.set_location_info("dc1", f"rack{i + 1}") + + leader = hosts[2] + other_replica = hosts[3] + leader.set_down() # Simulate leader being unreachable. + + tablet = Tablet( + first_token=-100, last_token=100, + replicas=[(leader.host_id, 0), (other_replica.host_id, 1)], + tablet_version=0xCAFEBABE00000001 + ) + + cluster = Mock(spec=Cluster) + cluster.metadata = Mock(spec=Metadata) + cluster.metadata._tablets = Mock(spec=Tablets) + cluster.metadata._tablets.get_tablet_for_key.return_value = tablet + cluster.metadata.get_replicas.return_value = [leader, other_replica] + cluster.metadata.keyspaces = {'ks': Mock(_consistency_mode=_ConsistencyMode.GLOBAL)} + + child_policy = Mock() + child_policy.make_query_plan.return_value = hosts + child_policy.distance.return_value = HostDistance.LOCAL + + policy = TokenAwarePolicy(child_policy) + policy.populate(cluster, hosts) + + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + # A non-weak consistency level makes the leader the preferred target. + query.consistency_level = ConsistencyLevel.LOCAL_QUORUM + qplan = list(policy.make_query_plan(None, query)) + + # Leader is down, should not appear in the plan. + self.assertNotIn(leader, qplan) + # Other replica should be first. + self.assertEqual(qplan[0], other_replica) + + def test_no_leader_routing_without_tablet_version(self): + """ + replicas[0] is only leader-ordered for a tablet that came from a + TABLETS_ROUTING_V2 payload. A versionless tablet (tablet_version=None, + e.g. cached from V1 or stale across a consistency flip) has arbitrary + replica order, so leader-first routing must NOT fire even for a + strongly-consistent keyspace. The version gate is the only thing that + should suppress it here. + """ + hosts = [Host(DefaultEndPoint(str(i)), SimpleConvictionPolicy, host_id=uuid.uuid4()) for i in range(4)] + for i, host in enumerate(hosts): + host.set_up() + host.set_location_info("dc1", f"rack{i + 1}") + + first_replica = hosts[2] + second_replica = hosts[3] + # Strongly-consistent keyspace but a versionless (V1-style) tablet. + tablet = Tablet( + first_token=-100, last_token=100, + replicas=[(first_replica.host_id, 0), (second_replica.host_id, 1)], + tablet_version=None + ) + + cluster = Mock(spec=Cluster) + cluster.metadata = Mock(spec=Metadata) + cluster.metadata._tablets = Mock(spec=Tablets) + cluster.metadata._tablets.get_tablet_for_key.return_value = tablet + cluster.metadata.get_replicas.return_value = [first_replica, second_replica] + cluster.metadata.keyspaces = {'ks': Mock(_consistency_mode=_ConsistencyMode.GLOBAL)} + + child_policy = Mock() + # Order the child plan so the second replica comes before replicas[0]; if + # leader-first wrongly triggered, first_replica would be forced to front. + child_policy.make_query_plan.return_value = [second_replica, first_replica, hosts[0], hosts[1]] + child_policy.distance.return_value = HostDistance.LOCAL + + # shuffle_replicas=False keeps replica ordering deterministic so we can + # assert that no leader is forced to the front. + policy = TokenAwarePolicy(child_policy, shuffle_replicas=False) + policy.populate(cluster, hosts) + + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + qplan = list(policy.make_query_plan(None, query)) + + # Leader-first must NOT apply without a tablet_version: ordering follows + # the child plan, so the second replica (not replicas[0]) stays first. + self.assertEqual(qplan[0], second_replica) + self.assertEqual(len(qplan), 4) + + def test_no_leader_routing_for_eventually_consistent_keyspace(self): + """ + A tablet_version is assigned to eventually-consistent tablet tables too + (TABLETS_ROUTING_V2), but the leader concept only exists for + strongly-consistent keyspaces. For an eventually-consistent keyspace the + leader-first optimization must NOT apply even when a tablet_version is + present. + """ + hosts = [Host(DefaultEndPoint(str(i)), SimpleConvictionPolicy, host_id=uuid.uuid4()) for i in range(4)] + for i, host in enumerate(hosts): + host.set_up() + host.set_location_info("dc1", f"rack{i + 1}") + + first_replica = hosts[2] + second_replica = hosts[3] + tablet = Tablet( + first_token=-100, last_token=100, + replicas=[(first_replica.host_id, 0), (second_replica.host_id, 1)], + tablet_version=0xDEADBEEF12345678 + ) + + cluster = Mock(spec=Cluster) + cluster.metadata = Mock(spec=Metadata) + cluster.metadata._tablets = Mock(spec=Tablets) + cluster.metadata._tablets.get_tablet_for_key.return_value = tablet + cluster.metadata.get_replicas.return_value = [first_replica, second_replica] + cluster.metadata.keyspaces = {'ks': Mock(_consistency_mode=_ConsistencyMode.EVENTUAL)} + + child_policy = Mock() + # Order the child plan so the second replica comes before the first; if + # leader-first logic wrongly triggered, first_replica would be forced to + # the front instead. + child_policy.make_query_plan.return_value = [second_replica, first_replica, hosts[0], hosts[1]] + child_policy.distance.return_value = HostDistance.LOCAL + + # shuffle_replicas=False keeps replica ordering deterministic so we can + # assert that no leader is forced to the front. + policy = TokenAwarePolicy(child_policy, shuffle_replicas=False) + policy.populate(cluster, hosts) + + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + qplan = list(policy.make_query_plan(None, query)) + + # Leader-first must NOT apply: ordering follows the child plan, so the + # second replica (not replicas[0]) stays first. + self.assertEqual(qplan[0], second_replica) + self.assertEqual(len(qplan), 4) + + def test_no_leader_routing_when_keyspace_metadata_missing(self): + """ + If keyspace metadata is unavailable (e.g. schema refresh disabled), the + policy must safely fall back to no leader-first routing rather than + crashing or guessing. + """ + hosts = [Host(DefaultEndPoint(str(i)), SimpleConvictionPolicy, host_id=uuid.uuid4()) for i in range(4)] + for i, host in enumerate(hosts): + host.set_up() + host.set_location_info("dc1", f"rack{i + 1}") + + first_replica = hosts[2] + second_replica = hosts[3] + tablet = Tablet( + first_token=-100, last_token=100, + replicas=[(first_replica.host_id, 0), (second_replica.host_id, 1)], + tablet_version=0xDEADBEEF12345678 + ) + + cluster = Mock(spec=Cluster) + cluster.metadata = Mock(spec=Metadata) + cluster.metadata._tablets = Mock(spec=Tablets) + cluster.metadata._tablets.get_tablet_for_key.return_value = tablet + cluster.metadata.get_replicas.return_value = [first_replica, second_replica] + cluster.metadata.keyspaces = {} # no metadata for 'ks' + + child_policy = Mock() + child_policy.make_query_plan.return_value = [second_replica, first_replica, hosts[0], hosts[1]] + child_policy.distance.return_value = HostDistance.LOCAL + + # shuffle_replicas=False keeps replica ordering deterministic so we can + # assert that no leader is forced to the front. + policy = TokenAwarePolicy(child_policy, shuffle_replicas=False) + policy.populate(cluster, hosts) + + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + qplan = list(policy.make_query_plan(None, query)) + + self.assertEqual(qplan[0], second_replica) + self.assertEqual(len(qplan), 4) + + def test_leader_skipped_when_child_policy_ignores_it(self): + """ + The leader is yielded first only if the child policy would actually use + it. If a (custom) child policy reports the leader as IGNORED, leader-first + routing must respect that and not front-run an excluded host. The leader + should not appear in the plan at all. + """ + hosts = [Host(DefaultEndPoint(str(i)), SimpleConvictionPolicy, host_id=uuid.uuid4()) for i in range(4)] + for i, host in enumerate(hosts): + host.set_up() + host.set_location_info("dc1", f"rack{i + 1}") + + leader = hosts[2] + other_replica = hosts[3] + tablet = Tablet( + first_token=-100, last_token=100, + replicas=[(leader.host_id, 0), (other_replica.host_id, 1)], + tablet_version=0xDEADBEEF12345678 + ) + + cluster = Mock(spec=Cluster) + cluster.metadata = Mock(spec=Metadata) + cluster.metadata._tablets = Mock(spec=Tablets) + cluster.metadata._tablets.get_tablet_for_key.return_value = tablet + cluster.metadata.get_replicas.return_value = [leader, other_replica] + cluster.metadata.keyspaces = {'ks': Mock(_consistency_mode=_ConsistencyMode.GLOBAL)} + + child_policy = Mock() + # The child policy yields the leader but reports it as IGNORED, i.e. it + # would never actually route to it. + child_policy.make_query_plan.return_value = [leader, other_replica, hosts[0], hosts[1]] + distances = { + leader: HostDistance.IGNORED, + other_replica: HostDistance.LOCAL, + hosts[0]: HostDistance.LOCAL, + hosts[1]: HostDistance.LOCAL, + } + child_policy.distance.side_effect = lambda host: distances.get(host, HostDistance.LOCAL) + + # shuffle_replicas=False keeps replica ordering deterministic. + policy = TokenAwarePolicy(child_policy, shuffle_replicas=False) + policy.populate(cluster, hosts) + + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + # A non-weak consistency level keeps the leader eligible; the child + # policy reporting it as IGNORED is what must exclude it here. + query.consistency_level = ConsistencyLevel.LOCAL_QUORUM + qplan = list(policy.make_query_plan(None, query)) + + # The IGNORED leader must not be front-run, nor appear at all. + self.assertNotIn(leader, qplan) + self.assertEqual(qplan[0], other_replica) + + def _make_leader_routing_setup(self, *, consistency_mode=_ConsistencyMode.GLOBAL, + tablet_version=0xDEADBEEF12345678, + default_consistency_level=None, + prefer_tablet_leader=True): + """ + Build a TokenAwarePolicy over a strongly-consistent tablet keyspace in + which the leader (hosts[2]) is the *farther* replica (LOCAL) while + other_replica (hosts[3]) is closer (LOCAL_RACK). With shuffling off, the + only thing that can pull the leader to the front of the plan is the + leader-first hint, so a test can infer whether that hint fired purely + from the resulting order. ``default_consistency_level`` seeds the default + execution profile so tests can exercise the effective-consistency + fallback used when a statement leaves consistency_level unset. + Returns (policy, leader, other_replica). + """ + hosts = [Host(DefaultEndPoint(str(i)), SimpleConvictionPolicy, host_id=uuid.uuid4()) for i in range(4)] + for i, host in enumerate(hosts): + host.set_up() + host.set_location_info("dc1", f"rack{i + 1}") + + leader = hosts[2] + other_replica = hosts[3] + tablet = Tablet( + first_token=-100, last_token=100, + replicas=[(leader.host_id, 0), (other_replica.host_id, 1)], + tablet_version=tablet_version, + ) + + cluster = Mock(spec=Cluster) + cluster.metadata = Mock(spec=Metadata) + cluster.metadata._tablets = Mock(spec=Tablets) + cluster.metadata._tablets.get_tablet_for_key.return_value = tablet + cluster.metadata.get_replicas.return_value = [leader, other_replica] + cluster.metadata.keyspaces = {'ks': Mock(_consistency_mode=consistency_mode)} + cluster.profile_manager.default.consistency_level = default_consistency_level + + child_policy = Mock() + # Leader is last in the child plan and the farther replica (LOCAL vs + # LOCAL_RACK); without leader-first, other_replica is yielded first. + child_policy.make_query_plan.return_value = [hosts[0], hosts[1], other_replica, leader] + distances = { + leader: HostDistance.LOCAL, + other_replica: HostDistance.LOCAL_RACK, + hosts[0]: HostDistance.LOCAL, + hosts[1]: HostDistance.LOCAL, + } + child_policy.distance.side_effect = lambda host: distances.get(host, HostDistance.LOCAL) + + policy = TokenAwarePolicy(child_policy, shuffle_replicas=False, + _prefer_tablet_leader=prefer_tablet_leader) + policy.populate(cluster, hosts) + return policy, leader, other_replica + + def test_no_leader_routing_for_read_with_consistency_level_one_or_local_one(self): + """ + A request at consistency level ONE or LOCAL_ONE is satisfied by any + single replica, so even on a strongly-consistent keyspace the leader + must NOT be forced to the front -- doing so would only create a leader + hotspot. Ordering follows the normal token-aware plan, so the closer + replica stays first and the leader is not front-run. + """ + for cl in (ConsistencyLevel.ONE, ConsistencyLevel.LOCAL_ONE): + policy, leader, other_replica = self._make_leader_routing_setup() + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + query.consistency_level = cl + qplan = list(policy.make_query_plan(None, query)) + + self.assertEqual(qplan[0], other_replica, + "leader must not be front-run for consistency level %s" % cl) + # The leader is still a valid replica -- it just isn't preferred. + self.assertEqual(qplan.count(leader), 1) + + def test_leader_routing_only_for_global_consistency_mode(self): + """ + Only a keyspace whose consistency mode is GLOBAL has a tablet leader. + ScyllaDB does not implement 'local' consistency yet, so LOCAL must be + treated exactly like EVENTUAL and get plain token-aware ordering; this + test has to be revisited once 'local' consistency exists. + """ + for mode in (_ConsistencyMode.LOCAL, _ConsistencyMode.EVENTUAL): + policy, leader, other_replica = self._make_leader_routing_setup(consistency_mode=mode) + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + # A leader-requiring consistency level, so the mode is the only + # thing that can suppress the leader-first hint. + query.consistency_level = ConsistencyLevel.LOCAL_QUORUM + qplan = list(policy.make_query_plan(None, query)) + + self.assertEqual(qplan[0], other_replica, + "leader must not be front-run for consistency mode %s" % mode) + self.assertEqual(qplan.count(leader), 1) + + def test_leader_routing_for_global_consistency_mode(self): + """ + The GLOBAL counterpart of the test above: with the same setup and the + same consistency level, the leader is pulled to the front of the plan + even though it is the farther replica. + """ + policy, leader, other_replica = self._make_leader_routing_setup( + consistency_mode=_ConsistencyMode.GLOBAL) + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + query.consistency_level = ConsistencyLevel.LOCAL_QUORUM + qplan = list(policy.make_query_plan(None, query)) + + self.assertEqual(qplan[0], leader) + self.assertEqual(qplan.count(leader), 1) + + def test_leader_routing_is_on_by_default(self): + # Leader-aware routing is not opt-in: a user who never heard of the + # option still gets the leader-first plan for a strongly-consistent + # table, which is what makes the feature useful by default. + assert TokenAwarePolicy(RoundRobinPolicy())._prefer_tablet_leader is True + + def test_leader_routing_can_be_disabled(self): + """ + With the option off, a strongly-consistent table gets plain token-aware + ordering: the closer replica comes first and the leader is not front-run, + even at a consistency level that the leader would otherwise coordinate. + """ + policy, leader, other_replica = self._make_leader_routing_setup( + prefer_tablet_leader=False) + query = Statement(routing_key=b'\x00\x00\x00\x01', keyspace='ks', table='tbl') + query.consistency_level = ConsistencyLevel.LOCAL_QUORUM + qplan = list(policy.make_query_plan(None, query)) + + self.assertEqual(qplan[0], other_replica) + # The leader is still a replica of the tablet, so it stays in the plan -- + # it just no longer jumps the queue. + self.assertEqual(qplan.count(leader), 1) + + @patch('cassandra.policies.shuffle') + def test_no_shuffle_for_serial_consistency(self, patched_shuffle): + """ + Test to validate that replicas are not shuffled when the statement + has SERIAL or LOCAL_SERIAL consistency level, since such statements + should be routed like LWT requests. + @jira_ticket PYTHON-1394 + @expected_result shuffle should not be called for serial consistency + + @test_category policy + """ + for cl in (ConsistencyLevel.SERIAL, ConsistencyLevel.LOCAL_SERIAL): + for cluster in (self._prepare_cluster_with_vnodes(), self._prepare_cluster_with_tablets()): + patched_shuffle.reset_mock() + hosts = cluster.metadata.all_hosts() + child_policy = Mock() + child_policy.make_query_plan.return_value = hosts + child_policy.distance.return_value = HostDistance.LOCAL + + policy = TokenAwarePolicy(child_policy, shuffle_replicas=True) + policy.populate(cluster, hosts) + + query = Statement(routing_key='routing_key') + query.consistency_level = cl + list(policy.make_query_plan('keyspace', query)) + assert patched_shuffle.call_count == 0, \ + "shuffle should not be called for consistency level %s" % cl + class ConvictionPolicyTest(unittest.TestCase): def test_not_implemented(self): @@ -1389,6 +1839,35 @@ def test_unavailable(self): assert retry == RetryPolicy.RETRY assert consistency == ConsistencyLevel.ONE + def test_serial_consistency_not_downgraded(self): + """ + Test that SERIAL/LOCAL_SERIAL consistency is never downgraded + to a non-serial consistency level by the retry policy. + @jira_ticket PYTHON-1394 + @expected_result retry policy should rethrow or retry on next host + without downgrading serial consistency + + @test_category policy + """ + policy = DowngradingConsistencyRetryPolicy() + + for cl in (ConsistencyLevel.SERIAL, ConsistencyLevel.LOCAL_SERIAL): + # on_read_timeout should rethrow for serial consistency + retry, consistency = policy.on_read_timeout( + query=None, consistency=cl, required_responses=3, + received_responses=1, data_retrieved=True, retry_num=0) + assert retry == RetryPolicy.RETHROW, \ + "Expected RETHROW for serial consistency %s on read timeout" % cl + assert consistency is None + + # on_unavailable should retry on next host without downgrading + retry, consistency = policy.on_unavailable( + query=None, consistency=cl, required_replicas=3, + alive_replicas=1, retry_num=0) + assert retry == RetryPolicy.RETRY_NEXT_HOST, \ + "Expected RETRY_NEXT_HOST for serial consistency %s on unavailable" % cl + assert consistency is None + class ExponentialRetryPolicyTest(unittest.TestCase): def test_calculate_backoff(self): diff --git a/tests/unit/test_protocol.py b/tests/unit/test_protocol.py index 9704811239..75dc69bca5 100644 --- a/tests/unit/test_protocol.py +++ b/tests/unit/test_protocol.py @@ -12,20 +12,22 @@ # See the License for the specific language governing permissions and # limitations under the License. +import io +import struct import unittest +from typing import ClassVar from unittest.mock import Mock -from cassandra import ProtocolVersion, UnsupportedOperation +from cassandra import ConsistencyLevel, ProtocolVersion, UnsupportedOperation from cassandra.protocol import ( - PrepareMessage, QueryMessage, ExecuteMessage, UnsupportedOperation, - _PAGING_OPTIONS_FLAG, _WITH_SERIAL_CONSISTENCY_FLAG, - _PAGE_SIZE_FLAG, _WITH_PAGING_STATE_FLAG, - BatchMessage + PrepareMessage, QueryMessage, ExecuteMessage, + BatchMessage, StartupMessage, OptionsMessage, RegisterMessage, + AuthResponseMessage, ProtocolHandler, _MessageType, + ResultMessage, RESULT_KIND_ROWS ) +from cassandra.protocol_features import ProtocolFeatures from cassandra.query import BatchType -from cassandra.marshal import uint32_unpack -from cassandra.cluster import ContinuousPagingOptions import pytest @@ -68,6 +70,253 @@ def test_execute_message(self): (b'\x00\x04',), (b'\x00\x00\x00\x01',), (b'\x00\x00',)]) + def test_execute_message_skip_meta_flag_with_extension(self): + """ + skip_meta=True must set _SKIP_METADATA_FLAG (0x02) in the flags byte when + the connection negotiated SCYLLA_USE_METADATA_ID, and the metadata id + field must be written on the wire. + """ + message = ExecuteMessage('1', [], 4, skip_meta=True, result_metadata_id=b'foo') + mock_io = Mock() + + message.send_body(mock_io, 4, ProtocolFeatures(use_metadata_id=True)) + # flags byte should be VALUES_FLAG | SKIP_METADATA_FLAG = 0x01 | 0x02 = 0x03 + self._check_calls(mock_io, [(b'\x00\x01',), (b'1',), + (b'\x00\x03',), (b'foo',), + (b'\x00\x04',), (b'\x03',), (b'\x00\x00',)]) + + def test_execute_message_skip_meta_suppressed_without_extension(self): + """ + skip_meta=True must NOT reach the wire on a pre-v5 connection that did not + negotiate SCYLLA_USE_METADATA_ID: without the metadata-id mechanism, a + schema change after PREPARE would leave the driver decoding rows with + stale cached metadata. The metadata id field must not be written either. + """ + message = ExecuteMessage('1', [], 4, skip_meta=True, result_metadata_id=b'foo') + mock_io = Mock() + + message.send_body(mock_io, 4) + # flags byte contains only VALUES_FLAG; no metadata id field + self._check_calls(mock_io, [(b'\x00\x01',), (b'1',), (b'\x00\x04',), (b'\x01',), (b'\x00\x00',)]) + + def test_execute_message_v5_native_skip_meta_not_set(self): + """ + On a native protocol v5 connection (no Scylla extension), skip_meta=True must + NOT set _SKIP_METADATA_FLAG. Upstream never emitted the flag on any version, and + this PR keeps native v5 byte-identical to upstream — enabling skip on native v5 is + a separate, out-of-scope behavior change. The metadata id field is still written + (it is part of the v5 EXECUTE frame layout), so only VALUES_FLAG is set. + """ + message = ExecuteMessage('1', [], 4, skip_meta=True) + mock_io = Mock() + + message.send_body(mock_io, 5) + # v5 wire layout: + # query_id: short(1) + b'1' + # result_metadata_id: short(0) + b'' (sentinel — None on init) + # consistency: short(4) = ONE + # flags (4-byte int): VALUES_FLAG(0x01) only — skip is NOT set on native v5 + # param count: short(0) + self._check_calls(mock_io, [ + (b'\x00\x01',), (b'1',), + (b'\x00\x00',), (b'',), + (b'\x00\x04',), + (b'\x00\x00\x00\x01',), (b'\x00\x00',), + ]) + + def test_execute_message_v5_with_extension_sets_skip_flag(self): + """ + skip is extension-driven, not version-driven: on a v5 connection that ALSO + negotiated SCYLLA_USE_METADATA_ID, skip_meta=True does set _SKIP_METADATA_FLAG. + This also confirms _SKIP_METADATA_FLAG actually reaches the wire (it was dead code + upstream) whenever the extension gates it on. + """ + message = ExecuteMessage('1', [], 4, skip_meta=True) + mock_io = Mock() + + message.send_body(mock_io, 5, ProtocolFeatures(use_metadata_id=True)) + # flags (4-byte int): VALUES_FLAG(0x01) | SKIP_METADATA_FLAG(0x02) = 0x03 + self._check_calls(mock_io, [ + (b'\x00\x01',), (b'1',), + (b'\x00\x00',), (b'',), + (b'\x00\x04',), + (b'\x00\x00\x00\x03',), (b'\x00\x00',), + ]) + + def test_execute_message_scylla_metadata_id_v4(self): + """result_metadata_id should be written on protocol v4 when the connection negotiated the Scylla extension.""" + message = ExecuteMessage('1', [], 4, result_metadata_id=b'foo') + mock_io = Mock() + + message.send_body(mock_io, 4, ProtocolFeatures(use_metadata_id=True)) + # metadata_id written before query params (same position as v5) + self._check_calls(mock_io, [(b'\x00\x01',), (b'1',), + (b'\x00\x03',), (b'foo',), + (b'\x00\x04',), (b'\x01',), (b'\x00\x00',)]) + + def test_execute_message_scylla_metadata_id_none_writes_sentinel(self): + """ + When the connection negotiated the extension but result_metadata_id is None + (e.g. LWT statement or mixed cluster), send_body must still write the field + as an empty string sentinel (\\x00\\x00) so the frame layout matches what + the server expects. + """ + message = ExecuteMessage('1', [], 4) + # result_metadata_id intentionally left as None + mock_io = Mock() + + message.send_body(mock_io, 4, ProtocolFeatures(use_metadata_id=True)) + # empty sentinel: \x00\x00 (zero-length short) + b'' (zero bytes), then normal query params + self._check_calls(mock_io, [(b'\x00\x01',), (b'1',), + (b'\x00\x00',), (b'',), + (b'\x00\x04',), (b'\x01',), (b'\x00\x00',)]) + + def test_execute_message_v5_metadata_id_none_writes_sentinel(self): + """ + On protocol v5, result_metadata_id is always written (uses_prepared_metadata). + When result_metadata_id is None (e.g. LWT statement or mixed cluster where the + statement was prepared before the extension was active), send_body must write an + empty sentinel instead of crashing with TypeError. + """ + message = ExecuteMessage('1', [], 4) + # result_metadata_id intentionally left as None; use_metadata_id stays False (v5 native path) + mock_io = Mock() + + message.send_body(mock_io, 5) + # v5 always writes metadata_id: None → empty sentinel \x00\x00 + b'', then query params + # v5 uses 4-byte flags: VALUES_FLAG = \x00\x00\x00\x01 + self._check_calls(mock_io, [(b'\x00\x01',), (b'1',), + (b'\x00\x00',), (b'',), + (b'\x00\x04',), + (b'\x00\x00\x00\x01',), (b'\x00\x00',)]) + + def test_recv_results_prepared_scylla_extension_reads_metadata_id(self): + """ + When use_metadata_id is True (Scylla extension), result_metadata_id must be + read from the PREPARE response even for protocol v4. + """ + # Build a minimal valid PREPARE response binary (no bind/result columns): + # query_id: short(2) + b'ab' + # result_metadata_id: short(3) + b'xyz' <-- only present when extension active + # prepared flags: int(1) = global_tables_spec + # colcount: int(0) + # num_pk_indexes: int(0) + # ksname: short(2) + b'ks' + # cfname: short(2) + b'tb' + # result flags: int(4) = no_metadata + # result colcount: int(0) + buf = io.BytesIO( + struct.pack('>H', 2) + b'ab' # query_id + + struct.pack('>H', 3) + b'xyz' # result_metadata_id + + struct.pack('>i', 1) # prepared flags: global_tables_spec + + struct.pack('>i', 0) # colcount = 0 + + struct.pack('>i', 0) # num_pk_indexes = 0 + + struct.pack('>H', 2) + b'ks' # ksname + + struct.pack('>H', 2) + b'tb' # cfname + + struct.pack('>i', 4) # result flags: no_metadata + + struct.pack('>i', 0) # result colcount = 0 + ) + + features_with_extension = ProtocolFeatures(use_metadata_id=True) + msg = ResultMessage(kind=4) # RESULT_KIND_PREPARED = 4 + msg.recv_results_prepared(buf, protocol_version=4, + protocol_features=features_with_extension, + user_type_map={}) + assert msg.query_id == b'ab' + assert msg.result_metadata_id == b'xyz' + + def test_recv_results_prepared_no_extension_skips_metadata_id(self): + """ + Without use_metadata_id, result_metadata_id must NOT be read on protocol v4. + The buffer must NOT contain a metadata_id field. + """ + buf = io.BytesIO( + struct.pack('>H', 2) + b'ab' # query_id + # no result_metadata_id + + struct.pack('>i', 1) # prepared flags: global_tables_spec + + struct.pack('>i', 0) # colcount = 0 + + struct.pack('>i', 0) # num_pk_indexes = 0 + + struct.pack('>H', 2) + b'ks' # ksname + + struct.pack('>H', 2) + b'tb' # cfname + + struct.pack('>i', 4) # result flags: no_metadata + + struct.pack('>i', 0) # result colcount = 0 + ) + + features_without_extension = ProtocolFeatures(use_metadata_id=False) + msg = ResultMessage(kind=4) + msg.recv_results_prepared(buf, protocol_version=4, + protocol_features=features_without_extension, + user_type_map={}) + assert msg.query_id == b'ab' + assert msg.result_metadata_id is None + + def test_recv_results_prepared_v5_reads_metadata_id(self): + """ + On protocol v5, ProtocolVersion.uses_prepared_metadata() is True, so + result_metadata_id must be read from the PREPARE response even when + use_metadata_id is False (native v5 path, not the Scylla extension). + """ + buf = io.BytesIO( + struct.pack('>H', 2) + b'ab' # query_id + + struct.pack('>H', 3) + b'xyz' # result_metadata_id (always present on v5) + + struct.pack('>i', 1) # prepared flags: global_tables_spec + + struct.pack('>i', 0) # colcount = 0 + + struct.pack('>i', 0) # num_pk_indexes = 0 + + struct.pack('>H', 2) + b'ks' # ksname + + struct.pack('>H', 2) + b'tb' # cfname + + struct.pack('>i', 4) # result flags: no_metadata + + struct.pack('>i', 0) # result colcount = 0 + ) + + features_no_extension = ProtocolFeatures(use_metadata_id=False) + msg = ResultMessage(kind=4) # RESULT_KIND_PREPARED = 4 + msg.recv_results_prepared(buf, protocol_version=5, + protocol_features=features_no_extension, + user_type_map={}) + assert msg.query_id == b'ab' + assert msg.result_metadata_id == b'xyz' + + def test_recv_results_metadata_reads_metadata_id_on_change(self): + """ + When _METADATA_ID_FLAG (0x0008) is set in a ROWS result, + recv_results_metadata must read and store the new result_metadata_id + sent by the server (METADATA_CHANGED signal), and still populate + column_metadata normally. + """ + # Wire layout for a ROWS result with METADATA_CHANGED: + # flags: int(0x0008) = _METADATA_ID_FLAG + # colcount: int(0) + # result_metadata_id: short(4) + b'new1' + # (no columns — colcount=0 — to keep the buffer minimal) + buf = io.BytesIO( + struct.pack('>i', 0x0008) # flags: METADATA_ID_FLAG + + struct.pack('>i', 0) # colcount = 0 + + struct.pack('>H', 4) + b'new1' # result_metadata_id = b'new1' + ) + msg = ResultMessage(kind=RESULT_KIND_ROWS) + msg.recv_results_metadata(buf, user_type_map={}) + assert msg.result_metadata_id == b'new1' + assert msg.column_metadata == [] + + def test_recv_results_metadata_no_metadata_flag_skips_metadata_id(self): + """ + When _NO_METADATA_FLAG (0x0004) is set, recv_results_metadata returns + early and must NOT read or set result_metadata_id, even if the caller + mistakenly sets _METADATA_ID_FLAG alongside it. + """ + # flags = _NO_METADATA_FLAG (0x0004), colcount = 0 + buf = io.BytesIO( + struct.pack('>i', 0x0004) # flags: NO_METADATA + + struct.pack('>i', 0) # colcount = 0 + ) + msg = ResultMessage(kind=RESULT_KIND_ROWS) + msg.recv_results_metadata(buf, user_type_map={}) + # recv_results_metadata returns early on NO_METADATA; result_metadata_id + # must never be set as an instance attribute (it is not a class default). + # column_metadata is a class attribute defaulting to None and must remain so. + assert not hasattr(msg, 'result_metadata_id') + assert msg.column_metadata is None + def test_query_message(self): """ Test to check the appropriate calls are made @@ -189,3 +438,120 @@ def test_batch_message_with_keyspace(self): (b'\x00\x03',), (b'\x00\x00\x00\x80',), (b'\x00\x02',), (b'ks',)) ) + + +class ProtocolFeaturesPlumbingTest(unittest.TestCase): + """ + The negotiated ProtocolFeatures must flow from encode_message into each + message's send_body, so serialization can emit fields belonging to + protocol extensions exactly on the connections that negotiated them. + """ + + class CapturingMessage(_MessageType): + opcode = 0x00 + name = 'CAPTURE' + + def __init__(self): + self.seen_features = [] + + def send_body(self, f, protocol_version, protocol_features=None): + self.seen_features.append(protocol_features) + + def test_encode_message_forwards_protocol_features_to_send_body(self): + features = ProtocolFeatures() + msg = self.CapturingMessage() + ProtocolHandler.encode_message(msg, stream_id=0, protocol_version=4, compressor=None, + allow_beta_protocol_version=False, protocol_features=features) + assert msg.seen_features == [features] + assert msg.seen_features[0] is features + + def test_encode_message_forwards_protocol_features_when_compressing(self): + features = ProtocolFeatures() + msg = self.CapturingMessage() + ProtocolHandler.encode_message(msg, stream_id=0, protocol_version=4, compressor=lambda body: body, + allow_beta_protocol_version=False, protocol_features=features) + assert msg.seen_features[0] is features + + def test_encode_message_fails_without_protocol_features(self): + msg = self.CapturingMessage() + + with pytest.raises(TypeError, match='positional argument'): + ProtocolHandler.encode_message(msg, stream_id=0, protocol_version=4, compressor=None, + allow_beta_protocol_version=False) + + +class FrameByteIdentityTest(unittest.TestCase): + """ + Threading ProtocolFeatures into serialization is pure plumbing: with no + extension consuming it (and for all-default features), every frame must be + byte-identical to what the driver produced before the parameter existed. + The expected frames below were captured from the pre-change encoder. + """ + + EXPECTED_FRAMES: ClassVar[dict] = { + 'startup_v4': '0400000701000000160001000b43514c5f56455253494f4e0005332e342e35', + 'options_v4': '040000070500000000', + 'register_v4': '040000070b000000220002000f544f504f4c4f47595f4348414e4745000d5354415455535f4348414e4745', + 'auth_response_v4': '040000070f0000000e0000000a00757365720070617373', + 'prepare_v4': '0400000709000000220000001e53454c454354202a2046524f4d206b732e74205748455245206b203d203f', + 'prepare_v5_keyspace': '0500000709000000270000001b53454c454354202a2046524f4d2074205748455245206b203d203f0000000100026b73', + 'query_v3': '0300000707000000270000001253454c454354202a2046524f4d206b732e74000434000013880008000462d53c8abac0', + 'execute_v3': '030000070a00000033000412345678000a2d000200000002000100000003616263000000640000000b504147494e475354415445000000003ade68b1', + 'batch_v3': '030000070d00000043000002000000001f494e5345525420494e544f206b732e7420286b292056414c5545532028312900000100041234567800010000000200020001200000000006a11e3d', + 'query_v4': '0400000707000000270000001253454c454354202a2046524f4d206b732e74000434000013880008000462d53c8abac0', + 'execute_v4': '040000070a00000033000412345678000a2d000200000002000100000003616263000000640000000b504147494e475354415445000000003ade68b1', + 'batch_v4': '040000070d00000043000002000000001f494e5345525420494e544f206b732e7420286b292056414c5545532028312900000100041234567800010000000200020001200000000006a11e3d', + 'query_v5': '05000007070000002a0000001253454c454354202a2046524f4d206b732e74000400000034000013880008000462d53c8abac0', + 'execute_v5': '050000070a0000003c0004123456780004aabbccdd000a0000002d000200000002000100000003616263000000640000000b504147494e475354415445000000003ade68b1', + 'batch_v5': '050000070d00000046000002000000001f494e5345525420494e544f206b732e7420286b292056414c5545532028312900000100041234567800010000000200020001000000200000000006a11e3d', + } + + @staticmethod + def _make_cases(): + cases = [ + ('startup_v4', StartupMessage(cqlversion="3.4.5", options={}), 4), + ('options_v4', OptionsMessage(), 4), + ('register_v4', RegisterMessage(["TOPOLOGY_CHANGE", "STATUS_CHANGE"]), 4), + ('auth_response_v4', AuthResponseMessage(b"\x00user\x00pass"), 4), + ('prepare_v4', PrepareMessage("SELECT * FROM ks.t WHERE k = ?"), 4), + ('prepare_v5_keyspace', PrepareMessage("SELECT * FROM t WHERE k = ?", keyspace="ks"), 5), + ] + for pv in (3, 4, 5): + cases.append(( + 'query_v%d' % pv, + QueryMessage("SELECT * FROM ks.t", ConsistencyLevel.QUORUM, + serial_consistency_level=ConsistencyLevel.SERIAL, + fetch_size=5000, timestamp=1234567890123456), + pv, + )) + cases.append(( + 'execute_v%d' % pv, + ExecuteMessage(b"\x12\x34\x56\x78", [b"\x00\x01", b"abc"], + ConsistencyLevel.LOCAL_ONE, fetch_size=100, + paging_state=b"PAGINGSTATE", + result_metadata_id=b"\xaa\xbb\xcc\xdd" if pv >= 5 else None, + timestamp=987654321), + pv, + )) + cases.append(( + 'batch_v%d' % pv, + BatchMessage(BatchType.LOGGED, + [(False, "INSERT INTO ks.t (k) VALUES (1)", []), + (True, b"\x12\x34\x56\x78", [b"\x00\x02"])], + ConsistencyLevel.ONE, timestamp=111222333), + pv, + )) + return cases + + def _assert_frames(self, protocol_features): + for name, msg, pv in self._make_cases(): + frame = ProtocolHandler.encode_message( + msg, stream_id=7, protocol_version=pv, compressor=None, + allow_beta_protocol_version=False, protocol_features=protocol_features) + assert frame.hex() == self.EXPECTED_FRAMES[name], name + + def test_frames_without_features(self): + self._assert_frames(None) + + def test_frames_with_default_features(self): + self._assert_frames(ProtocolFeatures()) diff --git a/tests/unit/test_protocol_features.py b/tests/unit/test_protocol_features.py index 895c384f7e..915f8b84fd 100644 --- a/tests/unit/test_protocol_features.py +++ b/tests/unit/test_protocol_features.py @@ -2,7 +2,7 @@ import logging -from cassandra.protocol_features import ProtocolFeatures +from cassandra.protocol_features import ProtocolFeatures, TABLETS_ROUTING_V1, TABLETS_ROUTING_V2 LOGGER = logging.getLogger(__name__) @@ -22,3 +22,80 @@ class OptionsHolder(object): assert protocol_features.rate_limit_error == 123 assert protocol_features.shard_id == 0 assert protocol_features.sharding_info is None + + def test_use_metadata_id_parsing(self): + """ + Test that SCYLLA_USE_METADATA_ID is parsed from SUPPORTED options. + """ + options = {'SCYLLA_USE_METADATA_ID': ['']} + protocol_features = ProtocolFeatures.parse_from_supported(options) + assert protocol_features.use_metadata_id is True + + def test_use_metadata_id_missing(self): + """ + Test that use_metadata_id is False when SCYLLA_USE_METADATA_ID is absent. + """ + options = {'SCYLLA_RATE_LIMIT_ERROR': ['ERROR_CODE=1']} + protocol_features = ProtocolFeatures.parse_from_supported(options) + assert protocol_features.use_metadata_id is False + + def test_use_metadata_id_startup_options(self): + """ + Test that SCYLLA_USE_METADATA_ID is included in STARTUP options when negotiated. + """ + options = {'SCYLLA_USE_METADATA_ID': ['']} + protocol_features = ProtocolFeatures.parse_from_supported(options) + startup = {} + protocol_features.add_startup_options(startup) + assert 'SCYLLA_USE_METADATA_ID' in startup + + def test_use_metadata_id_not_in_startup_when_not_negotiated(self): + """ + Test that SCYLLA_USE_METADATA_ID is NOT included in STARTUP when not negotiated. + """ + protocol_features = ProtocolFeatures.parse_from_supported({}) + startup = {} + protocol_features.add_startup_options(startup) + assert 'SCYLLA_USE_METADATA_ID' not in startup + + def test_tablets_routing_v2_negotiation(self): + """V2 is detected from SUPPORTED and subsumes V1 in STARTUP options.""" + options = { + TABLETS_ROUTING_V1: [''], + TABLETS_ROUTING_V2: [''], + } + features = ProtocolFeatures.parse_from_supported(options) + assert features.tablets_routing_v1 is True + assert features.tablets_routing_v2 is True + + # V2 subsumes V1: only TABLETS_ROUTING_V2 should appear in startup. + startup = {} + features.add_startup_options(startup) + assert TABLETS_ROUTING_V2 in startup + assert TABLETS_ROUTING_V1 not in startup + + def test_tablets_routing_v1_only(self): + """When server only advertises V1, only V1 is negotiated.""" + options = { + TABLETS_ROUTING_V1: [''], + } + features = ProtocolFeatures.parse_from_supported(options) + assert features.tablets_routing_v1 is True + assert features.tablets_routing_v2 is False + + startup = {} + features.add_startup_options(startup) + assert TABLETS_ROUTING_V1 in startup + assert TABLETS_ROUTING_V2 not in startup + + def test_no_tablets_routing(self): + """When server advertises neither V1 nor V2.""" + options = {} + features = ProtocolFeatures.parse_from_supported(options) + assert features.tablets_routing_v1 is False + assert features.tablets_routing_v2 is False + + startup = {} + features.add_startup_options(startup) + assert TABLETS_ROUTING_V1 not in startup + assert TABLETS_ROUTING_V2 not in startup diff --git a/tests/unit/test_query.py b/tests/unit/test_query.py index 6b0ebe690e..1bbe069667 100644 --- a/tests/unit/test_query.py +++ b/tests/unit/test_query.py @@ -14,6 +14,8 @@ import unittest +import pytest + from cassandra.query import BatchStatement, PreparedStatement, SimpleStatement @@ -115,3 +117,53 @@ def is_lwt(self): batch_with_simple = BatchStatement() batch_with_simple.add(LwtSimpleStatement()) assert batch_with_simple.is_lwt() is True + + +class PreparedStatementMetadataPairTest(unittest.TestCase): + """ + result_metadata and result_metadata_id are stored as one tuple replaced in a + single attribute assignment: response callbacks update a statement while + request threads read it, and a torn pair (fresh id + stale metadata) would + make the server skip sending metadata while rows are decoded against the + wrong columns. + """ + + @staticmethod + def _make_statement(result_metadata, result_metadata_id): + return PreparedStatement( + column_metadata=[], query_id=b'qid', routing_key_indexes=None, + query="SELECT * FROM foo", keyspace='ks', protocol_version=4, + result_metadata=result_metadata, result_metadata_id=result_metadata_id) + + def test_constructor_sets_pair(self): + meta = [('ks', 'tb', 'col', None)] + ps = self._make_statement(meta, b'hash') + assert ps.result_metadata is meta + assert ps.result_metadata_id == b'hash' + assert ps.result_metadata_and_id == (meta, b'hash') + + def test_update_replaces_pair_atomically(self): + ps = self._make_statement([('ks', 'tb', 'old', None)], b'old') + snapshot_before = ps.result_metadata_and_id + + new_meta = [('ks', 'tb', 'new', None)] + ps.update_result_metadata(new_meta, b'new') + + # a snapshot taken before the update stays internally consistent + assert snapshot_before == ([('ks', 'tb', 'old', None)], b'old') + assert ps.result_metadata_and_id == (new_meta, b'new') + + def test_halves_of_the_pair_cannot_be_assigned_individually(self): + # Assigning one half alone would leave the other stale, which is exactly + # the torn state update_result_metadata() exists to prevent, so neither + # attribute is writable. + meta = [('ks', 'tb', 'col', None)] + ps = self._make_statement(meta, b'hash') + + with pytest.raises(AttributeError): + ps.result_metadata_id = b'other' + + with pytest.raises(AttributeError): + ps.result_metadata = [] + + assert ps.result_metadata_and_id == (meta, b'hash') diff --git a/tests/unit/test_response_future.py b/tests/unit/test_response_future.py index 7168ad2940..d71943ec04 100644 --- a/tests/unit/test_response_future.py +++ b/tests/unit/test_response_future.py @@ -16,13 +16,14 @@ from collections import deque from threading import RLock -from unittest.mock import Mock, MagicMock, ANY +from unittest.mock import Mock, MagicMock, ANY, patch from cassandra import ConsistencyLevel, Unavailable, SchemaTargetType, SchemaChangeType, OperationTimedOut -from cassandra.cluster import Session, ResponseFuture, NoHostAvailable, ProtocolVersion +from cassandra.cluster import Session, ResponseFuture, NoHostAvailable, ProtocolVersion, ControlConnectionQueryFallback from cassandra.connection import Connection, ConnectionException from cassandra.protocol import (ReadTimeoutErrorMessage, WriteTimeoutErrorMessage, UnavailableErrorMessage, ResultMessage, QueryMessage, + ExecuteMessage, OverloadedErrorMessage, IsBootstrappingErrorMessage, PreparedQueryNotFound, PrepareMessage, ServerError, RESULT_KIND_ROWS, RESULT_KIND_SET_KEYSPACE, @@ -30,7 +31,7 @@ ProtocolHandler) from cassandra.policies import RetryPolicy, ExponentialBackoffRetryPolicy from cassandra.pool import NoConnectionsAvailable -from cassandra.query import SimpleStatement +from cassandra.query import SimpleStatement, PreparedStatement, BoundStatement from tests.util import assertEqual, assertIsInstance import pytest @@ -40,7 +41,7 @@ class ResponseFutureTests(unittest.TestCase): def make_basic_session(self): s = Mock(spec=Session) s.row_factory = lambda col_names, rows: [(col_names, rows)] - s.cluster.control_connection._tablets_routing_v1 = False + s.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.Disabled return s def make_pool(self): @@ -49,6 +50,27 @@ def make_pool(self): pool.borrow_connection.return_value = [Mock(), Mock()] return pool + def make_control_connection(self): + connection = Mock(spec=Connection) + connection.endpoint = 'control-host' + connection.lock = RLock() + connection.in_flight = 0 + connection.max_request_id = 100 + connection.request_ids = deque() + connection._requests = {} + connection.orphaned_request_ids = set() + connection.orphaned_threshold = 75 + connection.orphaned_threshold_reached = False + connection.is_control_connection = True + connection.get_request_id.return_value = 7 + connection.send_msg.return_value = 128 + # These tests exercise control-connection query fallback, not tablet + # routing; default the tablet features off so _set_result skips + # tablet-payload parsing for the mocked responses. + connection.features.tablets_routing_v2 = False + connection.features.tablets_routing_v1 = False + return connection + def make_session(self): session = self.make_basic_session() session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1', 'ip2'] @@ -76,7 +98,7 @@ def test_result_message(self): rf.send_request() rf.session._pools.get.assert_called_once_with('ip1') - pool.borrow_connection.assert_called_once_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY) + pool.borrow_connection.assert_called_once_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY, routing_token=ANY) connection.send_msg.assert_called_once_with(rf.message, 1, cb=ANY, encoder=ProtocolHandler.encode_message, decoder=ProtocolHandler.decode_message, result_metadata=[]) @@ -120,6 +142,9 @@ def test_schema_change_result(self): kind=RESULT_KIND_SCHEMA_CHANGE, schema_change_event=event_results) connection = Mock() + # Skip tablet-payload parsing for this mocked response/connection pair. + connection.features.tablets_routing_v2 = False + connection.features.tablets_routing_v1 = False rf._set_result(None, connection, None, result) session.submit.assert_called_once_with(ANY, ANY, rf, connection, **event_results) @@ -142,6 +167,8 @@ def test_heartbeat_defunct_deadlock(self): connection = MagicMock(spec=Connection) connection._requests = {} + connection.in_flight = 5 + connection.orphaned_request_ids = set() pool = Mock() pool.is_shutdown = False @@ -162,8 +189,10 @@ def test_heartbeat_defunct_deadlock(self): # Simulate ResponseFuture timing out rf._on_timeout() - with pytest.raises(OperationTimedOut, match="Connection defunct by heartbeat"): + with pytest.raises(OperationTimedOut, match="Connection defunct by heartbeat") as exc_info: rf.result() + assert exc_info.value.timeout == 1 + assert exc_info.value.in_flight == 5 def test_read_timeout_error_message(self): session = self.make_session() @@ -263,7 +292,7 @@ def test_retry_policy_says_retry(self): rf.send_request() rf.session._pools.get.assert_called_once_with('ip1') - pool.borrow_connection.assert_called_once_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY) + pool.borrow_connection.assert_called_once_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY, routing_token=ANY) connection.send_msg.assert_called_once_with(rf.message, 1, cb=ANY, encoder=ProtocolHandler.encode_message, decoder=ProtocolHandler.decode_message, result_metadata=[]) result = Mock(spec=UnavailableErrorMessage, info={}) @@ -282,7 +311,7 @@ def test_retry_policy_says_retry(self): # it should try again with the same host since this was # an UnavailableException rf.session._pools.get.assert_called_with(host) - pool.borrow_connection.assert_called_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY) + pool.borrow_connection.assert_called_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY, routing_token=ANY) connection.send_msg.assert_called_with(rf.message, 2, cb=ANY, encoder=ProtocolHandler.encode_message, decoder=ProtocolHandler.decode_message, result_metadata=[]) def test_retry_with_different_host(self): @@ -297,7 +326,7 @@ def test_retry_with_different_host(self): rf.send_request() rf.session._pools.get.assert_called_once_with('ip1') - pool.borrow_connection.assert_called_once_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY) + pool.borrow_connection.assert_called_once_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY, routing_token=ANY) connection.send_msg.assert_called_once_with(rf.message, 1, cb=ANY, encoder=ProtocolHandler.encode_message, decoder=ProtocolHandler.decode_message, result_metadata=[]) assert ConsistencyLevel.QUORUM == rf.message.consistency_level @@ -316,7 +345,7 @@ def test_retry_with_different_host(self): # it should try with a different host rf.session._pools.get.assert_called_with('ip2') - pool.borrow_connection.assert_called_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY) + pool.borrow_connection.assert_called_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY, routing_token=ANY) connection.send_msg.assert_called_with(rf.message, 2, cb=ANY, encoder=ProtocolHandler.encode_message, decoder=ProtocolHandler.decode_message, result_metadata=[]) # the consistency level should be the same @@ -387,6 +416,268 @@ def test_all_pools_shutdown(self): with pytest.raises(NoHostAvailable): rf.result() + def test_control_connection_fallback_disabled_by_default(self): + session = self.make_basic_session() + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + session._pools = {} + connection = self.make_control_connection() + session.cluster.control_connection._connection = connection + + rf = self.make_response_future(session) + rf.send_request() + + connection.send_msg.assert_not_called() + with pytest.raises(NoHostAvailable): + rf.result() + + def test_control_connection_fallback_updates_connection_keyspace(self): + session = self.make_basic_session() + session.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.Fallback + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + session._pools = {} + + def set_keyspace_for_all_pools(keyspace, callback): + session.keyspace = keyspace + callback({}) + + session._set_keyspace_for_all_pools.side_effect = set_keyspace_for_all_pools + + connection = self.make_control_connection() + connection.keyspace = 'oldks' + session.cluster.control_connection._connection = connection + control_host = Mock(endpoint=connection.endpoint) + session.cluster.get_control_connection_host.return_value = control_host + + rf = self.make_response_future(session) + assert rf.send_request() + + result = Mock(spec=ResultMessage, kind=RESULT_KIND_SET_KEYSPACE, new_keyspace='newks') + connection.send_msg.call_args[1]['cb'](result) + + assert connection.keyspace == 'newks' + assert session.keyspace == 'newks' + assert rf.result().current_rows == [] + + def test_control_connection_fallback_when_no_usable_pools(self): + session = self.make_basic_session() + session.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.SkipPoolCreation + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1', 'ip2'] + session._pools = {} + connection = self.make_control_connection() + session.cluster.control_connection._connection = connection + control_host = Mock(endpoint=connection.endpoint) + session.cluster.get_control_connection_host.return_value = control_host + + rf = self.make_response_future(session) + assert rf.send_request() + + connection.send_msg.assert_called_once_with( + rf.message, 7, cb=ANY, encoder=ProtocolHandler.encode_message, + decoder=ProtocolHandler.decode_message, result_metadata=[]) + assert connection.in_flight == 1 + assert rf.attempted_hosts == [control_host] + + cb = connection.send_msg.call_args[1]['cb'] + expected_result = (object(), object()) + cb(self.make_mock_response(expected_result[0], expected_result[1])) + + assert connection.in_flight == 0 + assert rf.result()[0] == expected_result + + def test_control_connection_fallback_retries_after_server_error(self): + session = self.make_basic_session() + session.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.Fallback + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + session._pools = {} + connection = self.make_control_connection() + connection.get_request_id.side_effect = [7, 8] + session.cluster.control_connection._connection = connection + control_host = Mock(endpoint=connection.endpoint) + session.cluster.get_control_connection_host.return_value = control_host + + rf = self.make_response_future(session) + assert rf.send_request() + + first_response = Mock(spec=ServerError, info={}) + first_response.summary = 'boom' + first_response.to_exception.return_value = first_response + connection.send_msg.call_args[1]['cb'](first_response) + + rf.session.cluster.scheduler.schedule.assert_called_once_with(ANY, rf._retry_task, False, control_host) + + # The retry decision must come from the future state, not the live connection reference. + rf._connection = Mock(is_control_connection=False) + + rf._retry_task(False, control_host) + + assert connection.send_msg.call_count == 2 + assert connection.send_msg.call_args_list[1][0][0] is rf.message + assert connection.send_msg.call_args_list[1][0][1] == 8 + assert rf.attempted_hosts == [control_host, control_host] + + expected_result = (object(), object()) + connection.send_msg.call_args_list[1][1]['cb']( + self.make_mock_response(expected_result[0], expected_result[1])) + + assert connection.in_flight == 0 + assert rf.result()[0] == expected_result + + def test_control_connection_fallback_fetches_next_page(self): + session = self.make_basic_session() + session.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.Fallback + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + session._pools = {} + connection = self.make_control_connection() + connection.get_request_id.side_effect = [7, 8] + session.cluster.control_connection._connection = connection + control_host = Mock(endpoint=connection.endpoint) + session.cluster.get_control_connection_host.return_value = control_host + + rf = self.make_response_future(session) + assert rf.send_request() + + first_response = self.make_mock_response(['col'], [(1,)]) + first_response.paging_state = b'next-page' + connection.send_msg.call_args[1]['cb'](first_response) + + assert rf.result().current_rows == [(['col'], [(1,)])] + assert rf.has_more_pages + + rf.start_fetching_next_page() + + assert connection.send_msg.call_count == 2 + assert connection.send_msg.call_args_list[1][0][0] is rf.message + assert connection.send_msg.call_args_list[1][0][1] == 8 + assert rf.message.paging_state == b'next-page' + + second_response = self.make_mock_response(['col'], [(2,)]) + connection.send_msg.call_args_list[1][1]['cb'](second_response) + + assert connection.in_flight == 0 + assert rf.result().current_rows == [(['col'], [(2,)])] + + def test_control_connection_fallback_reprepares_prepared_statement(self): + session = self.make_basic_session() + session.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.Fallback + session.cluster.protocol_version = ProtocolVersion.V4 + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + session._pools = {} + session.submit.side_effect = lambda fn, *args, **kwargs: fn(*args, **kwargs) + + query_id = b'a' * 16 + prepared_statement = Mock( + query_id=query_id, + query_string="SELECT * FROM foobar", + keyspace="FooKeyspace", + result_metadata=[], + result_metadata_id=None) + session.cluster._prepared_statements = {query_id: prepared_statement} + + connection = self.make_control_connection() + connection.keyspace = "FooKeyspace" + connection.get_request_id.side_effect = [7, 8, 9] + session.cluster.control_connection._connection = connection + control_host = Mock(endpoint=connection.endpoint) + session.cluster.get_control_connection_host.return_value = control_host + + rf = self.make_response_future(session) + rf.prepared_statement = prepared_statement + assert rf.send_request() + + missing = Mock(spec=PreparedQueryNotFound, info=query_id) + connection.send_msg.call_args_list[0][1]['cb'](missing) + + assert connection.send_msg.call_count == 2 + prepare_message = connection.send_msg.call_args_list[1][0][0] + assert isinstance(prepare_message, PrepareMessage) + assert prepare_message.query == "SELECT * FROM foobar" + assert connection.send_msg.call_args_list[1][0][1] == 8 + + prepared_response = Mock( + spec=ResultMessage, + kind=RESULT_KIND_PREPARED, + query_id=query_id, + column_metadata=[], + result_metadata_id=None) + connection.send_msg.call_args_list[1][1]['cb'](prepared_response) + + assert connection.send_msg.call_count == 3 + assert connection.send_msg.call_args_list[2][0][0] is rf.message + assert connection.send_msg.call_args_list[2][0][1] == 9 + + expected_result = (['col'], [(1,)]) + connection.send_msg.call_args_list[2][1]['cb']( + self.make_mock_response(expected_result[0], expected_result[1])) + + assert connection.in_flight == 0 + assert rf.result()[0] == expected_result + + def test_control_connection_fallback_not_used_when_pool_can_serve(self): + session = self.make_basic_session() + session.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.Fallback + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + pool = Mock(is_shutdown=False) + pool.borrow_connection.side_effect = NoConnectionsAvailable() + session._pools = {'ip1': pool} + connection = self.make_control_connection() + session.cluster.control_connection._connection = connection + + rf = self.make_response_future(session) + rf.send_request() + + connection.send_msg.assert_not_called() + with pytest.raises(NoHostAvailable): + rf.result() + + def test_control_connection_fallback_orphans_stream_on_timeout(self): + session = self.make_basic_session() + session.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.Fallback + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + session._pools = {} + connection = self.make_control_connection() + session.cluster.control_connection._connection = connection + + def send_msg(message, request_id, cb, **kwargs): + connection._requests[request_id] = (cb, kwargs.get('decoder'), kwargs.get('result_metadata')) + return 128 + + connection.send_msg.side_effect = send_msg + + rf = self.make_response_future(session) + rf.send_request() + rf._on_timeout() + + assert 7 in connection.orphaned_request_ids + assert connection.in_flight == 1 + with pytest.raises(OperationTimedOut): + rf.result() + + def test_control_connection_fallback_timeout_without_metadata_host_uses_connection_endpoint(self): + session = self.make_basic_session() + session.cluster.allow_control_connection_query_fallback = ControlConnectionQueryFallback.Fallback + session.cluster._default_load_balancing_policy.make_query_plan.return_value = [] + session._pools = {} + session.cluster.get_control_connection_host.return_value = None + connection = self.make_control_connection() + session.cluster.control_connection._connection = connection + + def send_msg(message, request_id, cb, **kwargs): + connection._requests[request_id] = (cb, kwargs.get('decoder'), kwargs.get('result_metadata')) + return 128 + + connection.send_msg.side_effect = send_msg + + rf = self.make_response_future(session) + assert rf.send_request() + rf._on_timeout() + + with pytest.raises(OperationTimedOut) as exc_info: + rf.result() + + assert exc_info.value.errors == { + 'control-host': 'Client request timeout. See Session.execute[_async](timeout)' + } + def test_first_pool_shutdown(self): session = self.make_basic_session() session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1', 'ip2'] @@ -628,7 +919,7 @@ def test_repeat_orig_query_after_succesful_reprepare(self): response = Mock(spec=ResultMessage, kind=RESULT_KIND_PREPARED, - result_metadata_id='foo') + result_metadata_id=b'foo') response.results = (None, None, None, None, None) response.query_id = query_id @@ -636,11 +927,83 @@ def test_repeat_orig_query_after_succesful_reprepare(self): rf._execute_after_prepare('host', None, None, response) rf._query.assert_called_once_with('host') - rf.prepared_statement = Mock() - rf.prepared_statement.query_id = query_id + rf.prepared_statement = PreparedStatement( + column_metadata=[], query_id=query_id, routing_key_indexes=None, + query="SELECT * FROM foo", keyspace='ks', protocol_version=4, + result_metadata=[], result_metadata_id=None) rf._query = Mock(return_value=True) rf._execute_after_prepare('host', None, None, response) rf._query.assert_called_once_with('host') + assert rf.prepared_statement.result_metadata_id == b'foo' + + def test_execute_after_prepare_updates_result_metadata_id(self): + """ + After a PreparedQueryNotFound triggers a reprepare, _execute_after_prepare + must update both prepared_statement.result_metadata and + prepared_statement.result_metadata_id when the PREPARE response carries a + new metadata id. Deleting those update lines must break this test. + """ + query_id = b'reprepare_qid' + session = self.make_session() + rf = self.make_response_future(session) + + new_meta = [('ks', 'tb', 'new_col', Mock())] + response = Mock(spec=ResultMessage, + kind=RESULT_KIND_PREPARED, + result_metadata_id=b'new_hash', + column_metadata=new_meta) + response.query_id = query_id + + rf.prepared_statement = self._make_prepared_statement( + [('ks', 'tb', 'old_col', Mock())], b'old_hash', query_id=query_id) + # Pretend the anomaly warning already fired for this statement. + rf.prepared_statement._warned_missing_column_metadata = True + + rf._query = Mock(return_value=True) + rf._execute_after_prepare('host', None, None, response) + + # Both metadata fields must be refreshed from the reprepare response. + assert rf.prepared_statement.result_metadata is new_meta + assert rf.prepared_statement.result_metadata_id == b'new_hash' + assert rf.prepared_statement.result_metadata_and_id == (new_meta, b'new_hash') + # Recovering the metadata re-arms the anomaly warning, on this path too. + assert rf.prepared_statement._warned_missing_column_metadata is False + rf._query.assert_called_once_with('host') + + def test_execute_after_prepare_no_metadata_id_in_response_clears_id(self): + """ + When the PREPARE response does not carry a result_metadata_id (e.g. the + extension is not active on the reprepare connection), _execute_after_prepare + must clear the cached result_metadata_id rather than keep the previous one: + carrying it forward could pair a stale id with the freshly reprepared column + metadata (e.g. if the schema changed and reverted between the two PREPAREs, + the old id could become valid again for the current schema while paired + locally with an intermediate schema's metadata, with no server-side mismatch + to catch it). Clearing it instead lets the next id-aware execute re-acquire a + correctly paired id via the same b'' sentinel / METADATA_CHANGED self-healing + path a never-prepared statement uses. + """ + query_id = b'reprepare_qid2' + session = self.make_session() + rf = self.make_response_future(session) + + new_meta = [('ks', 'tb', 'col', Mock())] + response = Mock(spec=ResultMessage, + kind=RESULT_KIND_PREPARED, + result_metadata_id=None, + column_metadata=new_meta) + response.query_id = query_id + + rf.prepared_statement = self._make_prepared_statement( + [('ks', 'tb', 'old_col', Mock())], b'old_hash', query_id=query_id) + + rf._query = Mock(return_value=True) + rf._execute_after_prepare('host', None, None, response) + + # result_metadata is refreshed (always); result_metadata_id is cleared, not + # carried forward from the old pair. + assert rf.prepared_statement.result_metadata is new_meta + assert rf.prepared_statement.result_metadata_id is None def test_timeout_does_not_release_stream_id(self): """ @@ -653,7 +1016,7 @@ def test_timeout_does_not_release_stream_id(self): pool = self.make_pool() session._pools.get.return_value = pool connection = Mock(spec=Connection, lock=RLock(), _requests={}, request_ids=deque(), - orphaned_request_ids=set(), orphaned_threshold=256) + orphaned_request_ids=set(), orphaned_threshold=256, in_flight=3) pool.borrow_connection.return_value = (connection, 1) rf = self.make_response_future(session) @@ -663,8 +1026,10 @@ def test_timeout_does_not_release_stream_id(self): rf._on_timeout() pool.return_connection.assert_called_once_with(connection, stream_was_orphaned=True) - with pytest.raises(OperationTimedOut, match="Client request timeout"): + with pytest.raises(OperationTimedOut, match="Client request timeout") as exc_info: rf.result() + assert exc_info.value.timeout == 1 + assert exc_info.value.in_flight == 3 assert len(connection.request_ids) == 0, \ "Request IDs should be empty but it's not: {}".format(connection.request_ids) @@ -697,7 +1062,7 @@ def test_single_host_query_plan_exhausted_after_one_retry(self): # Verify initial request was sent rf.session._pools.get.assert_called_once_with(specific_host) - pool.borrow_connection.assert_called_once_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY) + pool.borrow_connection.assert_called_once_with(timeout=ANY, routing_key=ANY, keyspace=ANY, table=ANY, routing_token=ANY) connection.send_msg.assert_called_once_with(rf.message, 1, cb=ANY, encoder=ProtocolHandler.encode_message, decoder=ProtocolHandler.decode_message, result_metadata=[]) # Simulate a ServerError response (which triggers RETRY_NEXT_HOST by default) @@ -723,3 +1088,428 @@ def test_single_host_query_plan_exhausted_after_one_retry(self): # Instead, it should set a NoHostAvailable exception assert rf._final_exception is not None assert isinstance(rf._final_exception, NoHostAvailable) + + # ------------------------------------------------------------------------- + # Helpers for SCYLLA_USE_METADATA_ID tests + # ------------------------------------------------------------------------- + + def _make_rows_response(self, result_metadata_id=None, column_metadata=None): + """ + Return a real ResultMessage(kind=RESULT_KIND_ROWS) with all attributes + that _set_result accesses pre-set, so it passes isinstance checks and + doesn't trigger unexpected code paths. + """ + response = ResultMessage(kind=RESULT_KIND_ROWS) + response.paging_state = None + response.column_names = ['col'] + response.parsed_rows = [] + response.column_types = [] + response.column_metadata = column_metadata + response.result_metadata_id = result_metadata_id + response.trace_id = None + response.warnings = None + response.custom_payload = None + return response + + def _make_prepared_statement(self, result_metadata, result_metadata_id, query_id=b'qid'): + return PreparedStatement( + column_metadata=[], query_id=query_id, routing_key_indexes=None, + query="SELECT * FROM foo", keyspace='ks', protocol_version=4, + result_metadata=result_metadata, result_metadata_id=result_metadata_id) + + def _make_execute_response_future(self, session, connection, prepared_statement): + """ + Return a ResponseFuture whose message is an ExecuteMessage and which + has a prepared_statement set, as _create_response_future would build it. + """ + execute_msg = ExecuteMessage(b'qid', [], ConsistencyLevel.ONE) + query = SimpleStatement("SELECT * FROM foo") + rf = ResponseFuture( + session, execute_msg, query, timeout=1, + prepared_statement=prepared_statement, + # mirror _create_response_future: snapshot the metadata paired with the id + bound_result_metadata=prepared_statement.result_metadata, + ) + pool = session._pools.get.return_value + pool.borrow_connection.return_value = (connection, 1) + return rf + + def _create_execute_future(self, prepared_statement, continuous_paging_options=None): + """ + Drive the real Session._create_response_future (with a mock session) for + a statement bound to `prepared_statement`, returning the ResponseFuture. + This exercises the ExecuteMessage construction path where skip_meta and + result_metadata_id are decided from the statement's metadata pair. + """ + session = self.make_session() + profile = session._maybe_get_execution_profile.return_value + profile.consistency_level = ConsistencyLevel.ONE + profile.serial_consistency_level = None + profile.continuous_paging_options = continuous_paging_options + profile.speculative_execution_policy = None + profile.load_balancing_policy.make_query_plan.return_value = ['ip1'] + session.default_fetch_size = 5000 + session.use_client_timestamp = False + bound = BoundStatement(prepared_statement).bind(()) + return Session._create_response_future( + session, bound, parameters=None, trace=False, custom_payload=None, timeout=1) + + # ------------------------------------------------------------------------- + # _set_result: METADATA_CHANGED update path + # ------------------------------------------------------------------------- + + def test_set_result_updates_metadata_when_metadata_changed(self): + """ + When the EXECUTE response carries a new result_metadata_id (server + detected a schema change), _set_result must update both + prepared_statement.result_metadata and prepared_statement.result_metadata_id. + """ + session = self.make_session() + pool = session._pools.get.return_value + connection = Mock(spec=Connection) + connection.protocol_version = 4 + connection.features = Mock() + connection.features.use_metadata_id = False + pool.borrow_connection.return_value = (connection, 1) + + old_meta = [('ks', 'tb', 'old_col', Mock())] + new_meta = [('ks', 'tb', 'new_col', Mock())] + ps = self._make_prepared_statement(old_meta, b'old_id') + + rf = self.make_response_future(session) + rf.prepared_statement = ps + rf.send_request() + + response = self._make_rows_response( + result_metadata_id=b'new_id', + column_metadata=new_meta, + ) + rf._set_result(None, None, None, response) + + assert ps.result_metadata is new_meta + assert ps.result_metadata_id == b'new_id' + # the pair is replaced as one unit — a snapshot can never be torn + assert ps.result_metadata_and_id == (new_meta, b'new_id') + + def test_set_result_does_not_update_metadata_when_metadata_id_absent(self): + """ + When the EXECUTE response has no result_metadata_id (normal skip-meta + path — server metadata unchanged), _set_result must leave the + prepared_statement's cached metadata untouched. + """ + session = self.make_session() + pool = session._pools.get.return_value + connection = Mock(spec=Connection) + connection.protocol_version = 4 + connection.features = Mock() + connection.features.use_metadata_id = False + pool.borrow_connection.return_value = (connection, 1) + + old_meta = [('ks', 'tb', 'col', Mock())] + ps = self._make_prepared_statement(old_meta, b'old_id') + + rf = self.make_response_future(session) + rf.prepared_statement = ps + rf.send_request() + + # result_metadata_id is None → server sent full metadata, no hash update + response = self._make_rows_response( + result_metadata_id=None, + column_metadata=old_meta, + ) + rf._set_result(None, None, None, response) + + assert ps.result_metadata is old_meta + assert ps.result_metadata_id == b'old_id' + + def test_set_result_warns_when_metadata_id_but_no_column_metadata(self): + """ + If the server sends a new result_metadata_id but no column metadata + (protocol violation), _set_result must emit a WARNING and cache + NEITHER value: adopting the new id while keeping the old metadata would + make the server skip sending metadata on subsequent executes (the ids + match) while the driver decodes with stale metadata — with no recovery. + Keeping the old pair means the next EXECUTE sends the old id, the server + detects the mismatch, and the driver recovers with full metadata. + """ + session = self.make_session() + pool = session._pools.get.return_value + connection = Mock(spec=Connection) + connection.protocol_version = 4 + connection.features = Mock() + connection.features.use_metadata_id = False + pool.borrow_connection.return_value = (connection, 1) + + old_meta = [('ks', 'tb', 'col', Mock())] + ps = self._make_prepared_statement(old_meta, b'old_id') + + rf = self.make_response_future(session) + rf.prepared_statement = ps + rf.send_request() + + # column_metadata is falsy (empty list) but result_metadata_id is set + response = self._make_rows_response( + result_metadata_id=b'new_id', + column_metadata=[], + ) + + with self.assertLogs('cassandra.cluster', level='WARNING') as log_ctx: + rf._set_result(None, None, None, response) + + assert any('result_metadata_id' in msg for msg in log_ctx.output) + # nothing is cached from the anomalous response + assert ps.result_metadata_and_id == (old_meta, b'old_id') + + def test_set_result_warns_when_metadata_id_but_column_metadata_is_none(self): + """ + Like the empty-list variant above, but column_metadata=None (attribute + absent rather than explicitly empty). Both None and [] are falsy, so + the warning branch is taken and the cached pair is left unchanged. + """ + session = self.make_session() + pool = session._pools.get.return_value + connection = Mock(spec=Connection) + connection.protocol_version = 4 + connection.features = Mock() + connection.features.use_metadata_id = False + pool.borrow_connection.return_value = (connection, 1) + + old_meta = [('ks', 'tb', 'col', Mock())] + ps = self._make_prepared_statement(old_meta, b'old_id') + + rf = self.make_response_future(session) + rf.prepared_statement = ps + rf.send_request() + + response = self._make_rows_response( + result_metadata_id=b'new_id', + column_metadata=None, + ) + + with self.assertLogs('cassandra.cluster', level='WARNING') as log_ctx: + rf._set_result(None, None, None, response) + + assert any('result_metadata_id' in msg for msg in log_ctx.output) + assert ps.result_metadata_and_id == (old_meta, b'old_id') + + def test_set_result_no_metadata_statement_adopts_metadata_changed(self): + """ + A statement whose PREPARE returned NO_METADATA for the result columns + (result_metadata None while the id is live) is not special-cased. A + METADATA_CHANGED response updates its cached pair like any other + statement's: the id describes the metadata the server sent alongside it, + and a server that later produces different result metadata must report the + id mismatch — the same contract every other statement already relies on to + avoid decoding rows against stale columns. + """ + session = self.make_session() + pool = session._pools.get.return_value + connection = Mock(spec=Connection) + connection.protocol_version = 4 + connection.features = Mock() + connection.features.use_metadata_id = True + pool.borrow_connection.return_value = (connection, 1) + + ps = self._make_prepared_statement(None, b'old_id') + + rf = self.make_response_future(session) + rf.prepared_statement = ps + rf.send_request() + + new_meta = [('ks', 'tb', '[applied]', Mock())] + response = self._make_rows_response( + result_metadata_id=b'new_id', + column_metadata=new_meta, + ) + + # Ordinary METADATA_CHANGED handling, so no anomaly warning either. + with patch('cassandra.cluster.log.warning') as warning: + rf._set_result(None, None, None, response) + warning.assert_not_called() + + assert ps.result_metadata_and_id == (new_meta, b'new_id') + + def test_set_result_anomalous_metadata_id_warns_once_and_rearms(self): + """ + The anomalous-response warning (new id, no column metadata) is logged + once per prepared statement, not once per execute: a persistently + misbehaving server must not spam the log. A successful METADATA_CHANGED + in between re-arms the warning so a later recurrence is logged again. + """ + session = self.make_session() + pool = session._pools.get.return_value + connection = Mock(spec=Connection) + connection.protocol_version = 4 + connection.features = Mock() + connection.features.use_metadata_id = False + pool.borrow_connection.return_value = (connection, 1) + + old_meta = [('ks', 'tb', 'col', Mock())] + ps = self._make_prepared_statement(old_meta, b'old_id') + + rf = self.make_response_future(session) + rf.prepared_statement = ps + rf.send_request() + + anomalous = self._make_rows_response(result_metadata_id=b'new_id', column_metadata=[]) + + # First anomalous response: warns once. + with self.assertLogs('cassandra.cluster', level='WARNING') as first: + rf._set_result(None, None, None, anomalous) + assert sum('result_metadata_id' in msg for msg in first.output) == 1 + + # Second identical anomalous response: no new warning (deduped). + with patch('cassandra.cluster.log.warning') as warning: + rf._set_result(None, None, None, anomalous) + warning.assert_not_called() + assert ps.result_metadata_and_id == (old_meta, b'old_id') + + # A genuine METADATA_CHANGED recovers the metadata and re-arms the warning. + new_meta = [('ks', 'tb', 'new_col', Mock())] + rf._set_result(None, None, None, + self._make_rows_response(result_metadata_id=b'new_id', column_metadata=new_meta)) + assert ps.result_metadata_and_id == (new_meta, b'new_id') + + # After recovery, the anomaly warns again. + with self.assertLogs('cassandra.cluster', level='WARNING') as after: + rf._set_result(None, None, None, anomalous) + assert sum('result_metadata_id' in msg for msg in after.output) == 1 + + def test_create_execute_message_with_metadata_and_id(self): + """ + When the prepared statement carries both a result_metadata_id and usable + cached result_metadata, _create_response_future must build the + ExecuteMessage with skip_meta=True and the metadata id attached. Whether + either actually reaches the wire is decided per connection at + serialization time (ExecuteMessage.send_body). + """ + ps = self._make_prepared_statement([('ks', 'tbl', 'col', Mock())], b'meta_hash') + + rf = self._create_execute_future(ps) + + assert rf.message.skip_meta is True + assert rf.message.result_metadata_id == b'meta_hash' + + def test_create_execute_message_without_metadata_id(self): + """ + A statement prepared before the extension was active (result_metadata_id + is None) must never request skip_meta — the driver has no hash the server + could validate the cached metadata against. + """ + ps = self._make_prepared_statement([('ks', 'tbl', 'col', Mock())], None) + + rf = self._create_execute_future(ps) + + assert rf.message.skip_meta is False + assert rf.message.result_metadata_id is None + + def test_create_execute_message_result_metadata_none(self): + """ + A statement can carry a result_metadata_id while its PREPARE response set + NO_METADATA for the result columns, leaving result_metadata as None — + Cassandra does this for conditional statements (Scylla instead describes + them up front, see the conditional-statement integration test). skip_meta + must stay off: the server would omit column definitions while the driver + has nothing cached to decode with. The id still rides on the message so + id-aware connections always send it. + """ + ps = self._make_prepared_statement(None, b'lwt_hash') + + rf = self._create_execute_future(ps) + + assert rf.message.skip_meta is False + assert rf.message.result_metadata_id == b'lwt_hash' + + def test_create_execute_message_result_metadata_empty(self): + """ + Statements returning zero result columns (plain INSERT/UPDATE/DELETE) + have result_metadata == []. Like the None case, skip_meta stays off — + there is no metadata worth skipping. + """ + ps = self._make_prepared_statement([], b'meta_hash') + + rf = self._create_execute_future(ps) + + assert rf.message.skip_meta is False + assert rf.message.result_metadata_id == b'meta_hash' + + def test_create_execute_message_continuous_paging_disables_skip_meta(self): + """ + Continuous paging sessions must never get skip_meta=True, even with a + statement that otherwise qualifies (valid cached metadata + id): + Connection.process_msg hardcodes result_metadata=None for every page + after the first (it isn't threaded through the paging session), so a + skip_meta response would leave nothing to decode page 2+ against. + """ + ps = self._make_prepared_statement([('ks', 'tbl', 'col', Mock())], b'meta_hash') + + rf = self._create_execute_future(ps, continuous_paging_options=Mock()) + + assert rf.message.skip_meta is False + assert rf.message.result_metadata_id == b'meta_hash' + + def test_query_does_not_mutate_execute_message(self): + """ + _query() must send the ExecuteMessage exactly as constructed: all + per-connection decisions (whether the id field and the skip_meta flag hit + the wire) happen at serialization time from the connection's negotiated + features. Mutating the shared message per attempt would race with + speculative executions sending the same message on another connection. + """ + session = self.make_basic_session() + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + session._pools.get.return_value = self.make_pool() + + connection = Mock(spec=Connection) + connection.protocol_version = 4 + connection.features = Mock() + connection.features.use_metadata_id = True + session._pools.get.return_value.borrow_connection.return_value = (connection, 1) + + ps = self._make_prepared_statement([('ks', 'tbl', 'col', Mock())], b'meta_hash') + rf = self._make_execute_response_future(session, connection, ps) + original_skip_meta = rf.message.skip_meta + original_id = rf.message.result_metadata_id + + rf.send_request() + + connection.send_msg.assert_called_once() + sent_message = connection.send_msg.call_args[0][0] + assert sent_message is rf.message + assert rf.message.skip_meta is original_skip_meta + assert rf.message.result_metadata_id is original_id + assert not hasattr(rf.message, 'use_metadata_id') + + def test_query_decodes_with_construction_snapshot_not_live_cache(self): + """ + The metadata handed to the decoder must be the snapshot taken when the message + was built (paired with the id the immutable message carries), not a fresh read of + the prepared statement's cache. Otherwise a concurrent METADATA_CHANGED landing + between construction and send could pair the message's id with a different schema + version's metadata — the torn read the atomic pair was meant to prevent. + """ + session = self.make_basic_session() + session.cluster._default_load_balancing_policy.make_query_plan.return_value = ['ip1'] + session._pools.get.return_value = self.make_pool() + + connection = Mock(spec=Connection) + connection.protocol_version = 4 + connection.features = Mock() + connection.features.use_metadata_id = True + session._pools.get.return_value.borrow_connection.return_value = (connection, 1) + + meta_v1 = [('ks', 'tbl', 'col_v1', Mock())] + ps = self._make_prepared_statement(meta_v1, b'id1') + rf = self._make_execute_response_future(session, connection, ps) + # snapshot captured at construction, independent of the live pair + assert rf._bound_result_metadata is meta_v1 + + # a concurrent METADATA_CHANGED replaces the statement's cached pair + ps.update_result_metadata([('ks', 'tbl', 'col_v2', Mock())], b'id2') + assert rf._bound_result_metadata is meta_v1 + + rf.send_request() + + connection.send_msg.assert_called_once() + # _query decodes with the construction snapshot, not the mutated cache + assert connection.send_msg.call_args.kwargs['result_metadata'] is meta_v1 diff --git a/tests/unit/test_session_schema_agreement.py b/tests/unit/test_session_schema_agreement.py new file mode 100644 index 0000000000..ffad687fcc --- /dev/null +++ b/tests/unit/test_session_schema_agreement.py @@ -0,0 +1,204 @@ +from datetime import timedelta +from types import SimpleNamespace +from unittest.mock import Mock +import uuid + +import pytest + +import cassandra.cluster as cluster_module +from cassandra.connection import ConnectionBusy +from cassandra.cluster import ControlConnection, Session, ResultSet +from cassandra.policies import HostDistance, SimpleConvictionPolicy +from cassandra.pool import Host +from cassandra.util import maybe_add_timeout_to_query + + +class FakeTime: + def __init__(self): + self.clock = 0 + + def time(self): + return self.clock + + def sleep(self, amount): + self.clock += amount + + +class MockPool: + def __init__(self, host): + self.host = host + self.is_shutdown = False + + +class MockSchemaVersionFuture: + def __init__(self, outcome, auto_complete=True): + self._outcome = outcome + self._auto_complete = auto_complete + self._delivered = False + self._callback_state = None + self._col_names = ("schema_version",) + self._col_types = None + self.has_more_pages = False + self._continuous_paging_session = None + + def _deliver(self): + if self._delivered or self._callback_state is None: + return + + self._delivered = True + callback, errback, callback_args, callback_kwargs, errback_args, errback_kwargs = self._callback_state + if isinstance(self._outcome, Exception): + errback(self._outcome, *errback_args, **errback_kwargs) + else: + row = SimpleNamespace(schema_version=self._outcome) + callback([row], *callback_args, **callback_kwargs) + + def add_callbacks(self, callback, errback, + callback_args=(), callback_kwargs=None, + errback_args=(), errback_kwargs=None): + self._callback_state = ( + callback, + errback, + callback_args, + callback_kwargs or {}, + errback_args, + errback_kwargs or {}, + ) + if self._auto_complete: + self._deliver() + return self + + def complete(self): + self._deliver() + + def result(self): + if isinstance(self._outcome, Exception): + raise self._outcome + return ResultSet(self, [SimpleNamespace(schema_version=self._outcome)]) + + +def _host_query_count(session, target_host): + return sum(1 for call in session.execute_async.call_args_list if call.kwargs.get("host") is target_host) + + +def _new_session(schema_versions, distances=None, metadata_request_timeout=timedelta(seconds=2), timeout=2.0): + hosts = [] + connections = {} + distance_map = {} + + if distances is None: + distances = [HostDistance.LOCAL] * len(schema_versions) + + for index, schema_version in enumerate(schema_versions): + host = Host("127.0.0.%d" % (index + 1), SimpleConvictionPolicy, host_id=uuid.uuid4()) + host.set_up() + hosts.append(host) + distance_map[host] = distances[index] + + cluster = SimpleNamespace( + max_schema_agreement_wait=10, + control_connection=SimpleNamespace( + _timeout=timeout, + _metadata_request_timeout=metadata_request_timeout, + ), + ) + + session = Session.__new__(Session) + session.cluster = cluster + session._profile_manager = SimpleNamespace(distance=lambda host: distance_map.get(host, HostDistance.LOCAL)) + session._pools = {} + session.is_shutdown = False + + for host, schema_version in zip(hosts, schema_versions): + connection = Mock(endpoint=host.endpoint) + connection.future_outcomes = [schema_version] + session._pools[host] = MockPool(host) + connections[host] = connection + + def execute_async(query, parameters=None, trace=False, + custom_payload=None, execution_profile=None, + paging_state=None, timeout=None, host=None, execute_as=None): + connection = connections[host] + outcome = connection.future_outcomes.pop(0) if len(connection.future_outcomes) > 1 else connection.future_outcomes[0] + return MockSchemaVersionFuture(outcome) + + session.execute_async = Mock(side_effect=execute_async) + + return session, hosts, connections + + +def test_wait_for_schema_agreement_retries_with_module_time(monkeypatch): + session, hosts, connections = _new_session(["a", "b"]) + clock = FakeTime() + monkeypatch.setattr(cluster_module, "time", clock) + connections[hosts[1]].future_outcomes = ["b", "a"] + + assert session.wait_for_schema_agreement(wait_time=1) + assert clock.clock == pytest.approx(0.2) + for host in hosts: + assert _host_query_count(session, host) == 2 + + +@pytest.mark.parametrize("wait_time", [0, -1]) +def test_wait_for_schema_agreement_rejects_non_positive_wait_time(wait_time): + session, _, _ = _new_session(["a"]) + + with pytest.raises(ValueError, match="wait_time must be greater than 0"): + session.wait_for_schema_agreement(wait_time=wait_time) + + assert session.execute_async.call_count == 0 + + +def test_wait_for_schema_agreement_returns_false_when_no_hosts_match_scope(monkeypatch): + session, _, _ = _new_session(["a"], distances=[HostDistance.IGNORED]) + clock = FakeTime() + monkeypatch.setattr(cluster_module, "time", clock) + + assert session.wait_for_schema_agreement(wait_time=1) is False + assert session.execute_async.call_count == 0 + assert clock.clock == pytest.approx(1.0) + + +def test_wait_for_schema_agreement_uses_host_targeted_session_queries(): + session, hosts, _ = _new_session(["a", "a"]) + + assert session.wait_for_schema_agreement(wait_time=0.1) + + expected_query = maybe_add_timeout_to_query( + ControlConnection._SELECT_SCHEMA_LOCAL, + timedelta(seconds=2), + ) + assert session.execute_async.call_count == 2 + assert [call.args[0] for call in session.execute_async.call_args_list] == [expected_query, expected_query] + assert [call.kwargs["host"] for call in session.execute_async.call_args_list] == hosts + for call in session.execute_async.call_args_list: + assert 0 < call.kwargs["timeout"] <= 0.1 + + +def test_wait_for_schema_agreement_retries_after_host_targeted_query_error(monkeypatch): + session, hosts, connections = _new_session(["a", "a"]) + clock = FakeTime() + monkeypatch.setattr(cluster_module, "time", clock) + connections[hosts[1]].future_outcomes = [ConnectionBusy("connection overloaded"), "a"] + + assert session.wait_for_schema_agreement(wait_time=1) + assert clock.clock == pytest.approx(0.2) + for host in hosts: + assert _host_query_count(session, host) == 2 + + +def test_wait_for_schema_agreement_queries_hosts_in_order_under_one_deadline(monkeypatch): + session, hosts, _ = _new_session(["a", "a", "a"]) + clock = FakeTime() + monkeypatch.setattr(cluster_module, "time", clock) + + def execute_async(query, parameters=None, trace=False, + custom_payload=None, execution_profile=None, + paging_state=None, timeout=None, host=None, execute_as=None): + clock.sleep(0.01) + return MockSchemaVersionFuture("a") + + session.execute_async = Mock(side_effect=execute_async) + + assert session.wait_for_schema_agreement(wait_time=1) + assert [call.kwargs["host"] for call in session.execute_async.call_args_list] == hosts diff --git a/tests/unit/test_shard_aware.py b/tests/unit/test_shard_aware.py index e7d26ae207..902b48a276 100644 --- a/tests/unit/test_shard_aware.py +++ b/tests/unit/test_shard_aware.py @@ -15,6 +15,7 @@ import unittest import logging +import time from unittest.mock import MagicMock from concurrent.futures import ThreadPoolExecutor @@ -27,6 +28,50 @@ LOGGER = logging.getLogger(__name__) +class MockSession(MagicMock): + is_shutdown = False + keyspace = "ks1" + + def __init__(self, ssl_options=None, ssl_context=None, sharding_info=None, + *args, **kwargs): + super(MockSession, self).__init__(*args, **kwargs) + self.cluster = MagicMock() + self.cluster.ssl_options = ssl_options + self.cluster.ssl_context = ssl_context + self.cluster.shard_aware_options = ShardAwareOptions() + self.cluster.executor = ThreadPoolExecutor(max_workers=2) + self.cluster.signal_connection_failure = lambda *args, **kwargs: False + self.cluster.connection_factory = self.mock_connection_factory + self.connection_counter = 0 + self.futures = [] + self.sharding_info = sharding_info + + def submit(self, fn, *args, **kwargs): + logging.info("Scheduling %s with args: %s, kwargs: %s", fn, args, kwargs) + if not self.is_shutdown: + f = self.cluster.executor.submit(fn, *args, **kwargs) + self.futures += [f] + return f + + def mock_connection_factory(self, *args, **kwargs): + connection = MagicMock() + connection.is_shutdown = False + connection.is_defunct = False + connection.is_closed = False + connection.orphaned_threshold_reached = False + connection.endpoint = args[0] + sharding_info = self.sharding_info or ShardingInfo( + shard_id=1, shards_count=4, partitioner="", + sharding_algorithm="", sharding_ignore_msb=0, + shard_aware_port=19042, shard_aware_port_ssl=19045) + connection.features = ProtocolFeatures( + shard_id=kwargs.get('shard_id', self.connection_counter), + sharding_info=sharding_info) + self.connection_counter += 1 + + return connection + + class TestShardAware(unittest.TestCase): def test_parsing_and_calculating_shard_id(self): """ @@ -55,58 +100,92 @@ def test_advanced_shard_aware_port(self): Test that on given a `shard_aware_port` on the OPTIONS message (ShardInfo class) the next connections would be open using this port """ - class MockSession(MagicMock): - is_shutdown = False - keyspace = "ks1" - - def __init__(self, is_ssl=False, *args, **kwargs): - super(MockSession, self).__init__(*args, **kwargs) - self.cluster = MagicMock() - if is_ssl: - self.cluster.ssl_options = {'some_ssl_options': True} - else: - self.cluster.ssl_options = None - self.cluster.shard_aware_options = ShardAwareOptions() - self.cluster.executor = ThreadPoolExecutor(max_workers=2) - self.cluster.signal_connection_failure = lambda *args, **kwargs: False - self.cluster.connection_factory = self.mock_connection_factory - self.connection_counter = 0 - self.futures = [] - - def submit(self, fn, *args, **kwargs): - logging.info("Scheduling %s with args: %s, kwargs: %s", fn, args, kwargs) - if not self.is_shutdown: - f = self.cluster.executor.submit(fn, *args, **kwargs) - self.futures += [f] - return f - - def mock_connection_factory(self, *args, **kwargs): - connection = MagicMock() - connection.is_shutdown = False - connection.is_defunct = False - connection.is_closed = False - connection.orphaned_threshold_reached = False - connection.endpoint = args[0] - sharding_info = ShardingInfo(shard_id=1, shards_count=4, partitioner="", sharding_algorithm="", sharding_ignore_msb=0, shard_aware_port=19042, shard_aware_port_ssl=19045) - connection.features = ProtocolFeatures(shard_id=kwargs.get('shard_id', self.connection_counter), sharding_info=sharding_info) - self.connection_counter += 1 - - return connection - host = MagicMock() host.endpoint = DefaultEndPoint("1.2.3.4") - for port, is_ssl in [(19042, False), (19045, True)]: - session = MockSession(is_ssl=is_ssl) + for port, ssl_options, ssl_context in [ + (19042, None, None), + (19045, {'some_ssl_options': True}, None), + (19045, {}, None), + (19045, None, object())]: + session = MockSession(ssl_options=ssl_options, ssl_context=ssl_context) pool = HostConnection(host=host, host_distance=HostDistance.REMOTE, session=session) - for f in session.futures: - f.result() - assert len(pool._connections) == 4 - for shard_id, connection in pool._connections.items(): - assert connection.features.shard_id == shard_id - if shard_id == 0: - assert connection.endpoint == DefaultEndPoint("1.2.3.4") - else: - assert connection.endpoint == DefaultEndPoint("1.2.3.4", port=port) - - session.cluster.executor.shutdown(wait=True) + try: + for f in session.futures: + f.result() + assert len(pool._connections) == 4 + for shard_id, connection in pool._connections.items(): + assert connection.features.shard_id == shard_id + if shard_id == 0: + assert connection.endpoint == DefaultEndPoint("1.2.3.4") + else: + assert connection.endpoint == DefaultEndPoint("1.2.3.4", port=port) + finally: + session.cluster.executor.shutdown(wait=True) + + def test_ssl_advanced_shard_aware_port_requires_ssl_port(self): + """ + Test that SSL connections do not fall back to the plaintext + shard-aware port when the SSL shard-aware port is unavailable. + """ + host = MagicMock() + host.endpoint = DefaultEndPoint("1.2.3.4") + sharding_info = ShardingInfo( + shard_id=1, shards_count=4, partitioner="", sharding_algorithm="", + sharding_ignore_msb=0, shard_aware_port=19042, + shard_aware_port_ssl=None) + for label, ssl_options, ssl_context in [ + ('ssl_options', {'some_ssl_options': True}, None), + ('empty_ssl_options', {}, None), + ('ssl_context', None, object())]: + with self.subTest(label=label): + session = MockSession( + ssl_options=ssl_options, + ssl_context=ssl_context, + sharding_info=sharding_info) + pool = HostConnection(host=host, host_distance=HostDistance.REMOTE, session=session) + + try: + for f in session.futures: + f.result() + + assert pool._get_shard_aware_endpoint() is None + finally: + session.cluster.executor.shutdown(wait=True) + + def test_advanced_shard_aware_cooldown(self): + """ + `disable_advanced_shard_aware` must suppress the shard-aware endpoint for + the duration of the cool-down window, then automatically restore it once + the deadline has passed. The hard-disable flag must suppress the endpoint + unconditionally. + """ + host = MagicMock() + host.endpoint = DefaultEndPoint("1.2.3.4") + session = MockSession() + + pool = HostConnection(host=host, host_distance=HostDistance.REMOTE, session=session) + for f in session.futures: + f.result() + + try: + # Baseline: shard-aware port is returned. + endpoint = pool._get_shard_aware_endpoint() + assert endpoint is not None + assert endpoint.port == 19042 + + # During the cool-down window `_get_shard_aware_endpoint` must return None. + pool.disable_advanced_shard_aware(600) + assert pool._get_shard_aware_endpoint() is None + + # Once the deadline has passed, the shard-aware port must be used again. + pool.advanced_shardaware_block_until = time.time() - 1 + endpoint = pool._get_shard_aware_endpoint() + assert endpoint is not None + assert endpoint.port == 19042 + + # The hard-disable flag must suppress the endpoint regardless of the timer. + session.cluster.shard_aware_options.disable_shardaware_port = True + assert pool._get_shard_aware_endpoint() is None + finally: + session.cluster.executor.shutdown(wait=True) diff --git a/tests/unit/test_tablets.py b/tests/unit/test_tablets.py index 5e640fa4c9..656ae42da7 100644 --- a/tests/unit/test_tablets.py +++ b/tests/unit/test_tablets.py @@ -1,6 +1,11 @@ import unittest +from io import BytesIO +from uuid import uuid4 -from cassandra.tablets import Tablets, Tablet +from cassandra import ConsistencyLevel, ProtocolVersion +from cassandra.protocol import ExecuteMessage +from cassandra.protocol_features import ProtocolFeatures +from cassandra.tablets import Tablets, Tablet, choose_tablet_version_block, random_tablet_version_block class TabletsTest(unittest.TestCase): def compare_ranges(self, tablets, ranges): @@ -86,3 +91,191 @@ def test_add_tablet_intersecting_with_last(self): self.compare_ranges(tablets_list, [(-8611686018427387905, -7917529027641081857), (-5011686018427387905, -2987529027641081857)]) + + +class GetTabletForKeyTest(unittest.TestCase): + """Tests for Tablets.get_tablet_for_key.""" + + def test_found(self): + t1 = Tablet(0, 100, [("host1", 0)]) + t2 = Tablet(100, 200, [("host2", 0)]) + t3 = Tablet(200, 300, [("host3", 0)]) + tablets = Tablets({("ks", "tb"): [t1, t2, t3]}) + + class Token: + def __init__(self, v): + self.value = v + + result = tablets.get_tablet_for_key("ks", "tb", Token(150)) + self.assertIs(result, t2) + + def test_not_found_empty(self): + tablets = Tablets({}) + + class Token: + def __init__(self, v): + self.value = v + + self.assertIsNone(tablets.get_tablet_for_key("ks", "tb", Token(50))) + + def test_not_found_outside_range(self): + t1 = Tablet(100, 200, [("host1", 0)]) + tablets = Tablets({("ks", "tb"): [t1]}) + + class Token: + def __init__(self, v): + self.value = v + + # Token value 50 is not > first_token (100) of the tablet whose + # last_token (200) is >= 50, so no match. + self.assertIsNone(tablets.get_tablet_for_key("ks", "tb", Token(50))) + + +class TabletLeaderTest(unittest.TestCase): + """Tests for Tablet.leader, the leader-first replica ordering V2 provides.""" + + def test_leader_is_the_first_replica(self): + leader = uuid4() + follower = uuid4() + tablet = Tablet(first_token=-100, last_token=100, + replicas=[(leader, 3), (follower, 7)], tablet_version=1) + assert tablet.leader == leader + + def test_leader_is_none_without_replicas(self): + # An accessor that raised here would push the guard onto every caller; + # the load balancing policy relies on getting None instead. + assert Tablet(first_token=-100, last_token=100, replicas=[]).leader is None + assert Tablet(first_token=-100, last_token=100, replicas=None).leader is None + + def test_leader_is_reported_regardless_of_version(self): + # Tablet.leader answers "which replica is first", nothing more: a + # versionless (V1-sourced) tablet has no meaningful leader, and deciding + # that is the caller's job, not this property's. + leader = uuid4() + tablet = Tablet(first_token=-100, last_token=100, replicas=[(leader, 0)]) + assert tablet.tablet_version is None + assert tablet.leader == leader + + +class TabletVersionBlockTest(unittest.TestCase): + """Tests for tablet_version_block encoding used by TABLETS_ROUTING_V2.""" + + def _server_block_matches(self, version, block): + """Reimplements the server's locator::compare_tablet_version_block.""" + block_value = block & 0x0F + block_index = (block & 0xF0) >> 4 + hash_block = (version >> (block_index * 4)) & 0x0F + return hash_block == block_value + + def test_choose_tablet_version_block_matches_server(self): + """Every block produced by the driver must match the server's check.""" + version = 0x0123456789ABCDEF + # The index is chosen randomly; sample enough times to exercise many indices. + for _ in range(256): + block = choose_tablet_version_block(version) + self.assertTrue(self._server_block_matches(version, block), + f"Block 0x{block:02X} did not match server check for version 0x{version:016X}") + + def test_choose_tablet_version_block_covers_all_indices(self): + """Over many calls the random index selection should probe every block + index, so that any server-side version change is eventually detected.""" + version = 0xFFFFFFFFFFFFFFFF # All nibbles are 0xF + seen_indices = set() + # 16 indices; 1000 draws makes a missing index astronomically unlikely. + for _ in range(1000): + block = choose_tablet_version_block(version) + seen_indices.add((block >> 4) & 0xF) + self.assertEqual(seen_indices, set(range(16))) + + def test_choose_tablet_version_block_matches_server_for_signed_version(self): + """tablet_version is decoded as a *signed* 64-bit int (LongType), so a + version with the high bit set is stored negative in the driver while the + server treats it as unsigned. The block the driver emits must still match + the server's check computed on the unsigned value (sign-boundary guard).""" + for unsigned in (0x8000000000000000, 0xDEADBEEFCAFEBABE, 0xFFFFFFFFFFFFFFFF): + signed = unsigned - (1 << 64) # how LongType stores a high-bit value + self.assertLess(signed, 0) + # Sample enough times to exercise every one of the 16 block indices. + for _ in range(256): + block = choose_tablet_version_block(signed) + self.assertTrue( + self._server_block_matches(unsigned, block), + f"signed version {signed} (unsigned 0x{unsigned:016X}) produced " + f"block 0x{block:02X} that failed the server check") + + def test_random_tablet_version_block_returns_byte(self): + """Verify random_tablet_version_block returns a value in [0, 255].""" + for _ in range(100): + block = random_tablet_version_block() + self.assertIsInstance(block, int) + self.assertGreaterEqual(block, 0) + self.assertLessEqual(block, 255) + + def test_from_row_stores_tablet_version(self): + """Tablet.from_row stores the tablet_version it is given (the V2 payload field).""" + version = 0xDEADBEEFCAFEBABE + tablet = Tablet.from_row(-100, 100, [("host1", 0), ("host2", 1)], tablet_version=version) + self.assertIsNotNone(tablet) + self.assertEqual(tablet.tablet_version, version) + self.assertEqual(tablet.first_token, -100) + self.assertEqual(tablet.last_token, 100) + self.assertEqual(len(tablet.replicas), 2) + + +class ExecuteMessageSerializationTest(unittest.TestCase): + """ExecuteMessage.send_body decides whether to emit the tablet_version_block + from the serving connection's negotiated protocol features, so the message no + longer has to be copied per send attempt (TABLETS_ROUTING_V2).""" + + # V4 keeps the encoding minimal: no prepared-metadata id, single-byte flags. + PROTOCOL_VERSION = ProtocolVersion.V4 + + def _make_message(self, tablet_version_block): + return ExecuteMessage( + query_id=b"\x01\x02\x03\x04", + query_params=[], + consistency_level=ConsistencyLevel.ONE, + tablet_version_block=tablet_version_block, + ) + + def _encode_body(self, message, protocol_features): + f = BytesIO() + message.send_body(f, self.PROTOCOL_VERSION, protocol_features) + return f.getvalue() + + def test_block_appended_on_v2_connection(self): + """A V2 connection appends exactly one trailing byte carrying the + precomputed tablet_version_block.""" + message = self._make_message(0x7A) + v2 = self._encode_body(message, ProtocolFeatures(tablets_routing_v2=True)) + plain = self._encode_body(message, ProtocolFeatures(tablets_routing_v2=False)) + self.assertEqual(v2, plain + bytes([0x7A])) + + def test_block_absent_without_v2(self): + """No trailing byte when the connection did not negotiate V2, and passing + no features at all is equivalent to V2 being off.""" + message = self._make_message(0x7A) + no_features = self._encode_body(message, None) + v2_off = self._encode_body(message, ProtocolFeatures(tablets_routing_v2=False)) + self.assertEqual(no_features, v2_off) + self.assertNotIn(bytes([0x7A]), no_features[-1:]) + + def test_missing_block_coalesces_to_zero_on_v2(self): + """On a V2 connection the server reads exactly one trailing byte per + EXECUTE, so a message whose block was never computed must still emit a + zero byte to keep the frame in sync.""" + message = self._make_message(None) + v2 = self._encode_body(message, ProtocolFeatures(tablets_routing_v2=True)) + plain = self._encode_body(message, ProtocolFeatures(tablets_routing_v2=False)) + self.assertEqual(v2, plain + bytes([0x00])) + + def test_same_message_encodes_consistently_across_connections(self): + """The same shared message instance yields the V2 or non-V2 framing purely + from the features argument, so it is safe to encode concurrently on + connections with different capabilities without copying it.""" + message = self._make_message(0x3C) + first = self._encode_body(message, ProtocolFeatures(tablets_routing_v2=True)) + second_plain = self._encode_body(message, ProtocolFeatures(tablets_routing_v2=False)) + first_again = self._encode_body(message, ProtocolFeatures(tablets_routing_v2=True)) + self.assertEqual(first, first_again) + self.assertEqual(first, second_plain + bytes([0x3C])) diff --git a/tests/unit/test_tcp_proxy.py b/tests/unit/test_tcp_proxy.py new file mode 100644 index 0000000000..4c173c6576 --- /dev/null +++ b/tests/unit/test_tcp_proxy.py @@ -0,0 +1,246 @@ +# Copyright 2026 ScyllaDB, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Regression tests for the ``TcpProxy`` test helper's connection +shutdown/join synchronization path (GitHub issue #948). + +``TcpProxy`` lives in ``tests/tcp_proxy.py`` because it backs the Client +Routes / NLB integration tests, but it is a plain socket-based helper with +no dependency on a running Cassandra/Scylla cluster or CCM. These tests +exercise it directly against a local dummy TCP echo backend, so they run as +fast, deterministic, checked-in unit tests instead of only being covered +incidentally (and non-deterministically) by the integration suite. +""" + +import socket +import threading +import time +import unittest +from unittest.mock import patch + +from tests.tcp_proxy import TcpProxy + + +class _EchoServer: + """Minimal threaded TCP echo server used as TcpProxy's backend target.""" + + def __init__(self): + self._sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + self._sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + self._sock.bind(("127.0.0.1", 0)) + self.port = self._sock.getsockname()[1] + self._sock.listen(128) + self._sock.settimeout(0.2) + self._running = True + self._accept_thread = threading.Thread(target=self._accept_loop, daemon=True) + self._accept_thread.start() + + def _accept_loop(self): + while self._running: + try: + conn, _ = self._sock.accept() + except socket.timeout: + continue + except OSError: + return + threading.Thread(target=self._echo, args=(conn,), daemon=True).start() + + @staticmethod + def _echo(conn): + try: + while True: + data = conn.recv(4096) + if not data: + return + conn.sendall(data) + except OSError: + pass + finally: + try: + conn.close() + except OSError: + pass + + def stop(self): + self._running = False + try: + self._sock.close() + except OSError: + pass + self._accept_thread.join(timeout=2) + + +def _open_client(host, port, timeout=5): + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.settimeout(timeout) + s.connect((host, port)) + return s + + +class TestTcpProxyShutdownJoin(unittest.TestCase): + """ + Regression coverage for the forwarder-thread bookkeeping bug described + in issue #948: ``_shutdown_and_join_connections`` used to unconditionally + discard every tracked connection from ``_connections``, even ones whose + forwarder thread was still alive after ``thread.join(timeout=5)`` timed + out. That made ``active_connections`` under-report live connections and + made it impossible for a later ``stop()``/``drop_connections()`` call to + retry reaping an orphaned thread, permanently leaking the thread and its + file descriptors. + """ + + def setUp(self): + self.echo = _EchoServer() + self.addCleanup(self.echo.stop) + self.proxy = TcpProxy("127.0.0.1", 0, "127.0.0.1", self.echo.port) + self.proxy.start() + self.addCleanup(self._safe_stop_proxy) + + def _safe_stop_proxy(self): + try: + self.proxy.stop() + except Exception: + pass + + def test_timed_out_forwarder_thread_is_retained_until_it_exits(self): + """ + Exact regression test for the fix: if a forwarder thread does not + exit within the join timeout, its entry must NOT be dropped from + ``_connections`` -- it must stay tracked (so ``active_connections`` + reflects reality and a later shutdown call can retry) until the + thread actually finishes. + """ + client = _open_client(self.proxy.listen_host, self.proxy.listen_port) + self.addCleanup(client.close) + client.sendall(b"ping") + self.assertEqual(client.recv(16), b"ping") + + self.assertEqual(self.proxy.active_connections, 1) + (csock, tsock), thread = list(self.proxy._connections.items())[0] + + # Shrink this thread's effective join timeout so the test doesn't + # have to block for the real 5s timeout, while neutering + # _shutdown_pair so the forwarder genuinely cannot be unblocked -- + # deterministically reproducing "still alive after the timeout". + real_join = thread.join + thread.join = lambda timeout=None: real_join(timeout=0.05) + try: + with patch.object(TcpProxy, "_shutdown_pair", + new=staticmethod(lambda a, b: None)): + self.proxy.drop_connections() + finally: + thread.join = real_join + + # The forwarder thread is still alive: the fixed code must keep + # tracking it instead of discarding the entry. + self.assertTrue(thread.is_alive(), + "test setup issue: forwarder thread should still " + "be running at this point") + self.assertEqual( + self.proxy.active_connections, 1, + "a still-alive forwarder thread's connection entry must not be " + "dropped after its join times out") + self.assertIn((csock, tsock), self.proxy._connections) + + # Retry for real: this time _shutdown_pair actually runs and + # unblocks the thread, so the retry can finish reaping it. + self.proxy.drop_connections() + + thread.join(timeout=5) + self.assertFalse(thread.is_alive()) + self.assertEqual(self.proxy.active_connections, 0) + self.assertNotIn((csock, tsock), self.proxy._connections) + + def test_concurrent_stop_and_drop_leaves_no_live_forwarders(self): + """ + Deterministic stress regression test: concurrently open/close real + connections through the proxy while other threads hammer + drop_connections(), then stop(); assert that (a) no unhandled + exception escaped any thread and (b) no forwarder thread is left + alive or tracked once stop() returns. + """ + errors = [] + stop_event = threading.Event() + forwarder_threads = set() + threads_lock = threading.Lock() + + def client_worker(): + while not stop_event.is_set(): + try: + s = _open_client(self.proxy.listen_host, + self.proxy.listen_port, timeout=1) + except OSError: + continue + try: + with self.proxy._lock: + with threads_lock: + forwarder_threads.update(self.proxy._connections.values()) + s.sendall(b"x") + s.recv(16) + except OSError: + pass + finally: + try: + s.close() + except OSError: + pass + time.sleep(0.005) + + def dropper_worker(): + while not stop_event.is_set(): + try: + self.proxy.drop_connections() + except Exception as e: + errors.append(e) + time.sleep(0.01) + + def thread_excepthook(args): + errors.append(args.exc_value) + + old_hook = threading.excepthook + threading.excepthook = thread_excepthook + try: + client_threads = [threading.Thread(target=client_worker) + for _ in range(4)] + dropper_threads = [threading.Thread(target=dropper_worker) + for _ in range(2)] + for t in client_threads + dropper_threads: + t.start() + + time.sleep(1.0) + + stop_event.set() + for t in client_threads + dropper_threads: + t.join(timeout=5) + self.assertFalse(t.is_alive()) + + self.proxy.stop() + finally: + threading.excepthook = old_hook + + self.assertEqual(errors, [], + "unhandled exceptions during concurrent " + "stop/drop: %r" % (errors,)) + self.assertEqual(self.proxy.active_connections, 0) + + with threads_lock: + collected = list(forwarder_threads) + for t in collected: + self.assertFalse(t.is_alive(), + "%s left alive after stop()" % t.name) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/unit/test_time_util.py b/tests/unit/test_time_util.py index d87a3fe2ad..05b4349cf8 100644 --- a/tests/unit/test_time_util.py +++ b/tests/unit/test_time_util.py @@ -51,15 +51,17 @@ def test_datetime_from_ms_timestamp(self): def test_times_from_uuid1(self): node = uuid.getnode() - now = time.time() + before = time.time() u = uuid.uuid1(node, 0) + after = time.time() - t = util.unix_time_from_uuid1(u) - assert now == pytest.approx(t, abs=1e-2) + uuid_time = util.unix_time_from_uuid1(u) + # Allow for coarse platform clocks and uuid1's monotonic adjustment. + assert before - 0.1 <= uuid_time <= after + 0.1 dt = util.datetime_from_uuid1(u) - t = calendar.timegm(dt.timetuple()) + dt.microsecond / 1e6 - assert now == pytest.approx(t, abs=1e-2) + datetime_time = calendar.timegm(dt.timetuple()) + dt.microsecond / 1e6 + assert datetime_time == pytest.approx(uuid_time, abs=1e-6, rel=0) def test_uuid_from_time(self): t = time.time() diff --git a/tests/unit/test_types.py b/tests/unit/test_types.py index 7a8c584f75..11aab2748d 100644 --- a/tests/unit/test_types.py +++ b/tests/unit/test_types.py @@ -120,8 +120,9 @@ def test_lookup_casstype(self): assert str(lookup_casstype('unknown')) == str(cassandra.cqltypes.mkUnrecognizedType('unknown')) - with pytest.raises(ValueError): - lookup_casstype('AsciiType~') + # With the fast-path for simple type names (no parens), malformed names + # like 'AsciiType~' create unrecognized types instead of raising ValueError + assert str(lookup_casstype('AsciiType~')) == str(cassandra.cqltypes.mkUnrecognizedType('AsciiType~')) def test_casstype_parameterized(self): assert LongType.cass_parameterized_type_with(()) == 'LongType'