dpe-conformance 0.4.0__py3-none-any.whl

dpe_conformance/__init__.py

@@ -0,0 +1,16 @@
+"""dpe-conformance：DPE 服务端一致性跑分器。
+
+黑盒对任意 remote 运行协议检查（检查面见仓库 `conformance/README.md`）：套件以 pytest
+实现、按章节组织在 ``dpe_conformance.checks`` 下；``dpe-conformance`` CLI 按中性配置
+（身份与服务端钩子，见 ``dpe_conformance.config``）驱动套件，输出 JUnit XML 与「已执行 /
+跳过」计数，供 CI 断言执行数不低于基线（防止因 skip 而假绿）。
+
+跑分器本体只依赖 dpe-hash（期望 hash）与 HTTP；不 import 任何服务端实现——参考服务端
+（``dpe_sdk.testing``）只在本包的测试里作为自测对手，以独立进程或 ASGI 方式连接。
+"""
+
+from importlib.metadata import version
+
+__version__ = version("dpe-conformance")
+
+__all__ = ["__version__"]

dpe_conformance/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m dpe_conformance``：等价于 ``dpe-conformance`` 控制台脚本。"""
+
+from __future__ import annotations
+
+import sys
+
+from dpe_conformance.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

dpe_conformance/_env_transport.py

@@ -0,0 +1,64 @@
+"""按目的地套用代理规则的 httpx 传输层（#194）：跑分器不读操作系统的代理设置。
+
+httpx 缺省（``trust_env=True``）在 macOS / Windows 上环境变量为空时会回退读系统代理，对被测
+服务端（含本机回环地址）的请求可能被悄悄送进系统代理。给客户端显式传入本传输层后，httpx 不再
+自行探测代理；是否经代理、经哪个，由 ``dpe_conformance._proxy`` 的规则按**每个请求的目的地**
+判定——target 与服务端钩子（``hooks``，可在另一个 origin）共用一个客户端，不能只按 target 判定
+一次。环境变量在构造时快照一次。
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Mapping
+
+import httpx
+
+from dpe_conformance._proxy import proxy_for
+
+__all__ = ["EnvProxyTransport", "destination"]
+
+
+def destination(url: httpx.URL | str) -> str:
+    """规则按 scheme 与主机判定：把一个 URL 化成 ``scheme://主机/``（IPv6 带方括号）。
+
+    主机取线上的 ASCII 形式（``raw_host``）：``host`` 会把 ``xn--`` 主机解码成 Unicode，与 SDK
+    按原串字符切分的口径不同（``NO_PROXY`` 的 ``xn--`` 条目会因此匹配不上）。
+    """
+    parsed = httpx.URL(url)
+    host = parsed.raw_host.decode("ascii")
+    if ":" in host:
+        host = f"[{host}]"
+    return f"{parsed.scheme}://{host}/"
+
+
+class EnvProxyTransport(httpx.BaseTransport):
+    """按目的地选择直连或经代理的 ``httpx.HTTPTransport``（同一代理复用同一个传输层）。
+
+    代理 URL 不合法时 ``proxy_for`` 抛 ``ValueError``；跑分器在配置阶段已对 target 与每个 HTTP
+    钩子预先判定过（见 ``plugin``），请求期不会遇到。
+    """
+
+    def __init__(self, environ: Mapping[str, str]) -> None:
+        self._environ = dict(environ)
+        self._transports: dict[str | None, httpx.HTTPTransport] = {}
+        self._lock = threading.Lock()  # 并发请求不重复创建（泄漏）同一代理的连接池
+
+    def proxy_for(self, url: httpx.URL | str) -> str | None:
+        """该目的地应经的代理 URL；直连为 ``None``。"""
+        return proxy_for(destination(url), self._environ)
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        proxy = self.proxy_for(request.url)
+        with self._lock:
+            transport = self._transports.get(proxy)
+            if transport is None:
+                transport = self._transports[proxy] = httpx.HTTPTransport(proxy=proxy)
+        return transport.handle_request(request)
+
+    def close(self) -> None:
+        with self._lock:
+            transports = list(self._transports.values())
+            self._transports.clear()
+        for transport in transports:
+            transport.close()

dpe_conformance/_proxy.py

