create-windy 0.6.0 → 0.6.2

package/template/apps/embedding-server/src/southwind_embedding_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 EmbeddingConfig:
@@ -19,14 +27,35 @@ class EmbeddingConfig:
     dimensions: int
     normalized: bool
     capabilities: tuple[str, ...]
+    deployment_identity: str | None = None
+    release_digest: str | None = None
+    offers_digest: str | None = None
     max_units: int = 256
+    max_duration_seconds: int = 600
+    max_input_bytes: int = 268_435_456
+    max_output_bytes: int = 268_435_456
+    max_artifacts: int = 16
+    max_pixels_per_artifact: int = 100_000_000
     connect_timeout_seconds: float = 5
     request_timeout_seconds: float = 120
     run_store_path: str = "/app/data/embedding/runs.sqlite3"
     run_encryption_secret: str = ""
     max_concurrent_runs: int = 1
+    max_queue_depth: int = 0
+    readiness_timeout_seconds: float = 5
+    readiness_ttl_seconds: int = 60
     terminal_ttl_seconds: int = 7 * 24 * 60 * 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]) -> EmbeddingConfig:
         artifact_url = environment.get(
@@ -53,8 +82,18 @@ class EmbeddingConfig:
             adapter_url=adapter_url,
             adapter_token=environment.get("EMBEDDING_ADAPTER_TOKEN", "").strip()
             or None,
-            deployment_key=environment.get("EMBEDDING_DEPLOYMENT_KEY", "").strip()
-            or None,
+            deployment_key=optional_match(
+                environment, "EMBEDDING_DEPLOYMENT_KEY", _STABLE_KEY
+            ),
+            deployment_identity=optional_match(
+                environment, "EMBEDDING_DEPLOYMENT_IDENTITY", _DEPLOYMENT_IDENTITY
+            ),
+            release_digest=optional_match(
+                environment, "EMBEDDING_RELEASE_DIGEST", _DIGEST
+            ),
+            offers_digest=optional_match(
+                environment, "EMBEDDING_OFFERS_DIGEST", _DIGEST
+            ),
             deployment_alias=required(environment, "EMBEDDING_DEPLOYMENT_ALIAS"),
             model=required(environment, "EMBEDDING_MODEL"),
             version=required(environment, "EMBEDDING_MODEL_VERSION"),
@@ -75,6 +114,19 @@ class EmbeddingConfig:
                 )
             ),
             max_units=positive_int(environment, "EMBEDDING_MAX_UNITS", 256),
+            max_duration_seconds=positive_int(
+                environment, "EMBEDDING_MAX_DURATION_SECONDS", 600
+            ),
+            max_input_bytes=positive_int(
+                environment, "EMBEDDING_MAX_INPUT_BYTES", 268_435_456
+            ),
+            max_output_bytes=positive_int(
+                environment, "EMBEDDING_MAX_OUTPUT_BYTES", 268_435_456
+            ),
+            max_artifacts=positive_int(environment, "EMBEDDING_MAX_ARTIFACTS", 16),
+            max_pixels_per_artifact=positive_int(
+                environment, "EMBEDDING_MAX_PIXELS_PER_ARTIFACT", 100_000_000
+            ),
             run_store_path=environment.get(
                 "EMBEDDING_RUN_STORE_PATH", "/app/data/embedding/runs.sqlite3"
             ).strip(),
@@ -84,6 +136,15 @@ class EmbeddingConfig:
             max_concurrent_runs=positive_int(
                 environment, "EMBEDDING_MAX_CONCURRENT_RUNS", 1
             ),
+            max_queue_depth=non_negative_int(
+                environment, "EMBEDDING_MAX_QUEUE_DEPTH", 0
+            ),
+            readiness_timeout_seconds=bounded_positive_float(
+                environment, "EMBEDDING_READINESS_TIMEOUT_SECONDS", 5, 30
+            ),
+            readiness_ttl_seconds=bounded_positive_int(
+                environment, "EMBEDDING_READINESS_TTL_SECONDS", 60, 300
+            ),
             terminal_ttl_seconds=positive_int(
                 environment, "EMBEDDING_RUN_TERMINAL_TTL_SECONDS", 7 * 24 * 60 * 60
             ),
@@ -120,8 +181,54 @@ def boolean(environment: dict[str, str], key: str, default: bool) -> bool:
 
 
 def required_capabilities(value: tuple[str, ...]) -> tuple[str, ...]:
-    if not value:
-        raise ValueError("EMBEDDING_CAPABILITIES 不能为空")
+    if (
+        not value
+        or len(value) != len(set(value))
+        or any(not _STABLE_KEY.fullmatch(item) for item in value)
+    ):
+        raise ValueError("EMBEDDING_CAPABILITIES 无效")
+    return value
+
+
+def optional_match(
+    environment: dict[str, str], key: str, pattern: re.Pattern[str]
+) -> str | None:
+    value = environment.get(key, "").strip()
+    if value and not pattern.fullmatch(value):
+        raise ValueError(f"{key} 格式无效")
+    return value or None
+
+
+def non_negative_int(environment: dict[str, str], key: str, default: int) -> int:
+    raw = environment.get(key, str(default)).strip()
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ValueError(f"{key} 必须是非负整数") from None
+    if value < 0:
+        raise ValueError(f"{key} 必须是非负整数")
+    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 bounded_positive_float(
+    environment: dict[str, str], key: str, default: float, maximum: float
+) -> float:
+    raw = environment.get(key, str(default)).strip()
+    try:
+        value = float(raw)
+    except ValueError:
+        raise ValueError(f"{key} 必须是正数") from None
+    if value <= 0 or value > maximum:
+        raise ValueError(f"{key} 必须大于 0 且不超过 {maximum:g}")
     return value
 
 

