create-windy 0.5.1 → 0.6.0

package/template/apps/speech-server/src/southwind_speech_server/service.py

@@ -16,36 +16,98 @@ class SpeechRunService:
         self.adapter = adapter
         self.store = store
         self.tasks: dict[str, asyncio.Task[None]] = {}
+        self._start_lock = asyncio.Lock()
+        self._execution_slots = asyncio.Semaphore(adapter.config.max_concurrent_runs)
+        self._capacity = (
+            adapter.config.max_concurrent_runs + adapter.config.max_queue_depth
+        )
+        self._reserved: set[str] = set()
 
     async def start(
-        self, request: StartSpeechRunRequest, idempotency_key: str
+        self,
+        request: StartSpeechRunRequest,
+        idempotency_key: str,
+        output_grant: str | None = None,
     ) -> RunRecord:
         validate_options(request)
         fingerprint = hashlib.sha256(
             json.dumps(
                 {
+                    "contractVersion": request.contract_version,
+                    "variant": request.effective_variant,
                     "operationKey": request.operation_key,
-                    "sourceSha256": request.source.sha256,
+                    "source": {
+                        "mediaType": request.source.media_type,
+                        "byteSize": request.source.byte_size,
+                        "sha256": request.source.sha256,
+                    },
                     "options": request.options,
                     "capabilities": sorted(request.required_capabilities),
+                    "limits": request.limits.model_dump(by_alias=True),
+                    "providerEgress": request.provider_egress.model_dump(by_alias=True),
+                    "providerDataPolicy": (
+                        request.provider_data_policy.model_dump(by_alias=True)
+                        if request.provider_data_policy
+                        else None
+                    ),
+                    "outputArtifactSink": sink_fingerprint(request),
                 },
                 ensure_ascii=False,
                 separators=(",", ":"),
                 sort_keys=True,
             ).encode()
         ).hexdigest()
-        record, created = self.store.create(
-            f"speech_{uuid.uuid4().hex}",
-            request.operation_key,
-            idempotency_key,
-            fingerprint,
-        )
-        if created:
-            task = asyncio.create_task(self._execute(record.run_id, request))
+        async with self._start_lock:
+            record, created = self.store.create(
+                request.run_id or f"speech_{uuid.uuid4().hex}",
+                request.operation_key,
+                idempotency_key,
+                fingerprint,
+            )
+            if not created:
+                return record
+            if len(self._reserved) >= self._capacity:
+                self.store.delete_accepted(record.run_id)
+                raise SafeSpeechError(
+                    "CAPABILITY_UNAVAILABLE", "Speech Runtime 队列已满", True
+                )
+            self._reserved.add(record.run_id)
+            try:
+                await self.adapter.accept_output_grant(request, output_grant)
+            except Exception:
+                self._reserved.discard(record.run_id)
+                self.store.delete_accepted(record.run_id)
+                raise
+            task = asyncio.create_task(
+                self._execute_reserved(record.run_id, request, output_grant)
+            )
             self.tasks[record.run_id] = task
-            task.add_done_callback(lambda _task: self.tasks.pop(record.run_id, None))
+            task.add_done_callback(
+                lambda _task: self._release_reservation(record.run_id)
+            )
         return record
 
+    async def _execute_reserved(
+        self, run_id: str, request: StartSpeechRunRequest, output_grant: str | None
+    ) -> None:
+        entered = False
+        try:
+            await self._execution_slots.acquire()
+            entered = True
+            await self._execute(run_id, request, output_grant)
+        finally:
+            if entered:
+                self._execution_slots.release()
+            elif (
+                request.effective_variant == "normalize"
+                and self.require(run_id).status != "completed"
+            ):
+                await self._retry_output_cleanup(request, output_grant)
+
+    def _release_reservation(self, run_id: str) -> None:
+        self.tasks.pop(run_id, None)
+        self._reserved.discard(run_id)
+
     async def cancel(self, run_id: str) -> RunRecord:
         record = self.require(run_id)
         if not record.terminal:
@@ -61,13 +123,18 @@ class SpeechRunService:
             raise KeyError(run_id)
         return record
 
-    async def _execute(self, run_id: str, request: StartSpeechRunRequest) -> None:
+    async def _execute(
+        self, run_id: str, request: StartSpeechRunRequest, output_grant: str | None
+    ) -> None:
         self.store.append(run_id, "run.started")
         try:
             async with asyncio.timeout(request.limits.max_duration_seconds):
-                output = await self.adapter.execute(request)
+                output = await self.adapter.execute(request, output_grant)
                 if self.require(run_id).status == "cancelled":
                     return