@@ -0,0 +1,192 @@
+"""代理只来自环境变量（#194）：判定规则的**自留副本**，原件是 ``dpe_sdk._proxy``。
+
+跑分器不依赖 dpe-sdk（#26 的边界），代理判定又不是规范定义的契约、不进 dpe-hash（#194 架构
+裁决），所以在这里保留一份。本文件除模块说明外与原件**逐字相同**：测试比较两者的 AST，并逐例
+消费两个 SDK 共用的用例表 ``sdk/testdata/proxy_env.json``——改规则须先改原件、再同步这里。
+
+规则（详见原件的模块说明）：只读 ``HTTP_PROXY`` / ``HTTPS_PROXY`` / ``ALL_PROXY`` /
+``NO_PROXY``，从不读操作系统的代理设置；大写优先、ASCII 空白去掉后为空视为未设置；存在
+``REQUEST_METHOD`` 时全部忽略；``NO_PROXY`` 支持 ``*``、域名及子域、IP 与 CIDR；代理 URL 按
+固定文法校验，不合法抛 ``ValueError``（消息不回显值）。
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from collections.abc import Mapping
+
+__all__ = ["proxy_for"]
+
+_Address = ipaddress.IPv4Address | ipaddress.IPv6Address
+_Network = ipaddress.IPv4Network | ipaddress.IPv6Network
+
+#: 两个 SDK 共用的空白字符集（Python 的 ``str.strip()`` 还会去掉 ``\x1c``–``\x1f`` 等，Rust 的
+#: ``trim()`` 按 Unicode，二者都不用）
+_WHITESPACE = " \t\n\r\x0b\x0c"
+_ASCII_LOWER = str.maketrans("ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz")
+_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.\-]*", re.ASCII)
+_LABEL = re.compile(r"[A-Za-z0-9\-]+", re.ASCII)
+_PORT = re.compile(r"[0-9]{1,5}", re.ASCII)
+_NUMERIC_LABEL = re.compile(r"[0-9]+|0[xX].*", re.ASCII)
+#: 代理 URL 的长度上限（字符数，此时都是 ASCII）：reqwest 连接时经 ``http::Uri`` 重新解析，超过
+#: 其 65534 字节上限会静默直连——两侧都在构造时拒绝过长的值
+_MAX_PROXY_URL = 4096
+#: RFC 3986：URI 允许的字符（unreserved、gen-delims、sub-delims）与 pct-encoded
+_URI = re.compile(r"(?:[A-Za-z0-9\-._~:/?#\[\]@!$&'()*+,;=]|%[0-9A-Fa-f]{2})*", re.ASCII)
+#: RFC 3986 userinfo：unreserved、pct-encoded、sub-delims、``:``（没有 ``@``）
+_USERINFO = re.compile(r"(?:[A-Za-z0-9\-._~!$&'()*+,;=:]|%[0-9A-Fa-f]{2})*", re.ASCII)
+
+
+def _lower(text: str) -> str:
+    return text.translate(_ASCII_LOWER)
+
+
+def _lookup(environ: Mapping[str, str], name: str) -> tuple[str, str] | None:
+    """先大写、后小写，取第一个非空值：返回（变量名, 去掉首尾 ASCII 空白的值）。"""
+    for key in (name.upper(), name.lower()):
+        value = environ.get(key, "").strip(_WHITESPACE)
+        if value:
+            return key, value
+    return None
+
+
+def _remote_scheme_and_host(remote: str) -> tuple[str, str]:
+    """已按 HTTP 绑定 §1 校验过的 remote 的 scheme 与主机（IPv6 去掉方括号）：纯字符切分。"""
+    scheme, _, rest = remote.partition("://")
+    authority = rest.split("/", 1)[0]
+    if authority.startswith("["):
+        host = authority[1 : authority.find("]")]
+    else:
+        host = authority.partition(":")[0]
+    return _lower(scheme), _lower(host)
+
+
+def _address(text: str) -> _Address | None:
+    if text.startswith("[") and text.endswith("]"):
+        text = text[1:-1]
+    if "%" in text:  # 带 zone 的 IPv6 不按地址处理（两个 SDK 同一口径）
+        return None
+    try:
+        return ipaddress.ip_address(text)
+    except ValueError:
+        return None
+
+
+def _network(entry: str) -> _Network | None:
+    """IP 或 ``addr/前缀长度``（前缀只接受十进制数字，不接受掩码写法）。"""
+    text, slash, prefix = entry.partition("/")
+    address = _address(text)
+    if address is None:
+        return None
+    if not slash:
+        return ipaddress.ip_network(address)
+    if not prefix.isascii() or not prefix.isdigit():
+        return None
+    # 先去掉前导零再看位数：去零后超过 3 位必然大于 128，直接判不匹配——不把任意长的数字串交给
+    # int()（Python 对超过 4300 位的转换直接抛错，#206）。与 Rust 按 u32 解析的结论逐例一致：
+    # 前导零照常接受，越界（含 u32 溢出）都不匹配
+    digits = prefix.lstrip("0") or "0"
+    if len(digits) > 3 or int(digits) > address.max_prefixlen:
+        return None
+    return ipaddress.ip_network((address, int(digits)), strict=False)
+
+
+def _bypass(host: str, no_proxy: str) -> bool:
+    """remote 的主机是否命中 ``NO_PROXY``。"""
+    host_address = _address(host)
+    for raw in no_proxy.split(","):
+        entry = _lower(raw.strip(_WHITESPACE))
+        if not entry:
+            continue
+        if entry == "*":
+            return True
+        network = _network(entry)
+        if network is not None:
+            if host_address is not None and host_address in network:
+                return True
+            continue
+        domain = entry.removeprefix(".")
+        if domain and host_address is None and (host == domain or host.endswith("." + domain)):
+            return True
+    return False
+
+
+def _valid_host(host: str) -> bool:
+    """代理主机：方括号内的 IPv6、点分十进制 IPv4，或 LDH 标签组成的域名（见模块说明）。"""
+    if host.startswith("["):
+        inner = host[1:-1] if host.endswith("]") else ""
+        if not inner or "%" in inner:
+            return False
+        try:
+            ipaddress.IPv6Address(inner)
+        except ValueError:
+            return False
+        return True
+    labels = host.split(".")
+    if not all(_LABEL.fullmatch(label) for label in labels):
+        return False  # 含空标签（空主机、尾点、连续点）与 LDH 之外的字符
+    if any(_lower(label).startswith("xn--") for label in labels):
+        return False
+    if _NUMERIC_LABEL.fullmatch(labels[-1]):
+        try:
+            ipaddress.IPv4Address(host)
+        except ValueError:
+            return False
+    return True
+
+
+def _check_proxy_url(variable: str, url: str) -> tuple[str, int | None]:
+    """按模块说明第 5 条校验补全 scheme 之后的代理 URL，返回（主机, 端口）（IPv6 带方括号，
+    端口没写为 ``None``）；不合法抛 ``ValueError``。"""
+    invalid = ValueError(f"环境变量 {variable} 的代理 URL 不合法")
+    if len(url) > _MAX_PROXY_URL or not _URI.fullmatch(url):
+        raise invalid
+    scheme, _, rest = url.partition("://")
+    if not _SCHEME.fullmatch(scheme):
+        raise invalid  # 不回显：不合法的「scheme」里可能夹着凭证
+    if _lower(scheme) not in ("http", "https"):
+        raise ValueError(
+            f"环境变量 {variable} 的代理 scheme {scheme!r} 不受支持（只支持 http / https）"
+        )
+    end = min((i for i in (rest.find(c) for c in "/?#") if i >= 0), default=len(rest))
+    authority, tail = rest[:end], rest[end:]
+    if tail not in ("", "/"):
+        raise invalid
+    userinfo, at, hostport = authority.rpartition("@")
+    if at and not _USERINFO.fullmatch(userinfo):
+        raise invalid
+    if hostport.startswith("["):
+        close = hostport.find("]")
+        host, port_part = (hostport[: close + 1], hostport[close + 1 :]) if close >= 0 else ("", "")
+    else:
+        host, colon, port = hostport.partition(":")
+        port_part = colon + port
+    if not _valid_host(host):
+        raise invalid
+    if not port_part:
+        return host, None
+    port = port_part[1:]
+    if not port_part.startswith(":") or not _PORT.fullmatch(port) or int(port) > 65535:
+        raise invalid
+    return host, int(port)
+
+
+def proxy_for(remote: str, environ: Mapping[str, str]) -> str | None:
+    """按模块说明的规则判定 ``remote`` 应经的代理 URL；直连返回 ``None``。
+
+    代理 URL 不合法或 scheme 不受支持时抛 ``ValueError``（消息不回显可能带凭证的值）。
+    """
+    if "REQUEST_METHOD" in environ:
+        return None
+    scheme, host = _remote_scheme_and_host(remote)
+    found = _lookup(environ, f"{scheme}_proxy") or _lookup(environ, "all_proxy")
+    if found is None:
+        return None
+    no_proxy = _lookup(environ, "no_proxy")
+    if no_proxy is not None and _bypass(host, no_proxy[1]):
+        return None
+    variable, value = found
+    url = value if "://" in value else "http://" + value
+    _check_proxy_url(variable, url)
+    return url

dpe_conformance/checks/__init__.py

@@ -0,0 +1,5 @@
+"""检查套件：一节一章（``--section`` 过滤的粒度），模块或包。
+
+每章是普通 pytest 模块：用例经 ``dpe_conformance.plugin`` 的夹具取得被测 remote、已配置
+身份与服务端钩子；需要而未配置的依赖使对应用例显式 skip（计入计数，见包 README）。
+"""

dpe_conformance/checks/capabilities.py

@@ -0,0 +1,94 @@
+"""章：capabilities 与契约头（#27 子集 1）。
+
+- HTTP §4.1：capabilities 的字段与约束（``staging_ttl_seconds`` ≥ 3600 见 HTTP §4.1 与 CORE §3.4）；
+- HTTP §3.1：``DPE-Hash-Contract`` 是除 ``GET capabilities`` 外每个请求的必带头，
+  缺失或不受支持 → ``DPE_CONTRACT_UNSUPPORTED``；无体端点的校验顺序为「契约 → uri」（HTTP §3.1）。
+"""
+
+from __future__ import annotations
+
+from dpe_conformance.plugin import Target
+from dpe_conformance.support import (
+    assert_head_error,
+    assert_problem,
+    has_dpe_vary,
+    optional_identity,
+)
+
+_LIMIT_FIELDS = (
+    "max_payload_bytes",
+    "page_max_bytes",
+    "staging_ttl_seconds",
+    "blob_max_bytes",
+    "blob_chunk_bytes",
+    "batch_head_max",
+    "list_page_max",
+)
+
+
+def test_capabilities_fields(conformance_target: Target) -> None:
+    """HTTP §4.1：capabilities 的响应体字段与约束；该端点不带
+    ``Vary: DPE-Hash-Contract``（HTTP §3.1）。"""
+    response = conformance_target.send(
+        "GET", "capabilities", contract=None, identity=optional_identity(conformance_target)
+    )
+    assert response.status_code == 200, f"capabilities 返回 {response.status_code}"
+    body = response.json()
+    assert body.get("protocol") == "dpe/1", f"protocol 是 {body.get('protocol')!r}"
+    contracts = body.get("hash_contracts")
+    assert (
+        isinstance(contracts, list) and contracts and all(isinstance(c, str) for c in contracts)
+    ), f"hash_contracts 必须是非空字符串数组：{contracts!r}"
+    assert "dpe1" in contracts, "跑分器以 dpe1 校验，服务端必须声明它"
+    limits = body.get("limits")
+    assert isinstance(limits, dict), f"limits 必须是对象：{limits!r}"
+    for field in _LIMIT_FIELDS:
+        value = limits.get(field)
+        assert isinstance(value, int) and not isinstance(value, bool), (
+            f"limits.{field} 必须是整数：{value!r}"
+        )
+    assert limits["staging_ttl_seconds"] >= 3600, (
+        f"staging_ttl_seconds 必须 ≥ 3600，实际 {limits['staging_ttl_seconds']}"
+    )
+    for field in ("content_encodings", "features"):
+        value = body.get(field)
+        assert isinstance(value, list) and all(isinstance(item, str) for item in value), (
+            f"{field} 必须是字符串数组：{value!r}"
+        )
+    assert not has_dpe_vary(response), "capabilities 不带 Vary: DPE-Hash-Contract（HTTP §3.1）"
+
+
+def test_contract_header_missing_is_contract_unsupported(conformance_target: Target) -> None:
+    """HTTP §3.1：无契约头的 head → 400 + DPE_CONTRACT_UNSUPPORTED（HEAD 无体、只有错误码头）。"""
+    response = conformance_target.send(
+        "HEAD",
+        "documents",
+        contract=None,
+        identity=optional_identity(conformance_target),
+        params={"uri": conformance_target.uri("caps/absent")},
+    )
+    assert_head_error(response, status=400, code="DPE_CONTRACT_UNSUPPORTED")
+
+
+def test_contract_header_unsupported_is_contract_unsupported(conformance_target: Target) -> None:
+    """HTTP §3.1：声明不受支持的契约 → 400 + DPE_CONTRACT_UNSUPPORTED。"""
+    response = conformance_target.send(
+        "HEAD",
+        "documents",
+        contract="dpe9",
+        identity=optional_identity(conformance_target),
+        params={"uri": conformance_target.uri("caps/absent")},
+    )
+    assert_head_error(response, status=400, code="DPE_CONTRACT_UNSUPPORTED")
+
+
+def test_contract_header_missing_on_json_body_endpoint(conformance_target: Target) -> None:
+    """HTTP §4.2 + §3.1：带 JSON 体的端点缺契约头 → 400 + DPE_CONTRACT_UNSUPPORTED。"""
+    response = conformance_target.send(
+        "POST",
+        "heads",
+        contract=None,
+        identity=optional_identity(conformance_target),
+        json={"uris": [conformance_target.uri("caps/absent")]},
+    )
+    assert_problem(response, status=400, code="DPE_CONTRACT_UNSUPPORTED", documents_path=False)