package/template/apps/embedding-server/src/southwind_embedding_server/contracts.py

@@ -66,6 +66,18 @@ class ProviderDataPolicy(CanonicalModel):
     envelope_fields: list[dict[str, JsonValue]]
 
 
+class ReadinessPinV1(CanonicalModel):
+    key: str = Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$")
+    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}$")
+
+
 class EmbeddingRequest(CanonicalModel):
     kind: Literal["embedding"]
     operation_key: str = Field(min_length=1)
@@ -77,6 +89,7 @@ class EmbeddingRequest(CanonicalModel):
     limits: RuntimeLimits
     provider_egress: ProviderEgress
     provider_data_policy: ProviderDataPolicy | None = None
+    readiness_pin: ReadinessPinV1 | None = None
 
 
 class EmbeddingVector(CanonicalModel):

package/template/apps/embedding-server/src/southwind_embedding_server/pin_cli.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+
+import httpx
+
+from .config import EmbeddingConfig
+from .readiness_contracts import (
+    AdapterEmbeddingReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+)
+from .readiness_http import get_json
+
+
+async def compute_pins(
+    config: EmbeddingConfig,
+    transport: httpx.AsyncBaseTransport | None = None,
+) -> dict[str, str]:
+    if not config.deployment_key or not config.deployment_identity:
+        raise ValueError("Embedding deployment key/identity 缺失")
+    if not config.adapter_url:
+        raise ValueError("Embedding Adapter 未配置")
+    adapter = AdapterEmbeddingReadinessV1.model_validate(
+        await get_json(
+            f"{config.adapter_url.rstrip('/')}/v1/embedding/readiness",
+            config.adapter_token,
+            config.readiness_timeout_seconds,
+            transport,
+        )
+    )
+    deployment = adapter.deployment
+    if (
+        deployment.model != config.model
+        or deployment.version != config.version
+        or deployment.dimensions != config.dimensions
+        or deployment.normalized != config.normalized
+    ):
+        raise ValueError("Embedding Adapter deployment 漂移")
+    offers = final_offers(config, adapter)
+    return {
+        "deploymentKey": config.deployment_key,
+        "deploymentIdentity": config.deployment_identity,
+        "releaseDigest": compute_release_digest(adapter),
+        "offersDigest": compute_offers_digest(offers),
+    }
+
+
+async def main() -> None:
+    try:
+        pins = await compute_pins(EmbeddingConfig.from_environment(dict(os.environ)))
+    except Exception as error:
+        message = "Embedding readiness full probe 未通过，未写入 pins"
+        raise SystemExit(message) from error
+    print(json.dumps(pins, separators=(",", ":"), sort_keys=True))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/template/apps/embedding-server/src/southwind_embedding_server/readiness.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Protocol
+
+import httpx
+from pydantic import ValidationError
+
+from .config import EmbeddingConfig
+from .contracts import EmbeddingRequest
+from .readiness_contracts import (
+    AdapterEmbeddingReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+    supports_offer,
+)
+from .readiness_http import ProbeFailure, ProbeFailureCode, get_json
+
+type Snapshot = dict[str, object]
+
+
+@dataclass(frozen=True)
+class EmbeddingReadinessInspection:
+    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)
+
+
+class EmbeddingReadinessPort(Protocol):
+    async def inspect(self) -> EmbeddingReadinessInspection: ...
+
+    def supports(
+        self,
+        inspection: EmbeddingReadinessInspection,
+        request: EmbeddingRequest,
+    ) -> bool: ...
+
+
+class EmbeddingReadinessProbe:
+    def __init__(
+        self,
+        config: EmbeddingConfig,
+        transport: httpx.AsyncBaseTransport | None = None,
+        wall_clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+        monotonic_clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.config = config
+        self.transport = transport
+        self.wall_clock = wall_clock
+        self.monotonic_clock = monotonic_clock
+
+    async def inspect(self) -> EmbeddingReadinessInspection:
+        checked_at = self._now()
+        started = self.monotonic_clock()
+        adapter_url = self.config.adapter_url
+        if not self.config.readiness_configured or not adapter_url:
+            return EmbeddingReadinessInspection(self._not_configured(checked_at))
+        try:
+            async with asyncio.timeout(self.config.readiness_timeout_seconds):
+                adapter = AdapterEmbeddingReadinessV1.model_validate(
+                    await get_json(
+                        f"{adapter_url.rstrip('/')}/v1/embedding/readiness",
+                        self.config.adapter_token,
+                        self.config.readiness_timeout_seconds,
+                        self.transport,
+                    )
+                )
+                self._validate_adapter(adapter)
+                offers = final_offers(self.config, adapter)
+                offers_digest = compute_offers_digest(offers)
+                release_digest = compute_release_digest(adapter)
+                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 ProbeFailure as failure:
+            return self._failed(checked_at, started, failure.code, failure.retryable)
+        except (ValidationError, ValueError, KeyError, TypeError, AssertionError):
+            return self._failed(checked_at, started, "INVALID_RESPONSE", False)
+
+        observed_at = self._now()
+        valid_until = checked_at + timedelta(seconds=self.config.readiness_ttl_seconds)
+        deployment = self._deployment(release_digest, offers_digest)
+        if observed_at >= valid_until:
+            return EmbeddingReadinessInspection(
+                self._stale(checked_at, observed_at, valid_until, deployment)
+            )
+        snapshot: Snapshot = {
+            "schemaVersion": 1,
+            "status": "ready",
+            "configured": True,
+            "runtimeKind": "embedding",
+            "observedAt": canonical_time(observed_at),
+            "downstreamProbe": {
+                "status": "passed",
+                "checkedAt": canonical_time(checked_at),
+                "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": [],
+        }
+        return EmbeddingReadinessInspection(snapshot, tuple(offers), valid_until)
+
+    def supports(
+        self,
+        inspection: EmbeddingReadinessInspection,
+        request: EmbeddingRequest,
+    ) -> bool:
+        pin = request.readiness_pin
+        deployment = inspection.snapshot.get("deployment")
+        if (
+            not inspection.ready
+            or inspection.valid_until is None
+            or self._now() >= inspection.valid_until
+            or not isinstance(deployment, dict)
+            or (pin is not None and pin.model_dump(by_alias=True) != deployment)
+        ):
+            return False
+        return any(supports_offer(offer, request) for offer in inspection.offers)
+
+    def _validate_adapter(self, adapter: AdapterEmbeddingReadinessV1) -> None:
+        deployment = adapter.deployment
+        if (
+            deployment.model != self.config.model
+            or deployment.version != self.config.version
+            or deployment.dimensions != self.config.dimensions
+            or deployment.normalized != self.config.normalized
+        ):
+            raise ProbeFailure("INVALID_RESPONSE", False)
+
+    def _deployment(self, release_digest: str, offers_digest: str) -> dict[str, str]:
+        values = (
+            self.config.deployment_key,
+            self.config.deployment_identity,
+            self.config.release_digest,
+            self.config.offers_digest,
+        )
+        if not all(values):
+            raise ValueError("Embedding readiness 配置缺失")
+        return {
+            "key": str(values[0]),
+            "identity": str(values[1]),
+            "releaseDigest": release_digest,
+            "offersDigest": offers_digest,
+        }
+
+    def _not_configured(self, observed_at: datetime) -> Snapshot:
+        return {
+            "schemaVersion": 1,
+            "status": "unavailable",
+            "configured": False,
+            "runtimeKind": "embedding",
+            "observedAt": canonical_time(observed_at),
+            "downstreamProbe": {"status": "not-run", "reason": "NOT_CONFIGURED"},
+            "deployment": None,
+            "offers": [],
+            "unavailableReasons": [
+                {"code": "RUNTIME_NOT_CONFIGURED", "retryable": True}
+            ],
+        }
+
+    def _failed(
+        self,
+        checked_at: datetime,
+        started: float,
+        code: ProbeFailureCode,
+        retryable: bool,
+    ) -> EmbeddingReadinessInspection:
+        return EmbeddingReadinessInspection(
+            {
+                "schemaVersion": 1,
+                "status": "unavailable",
+                "configured": True,
+                "runtimeKind": "embedding",
+                "observedAt": canonical_time(self._now()),
+                "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 _stale(
+        self,
+        checked_at: datetime,
+        observed_at: datetime,
+        valid_until: datetime,
+        deployment: dict[str, str],
+    ) -> Snapshot:
+        return {
+            "schemaVersion": 1,
+            "status": "unavailable",
+            "configured": True,
+            "runtimeKind": "embedding",
+            "observedAt": canonical_time(observed_at),
+            "downstreamProbe": {
+                "status": "passed",
+                "checkedAt": canonical_time(checked_at),
+                "validUntil": canonical_time(valid_until),
+                "latencyMs": 0,
+                "deploymentIdentity": deployment["identity"],
+                "releaseDigest": deployment["releaseDigest"],
+                "offersDigest": deployment["offersDigest"],
+            },
+            "deployment": deployment,
+            "offers": [],
+            "unavailableReasons": [{"code": "PROBE_STALE", "retryable": True}],
+        }
+
+    def _now(self) -> datetime:
+        value = self.wall_clock()
+        if value.tzinfo is None:
+            raise ValueError("Embedding readiness wall clock 缺少时区")
+        return value.astimezone(UTC)
+
+
+def canonical_time(value: datetime) -> str:
+    return (
+        value.astimezone(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+    )
+
+
+def latency_ms(started: float, finished: float) -> int:
+    return max(0, round((finished - started) * 1000))