create-windy 0.5.2 → 0.6.0

package/template/apps/document-server/tests/support.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from typing import cast
+
+from southwind_document_server.config import DocumentRuntimeConfig
+from southwind_document_server.contracts import (
+    ArtifactInput,
+    JsonValue,
+    OutputArtifactDeclaration,
+    OutputArtifactLimits,
+    OutputArtifactSinkDescriptor,
+    ProviderEgress,
+    RuntimeLimits,
+    StartDocumentRunRequest,
+)
+from southwind_document_server.readiness_contracts import (
+    AdapterDocumentReadinessV1,
+    OutputArtifactSinkReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+)
+
+RAW_GRANT = f"outgrant_v1_{'A' * 43}"
+RUN_ID = f"doc_{'1' * 64}"
+RUNTIME_IDENTITY = "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01"
+ADAPTER_IDENTITY = "windy-deployment-v1_8c98de28-5af2-44ae-9d37-2a54173284bf"
+ADAPTER_RELEASE_DIGEST = f"sha256:{'a' * 64}"
+SINK_IDENTITY = "windy-deployment-v1_11c93162-e5f0-40af-93ce-9771a4bf12ed"
+SINK_RELEASE_DIGEST = f"sha256:{'9' * 64}"
+
+
+def adapter_readiness_payload(
+    *,
+    output_artifact: bool = True,
+) -> dict[str, object]:
+    return {
+        "contractVersion": 1,
+        "status": "ready",
+        "runtimeKind": "document",
+        "deployment": {
+            "identity": ADAPTER_IDENTITY,
+            "releaseDigest": ADAPTER_RELEASE_DIGEST,
+        },
+        "offers": [
+            {
+                "variant": "ocr",
+                "capabilityVersion": "intranet-ocr-2026-07",
+                "capabilities": [
+                    "document.ocr",
+                    "document.layout",
+                    "document.table",
+                ],
+                "inputModalities": ["document", "image"],
+                "outputModalities": ["document", "text"],
+                "limits": {
+                    "maxDurationSeconds": 1200,
+                    "maxInputBytes": 128 * 1024 * 1024,
+                    "maxOutputBytes": 32 * 1024 * 1024,
+                    "maxUnits": 500,
+                    "maxArtifacts": 100,
+                    "maxConcurrentRuns": 4,
+                    "maxQueueDepth": 32,
+                },
+                **({"outputArtifactContractVersion": 1} if output_artifact else {}),
+            }
+        ],
+    }
+
+
+def readiness_facts(
+    *,
+    output_artifact: bool = True,
+) -> tuple[str, str]:
+    response = AdapterDocumentReadinessV1.model_validate(
+        adapter_readiness_payload(output_artifact=output_artifact)
+    )
+    sink = (
+        OutputArtifactSinkReadinessV1.model_validate(sink_readiness_payload())
+        if output_artifact
+        else None
+    )
+    return (
+        compute_release_digest(response, sink),
+        compute_offers_digest(final_offers(response)),
+    )
+
+
+def runtime_config(store_path: str = ":memory:") -> DocumentRuntimeConfig:
+    release_digest, offers_digest = readiness_facts()
+    return DocumentRuntimeConfig(
+        internal_token="internal",
+        store_path=store_path,
+        artifact_url="http://server.internal/api/internal/ai/artifacts",
+        adapter_url="http://adapter.internal",
+        adapter_token=None,
+        deployment_key="document.intranet-ocr",
+        capabilities=(
+            "document.layout",
+            "document.ocr",
+            "document.table",
+        ),
+        deployment_identity=RUNTIME_IDENTITY,
+        release_digest=release_digest,
+        offers_digest=offers_digest,
+        output_artifact_url=("http://server.internal/api/internal/ai/output-artifacts"),
+    )
+
+
+def sink_descriptor(
+    generation: int = 1,
+    scope: str = f"outscope_{'2' * 32}",
+) -> OutputArtifactSinkDescriptor:
+    return OutputArtifactSinkDescriptor(
+        contract_version=1,
+        scope=scope,
+        output_kind="searchable-pdf",
+        deployment_identity=RUNTIME_IDENTITY,
+        release_digest=f"sha256:{'c' * 64}",
+        offers_digest=f"sha256:{'d' * 64}",
+        policy_digest="e" * 64,
+        grant_generation=generation,
+        allowed_media_types=["application/pdf"],
+        expires_at="2030-07-31T12:05:00.000Z",
+        limits=OutputArtifactLimits(
+            max_artifact_bytes=32 * 1024,
+            max_artifacts=2,
+            max_total_bytes=64 * 1024,
+        ),
+    )
+
+
+def readiness_sink_descriptor(
+    generation: int = 1,
+) -> OutputArtifactSinkDescriptor:
+    release_digest, offers_digest = readiness_facts()
+    return sink_descriptor(generation=generation).model_copy(
+        update={
+            "release_digest": release_digest,
+            "offers_digest": offers_digest,
+        }
+    )
+
+
+def sink_readiness_payload() -> dict[str, object]:
+    return {
+        "contractVersion": 1,
+        "status": "ready",
+        "capability": "document.output-artifact.v1",
+        "sink": {
+            "identity": SINK_IDENTITY,
+            "releaseDigest": SINK_RELEASE_DIGEST,
+            "protocolVersion": 1,
+        },
+    }
+
+
+def document_request(
+    *,
+    sink: OutputArtifactSinkDescriptor | None = None,
+) -> StartDocumentRunRequest:
+    return StartDocumentRunRequest(
+        kind="document",
+        run_id=RUN_ID if sink else None,
+        operation_key="evidence.document.ocr",
+        options={"outputs": ["pages"]},
+        sources=[
+            ArtifactInput(
+                value="opaque-artifact-ref",
+                media_type="application/pdf",
+                byte_size=12,
+                sha256="a" * 64,
+            )
+        ],
+        required_capabilities=["document.ocr"],
+        data_classification="sensitive",
+        limits=RuntimeLimits(
+            max_duration_seconds=60,
+            max_input_bytes=1024,
+            max_output_bytes=64 * 1024,
+            max_units=20,
+            max_artifacts=2,
+        ),
+        provider_egress=ProviderEgress(mode="forbidden"),
+        output_artifact_sink=sink,
+    )
+
+
+def artifact_declaration(
+    byte_size: int,
+    sha256: str,
+) -> OutputArtifactDeclaration:
+    return OutputArtifactDeclaration(
+        output_key="searchable-pdf",
+        filename="searchable.pdf",
+        media_type="application/pdf",
+        byte_size=byte_size,
+        sha256=sha256,
+    )
+
+
+def document_output(
+    artifacts: list[dict[str, JsonValue]] | None = None,
+) -> dict[str, JsonValue]:
+    return {
+        "pages": [{"pageNumber": 1, "text": "第一页", "blocks": []}],
+        "tables": [],
+        "artifacts": cast(list[JsonValue], artifacts or []),
+        "metadata": {"engine": "fixture"},
+    }

