create-windy 0.5.1 → 0.6.0

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

@@ -1,9 +1,17 @@
 from __future__ import annotations
 
 import ipaddress
+import re
 from dataclasses import dataclass
 from urllib.parse import urlparse
 
+_STABLE_KEY = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$")
+_DEPLOYMENT_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}$")
+
 
 @dataclass(frozen=True)
 class DocumentRuntimeConfig:
@@ -14,9 +22,25 @@ class DocumentRuntimeConfig:
     adapter_token: str | None
     deployment_key: str | None
     capabilities: tuple[str, ...]
+    deployment_identity: str | None = None
+    release_digest: str | None = None
+    offers_digest: str | None = None
+    output_artifact_url: str = "http://server:9747/api/internal/ai/output-artifacts"
     max_units: int = 500
     connect_timeout_seconds: float = 5
     request_timeout_seconds: float = 300
+    readiness_timeout_seconds: float = 2
+    readiness_ttl_seconds: int = 60
+
+    @property
+    def readiness_configured(self) -> bool:
+        return bool(
+            self.adapter_url
+            and self.deployment_key
+            and self.deployment_identity
+            and self.release_digest
+            and self.offers_digest
+        )
 
     @classmethod
     def from_environment(cls, environment: dict[str, str]) -> DocumentRuntimeConfig:
@@ -29,6 +53,11 @@ class DocumentRuntimeConfig:
             "http://server:9747/api/internal/ai/artifacts",
         ).strip()
         validate_intranet_url(artifact_url)
+        output_artifact_url = environment.get(
+            "DOCUMENT_OUTPUT_ARTIFACT_URL",
+            "http://server:9747/api/internal/ai/output-artifacts",
+        ).strip()
+        validate_intranet_url(output_artifact_url)
         adapter_url = environment.get("DOCUMENT_ADAPTER_URL", "").strip() or None
         if adapter_url:
             validate_intranet_url(adapter_url)
@@ -44,16 +73,45 @@ class DocumentRuntimeConfig:
                 }
             )
         )
+        validate_stable_keys(capabilities, "DOCUMENT_ADAPTER_CAPABILITIES")
+        deployment_key = optional(environment, "DOCUMENT_DEPLOYMENT_KEY")
+        if deployment_key and not _STABLE_KEY.fullmatch(deployment_key):
+            raise ValueError("DOCUMENT_DEPLOYMENT_KEY 无效")
+        deployment_identity = optional(environment, "DOCUMENT_DEPLOYMENT_IDENTITY")
+        if deployment_identity and not _DEPLOYMENT_IDENTITY.fullmatch(
+            deployment_identity
+        ):
+            raise ValueError("DOCUMENT_DEPLOYMENT_IDENTITY 无效")
+        release_digest = optional(environment, "DOCUMENT_RELEASE_DIGEST")
+        if release_digest and not _DIGEST.fullmatch(release_digest):
+            raise ValueError("DOCUMENT_RELEASE_DIGEST 无效")
+        offers_digest = optional(environment, "DOCUMENT_OFFERS_DIGEST")
+        if offers_digest and not _DIGEST.fullmatch(offers_digest):
+            raise ValueError("DOCUMENT_OFFERS_DIGEST 无效")
         return cls(
             internal_token=internal_token,
             store_path=store_path,
             artifact_url=artifact_url,
             adapter_url=adapter_url,
             adapter_token=environment.get("DOCUMENT_ADAPTER_TOKEN", "").strip() or None,
-            deployment_key=environment.get("DOCUMENT_DEPLOYMENT_KEY", "").strip()
-            or None,
+            deployment_key=deployment_key,
             capabilities=capabilities,
+            deployment_identity=deployment_identity,
+            release_digest=release_digest,
+            offers_digest=offers_digest,
+            output_artifact_url=output_artifact_url.rstrip("/"),
             max_units=positive_int(environment, "DOCUMENT_MAX_UNITS", 500),
+            readiness_timeout_seconds=positive_float(
+                environment,
+                "DOCUMENT_READINESS_TIMEOUT_SECONDS",
+                2,
+            ),
+            readiness_ttl_seconds=bounded_positive_int(
+                environment,
+                "DOCUMENT_READINESS_TTL_SECONDS",
+                60,
+                300,
+            ),
         )
 
 