+                if request.effective_variant == "normalize":
+                    self.store.complete(run_id, output)
+                    return
                 segments = output.get("segments") if isinstance(output, dict) else None
                 if not isinstance(segments, list):
                     raise SafeSpeechError(
@@ -111,6 +178,24 @@ class SpeechRunService:
             )
         except Exception:
             self._fail(run_id, "RUNTIME_UNAVAILABLE", "Speech Runtime 执行失败", True)
+        finally:
+            if (
+                request.effective_variant == "normalize"
+                and self.require(run_id).status != "completed"
+            ):
+                await self._retry_output_cleanup(request, output_grant)
+
+    async def _retry_output_cleanup(
+        self, request: StartSpeechRunRequest, output_grant: str | None
+    ) -> None:
+        for attempt in range(3):
+            try:
+                await self.adapter.abort_open_output(request, output_grant)
+                return
+            except SafeSpeechError:
+                if attempt == 2:
+                    return
+                await asyncio.sleep(0.05 * (attempt + 1))
 
     def _fail(self, run_id: str, code: str, message: str, retryable: bool) -> None:
         self.store.append(
@@ -131,7 +216,10 @@ def validate_options(request: StartSpeechRunRequest) -> None:
     options = request.options
     if not isinstance(options, dict):
         raise SafeSpeechError("INVALID_INPUT", "Speech options 必须是对象", False)
+    variant = request.effective_variant
     allowed = {"language", "vad", "timestamps"}
+    if variant == "translate":
+        allowed.add("targetLanguage")
     if any(key not in allowed for key in options):
         raise SafeSpeechError("INVALID_INPUT", "Speech options 含未知字段", False)
     language = options.get("language")
@@ -142,6 +230,12 @@ def validate_options(request: StartSpeechRunRequest) -> None:
     timestamps = options.get("timestamps")
     if timestamps is not None and timestamps not in {"segment", "word"}:
         raise SafeSpeechError("INVALID_INPUT", "Speech timestamps 无效", False)
+    if variant == "normalize" and options:
+        raise SafeSpeechError("INVALID_INPUT", "normalize 不接受 Speech options", False)
+    if variant == "translate":
+        target = options.get("targetLanguage")
+        if not isinstance(target, str) or not target.strip() or len(target) > 35:
+            raise SafeSpeechError("INVALID_INPUT", "Speech targetLanguage 无效", False)
     vad = options.get("vad")
     if vad is None:
         return
@@ -160,3 +254,14 @@ def validate_options(request: StartSpeechRunRequest) -> None:
             or value > 60_000
         ):
             raise SafeSpeechError("INVALID_INPUT", f"Speech VAD {key} 无效", False)
+
+
+def sink_fingerprint(request: StartSpeechRunRequest) -> dict[str, object] | None:
+    sink = request.output_artifact_sink
+    if sink is None:
+        return None
+    value = sink.model_dump(
+        by_alias=True,
+        exclude={"grant_generation", "expires_at"},
+    )
+    return value

package/template/apps/speech-server/src/southwind_speech_server/store.py

@@ -86,6 +86,13 @@ class SpeechRunStore:
             output=json.loads(str(row["output_json"])),
         )
 
+    def delete_accepted(self, run_id: str) -> None:
+        self.database.execute(
+            "delete from speech_runs where run_id = ? and status = 'accepted'",
+            (run_id,),
+        )
+        self.database.commit()
+
     def append(
         self, run_id: str, event_type: str, fields: dict[str, object] | None = None
     ) -> None:

package/template/apps/speech-server/tests/test_bounded_json.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from southwind_speech_server.bounded_json import BoundedJsonError, read_bounded_json
+
+
+async def test_streaming_json_rejects_oversize_duplicate_and_wrong_type() -> None:
+    for response, maximum in (
+        (
+            httpx.Response(
+                200,
+                content=b'{"value":"too-long"}',
+                headers={"content-type": "application/json"},
+            ),
+            16,
+        ),
+        (
+            httpx.Response(
+                200,
+                content=b'{"value":1,"value":2}',
+                headers={"content-type": "application/json"},
+            ),
+            64,
+        ),
+        (
+            httpx.Response(200, content=b"{}", headers={"content-type": "text/plain"}),
+            64,
+        ),
+        (
+            httpx.Response(
+                200,
+                content=b"{}",
+                headers={"content-type": "application/json", "content-length": ""},
+            ),
+            64,
+        ),
+    ):
+        with pytest.raises(BoundedJsonError):
+            await read_bounded_json(response, maximum)
+
+
+async def test_streaming_json_accepts_exact_bounded_utf8_object() -> None:
+    body = '{"text":"语音"}'.encode()
+    response = httpx.Response(
+        200,
+        content=body,
+        headers={
+            "content-type": "application/json; charset=utf-8",
+            "content-length": str(len(body)),
+        },
+    )
+
+    assert await read_bounded_json(response, len(body)) == {"text": "语音"}

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

