create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+
+from .adapter import EmbeddingAdapter
+from .config import EmbeddingConfig
+from .contracts import EmbeddingRequest
+from .error import SafeEmbeddingError
+from .run_store import EmbeddingRunRecord, EmbeddingRunStore, failure
+
+
+class EmbeddingRunService:
+    def __init__(
+        self,
+        adapter: EmbeddingAdapter,
+        store: EmbeddingRunStore,
+        max_concurrent_runs: int,
+    ) -> None:
+        self.adapter = adapter
+        self.store = store
+        self._tasks: dict[str, asyncio.Task[None]] = {}
+        self._queue = asyncio.Semaphore(max_concurrent_runs)
+
+    async def start(
+        self, request: EmbeddingRequest, idempotency_key: str, run_id: str
+    ) -> EmbeddingRunRecord:
+        record, created = await self.store.create_or_get(
+            run_id,
+            request,
+            idempotency_key,
+            fingerprint(request, self.adapter.config),
+            deployment_pin(self.adapter.config),
+        )
+        if created:
+            self._dispatch(record.run_id, request)
+        return record
+
+    async def recover(self) -> None:
+        for record, request in await self.store.recoverable():
+            self._dispatch(record.run_id, request)
+
+    async def cancel(self, run_id: str) -> EmbeddingRunRecord:
+        record = await self.require(run_id)
+        if not record.terminal:
+            await self.store.append(run_id, "run.cancelled")
+            task = self._tasks.get(run_id)
+            if task:
+                task.cancel()
+        return await self.require(run_id)
+
+    async def require(self, run_id: str) -> EmbeddingRunRecord:
+        record = await self.store.get(run_id)
+        if not record:
+            raise KeyError(run_id)
+        return record
+
+    def _dispatch(self, run_id: str, request: EmbeddingRequest) -> None:
+        if run_id in self._tasks:
+            return
+        task = asyncio.create_task(self._execute(run_id, request))
+        self._tasks[run_id] = task
+        task.add_done_callback(lambda _task: self._tasks.pop(run_id, None))
+
+    async def _execute(self, run_id: str, request: EmbeddingRequest) -> None:
+        try:
+            async with self._queue:
+                if (await self.require(run_id)).status == "cancelled":
+                    return
+                if (await self.require(run_id)).deployment_pin != deployment_pin(
+                    self.adapter.config
+                ):
+                    raise SafeEmbeddingError(
+                        "CAPABILITY_UNAVAILABLE",
+                        "Embedding Deployment 已漂移",
+                        False,
+                    )
+                await self.store.append(run_id, "run.started")
+                async with asyncio.timeout(request.limits.max_duration_seconds):
+                    output = await self.adapter.embed(request, run_id)
+                if (await self.require(run_id)).status != "cancelled":
+                    await self.store.complete(run_id, output)
+        except asyncio.CancelledError:
+            raise
+        except TimeoutError:
+            await self.store.append(
+                run_id, "run.failed", failure("RUN_TIMEOUT", "Embedding 任务超时", True)
+            )
+        except SafeEmbeddingError as error:
+            await self.store.append(
+                run_id,
+                "run.failed",
+                failure(error.code, error.safe_message, error.retryable),
+            )
+        except Exception:
+            await self.store.append(
+                run_id,
+                "run.failed",
+                failure("RUNTIME_UNAVAILABLE", "Embedding Runtime 执行失败", True),
+            )
+
+
+def fingerprint(request: EmbeddingRequest, config: EmbeddingConfig) -> str:
+    """Hashes stable governed input.
+
+    Signed Artifact URL expiry is intentionally absent.
+    """
+    value = request.model_dump(mode="json")
+    for item in value["items"]:
+        source = item.get("source")
+        if source:
+            source.pop("value", None)
+    value["deploymentPin"] = deployment_pin(config)
+    payload = json.dumps(
+        value, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+    )
+    return hashlib.sha256(payload.encode()).hexdigest()
+
+
+def deployment_pin(config: EmbeddingConfig) -> dict[str, object]:
+    return {
+        "alias": config.deployment_alias,
+        "model": config.model,
+        "version": config.version,
+        "dimensions": config.dimensions,
+        "normalized": config.normalized,
+        "maxUnits": config.max_units,
+        "capabilities": list(config.capabilities),
+    }

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

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, cast
+
+from .contracts import EmbeddingRequest, EmbeddingResponse, ErrorResponse
+from .run_cipher import EmbeddingRunCipher
+
+RunStatus = Literal["accepted", "running", "completed", "failed", "cancelled"]
+
+
+@dataclass(frozen=True)
+class EmbeddingRunRecord:
+    run_id: str
+    operation_key: str
+    idempotency_key: str
+    fingerprint: str
+    status: RunStatus
+    output: EmbeddingResponse | None
+    expires_at: float
+    deployment_pin: dict[str, object]
+
+    @property
+    def terminal(self) -> bool:
+        return self.status in {"completed", "failed", "cancelled"}
+
+
+class RunConflictError(Exception):
+    pass
+
+
+class EmbeddingRunStore:
+    """One SQLite replica owns run state, encrypted invocation and monotonic events."""
+
+    def __init__(
+        self, path: str, cipher: EmbeddingRunCipher, terminal_ttl: int
+    ) -> None:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(path, check_same_thread=False)
+        self._db.row_factory = sqlite3.Row
+        self._cipher = cipher
+        self._terminal_ttl = terminal_ttl
+        self._lock = asyncio.Lock()
+        self._initialize()
+
+    async def create_or_get(
+        self,
+        run_id: str,
+        request: EmbeddingRequest,
+        idempotency_key: str,
+        fingerprint: str,
+        deployment_pin: dict[str, object],
+    ) -> tuple[EmbeddingRunRecord, bool]:
+        async with self._lock:
+            existing = self._db.execute(
+                "select run_id from embedding_runs where idempotency_key = ?",
+                (idempotency_key,),
+            ).fetchone()
+            if existing:
+                record = self._require(str(existing["run_id"]))
+                if record.fingerprint != fingerprint:
+                    raise RunConflictError
+                return record, False
+            now = time.time()
+            self._db.execute(
+                """insert into embedding_runs (
+                    run_id, operation_key, idempotency_key, fingerprint, status,
+                    invocation_cipher, output_json, deployment_pin,
+                    created_at, updated_at, expires_at
+                ) values (?, ?, ?, ?, 'accepted', ?, 'null', ?, ?, ?, ?)""",
+                (
+                    run_id,
+                    request.operation_key,
+                    idempotency_key,
+                    fingerprint,
+                    self._cipher.seal(request.model_dump(mode="json")),
+                    encode(deployment_pin),
+                    now,
+                    now,
+                    now + self._terminal_ttl,
+                ),
+            )
+            self._db.commit()
+            return self._require(run_id), True
+
+    async def recoverable(self) -> list[tuple[EmbeddingRunRecord, EmbeddingRequest]]:
+        async with self._lock:
+            rows = self._db.execute(
+                "select run_id, invocation_cipher from embedding_runs "
+                "where status in ('accepted', 'running')"
+            ).fetchall()
+            result: list[tuple[EmbeddingRunRecord, EmbeddingRequest]] = []
+            for row in rows:
+                raw = self._cipher.open(str(row["invocation_cipher"]))
+                result.append(
+                    (
+                        self._require(str(row["run_id"])),
+                        EmbeddingRequest.model_validate(raw),
+                    )
+                )
+            return result
+
+    async def get(self, run_id: str) -> EmbeddingRunRecord | None:
+        async with self._lock:
+            row = self._db.execute(
+                "select * from embedding_runs where run_id = ?", (run_id,)
+            ).fetchone()
+            return self._record(row) if row else None
+
+    async def append(
+        self, run_id: str, event_type: str, fields: dict[str, object] | None = None
+    ) -> None:
+        async with self._lock:
+            record = self._require(run_id)
+            if record.terminal:
+                return
+            sequence = (
+                int(
+                    self._db.execute(
+                        "select count(*) from embedding_events where run_id = ?",
+                        (run_id,),
+                    ).fetchone()[0]
+                )
+                + 1
+            )
+            status = {
+                "run.started": "running",
+                "run.completed": "completed",
+                "run.failed": "failed",
+                "run.cancelled": "cancelled",
+            }.get(event_type, record.status)
+            event = {
+                "type": event_type,
+                "runId": run_id,
+                "sequence": sequence,
+                **(fields or {}),
+            }
+            self._db.execute(
+                "insert into embedding_events values (?, ?, ?)",
+                (run_id, sequence, encode(event)),
+            )
+            self._db.execute(
+                "update embedding_runs set status = ?, updated_at = ? where run_id = ?",
+                (status, time.time(), run_id),
+            )
+            self._db.commit()
+
+    async def complete(self, run_id: str, output: EmbeddingResponse) -> None:
+        async with self._lock:
+            record = self._require(run_id)
+            if record.terminal:
+                return
+            self._db.execute(
+                "update embedding_runs set output_json = ? where run_id = ?",
+                (output.model_dump_json(), run_id),
+            )
+            self._db.commit()
+        await self.append(run_id, "run.completed")
+
+    async def events_after(self, run_id: str, after: int) -> list[dict[str, object]]:
+        async with self._lock:
+            self._require(run_id)
+            return [
+                json.loads(str(row["event_json"]))
+                for row in self._db.execute(
+                    "select event_json from embedding_events "
+                    "where run_id = ? and sequence > ? order by sequence",
+                    (run_id, after),
+                )
+            ]
+
+    async def tombstone_if_expired(self, run_id: str) -> bool:
+        async with self._lock:
+            record = self._require(run_id)
+            if not record.terminal or record.expires_at > time.time():
+                return False
+            self._db.execute(
+                "update embedding_runs set output_json = 'null', "
+                "invocation_cipher = null where run_id = ?",
+                (run_id,),
+            )
+            self._db.commit()
+            return True
+
+    def _initialize(self) -> None:
+        self._db.executescript("""
+            create table if not exists embedding_runs (
+              run_id text primary key,
+              operation_key text not null,
+              idempotency_key text not null unique,
+              fingerprint text not null, status text not null, invocation_cipher text,
+              output_json text not null, deployment_pin text not null default '{}',
+              created_at real not null,
+              updated_at real not null,
+              expires_at real not null
+            );
+            create table if not exists embedding_events (
+              run_id text not null references embedding_runs(run_id) on delete cascade,
+              sequence integer not null,
+              event_json text not null,
+              primary key (run_id, sequence)
+            );
+        """)
+        columns = {
+            str(row[1]) for row in self._db.execute("pragma table_info(embedding_runs)")
+        }
+        if "deployment_pin" not in columns:
+            self._db.execute(
+                "alter table embedding_runs add column deployment_pin "
+                "text not null default '{}'"
+            )
+        self._db.commit()
+
+    def _require(self, run_id: str) -> EmbeddingRunRecord:
+        row = self._db.execute(
+            "select * from embedding_runs where run_id = ?", (run_id,)
+        ).fetchone()
+        if not row:
+            raise KeyError(run_id)
+        return self._record(row)
+
+    def _record(self, row: sqlite3.Row) -> EmbeddingRunRecord:
+        raw = json.loads(str(row["output_json"]))
+        return EmbeddingRunRecord(
+            run_id=str(row["run_id"]),
+            operation_key=str(row["operation_key"]),
+            idempotency_key=str(row["idempotency_key"]),
+            fingerprint=str(row["fingerprint"]),
+            status=cast(RunStatus, str(row["status"])),
+            output=EmbeddingResponse.model_validate(raw) if raw else None,
+            expires_at=float(row["expires_at"]),
+            deployment_pin=json.loads(str(row["deployment_pin"])),
+        )
+
+
+def failure(code: str, message: str, retryable: bool) -> dict[str, object]:
+    return {
+        "error": ErrorResponse(
+            code=code, message=message, request_id="embedding-run", retryable=retryable
+        ).model_dump(by_alias=True)
+    }
+
+
+def encode(value: object) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True)

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