@@ -75,6 +133,42 @@ def positive_int(environment: dict[str, str], key: str, default: int) -> int:
     return value
 
 
+def bounded_positive_int(
+    environment: dict[str, str],
+    key: str,
+    default: int,
+    maximum: int,
+) -> int:
+    value = positive_int(environment, key, default)
+    if value > maximum:
+        raise ValueError(f"{key} 不能超过 {maximum}")
+    return value
+
+
+def positive_float(
+    environment: dict[str, str],
+    key: str,
+    default: float,
+) -> float:
+    raw = environment.get(key, str(default)).strip()
+    try:
+        value = float(raw)
+    except ValueError:
+        raise ValueError(f"{key} 必须是正数") from None
+    if not 0 < value <= 30:
+        raise ValueError(f"{key} 必须大于 0 且不超过 30")
+    return value
+
+
+def optional(environment: dict[str, str], key: str) -> str | None:
+    return environment.get(key, "").strip() or None
+
+
+def validate_stable_keys(values: tuple[str, ...], key: str) -> None:
+    if any(not _STABLE_KEY.fullmatch(value) for value in values):
+        raise ValueError(f"{key} 包含无效 capability")
+
+
 def validate_intranet_url(raw: str) -> None:
     parsed = urlparse(raw)
     if parsed.scheme not in {"http", "https"} or not parsed.hostname:

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

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Literal, Self
+from datetime import datetime
+from typing import Annotated, Literal, Self
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
@@ -8,6 +9,16 @@ type JsonValue = (
     str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
 )
 type RunStatus = Literal["accepted", "running", "completed", "failed", "cancelled"]
+type Classification = Literal["public", "internal", "sensitive"]
+type Sha256 = Annotated[str, Field(pattern=r"^[a-f0-9]{64}$")]
+type MediaType = Annotated[
+    str,
+    Field(
+        min_length=3,
+        max_length=128,
+        pattern=r"^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*$",
+    ),
+]
 
 
 def to_camel(value: str) -> str:
@@ -20,14 +31,16 @@ class CanonicalModel(BaseModel):
         alias_generator=to_camel,
         populate_by_name=True,
         extra="forbid",
+        strict=True,
+        allow_inf_nan=False,
     )
 
 
 class ArtifactInput(CanonicalModel):
     value: str = Field(min_length=1, max_length=4096)
-    media_type: str = Field(min_length=1, max_length=160)
+    media_type: MediaType
     byte_size: int = Field(ge=0, le=512 * 1024 * 1024)
-    sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+    sha256: Sha256
 
 
 class RuntimeLimits(CanonicalModel):
@@ -40,7 +53,7 @@ class RuntimeLimits(CanonicalModel):
 
 class ProviderEgress(CanonicalModel):
     mode: Literal["forbidden", "configured-endpoint"]
-    deployment_key: str | None = None
+    deployment_key: str | None = Field(default=None, max_length=160)
 
     @model_validator(mode="after")
     def validate_deployment(self) -> Self:
@@ -54,19 +67,26 @@ class ProviderEgress(CanonicalModel):
 
 class ProviderFieldPolicy(CanonicalModel):
     field: Literal["artifact-content", "provider-output"]
-    classification: Literal["public", "internal", "sensitive"]
+    classification: Classification
     dlp_action: Literal["reject", "redact"]
 
 
 class ProviderInputFieldPolicy(CanonicalModel):
-    json_pointer: str = Field(pattern=r"^/[^/]+(?:/[^/]+)*$")
-    classification: Literal["public", "internal", "sensitive"]
+    json_pointer: str = Field(
+        min_length=2,
+        max_length=512,
+        pattern=r"^/(?:[^~/]|~[01])+(?:/(?:[^~/]|~[01])+)*$",
+    )
+    classification: Classification
     dlp_action: Literal["reject", "redact"]
 
 
 class ProviderDataPolicy(CanonicalModel):
-    input_fields: list[ProviderInputFieldPolicy] = Field(min_length=1)
-    envelope_fields: list[ProviderFieldPolicy] = Field(min_length=2)
+    input_fields: list[ProviderInputFieldPolicy] = Field(
+        min_length=1,
+        max_length=100,
+    )
+    envelope_fields: list[ProviderFieldPolicy] = Field(min_length=2, max_length=2)
 
     @model_validator(mode="after")
     def validate_fields(self) -> Self:
