Merge branch 'main' into fix-www-auth-substring-match-3009

Author: Whning0513

.github/actions/conformance/client.py

@@ -38,7 +38,7 @@
 from typing import Any, cast
 from urllib.parse import parse_qs, urlparse
 
-import httpx
+import httpx2
 import mcp_types as types
 from mcp_types.version import MODERN_PROTOCOL_VERSIONS
 from pydantic import AnyUrl
@@ -151,7 +151,7 @@ async def handle_redirect(self, authorization_url: str) -> None:
         """Fetch the authorization URL and extract the auth code from the redirect."""
         logger.debug(f"Fetching authorization URL: {authorization_url}")
 
-        async with httpx.AsyncClient() as client:
+        async with httpx2.AsyncClient() as client:
             response = await client.get(
                 authorization_url,
                 follow_redirects=False,
@@ -486,13 +486,13 @@ async def run_enterprise_managed_authorization(server_url: str) -> None:
     # learn it from the harness's PRM document (RFC 9728); production
     # deployments would supply it as static configuration instead.
     prm_url = build_protected_resource_metadata_discovery_urls(None, server_url)[0]
-    async with httpx.AsyncClient(timeout=30.0) as http:
+    async with httpx2.AsyncClient(timeout=30.0) as http:
         prm = (await http.get(prm_url)).raise_for_status().json()
     as_issuer = prm["authorization_servers"][0]
 
     async def fetch_id_jag(audience: str, resource: str) -> str:
         """Leg 1 - RFC 8693 token-exchange at the enterprise IdP."""
-        async with httpx.AsyncClient(timeout=30.0) as http:
+        async with httpx2.AsyncClient(timeout=30.0) as http:
             resp = await http.post(
                 idp_token_endpoint,
                 data={
@@ -563,9 +563,9 @@ async def run_auth_code_client(server_url: str) -> None:
     await _run_auth_session(server_url, oauth_auth)
 
 
-async def _run_auth_session(server_url: str, oauth_auth: httpx.Auth) -> None:
+async def _run_auth_session(server_url: str, oauth_auth: httpx2.Auth) -> None:
     """Common session logic for all OAuth flows."""
-    http_client = httpx.AsyncClient(auth=oauth_auth, timeout=30.0)
+    http_client = httpx2.AsyncClient(auth=oauth_auth, timeout=30.0)
     transport = streamable_http_client(url=server_url, http_client=http_client)
     async with Client(transport, mode=client_mode(), elicitation_callback=default_elicitation_callback) as client:
         logger.debug("Initialized successfully")

.github/actions/conformance/run-client.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# Run a client conformance suite, re-verifying unexpected failures solo.
+# Concurrent suite runs on a 2-vCPU runner can push scenarios with real-time
+# waits past tolerance; solo, a real failure fails again while a contention
+# artifact passes. Failures that only reproduce under concurrency are excused.
+set -uo pipefail
+
+: "${CONFORMANCE_PKG:?set CONFORMANCE_PKG (pinned in .github/workflows/conformance.yml)}"
+# One attempt: a solo failure on the quiet runner disproves the contention
+# hypothesis; a second try would be the blind retry this script avoids.
+SOLO_ATTEMPTS="${CONFORMANCE_SOLO_ATTEMPTS:-1}"
+
+# Relative args resolve from the repo root; same contract as run-server.sh.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR/../../.." || exit 1
+
+log="$(mktemp)"
+trap 'rm -f "$log"' EXIT
+
+npx --yes "$CONFORMANCE_PKG" client "$@" 2>&1 | tee "$log"
+rc=${PIPESTATUS[0]}
+if [ "$rc" -eq 0 ]; then
+    exit 0
+fi
+
+plain="$(sed 's/\x1b\[[0-9;]*m//g' "$log")"
+
+# If the harness's summary wording changes, the list comes up empty and the
+# original exit code passes through - never a false green.
+mapfile -t scenarios < <(
+    printf '%s\n' "$plain" |
+        sed -n '/^Unexpected failures (not in baseline):$/,/^$/p' |
+        sed -n 's/^  ✗ //p'
+)
+if [ "${#scenarios[@]}" -eq 0 ]; then
+    exit "$rc"
+fi
+for scenario in "${scenarios[@]}"; do
+    if ! [[ "$scenario" =~ ^[A-Za-z0-9/_-]+$ ]]; then
+        echo "Extracted unexpected-failure name '${scenario}' does not look like a scenario name; passing the suite failure through." >&2
+        exit "$rc"
+    fi
+done
+
+# A stale baseline entry is a configuration error a solo rerun cannot excuse.
+# Here-string, not a pipe: grep -q quitting early would SIGPIPE printf and,
+# under pipefail, skip this guard exactly when the pattern is present.
+if grep -q '^Stale baseline entries' <<<"$plain"; then
+    echo "Suite also reported stale baseline entries; not retrying." >&2
+    exit "$rc"
+fi
+
+# Drop the suite-only flags: --scenario replaces --suite, and solo runs are
+# judged directly rather than against the baseline.
+rerun_args=()
+output_dir=""
+skip_next=0
+expect_output_dir=0
+for arg in "$@"; do
+    if [ "$skip_next" -eq 1 ]; then
+        if [ "$expect_output_dir" -eq 1 ]; then
+            output_dir="$arg"
+        fi
+        skip_next=0
+        expect_output_dir=0
+        continue
+    fi
+    case "$arg" in
+    --output-dir)
+        skip_next=1
+        expect_output_dir=1
+        ;;
+    --suite | --expected-failures) skip_next=1 ;;
+    --output-dir=*) output_dir="${arg#--output-dir=}" ;;
+    --suite=* | --expected-failures=*) ;;
+    *) rerun_args+=("$arg") ;;
+    esac
+done
+if [ -n "$output_dir" ]; then
+    rerun_args+=(--output-dir "${output_dir}-solo")
+fi
+
+for scenario in "${scenarios[@]}"; do
+    passed=0
+    for attempt in $(seq 1 "$SOLO_ATTEMPTS"); do
+        echo ""
+        echo "Re-running '${scenario}' solo (attempt ${attempt}/${SOLO_ATTEMPTS})..."
+        if npx --yes "$CONFORMANCE_PKG" client --scenario "$scenario" "${rerun_args[@]}"; then
+            passed=1
+            break
+        fi
+    done
+    if [ "$passed" -ne 1 ]; then
+        echo "'${scenario}' still fails when run alone: real failure, not suite contention." >&2
+        exit 1
+    fi
+done
+
+if [ -n "$output_dir" ]; then
+    mkdir -p "$output_dir"
+    printf '%s\n' "${scenarios[@]}" > "$output_dir/FLAKE_RESCUED"
+fi
+echo "All ${#scenarios[@]} unexpected failure(s) passed when re-run solo; the suite failures were parallel-run contention."
+exit 0