package/template/apps/document-server/tests/test_adapter.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import tempfile
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import cast
+
+import httpx
+import pytest
+
+from southwind_document_server.adapter import DocumentAdapter, SafeDocumentError
+from southwind_document_server.contracts import ArtifactInput, JsonValue
+from southwind_document_server.multipart_output import parse_adapter_response
+
+from .support import (
+    RAW_GRANT,
+    adapter_readiness_payload,
+    artifact_declaration,
+    document_output,
+    document_request,
+    readiness_sink_descriptor,
+    runtime_config,
+    sink_descriptor,
+    sink_readiness_payload,
+)
+
+
+class BlockingInputStream(httpx.AsyncByteStream):
+    def __init__(self) -> None:
+        self.started = asyncio.Event()
+
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        self.started.set()
+        await asyncio.Event().wait()
+        yield b"unreachable"
+
+
+async def test_cancelled_input_download_removes_current_tempfile(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    stream = BlockingInputStream()
+    monkeypatch.setattr(tempfile, "tempdir", str(tmp_path))
+
+    async def handler(incoming: httpx.Request) -> httpx.Response:
+        if incoming.url.path.endswith("/v1/document/readiness"):
+            return httpx.Response(200, json=adapter_readiness_payload())
+        if incoming.url.path.endswith("/health/ready"):
+            return httpx.Response(200, json=sink_readiness_payload())
+        if incoming.url.path.endswith("/api/internal/ai/artifacts"):
+            return httpx.Response(200, stream=stream)
+        raise AssertionError("取消前不得调用 Provider")
+
+    adapter = DocumentAdapter(runtime_config(), httpx.MockTransport(handler))
+    task = asyncio.create_task(adapter.execute(document_request()))
+    await stream.started.wait()
+    task.cancel()
+
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert await asyncio.to_thread(lambda: not any(tmp_path.iterdir()))
+
+
+async def test_manifest_first_multipart_streams_artifacts_to_temp_files() -> None:
+    payload = b"%PDF-1.7\nsearchable"
+    declaration = artifact_declaration(
+        len(payload),
+        hashlib.sha256(payload).hexdigest(),
+    )
+    output = document_output([declaration.model_dump(by_alias=True)])
+    response = multipart_response(output, [(declaration.output_key, payload)])
+
+    execution = await parse_adapter_response(
+        response,
+        64 * 1024,
+        20,
+        sink_descriptor(),
+    )
+    assert execution.output == output
+    assert len(execution.artifacts) == 1
+    artifact = execution.artifacts[0]
+    assert artifact.path.read_bytes() == payload
+    await execution.cleanup()
+    assert not artifact.path.exists()
+
+
+async def test_json_legacy_requires_empty_artifacts_even_with_sink() -> None:
+    output = document_output(
+        [
+            {
+                "outputKey": "searchable-pdf",
+                "filename": "searchable.pdf",
+                "mediaType": "application/pdf",
+                "byteSize": 12,
+                "sha256": "a" * 64,
+            }
+        ]
+    )
+    response = httpx.Response(
+        200,
+        headers={"content-type": "application/json"},
+        content=json.dumps(output).encode(),
+    )
+    try:
+        await parse_adapter_response(
+            response,
+            64 * 1024,
+            20,
+            sink_descriptor(),
+        )
+    except SafeDocumentError as error:
+        assert error.code == "OUTPUT_VALIDATION_FAILED"
+    else:
+        raise AssertionError("JSON response 不得声明无对应流的 Artifact")
+
+
+async def test_multipart_rejects_hash_mime_and_total_drift() -> None:
+    payload = b"%PDF-drift"
+    declaration = artifact_declaration(len(payload), "a" * 64)
+    output = document_output([declaration.model_dump(by_alias=True)])
+    response = multipart_response(output, [(declaration.output_key, payload)])
+    try:
+        await parse_adapter_response(
+            response,
+            64 * 1024,
+            20,
+            sink_descriptor(),
+        )
+    except SafeDocumentError as error:
+        assert error.code == "OUTPUT_VALIDATION_FAILED"
+    else:
+        raise AssertionError("Artifact hash 漂移必须拒绝")
+
+    oversized = declaration.model_copy(update={"byte_size": 40 * 1024})
+    response = multipart_response(
+        document_output([oversized.model_dump(by_alias=True)]),
+        [(oversized.output_key, b"")],
+        declared_lengths=[40 * 1024],
+    )
+    try:
+        await parse_adapter_response(
+            response,
+            64 * 1024,
+            20,
+            sink_descriptor(),
+        )
+    except SafeDocumentError:
+        pass
+    else:
+        raise AssertionError("单 Artifact 声明超限必须在读取前拒绝")
+
+
+async def test_provider_receives_only_files_and_governed_fields() -> None:
+    source_bytes = b"source-bytes"
+    source_hash = hashlib.sha256(source_bytes).hexdigest()
+    sink = readiness_sink_descriptor()
+    request = document_request(sink=sink).model_copy(
+        update={
+            "sources": [
+                ArtifactInput(
+                    value="opaque-sensitive-input-ref",
+                    media_type="application/pdf",
+                    byte_size=len(source_bytes),
+                    sha256=source_hash,
+                )
+            ]
+        }
+    )
+    provider_body = b""
+
+    async def handler(incoming: httpx.Request) -> httpx.Response:
+        nonlocal provider_body
+        if incoming.url.path.endswith("/v1/document/readiness"):
+            return httpx.Response(200, json=adapter_readiness_payload())
+        if incoming.url.path.endswith("/health/ready"):
+            return httpx.Response(200, json=sink_readiness_payload())
+        if incoming.url.path.endswith("/api/internal/ai/artifacts"):
+            return httpx.Response(
+                200,
+                headers={"content-type": "application/pdf"},
+                content=source_bytes,
+            )
+        provider_body = await incoming.aread()
+        return httpx.Response(
+            200,
+            headers={"content-type": "application/json"},
+            content=json.dumps(document_output()).encode(),
+        )
+
+    adapter = DocumentAdapter(
+        runtime_config(),
+        httpx.MockTransport(handler),
+    )
+    execution = await adapter.execute(request)
+    await execution.cleanup()
+    assert b"source-1" in provider_body
+    assert b"opaque-sensitive-input-ref" not in provider_body
+    assert sink.scope.encode() not in provider_body
+    assert runtime_config().output_artifact_url.encode() not in provider_body
+    assert RAW_GRANT.encode() not in provider_body
+
+
+def multipart_response(
+    output: dict[str, JsonValue],
+    artifacts: list[tuple[str, bytes]],
+    declared_lengths: list[int] | None = None,
+) -> httpx.Response:
+    boundary = "southwind-document-v1"
+    manifest = json.dumps(
+        output,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode()
+    chunks = [
+        f"--{boundary}\r\n".encode(),
+        b"Content-Type: application/json\r\n",
+        f"Content-Length: {len(manifest)}\r\n\r\n".encode(),
+        manifest,
+    ]
+    declarations = output.get("artifacts", [])
+    if not isinstance(declarations, list):
+        raise AssertionError
+    for index, (output_key, payload) in enumerate(artifacts):
+        declaration = declarations[index]
+        if not isinstance(declaration, dict):
+            raise AssertionError
+        length = (
+            declared_lengths[index] if declared_lengths is not None else len(payload)
+        )
+        chunks.extend(
+            [
+                f"\r\n--{boundary}\r\n".encode(),
+                f"Content-ID: <{output_key}>\r\n".encode(),
+                (f"Content-Type: {cast(str, declaration['mediaType'])}\r\n").encode(),
+                f"Content-Length: {length}\r\n\r\n".encode(),
+                payload,
+            ]
+        )
+    chunks.append(f"\r\n--{boundary}--\r\n".encode())
+    return httpx.Response(
+        200,
+        headers={
+            "content-type": (
+                f'multipart/related; boundary="{boundary}"; type="application/json"'
+            )
+        },
+        content=b"".join(chunks),
+    )

package/template/apps/document-server/tests/test_config.py

@@ -25,6 +25,16 @@ def test_artifact_endpoint_must_be_local_or_intranet() -> None:
         )
 
 
+def test_output_artifact_endpoint_must_be_local_or_intranet() -> None:
+    with pytest.raises(ValueError, match="禁止使用公网地址"):
+        DocumentRuntimeConfig.from_environment(
+            {
+                "DOCUMENT_SERVER_INTERNAL_TOKEN": "internal-token",
+                "DOCUMENT_OUTPUT_ARTIFACT_URL": "https://8.8.8.8/output",
+            }
+        )
+
+
 def test_adapter_rejects_public_dns_names() -> None:
     with pytest.raises(ValueError, match="内部服务名"):
         DocumentRuntimeConfig.from_environment(
@@ -40,3 +50,36 @@ def test_unconfigured_adapter_keeps_runtime_bootable() -> None:
         {"DOCUMENT_SERVER_INTERNAL_TOKEN": "internal-token"}
     )
     assert config.adapter_url is None
+    assert config.output_artifact_url == (
+        "http://server:9747/api/internal/ai/output-artifacts"
+    )
+    assert not config.readiness_configured
+
+
+def test_url_without_complete_producer_facts_is_not_ready() -> None:
+    config = DocumentRuntimeConfig.from_environment(
+        {
+            "DOCUMENT_SERVER_INTERNAL_TOKEN": "internal-token",
+            "DOCUMENT_ADAPTER_URL": "http://ocr.internal:9000",
+            "DOCUMENT_DEPLOYMENT_KEY": "document.intranet-ocr",
+        }
+    )
+    assert config.adapter_url
+    assert not config.readiness_configured
+
+
+def test_producer_identity_and_probe_ttl_are_strict() -> None:
+    with pytest.raises(ValueError, match="DEPLOYMENT_IDENTITY"):
+        DocumentRuntimeConfig.from_environment(
+            {
+                "DOCUMENT_SERVER_INTERNAL_TOKEN": "internal-token",
+                "DOCUMENT_DEPLOYMENT_IDENTITY": "document.internal",
+            }
+        )
+    with pytest.raises(ValueError, match="不能超过 300"):
+        DocumentRuntimeConfig.from_environment(
+            {
+                "DOCUMENT_SERVER_INTERNAL_TOKEN": "internal-token",
+                "DOCUMENT_READINESS_TTL_SECONDS": "301",
+            }
+        )

package/template/apps/document-server/tests/test_contracts.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from pydantic import ValidationError
+
+from southwind_document_server.contracts import (
+    OutputArtifactDeclaration,
+    StartDocumentRunRequest,
+)
+
+from .support import RAW_GRANT, document_request, sink_descriptor
+
+
+def test_sink_request_requires_planned_run_and_forbids_raw_grant_json() -> None:
+    request = document_request(sink=sink_descriptor())
+    payload = request.model_dump(by_alias=True)
+    assert request.run_id is not None
+    assert RAW_GRANT not in request.model_dump_json(by_alias=True)
+
+    payload.pop("runId")
+    try:
+        StartDocumentRunRequest.model_validate(payload)
+    except ValidationError:
+        pass
+    else:
+        raise AssertionError("Sink request 必须包含 Host planned runId")
+
+    payload = request.model_dump(by_alias=True)
+    payload["outputArtifactSink"]["grant"] = RAW_GRANT
+    try:
+        StartDocumentRunRequest.model_validate(payload)
+    except ValidationError as error:
+        assert RAW_GRANT not in str(error)
+    else:
+        raise AssertionError("raw grant 不得进入 JSON DTO")
+
+
+def test_descriptor_and_capabilities_are_strict_and_bounded() -> None:
+    payload = document_request(sink=sink_descriptor()).model_dump(by_alias=True)
+    payload["outputArtifactSink"]["grantGeneration"] = True
+    try:
+        StartDocumentRunRequest.model_validate(payload)
+    except ValidationError:
+        pass
+    else:
+        raise AssertionError("bool generation 不得作为整数")
+
+    payload = document_request(sink=sink_descriptor()).model_dump(by_alias=True)
+    payload["requiredCapabilities"].append("document.ocr")
+    try:
+        StartDocumentRunRequest.model_validate(payload)
+    except ValidationError:
+        pass
+    else:
+        raise AssertionError("重复 capability 必须拒绝")
+
+
+def test_adapter_artifact_manifest_forbids_provider_urls_and_paths() -> None:
+    raw = {
+        "outputKey": "searchable-pdf",
+        "filename": "searchable.pdf",
+        "mediaType": "application/pdf",
+        "byteSize": 12,
+        "sha256": "a" * 64,
+        "url": "https://provider.example/output.pdf",
+    }
+    try:
+        OutputArtifactDeclaration.model_validate(raw)
+    except ValidationError:
+        pass
+    else:
+        raise AssertionError("Provider URL 不得进入 Artifact manifest")
+
+    raw.pop("url")
+    raw["filename"] = "../../searchable.pdf"
+    try:
+        OutputArtifactDeclaration.model_validate(raw)
+    except ValidationError:
+        pass
+    else:
+        raise AssertionError("Provider path 不得进入 Artifact manifest")