@@ -75,25 +95,160 @@ class ProviderDataPolicy(CanonicalModel):
             raise ValueError("Document Provider 字段治理策略不完整")
         if len(fields) != len(set(fields)):
             raise ValueError("Document Provider 字段治理策略重复")
+        pointers = [rule.json_pointer for rule in self.input_fields]
+        if len(pointers) != len(set(pointers)):
+            raise ValueError("Document Provider 输入字段策略重复")
+        return self
+
+
+class OutputArtifactLimits(CanonicalModel):
+    max_artifact_bytes: int = Field(ge=1, le=64 * 1024 * 1024)
+    max_artifacts: int = Field(ge=1, le=100)
+    max_total_bytes: int = Field(ge=1, le=64 * 1024 * 1024)
+
+    @model_validator(mode="after")
+    def validate_total(self) -> Self:
+        if self.max_artifact_bytes > self.max_total_bytes:
+            raise ValueError("Output Artifact 单文件上限超过总上限")
+        return self
+
+
+class OutputArtifactSinkDescriptor(CanonicalModel):
+    contract_version: Literal[1]
+    scope: str = Field(pattern=r"^outscope_[a-f0-9]{32}$")
+    output_kind: str = Field(
+        min_length=1,
+        max_length=80,
+        pattern=r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$",
+    )
+    deployment_identity: str = Field(
+        pattern=(
+            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}$"
+        )
+    )
+    release_digest: str = Field(pattern=r"^sha256:[a-f0-9]{64}$")
+    offers_digest: str = Field(pattern=r"^sha256:[a-f0-9]{64}$")
+    policy_digest: Sha256
+    grant_generation: int = Field(ge=1, le=2**53 - 1)
+    allowed_media_types: list[MediaType] = Field(min_length=1, max_length=32)
+    expires_at: str = Field(min_length=20, max_length=40)
+    limits: OutputArtifactLimits
+
+    @model_validator(mode="after")
+    def validate_descriptor(self) -> Self:
+        if len(self.allowed_media_types) != len(set(self.allowed_media_types)):
+            raise ValueError("Output Artifact MIME 重复")
+        try:
+            parsed = datetime.fromisoformat(self.expires_at.replace("Z", "+00:00"))
+        except ValueError:
+            raise ValueError("Output Artifact expiry 无效") from None
+        if parsed.tzinfo is None:
+            raise ValueError("Output Artifact expiry 必须包含时区")
         return self
 
 
 class StartDocumentRunRequest(CanonicalModel):
     kind: Literal["document"]
-    operation_key: str = Field(min_length=1, max_length=160)
+    run_id: str | None = Field(
+        default=None,
+        pattern=r"^doc_[a-f0-9]{64}$",
+    )
+    operation_key: str = Field(
+        min_length=1,
+        max_length=160,
+        pattern=r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$",
+    )
     options: JsonValue
     sources: list[ArtifactInput] = Field(min_length=1, max_length=100)
     required_capabilities: list[str] = Field(min_length=1, max_length=32)
-    data_classification: Literal["public", "internal", "sensitive"]
+    data_classification: Classification
     limits: RuntimeLimits
     provider_egress: ProviderEgress
     provider_data_policy: ProviderDataPolicy | None = None