.github/workflows/conformance.yml

@@ -64,17 +64,20 @@ jobs:
           ./.github/actions/conformance/run-server.sh
           --suite active
           --expected-failures ./.github/actions/conformance/expected-failures.yml
+          --output-dir conformance-results/server-active
       - name: Run server conformance (draft suite)
         run: >-
           ./.github/actions/conformance/run-server.sh
           --suite draft
           --expected-failures ./.github/actions/conformance/expected-failures.yml
+          --output-dir conformance-results/server-draft
       - name: Run server conformance (2026-07-28 wire, all suite)
         run: >-
           ./.github/actions/conformance/run-server.sh
           --suite all
           --spec-version 2026-07-28
           --expected-failures ./.github/actions/conformance/expected-failures.2026-07-28.yml
+          --output-dir conformance-results/server-2026-07-28
       - name: Run server conformance (all suite, extension scenarios)
         # A bare `--suite all` (no --spec-version) selects every scenario
         # shipped with the pinned harness — including the extension-tagged
@@ -91,6 +94,15 @@ jobs:
           ./.github/actions/conformance/run-server.sh
           --suite all
           --expected-failures ./.github/actions/conformance/expected-failures.yml
+          --output-dir conformance-results/server-all
+      - name: Upload conformance results
+        # The log has only summary counts; per-check data is in checks.json.
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: server-conformance-results
+          path: conformance-results/
+          if-no-files-found: ignore
 
   client-conformance:
     runs-on: ubuntu-latest
@@ -118,22 +130,39 @@ jobs:
               echo "CONFORMANCE_PKG=file:/tmp/conformance.tgz" >> "$GITHUB_ENV"
               ;;
           esac
-      - run: uv sync --frozen --all-extras --package mcp
+      # --compile-bytecode: without it, ~40 concurrently spawned interpreters
+      # race to byte-compile site-packages during the timing-sensitive window.
+      - run: uv sync --frozen --all-extras --package mcp --compile-bytecode
+      - name: Pre-compile bytecode (editable sources)
+        run: uv run --frozen python -m compileall -q src .github/actions/conformance
       - name: Run client conformance (all suite)
         # The harness runs all scenarios via unbounded Promise.all; with 40
         # scenarios on a 2-core runner the slowest one (sse-retry, which has a
         # real-time SSE reconnect wait) needs more than the 30s default budget.