@@ -31,3 +31,25 @@ def test_unconfigured_adapter_keeps_runtime_bootable() -> None:
     )
     assert config.adapter_url is None
     assert config.artifact_url == "http://server:9747/api/internal/ai/artifacts"
+    assert config.output_artifact_url == (
+        "http://server:9747/api/internal/ai/output-artifacts"
+    )
+    assert config.max_inline_output_bytes == 64 * 1024 * 1024
+    assert config.max_output_artifact_bytes == 512 * 1024 * 1024
+
+
+def test_readiness_and_artifact_caps_reject_invalid_values() -> None:
+    with pytest.raises(ValueError, match="SPEECH_MAX_QUEUE_DEPTH"):
+        SpeechRuntimeConfig.from_environment(
+            {
+                "SPEECH_SERVER_INTERNAL_TOKEN": "internal-token",
+                "SPEECH_MAX_QUEUE_DEPTH": "-1",
+            }
+        )
+    with pytest.raises(ValueError, match="SPEECH_READINESS_TIMEOUT_SECONDS"):
+        SpeechRuntimeConfig.from_environment(
+            {
+                "SPEECH_SERVER_INTERNAL_TOKEN": "internal-token",
+                "SPEECH_READINESS_TIMEOUT_SECONDS": "0",
+            }
+        )

package/template/apps/speech-server/tests/test_output_artifact.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+
+from southwind_speech_server.config import SpeechRuntimeConfig
+from southwind_speech_server.normalizer import estimated_pcm_bytes
+from southwind_speech_server.output_artifact import SpeechOutputArtifactClient
+
+
+def test_pcm_estimate_matches_16khz_mono_s16le_budget() -> None:
+    assert estimated_pcm_bytes(1_000) == 32_044
+    assert estimated_pcm_bytes(60_000) == 1_920_044
+
+
+async def test_output_upload_uses_bounded_ordered_parts(tmp_path: Path) -> None:
+    body = b"a" * (8 * 1024 * 1024) + b"tail"
+    path = tmp_path / "normalized.wav"
+    path.write_bytes(body)
+    parts: list[tuple[str, int, int]] = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        parts.append(
+            (
+                request.url.path.rsplit("/", 1)[-1],
+                int(request.headers["x-ai-output-part-offset"]),
+                len(request.content),
+            )
+        )
+        return httpx.Response(204)
+
+    client = SpeechOutputArtifactClient(config())
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handle)) as remote:
+        await client._upload_parts(
+            remote,
+            "http://server.internal/api/internal/ai/output-artifacts/scopes/scope",
+            "artifact",
+            {"authorization": "Bearer token"},
+            path,
+            len(body),
+        )
+
+    assert parts == [("0", 0, 8 * 1024 * 1024), ("1", 8 * 1024 * 1024, 4)]
+
+
+def config() -> SpeechRuntimeConfig:
+    return SpeechRuntimeConfig(
+        internal_token="internal",
+        store_path=":memory:",
+        artifact_url="http://server.internal/api/internal/ai/artifacts",
+        output_artifact_url=("http://server.internal/api/internal/ai/output-artifacts"),
+        adapter_url=None,
+        adapter_token=None,
+        deployment_key=None,
+        deployment_identity=None,
+        release_digest=None,
+        offers_digest=None,
+        capabilities=("speech.transcribe.batch",),
+    )

package/template/apps/speech-server/tests/test_output_validation.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from southwind_speech_server.errors import SafeSpeechError
+from southwind_speech_server.output_validation import canonicalize_output
+
+
+def test_output_has_stable_segments_and_rejects_overrun() -> None:
+    output = canonicalize_output(
+        {
+            "language": "zh",
+            "segments": [
+                {
+                    "id": "provider-id",
+                    "text": "第一段",
+                    "startMs": 0,
+                    "endMs": 1000,
+                    "confidence": 0.9,
+                }
+            ],
+        },
+        1000,
+        1,
+    )
+    assert isinstance(output, dict)
+    segments = output["segments"]
+    assert isinstance(segments, list)
+    assert isinstance(segments[0], dict)
+    assert segments[0]["id"] == "segment-000001"
+
+    try:
+        canonicalize_output(
+            {
+                "segments": [
+                    {"text": "一", "startMs": 0, "endMs": 500},
+                    {"text": "二", "startMs": 500, "endMs": 1000},
+                ]
+            },
+            1000,
+            1,
+        )
+    except SafeSpeechError as error:
+        assert error.code == "OUTPUT_VALIDATION_FAILED"
+    else:
+        raise AssertionError("超过分段配额的输出必须拒绝")