+    output_artifact_sink: OutputArtifactSinkDescriptor | None = None
+
+    @model_validator(mode="after")
+    def validate_operation(self) -> Self:
+        capabilities = self.required_capabilities
+        if any(
+            not item
+            or len(item) > 160
+            or item.strip() != item
+            or any(character.isspace() for character in item)
+            for item in capabilities
+        ) or len(capabilities) != len(set(capabilities)):
+            raise ValueError("Document capability 无效")
+        sink = self.output_artifact_sink
+        if sink is not None:
+            if self.run_id is None:
+                raise ValueError("Output Artifact Sink 必须绑定 Host Run ID")
+            if sink.limits.max_artifacts > self.limits.max_artifacts:
+                raise ValueError("Output Artifact 数量超过 Runtime 上限")
+            if sink.limits.max_total_bytes > self.limits.max_output_bytes:
+                raise ValueError("Output Artifact 总量超过 Runtime 上限")
+        return self
+
+
+class OutputArtifactDeclaration(CanonicalModel):
+    output_key: str = Field(
+        min_length=1,
+        max_length=80,
+        pattern=r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$",
+    )
+    filename: str = Field(min_length=1, max_length=240)
+    media_type: MediaType
+    byte_size: int = Field(ge=0, le=64 * 1024 * 1024)
+    sha256: Sha256
+
+    @model_validator(mode="after")
+    def validate_filename(self) -> Self:
+        if (
+            self.filename.strip() != self.filename
+            or "/" in self.filename
+            or "\\" in self.filename
+            or any(ord(character) < 32 for character in self.filename)
+        ):
+            raise ValueError("Output Artifact filename 无效")
+        return self
+
+
+class OutputArtifactReference(CanonicalModel):
+    contract_version: Literal[1]
+    output_key: str = Field(
+        min_length=1,
+        max_length=80,
+        pattern=r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$",
+    )
+    value: str = Field(
+        min_length=8,
+        max_length=4096,
+        pattern=r"^oa1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$",
+    )
+    media_type: MediaType
+    byte_size: int = Field(ge=0, le=64 * 1024 * 1024)
+    sha256: Sha256
+    expires_at: str = Field(min_length=20, max_length=40)
+
+    @model_validator(mode="after")
+    def validate_expiry(self) -> Self:
+        try:
+            parsed = datetime.fromisoformat(self.expires_at.replace("Z", "+00:00"))
+        except ValueError:
+            raise ValueError("Output Artifact reference expiry 无效") from None
+        if parsed.tzinfo is None:
+            raise ValueError("Output Artifact reference expiry 必须包含时区")
+        return self
 
 
 class StartRunResponse(CanonicalModel):
-    run_id: str
+    run_id: str = Field(
+        min_length=1,
+        max_length=80,
+        pattern=r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$",
+    )
     status: RunStatus