+        # `.venv/bin/python` (not `uv run`) avoids lockfile re-checks in ~40
+        # concurrent spawns; run-client.sh re-runs unexpected failures solo.
         run: >-
-          npx --yes "$CONFORMANCE_PKG" client
-          --command 'uv run --frozen python .github/actions/conformance/client.py'
+          ./.github/actions/conformance/run-client.sh
+          --command '.venv/bin/python .github/actions/conformance/client.py'
           --suite all
           --timeout 60000
           --expected-failures ./.github/actions/conformance/expected-failures.yml
+          --output-dir conformance-results/client-all
       - name: Run client conformance (2026-07-28 wire, all suite)
         run: >-
-          npx --yes "$CONFORMANCE_PKG" client
-          --command 'uv run --frozen python .github/actions/conformance/client.py'
+          ./.github/actions/conformance/run-client.sh
+          --command '.venv/bin/python .github/actions/conformance/client.py'
           --suite all
           --timeout 60000
           --spec-version 2026-07-28
           --expected-failures ./.github/actions/conformance/expected-failures.2026-07-28.yml
+          --output-dir conformance-results/client-2026-07-28
+      - name: Upload conformance results
+        # The log has only summary counts; per-check data is in checks.json.
+        # Also on FLAKE_RESCUED: rescued-flake evidence is otherwise discarded.
+        if: failure() || hashFiles('conformance-results/**/FLAKE_RESCUED') != ''
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: client-conformance-results
+          path: conformance-results/
+          if-no-files-found: ignore

.github/workflows/deploy-docs.yml

@@ -14,6 +14,7 @@ on:
       - src/mcp/**
       - src/mcp-types/**
       - scripts/build-docs.sh
+      - scripts/docs/**
       - pyproject.toml
       - uv.lock
       - .github/workflows/deploy-docs.yml

.github/workflows/docs-preview.yml

@@ -1,13 +1,14 @@
 name: Docs Preview
 
-# Builds the mkdocs site for a PR and deploys it to Cloudflare Pages.
+# Builds the docs site for a PR and deploys it to Cloudflare Pages.
 #
-# Security: mkdocs executes Python from the PR (mkdocstrings imports src/mcp,
-# `!!python/name:` directives). The build is gated by `authorize` (admin sender
-# for auto-preview, admin/maintainer commenter for /preview-docs) and isolated
-# from Cloudflare secrets — `build` runs PR code with no secrets and hands the
-# static site to `deploy` via an artifact, so PR code never shares a runner
-# with the Cloudflare token.
+# Security: the build executes Python from the PR (mkdocstrings imports
+# src/mcp, `!!python/name:` config directives run, and heads may ship their
+# own build scripts). The build is gated by `authorize` (admin sender for
+# auto-preview, admin/maintainer commenter for /preview-docs) and isolated
+# from Cloudflare secrets — `build` runs PR code with no secrets and hands
+# the static site to `deploy` via an artifact, so PR code never shares a
+# runner with the Cloudflare token.
 #
 # Required configuration:
 #   - secrets.CLOUDFLARE_API_TOKEN   (scope: Account → Cloudflare Pages → Edit)
@@ -21,6 +22,7 @@ on:
       - docs/**
       - docs_src/**
       - mkdocs.yml
+      - scripts/docs/**
       - pyproject.toml
   issue_comment:
     types: [created]
@@ -128,14 +130,30 @@ jobs:
           enable-cache: false
           version: 0.9.5
 
-      - run: uv sync --frozen --group docs
-      - run: uv run --frozen --no-sync mkdocs build
+      # pull_request_target runs this workflow file from the base branch, so
+      # the whole recipe — dependency sync included — must come from the
+      # checkout itself: heads that ship scripts/docs/build.sh (the Zensical
+      # toolchain) build with it; older heads, and v1.x heads previewed via
+      # /preview-docs, still build with MkDocs. Both arms must write the site
+      # to site/. Keep the detection in sync with build_site() in
+      # scripts/build-docs.sh.
+      - run: |
+          if [ -f scripts/docs/build.sh ]; then
+            bash scripts/docs/build.sh
+          else
+            uv sync --frozen --group docs
+            # The env var silences mkdocs-material's MkDocs 2.0 warning banner.
+            NO_MKDOCS_2_WARNING=1 uv run --frozen --no-sync mkdocs build
+          fi
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: site
           path: site/
           retention-days: 1
+          # An empty site/ means the build arm broke its output contract; fail
+          # here instead of surfacing as a confusing download error in deploy.
+          if-no-files-found: error
 
   deploy:
     needs: [authorize, build]