create-windy 0.5.1 → 0.6.0

package/template/apps/document-server/src/southwind_document_server/readiness.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+import httpx
+from pydantic import ValidationError
+
+from .config import DocumentRuntimeConfig
+from .contracts import StartDocumentRunRequest
+from .readiness_contracts import (
+    DOCUMENT_OUTPUT_ARTIFACT_CAPABILITY_V1,
+    AdapterDocumentReadinessV1,
+    OutputArtifactSinkReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+)
+from .readiness_http import (
+    ProbeFailure,
+    ProbeFailureCode,
+    get_json,
+)
+from .readiness_support import (
+    canonical_time,
+    latency_ms,
+    not_configured,
+    number,
+    required,
+    sink_matches_snapshot,
+    stale_snapshot,
+    string_list,
+    supports_offer,
+)
+
+type Snapshot = dict[str, object]
+
+
+@dataclass(frozen=True)
+class DocumentReadinessInspection:
+    snapshot: Snapshot
+    offers: tuple[dict[str, object], ...] = ()
+    valid_until: datetime | None = None
+
+    @property
+    def ready(self) -> bool:
+        return (
+            self.snapshot.get("status") == "ready"
+            and bool(self.offers)
+            and self.valid_until is not None
+        )
+
+
+class DocumentReadinessProbe:
+    def __init__(
+        self,
+        config: DocumentRuntimeConfig,
+        adapter_transport: httpx.AsyncBaseTransport | None = None,
+        sink_transport: httpx.AsyncBaseTransport | None = None,
+        wall_clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+        monotonic_clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.config = config
+        self.adapter_transport = adapter_transport
+        self.sink_transport = (
+            sink_transport if sink_transport is not None else adapter_transport
+        )
+        self.wall_clock = wall_clock
+        self.monotonic_clock = monotonic_clock
+
+    async def inspect(self) -> DocumentReadinessInspection:
+        checked_at = self._now()
+        started = self.monotonic_clock()
+        if not self.config.readiness_configured:
+            return DocumentReadinessInspection(
+                snapshot=not_configured(canonical_time(checked_at))
+            )
+        try:
+            async with asyncio.timeout(self.config.readiness_timeout_seconds):
+                response = await self._adapter_readiness()
+                output_artifact = any(
+                    offer.output_artifact_contract_version == 1
+                    for offer in response.offers
+                )
+                sink = await self._output_sink_readiness() if output_artifact else None
+                offers = final_offers(response)
+                self._validate_runtime_bounds(offers)
+                offers_digest = compute_offers_digest(offers)
+                release_digest = compute_release_digest(response, sink)
+                if (
+                    offers_digest != self.config.offers_digest
+                    or release_digest != self.config.release_digest
+                ):
+                    raise ProbeFailure("INVALID_RESPONSE", False)
+        except TimeoutError:
+            return self._failed(
+                checked_at,
+                started,
+                "TIMEOUT",
+                True,
+            )
+        except httpx.TimeoutException:
+            return self._failed(
+                checked_at,
+                started,
+                "TIMEOUT",
+                True,
+            )
+        except httpx.ConnectError:
+            return self._failed(
+                checked_at,
+                started,
+                "CONNECTION_FAILED",
+                True,
+            )
+        except httpx.HTTPError:
+            return self._failed(
+                checked_at,
+                started,
+                "CONNECTION_FAILED",
+                True,
+            )
+        except (ValidationError, ValueError, KeyError, TypeError):
+            return self._failed(
+                checked_at,
+                started,
+                "INVALID_RESPONSE",
+                False,
+            )
+        except ProbeFailure as failure:
+            return self._failed(
+                checked_at,
+                started,
+                failure.code,
+                failure.retryable,
+            )
+        observed_at = self._now()
+        valid_until = checked_at + timedelta(seconds=self.config.readiness_ttl_seconds)
+        deployment = {
+            "key": required(self.config.deployment_key),
+            "identity": required(self.config.deployment_identity),
+            "releaseDigest": required(self.config.release_digest),
+            "offersDigest": required(self.config.offers_digest),
+        }
+        if observed_at >= valid_until:
+            return DocumentReadinessInspection(
+                snapshot=stale_snapshot(
+                    checked_at=checked_at,
+                    observed_at=observed_at,
+                    valid_until=valid_until,
+                    latency=latency_ms(started, self.monotonic_clock()),
+                    deployment=deployment,
+                )
+            )
+        checked = canonical_time(checked_at)
+        return DocumentReadinessInspection(
+            snapshot={
+                "schemaVersion": 1,
+                "status": "ready",
+                "configured": True,
+                "runtimeKind": "document",
+                "observedAt": canonical_time(observed_at),
+                "downstreamProbe": {
+                    "status": "passed",
+                    "checkedAt": checked,
+                    "validUntil": canonical_time(valid_until),
+                    "latencyMs": latency_ms(started, self.monotonic_clock()),
+                    "deploymentIdentity": deployment["identity"],
+                    "releaseDigest": deployment["releaseDigest"],
+                    "offersDigest": deployment["offersDigest"],
+                },
+                "deployment": deployment,
+                "offers": offers,
+                "unavailableReasons": [],
+            },
+            offers=tuple(offers),
+            valid_until=valid_until,
+        )
+
+    def supports(
+        self,
+        inspection: DocumentReadinessInspection,
+        request: StartDocumentRunRequest,
+    ) -> bool:
+        if (
+            not inspection.ready
+            or inspection.valid_until is None
+            or self._now() >= inspection.valid_until
+        ):
+            return False
+        sink = request.output_artifact_sink
+        if sink and not sink_matches_snapshot(sink, inspection.snapshot):
+            return False
+        capabilities = set(request.required_capabilities)
+        inputs = {
+            "image" if source.media_type.startswith("image/") else "document"
+            for source in request.sources
+        }
+        outputs = {"text"}
+        if sink:
+            capabilities.add(DOCUMENT_OUTPUT_ARTIFACT_CAPABILITY_V1)
+            outputs.add("document")
+        for offer in inspection.offers:
+            if supports_offer(offer, capabilities, inputs, outputs, request):
+                return True
+        return False
+
+    async def _adapter_readiness(self) -> AdapterDocumentReadinessV1:
+        value = await get_json(
+            f"{required(self.config.adapter_url).rstrip('/')}/v1/document/readiness",
+            self.config.adapter_token,
+            self.config.readiness_timeout_seconds,
+            self.adapter_transport,
+        )
+        return AdapterDocumentReadinessV1.model_validate(value)
+
+    async def _output_sink_readiness(self) -> OutputArtifactSinkReadinessV1:
+        value = await get_json(
+            f"{self.config.output_artifact_url.rstrip('/')}/health/ready",
+            self.config.internal_token,
+            self.config.readiness_timeout_seconds,
+            self.sink_transport,
+        )
+        return OutputArtifactSinkReadinessV1.model_validate(value)
+
+    def _validate_runtime_bounds(self, offers: list[dict[str, object]]) -> None:
+        configured = set(self.config.capabilities)
+        for offer in offers:
+            capabilities = set(string_list(offer["capabilities"]))
+            capabilities.discard(DOCUMENT_OUTPUT_ARTIFACT_CAPABILITY_V1)
+            limits = offer["limits"]
+            if (
+                not capabilities.issubset(configured)
+                or not isinstance(limits, dict)
+                or number(limits, "maxUnits") > self.config.max_units
+            ):
+                raise ProbeFailure("INVALID_RESPONSE", False)
+
+    def _failed(
+        self,
+        checked_at: datetime,
+        started: float,
+        code: ProbeFailureCode,
+        retryable: bool,
+    ) -> DocumentReadinessInspection:
+        observed = canonical_time(self._now())
+        return DocumentReadinessInspection(
+            snapshot={
+                "schemaVersion": 1,
+                "status": "unavailable",
+                "configured": True,
+                "runtimeKind": "document",
+                "observedAt": observed,
+                "downstreamProbe": {
+                    "status": "failed",
+                    "checkedAt": canonical_time(checked_at),
+                    "latencyMs": latency_ms(started, self.monotonic_clock()),
+                    "failureCode": code,
+                    "retryable": retryable,
+                },
+                "deployment": None,
+                "offers": [],
+                "unavailableReasons": [
+                    {
+                        "code": "DOWNSTREAM_PROBE_FAILED",
+                        "retryable": retryable,
+                        "subject": code,
+                    }
+                ],
+            }
+        )
+
+    def _now(self) -> datetime:
+        value = self.wall_clock()
+        if value.tzinfo is None:
+            raise ValueError("Document readiness wall clock 缺少时区")
+        return value.astimezone(UTC)

package/template/apps/document-server/src/southwind_document_server/readiness_contracts.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from typing import Literal, Self
+
+from pydantic import Field, field_validator, model_validator
+
+from .contracts import CanonicalModel
+
+DOCUMENT_OUTPUT_ARTIFACT_CAPABILITY_V1 = "document.output-artifact.v1"
+DOCUMENT_RUNTIME_RELEASE_COMPONENT_V1 = "southwind-document-runtime/readiness-v1"
+MAX_SAFE_INTEGER_V1 = 2**53 - 1
+MAX_OFFERS_V1 = 16
+MAX_CAPABILITIES_PER_OFFER_V1 = 32
+MAX_MODALITIES_V1 = 6
+_MODALITIES_V1 = frozenset({"text", "image", "audio", "video", "document", "embedding"})
+_LIMIT_RULES_V1 = (
+    ("maxDurationSeconds", True, True),
+    ("maxInputBytes", True, True),
+    ("maxOutputBytes", True, True),
+    ("maxUnits", False, True),
+    ("maxMediaDurationSeconds", False, True),
+    ("maxArtifacts", False, True),
+    ("maxPixelsPerArtifact", False, True),
+    ("maxConcurrentRuns", True, True),
+    ("maxQueueDepth", True, False),
+)
+_STABLE_KEY = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$")
+_IDENTITY = re.compile(
+    r"^windy-deployment-v1_[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-"
+    r"[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
+)
+_DIGEST = re.compile(r"^sha256:[a-f0-9]{64}$")
+type Modality = Literal[
+    "text",
+    "image",
+    "audio",
+    "video",
+    "document",
+    "embedding",
+]
+
+
+class DocumentReadinessLimitsV1(CanonicalModel):
+    max_duration_seconds: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_input_bytes: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_output_bytes: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_units: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_media_duration_seconds: int | None = Field(
+        default=None,
+        ge=1,
+        le=MAX_SAFE_INTEGER_V1,
+    )
+    max_artifacts: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_pixels_per_artifact: int | None = Field(
+        default=None,
+        ge=1,
+        le=MAX_SAFE_INTEGER_V1,
+    )
+    max_concurrent_runs: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_queue_depth: int = Field(ge=0, le=MAX_SAFE_INTEGER_V1)
+
+    @field_validator("*", mode="before")
+    @classmethod
+    def normalize_integer_numbers(cls, value: object) -> object:
+        return normalize_integer_number(value)
+
+
+class AdapterDocumentOfferV1(CanonicalModel):
+    variant: str = Field(min_length=1, max_length=128)
+    capability_version: str = Field(min_length=1, max_length=128)
+    capabilities: list[str] = Field(
+        min_length=1,
+        max_length=MAX_CAPABILITIES_PER_OFFER_V1,
+    )
+    input_modalities: list[Modality] = Field(
+        min_length=1,
+        max_length=MAX_MODALITIES_V1,
+    )
+    output_modalities: list[Modality] = Field(
+        min_length=1,
+        max_length=MAX_MODALITIES_V1,
+    )
+    limits: DocumentReadinessLimitsV1
+    output_artifact_contract_version: Literal[1] | None = None
+
+    @model_validator(mode="after")
+    def validate_atomic_offer(self) -> Self:
+        stable = [self.variant, self.capability_version, *self.capabilities]
+        if any(not _STABLE_KEY.fullmatch(value) for value in stable):
+            raise ValueError("Document readiness stable key 无效")
+        if DOCUMENT_OUTPUT_ARTIFACT_CAPABILITY_V1 in self.capabilities:
+            raise ValueError("Adapter 不得自行声明 Runtime Sink capability")
+        if (
+            self.output_artifact_contract_version == 1
+            and len(self.capabilities) >= MAX_CAPABILITIES_PER_OFFER_V1
+        ):
+            raise ValueError("Output Artifact capability 会超过 V1 数量上限")
+        if len(self.capabilities) != len(set(self.capabilities)):
+            raise ValueError("Document readiness capability 重复")
+        if len(self.input_modalities) != len(set(self.input_modalities)):
+            raise ValueError("Document readiness input modality 重复")
+        if len(self.output_modalities) != len(set(self.output_modalities)):
+            raise ValueError("Document readiness output modality 重复")
+        if self.output_artifact_contract_version == 1 and not {
+            "document",
+            "image",
+        }.intersection(self.output_modalities):
+            raise ValueError("Output Artifact offer 缺少文件输出 modality")
+        return self
+
+
+class AdapterDocumentDeploymentV1(CanonicalModel):
+    identity: str = Field(pattern=_IDENTITY.pattern)
+    release_digest: str = Field(pattern=_DIGEST.pattern)
+
+
+class AdapterDocumentReadinessV1(CanonicalModel):
+    contract_version: Literal[1]
+    status: Literal["ready"]
+    runtime_kind: Literal["document"]
+    deployment: AdapterDocumentDeploymentV1
+    offers: list[AdapterDocumentOfferV1] = Field(
+        min_length=1,
+        max_length=MAX_OFFERS_V1,
+    )
+
+    @model_validator(mode="after")
+    def validate_variants(self) -> Self:
+        variants = [offer.variant for offer in self.offers]
+        if len(variants) != len(set(variants)):
+            raise ValueError("Document readiness variant 重复")
+        return self
+
+
+class OutputArtifactSinkDeploymentV1(CanonicalModel):
+    identity: str = Field(pattern=_IDENTITY.pattern)
+    release_digest: str = Field(pattern=_DIGEST.pattern)
+    protocol_version: Literal[1]
+
+
+class OutputArtifactSinkReadinessV1(CanonicalModel):
+    contract_version: Literal[1]
+    status: Literal["ready"]
+    capability: Literal["document.output-artifact.v1"]
+    sink: OutputArtifactSinkDeploymentV1
+
+
+def final_offers(
+    response: AdapterDocumentReadinessV1,
+) -> list[dict[str, object]]:
+    offers: list[dict[str, object]] = []
+    for offer in response.offers:
+        capabilities = list(offer.capabilities)
+        if offer.output_artifact_contract_version == 1:
+            capabilities.append(DOCUMENT_OUTPUT_ARTIFACT_CAPABILITY_V1)
+        offers.append(
+            {
+                "variant": offer.variant,
+                "capabilities": capabilities,
+                "inputModalities": list(offer.input_modalities),
+                "outputModalities": list(offer.output_modalities),
+                "limits": offer.limits.model_dump(
+                    by_alias=True,
+                    exclude_none=True,
+                ),
+            }
+        )
+    return offers
+
+
+def compute_offers_digest(offers: list[dict[str, object]]) -> str:
+    if not 0 < len(offers) <= MAX_OFFERS_V1:
+        raise ValueError("Document readiness offer 数量无效")
+    canonical: list[dict[str, object]] = []
+    variants: set[str] = set()
+    for offer in offers:
+        capabilities = strings(offer["capabilities"])
+        inputs = strings(offer["inputModalities"])
+        outputs = strings(offer["outputModalities"])
+        limits = offer["limits"]
+        variant = offer.get("variant")
+        if (
+            not isinstance(variant, str)
+            or not _STABLE_KEY.fullmatch(variant)
+            or variant in variants
+            or not 0 < len(capabilities) <= MAX_CAPABILITIES_PER_OFFER_V1
+            or len(capabilities) != len(set(capabilities))
+            or any(not _STABLE_KEY.fullmatch(value) for value in capabilities)
+            or not 0 < len(inputs) <= MAX_MODALITIES_V1
+            or len(inputs) != len(set(inputs))
+            or any(value not in _MODALITIES_V1 for value in inputs)
+            or not 0 < len(outputs) <= MAX_MODALITIES_V1
+            or len(outputs) != len(set(outputs))
+            or any(value not in _MODALITIES_V1 for value in outputs)
+            or not isinstance(limits, dict)
+        ):
+            raise ValueError("Document readiness limits 无效")
+        canonical_limits = validate_limits(limits)
+        variants.add(variant)
+        canonical.append(
+            {
+                "variant": variant,
+                "capabilities": sorted(capabilities),
+                "inputModalities": sorted(inputs),
+                "outputModalities": sorted(outputs),
+                "limits": canonical_limits,
+            }
+        )
+    canonical.sort(key=lambda offer: str(offer["variant"]))
+    encoded = json.dumps(
+        canonical,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode()
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
+
+
+def compute_release_digest(
+    response: AdapterDocumentReadinessV1,
+    output_artifact_sink: OutputArtifactSinkReadinessV1 | None,
+) -> str:
+    payload = {
+        "adapterCapabilityVersions": sorted(
+            (
+                {
+                    "variant": offer.variant,
+                    "capabilityVersion": offer.capability_version,
+                }
+                for offer in response.offers
+            ),
+            key=lambda item: item["variant"],
+        ),
+        "adapterDeploymentIdentity": response.deployment.identity,
+        "adapterReleaseDigest": response.deployment.release_digest,
+        "documentRuntimeRelease": DOCUMENT_RUNTIME_RELEASE_COMPONENT_V1,
+        "outputArtifactSink": (
+            output_artifact_sink.sink.model_dump(by_alias=True)
+            if output_artifact_sink
+            else None
+        ),
+    }
+    encoded = json.dumps(payload, separators=(",", ":")).encode()
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
+
+
+def strings(value: object) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ValueError("Document readiness string list 无效")
+    return value
+
+
+def validate_limits(limits: dict[str, object]) -> dict[str, int]:
+    allowed = {key for key, _, _ in _LIMIT_RULES_V1}
+    if any(key not in allowed for key in limits):
+        raise ValueError("Document readiness limit key 无效")
+    canonical: dict[str, int] = {}
+    for key, required, positive in _LIMIT_RULES_V1:
+        value = limits.get(key)
+        if value is None and not required:
+            continue
+        normalized = normalize_integer_number(value)
+        if (
+            not isinstance(normalized, int)
+            or isinstance(normalized, bool)
+            or normalized < (1 if positive else 0)
+            or normalized > MAX_SAFE_INTEGER_V1
+        ):
+            raise ValueError("Document readiness limit 不是安全整数")
+        canonical[key] = normalized
+    return canonical
+
+
+def normalize_integer_number(value: object) -> object:
+    if isinstance(value, float) and math.isfinite(value) and value.is_integer():
+        return int(value)
+    return value

package/template/apps/document-server/src/southwind_document_server/readiness_http.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import json
+from typing import Literal, cast
+
+import httpx
+
+_MAX_BODY_BYTES = 64 * 1024
+type ProbeFailureCode = Literal[
+    "AUTHENTICATION_FAILED",
+    "CONNECTION_FAILED",
+    "INVALID_RESPONSE",
+    "RESOURCE_UNAVAILABLE",
+    "TIMEOUT",
+    "UNHEALTHY",
+]
+
+
+class ProbeFailure(Exception):
+    def __init__(self, code: ProbeFailureCode, retryable: bool) -> None:
+        super().__init__(code)
+        self.code = code
+        self.retryable = retryable
+
+
+async def get_json(
+    url: str,
+    token: str | None,
+    timeout_seconds: float,
+    transport: httpx.AsyncBaseTransport | None,
+) -> object:
+    headers = {"authorization": f"Bearer {token}"} if token else {}
+    async with httpx.AsyncClient(
+        timeout=httpx.Timeout(timeout_seconds),
+        transport=transport,
+        follow_redirects=False,
+    ) as client:
+        async with client.stream("GET", url, headers=headers) as response:
+            if response.status_code != 200:
+                raise response_failure(response.status_code)
+            content_type = response.headers.get("content-type", "")
+            if content_type.split(";", 1)[0].strip() != "application/json":
+                raise ProbeFailure("INVALID_RESPONSE", False)
+            declared = response.headers.get("content-length")
+            if declared and (not declared.isdigit() or int(declared) > _MAX_BODY_BYTES):
+                raise ProbeFailure("INVALID_RESPONSE", False)
+            body = bytearray()
+            async for chunk in response.aiter_bytes():
+                if len(chunk) > _MAX_BODY_BYTES - len(body):
+                    raise ProbeFailure("INVALID_RESPONSE", False)
+                body.extend(chunk)
+            if declared and int(declared) != len(body):
+                raise ProbeFailure("INVALID_RESPONSE", False)
+    try:
+        return cast(
+            object,
+            json.loads(
+                body.decode("utf-8"),
+                object_pairs_hook=unique_object,
+                parse_constant=reject_constant,
+            ),
+        )
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError, RecursionError):
+        raise ProbeFailure("INVALID_RESPONSE", False) from None
+
+
+def response_failure(status: int) -> ProbeFailure:
+    if status in {401, 403}:
+        return ProbeFailure("AUTHENTICATION_FAILED", False)
+    if status in {408, 504}:
+        return ProbeFailure("TIMEOUT", True)
+    if status == 429 or status >= 500:
+        return ProbeFailure("RESOURCE_UNAVAILABLE", True)
+    return ProbeFailure("UNHEALTHY", False)
+
+
+def unique_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate key")
+        result[key] = value
+    return result
+
+
+def reject_constant(_value: str) -> object:
+    raise ValueError("non-finite number")