-    events_url: str
+    events_url: str = Field(min_length=1, max_length=240)
 
 
 class ErrorResponse(CanonicalModel):

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

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from decimal import Decimal
+from typing import cast
+
+from .contracts import JsonValue, StartDocumentRunRequest
+
+MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def document_request_fingerprint(
+    request: StartDocumentRunRequest,
+    run_id: str,
+) -> str:
+    sink = request.output_artifact_sink
+    value: JsonValue = {
+        "contractVersion": 1,
+        "kind": request.kind,
+        "runId": run_id,
+        "operationKey": request.operation_key,
+        "options": request.options,
+        "sources": [
+            {
+                "mediaType": source.media_type,
+                "byteSize": source.byte_size,
+                "sha256": source.sha256,
+            }
+            for source in request.sources
+        ],
+        "requiredCapabilities": cast(
+            list[JsonValue],
+            sorted(request.required_capabilities),
+        ),
+        "dataClassification": request.data_classification,
+        "limits": request.limits.model_dump(by_alias=True),
+        "providerEgress": request.provider_egress.model_dump(
+            by_alias=True,
+            exclude_none=True,
+        ),
+        **(
+            {
+                "providerDataPolicy": request.provider_data_policy.model_dump(
+                    by_alias=True
+                )
+            }
+            if request.provider_data_policy
+            else {}
+        ),
+        **(
+            {
+                "outputArtifactSink": {
+                    "contractVersion": sink.contract_version,
+                    "outputKind": sink.output_kind,
+                    "deploymentIdentity": sink.deployment_identity,
+                    "releaseDigest": sink.release_digest,
+                    "offersDigest": sink.offers_digest,
+                    "policyDigest": sink.policy_digest,
+                    "allowedMediaTypes": cast(
+                        list[JsonValue],
+                        sorted(sink.allowed_media_types),
+                    ),
+                    "limits": sink.limits.model_dump(by_alias=True),
+                }
+            }
+            if sink
+            else {}
+        ),
+    }
+    return hashlib.sha256(canonical_json(value).encode()).hexdigest()
+
+
+def canonical_json(value: JsonValue) -> str:
+    if value is None or isinstance(value, bool):
+        return json.dumps(value, separators=(",", ":"))
+    if isinstance(value, str):
+        if any(0xD800 <= ord(character) <= 0xDFFF for character in value):
+            raise ValueError("Document JSON Unicode 包含孤立 surrogate")
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if isinstance(value, int):
+        if abs(value) > MAX_SAFE_INTEGER:
+            raise ValueError("Document JSON integer 超出安全范围")
+        return str(value)
+    if isinstance(value, float):
+        return canonical_number(value)
+    if isinstance(value, list):
+        return f"[{','.join(canonical_json(item) for item in value)}]"
+    if isinstance(value, dict):
+        return (
+            "{"
+            + ",".join(
+                f"{canonical_json(key)}:{canonical_json(value[key])}"
+                for key in sorted(value, key=utf16_sort_key)
+            )
+            + "}"
+        )
+    raise ValueError("Document request 不是合法 JSON")
+
+
+def canonical_number(value: float) -> str:
+    if not math.isfinite(value):
+        raise ValueError("Document JSON number 必须有限")
+    if value.is_integer() and abs(value) > MAX_SAFE_INTEGER:
+        raise ValueError("Document JSON integer 超出安全范围")
+    if value == 0:
+        return "0"
+    absolute = abs(value)
+    raw = repr(value).lower()
+    if 1e-6 <= absolute < 1e21:
+        fixed = format(Decimal(raw), "f")
+        if "." in fixed:
+            fixed = fixed.rstrip("0").rstrip(".")
+        return fixed
+    if "e" not in raw:
+        raw = format(value, ".15e")
+    mantissa, exponent = raw.split("e", 1)
+    mantissa = mantissa.rstrip("0").rstrip(".")
+    sign = ""
+    if exponent.startswith(("+", "-")):
+        sign, exponent = exponent[0], exponent[1:]
+    exponent = exponent.lstrip("0") or "0"
+    return f"{mantissa}e{sign}{exponent}"
+
+
+def utf16_sort_key(value: str) -> bytes:
+    return value.encode("utf-16-be", errors="surrogatepass")

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

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import asyncio
+import hmac
+import re
+from dataclasses import dataclass
+
+GRANT_PATTERN = re.compile(r"^outgrant_v1_[A-Za-z0-9_-]{43}$")
+
+
+class GrantStateError(Exception):
+    pass
+
+
+@dataclass(frozen=True, repr=False)
+class _Credential:
+    generation: int
+    token: str
+
+
+class OutputGrantCell:
+    """Process-local raw credential cell. Raw values must never be serialized."""
+
+    def __init__(self) -> None:
+        self._credentials: dict[str, _Credential] = {}
+        self._lock = asyncio.Lock()
+
+    async def install(
+        self,
+        scope: str,
+        generation: int,
+        token: str,
+        persisted_generation: int,
+    ) -> None:
+        if not GRANT_PATTERN.fullmatch(token):
+            raise GrantStateError
+        async with self._lock:
+            current = self._credentials.get(scope)
+            if current is None:
+                if persisted_generation and generation <= persisted_generation:
+                    raise GrantStateError
+                self._credentials[scope] = _Credential(generation, token)
+                return
+            if generation < current.generation:
+                raise GrantStateError
+            if generation == current.generation:
+                if not hmac.compare_digest(current.token, token):
+                    raise GrantStateError
+                return
+            self._credentials[scope] = _Credential(generation, token)
+
+    async def token(self, scope: str) -> str:
+        async with self._lock:
+            current = self._credentials.get(scope)
+            if current is None:
+                raise GrantStateError
+            return current.token
+
+    async def token_for(self, scope: str, generation: int) -> str:
+        async with self._lock:
+            current = self._credentials.get(scope)
+            if current is None or current.generation != generation:
+                raise GrantStateError
+            return current.token
+
+    async def generation(self, scope: str) -> int | None:
+        async with self._lock:
+            current = self._credentials.get(scope)
+            return current.generation if current else None
+
+    async def discard(self, scope: str) -> None:
+        async with self._lock:
+            self._credentials.pop(scope, None)
+
+    async def discard_if_generation(self, scope: str, generation: int) -> bool:
+        async with self._lock:
+            current = self._credentials.get(scope)
+            if current is None or current.generation != generation:
+                return False
+            self._credentials.pop(scope)
+            return True