@@ -12,6 +12,7 @@ def config() -> EmbeddingConfig:
     return EmbeddingConfig(
         internal_token="internal",
         artifact_url="http://server:9747/api/internal/ai/artifacts",
+        run_artifact_url="http://server:9747/api/internal/embeddings/runs",
         adapter_url="http://adapter:9000",
         adapter_token=None,
         deployment_key="local",
@@ -90,3 +91,27 @@ async def test_rejects_vector_dimension_drift(
 
 def test_httpx_is_a_runtime_dependency() -> None:
     assert httpx.__version__
+
+
+@pytest.mark.asyncio
+async def test_readiness_requires_real_adapter_identity(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    class Response:
+        status_code = 200
+
+        def json(self) -> object:
+            return {"model": "local-model", "dimensions": 3}
+
+    class Client:
+        async def __aenter__(self) -> Client:
+            return self
+
+        async def __aexit__(self, *_value: object) -> None:
+            return None
+
+        async def get(self, *_value: object, **_kwargs: object) -> Response:
+            return Response()
+
+    monkeypatch.setattr(httpx, "AsyncClient", lambda **_kwargs: Client())
+    assert await EmbeddingAdapter(config()).readiness()

package/template/apps/embedding-server/tests/test_run_http.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+
+import httpx
+import pytest
+
+os.environ.setdefault("EMBEDDING_SERVER_INTERNAL_TOKEN", "test-internal")
+os.environ.setdefault("EMBEDDING_RUN_ENCRYPTION_SECRET", "x" * 32)
+os.environ.setdefault("EMBEDDING_RUN_STORE_PATH", "/tmp/embedding-test-runs.sqlite3")
+os.environ.setdefault("EMBEDDING_DEPLOYMENT_ALIAS", "test")
+os.environ.setdefault("EMBEDDING_MODEL", "test")
+os.environ.setdefault("EMBEDDING_MODEL_VERSION", "test")
+os.environ.setdefault("EMBEDDING_DIMENSIONS", "3")
+
+from southwind_embedding_server.app import create_app
+from southwind_embedding_server.config import EmbeddingConfig
+from southwind_embedding_server.contracts import EmbeddingRequest, EmbeddingResponse
+from southwind_embedding_server.error import SafeEmbeddingError
+
+
+def config(path: str) -> EmbeddingConfig:
+    return EmbeddingConfig(
+        internal_token="internal",
+        artifact_url="http://server:9747/api/internal/ai/artifacts",
+        run_artifact_url="http://server:9747/api/internal/embeddings/runs",
+        adapter_url="http://adapter:9000",
+        adapter_token=None,
+        deployment_key=None,
+        deployment_alias="intranet-v1",
+        model="embedding-model",
+        version="2026-08",
+        dimensions=3,
+        normalized=True,
+        capabilities=("embedding.text",),
+        run_store_path=path,
+        run_encryption_secret="x" * 32,
+    )
+
+
+def request() -> dict[str, object]:
+    return {
+        "kind": "embedding",
+        "operationKey": "analysis.embedding.text",
+        "items": [{"id": "one", "text": "安全文本"}],
+        "options": {},
+        "inputModalities": ["text"],
+        "requiredCapabilities": ["embedding.text"],
+        "dataClassification": "sensitive",
+        "limits": {
+            "maxDurationSeconds": 30,
+            "maxInputBytes": 1024,
+            "maxOutputBytes": 1024,
+            "maxUnits": 10,
+        },
+        "providerEgress": {"mode": "forbidden"},
+    }
+
+
+def response() -> EmbeddingResponse:
+    return EmbeddingResponse.model_validate(
+        {
+            "batchId": "batch-1",
+            "items": [{"id": "one", "vector": [1, 0, 0], "inputSha256": "a" * 64}],
+            "metadata": {
+                "deploymentAlias": "intranet-v1",
+                "model": "embedding-model",
+                "version": "2026-08",
+                "dimensions": 3,
+                "normalized": True,
+            },
+        }
+    )
+
+
+@pytest.mark.asyncio
+async def test_run_http_success_events_result_and_cancel(tmp_path: Path) -> None:
+    adapter = Adapter(response())
+    app = create_app(config(str(tmp_path / "runs.sqlite3")), adapter)
+    async with client(app) as remote:
+        denied = await remote.post("/api/embeddings/runs", json=request())
+        assert denied.status_code == 403
+        started = await remote.post(
+            "/api/embeddings/runs",
+            headers=headers("start-1"),
+            json=request(),
+        )
+        assert started.status_code == 202
+        run_id = started.json()["runId"]
+        await adapter.called.wait()
+        events = await remote.get(
+            f"/api/embeddings/runs/{run_id}/events", headers=headers()
+        )
+        assert events.status_code == 200
+        assert '"type":"run.started"' in events.text
+        assert '"type":"run.completed"' in events.text
+        result = await remote.get(
+            f"/api/embeddings/runs/{run_id}/result", headers=headers()
+        )
+        assert result.status_code == 200
+        assert result.json()["output"]["batchId"] == "batch-1"
+
+        waiting = Adapter(response(), block=True)
+        cancelled_app = create_app(config(str(tmp_path / "cancel.sqlite3")), waiting)
+        async with client(cancelled_app) as cancel_remote:
+            accepted = await cancel_remote.post(
+                "/api/embeddings/runs", headers=headers("cancel-1"), json=request()
+            )
+            cancel_id = accepted.json()["runId"]
+            await waiting.called.wait()
+            cancelled = await cancel_remote.post(
+                f"/api/embeddings/runs/{cancel_id}/cancel", headers=headers()
+            )
+            assert cancelled.status_code == 200
+            assert cancelled.json()["status"] == "cancelled"
+
+
+@pytest.mark.asyncio
+async def test_run_http_exposes_safe_remote_failure_only(tmp_path: Path) -> None:
+    app = create_app(
+        config(str(tmp_path / "failed.sqlite3")),
+        Adapter(None, failure=True),
+    )
+    async with client(app) as remote:
+        started = await remote.post(
+            "/api/embeddings/runs", headers=headers("fail-1"), json=request()
+        )
+        run_id = started.json()["runId"]
+        for _ in range(20):
+            events = await remote.get(
+                f"/api/embeddings/runs/{run_id}/events", headers=headers()
+            )
+            if '"type":"run.failed"' in events.text:
+                break
+            await asyncio.sleep(0)
+        assert '"code":"RUNTIME_UNAVAILABLE"' in events.text
+        result = await remote.get(
+            f"/api/embeddings/runs/{run_id}/result", headers=headers()
+        )
+        assert result.status_code == 409
+        assert result.json()["code"] == "RUN_NOT_READY"
+
+
+class Adapter:
+    def __init__(
+        self,
+        value: EmbeddingResponse | None,
+        failure: bool = False,
+        block: bool = False,
+    ) -> None:
+        self.value = value
+        self.failure = failure
+        self.block = block
+        self.called = asyncio.Event()
+        self.config = config("/tmp/unused.sqlite3")
+
+    async def readiness(self) -> bool:
+        return True
+
+    async def embed(
+        self, _request: EmbeddingRequest, _run_id: str | None = None
+    ) -> EmbeddingResponse:
+        self.called.set()
+        if self.block:
+            await asyncio.Event().wait()
+        if self.failure:
+            raise SafeEmbeddingError("RUNTIME_UNAVAILABLE", "adapter unavailable", True)
+        assert self.value is not None
+        return self.value
+
+
+def headers(key: str = "read") -> dict[str, str]:
+    return {
+        "authorization": "Bearer internal",
+        "idempotency-key": key,
+        "x-embedding-run-id": f"embedding_{key}",
+    }
+
+
+def client(app: object) -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://embedding"
+    )