openspeechapi 0.1.0__py3-none-any.whl

openspeech/dispatch/executors/base.py

@@ -0,0 +1,34 @@
+"""Executor abstract base class."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any
+
+from openspeech.core.base import SpeechProvider
+from openspeech.core.settings import BaseSettings
+
+
+class Executor(ABC):
+    """Abstract executor — runs provider methods in a specific execution mode."""
+
+    @abstractmethod
+    async def start(
+        self,
+        provider_cls: type[SpeechProvider],
+        settings: BaseSettings,
+        *,
+        http_client: Any = None,
+    ) -> None: ...
+
+    @abstractmethod
+    async def stop(self) -> None: ...
+
+    @abstractmethod
+    async def invoke(self, method: str, **kwargs: Any) -> Any: ...
+
+    @abstractmethod
+    async def invoke_stream(self, method: str, **kwargs: Any) -> AsyncIterator[Any]: ...
+
+    @abstractmethod
+    async def health_check(self) -> bool: ...

openspeech/dispatch/executors/in_process.py

@@ -0,0 +1,66 @@
+"""InProcessExecutor — runs provider directly in the main process."""
+from __future__ import annotations
+from collections.abc import AsyncIterator
+from typing import Any
+from openspeech.core.base import SpeechProvider
+from openspeech.core.settings import BaseSettings
+from openspeech.dispatch.executors.base import Executor
+from openspeech.telemetry.perf import Event, PerfTimer
+
+
+class InProcessExecutor(Executor):
+    def __init__(self) -> None:
+        self._provider: SpeechProvider | None = None
+        self._provider_cls: type[SpeechProvider] | None = None
+        self._settings: BaseSettings | None = None
+
+    async def start(
+        self,
+        provider_cls: type[SpeechProvider],
+        settings: BaseSettings,
+        *,
+        http_client: Any = None,
+    ) -> None:
+        self._provider_cls = provider_cls
+        self._settings = settings
+        self._provider = provider_cls(settings=settings)
+        if http_client is not None:
+            self._provider.set_http_client(http_client)
+        await self._provider.start()
+
+    def set_provider_info(self, provider_cls: type[SpeechProvider], settings: BaseSettings) -> None:
+        """Store provider class and settings for pre-start health checks."""
+        self._provider_cls = provider_cls
+        self._settings = settings
+
+    async def stop(self) -> None:
+        if self._provider:
+            await self._provider.stop()
+            self._provider = None
+
+    async def invoke(self, method: str, **kwargs: Any) -> Any:
+        if self._provider is None:
+            raise RuntimeError("Executor not started")
+        fn = getattr(self._provider, method)
+        with PerfTimer(Event.PROVIDER_TOTAL, method=method, exec_mode="in_process"):
+            return await fn(**kwargs)
+
+    async def invoke_stream(self, method: str, **kwargs: Any) -> AsyncIterator[Any]:
+        if self._provider is None:
+            raise RuntimeError("Executor not started")
+        fn = getattr(self._provider, method)
+        with PerfTimer(Event.PROVIDER_TOTAL, method=method, exec_mode="in_process") as t:
+            count = 0
+            async for item in fn(**kwargs):
+                count += 1
+                yield item
+            t.add(items=count)
+
+    async def health_check(self) -> bool:
+        if self._provider is not None:
+            return await self._provider.health_check()
+        # Provider not started yet — instantiate temporarily to check
+        if self._provider_cls is not None and self._settings is not None:
+            tmp = self._provider_cls(settings=self._settings)
+            return await tmp.health_check()
+        return False

openspeech/dispatch/executors/remote.py

@@ -0,0 +1,64 @@
+"""RemoteExecutor — delegates to provider adapter that handles its own remote protocol."""
+from __future__ import annotations
+from collections.abc import AsyncIterator
+from typing import Any
+from openspeech.core.base import SpeechProvider
+from openspeech.core.settings import BaseSettings
+from openspeech.dispatch.executors.base import Executor
+from openspeech.telemetry.perf import Event, PerfTimer
+
+
+class RemoteExecutor(Executor):
+    def __init__(self) -> None:
+        self._provider: SpeechProvider | None = None
+        self._provider_cls: type[SpeechProvider] | None = None
+        self._settings: BaseSettings | None = None
+
+    async def start(
+        self,
+        provider_cls: type[SpeechProvider],
+        settings: BaseSettings,
+        *,
+        http_client: Any = None,
+    ) -> None:
+        self._provider_cls = provider_cls
+        self._settings = settings
+        self._provider = provider_cls(settings=settings)
+        if http_client is not None:
+            self._provider.set_http_client(http_client)
+        await self._provider.start()
+
+    def set_provider_info(self, provider_cls: type[SpeechProvider], settings: BaseSettings) -> None:
+        """Store provider class and settings for pre-start health checks."""
+        self._provider_cls = provider_cls
+        self._settings = settings
+
+    async def stop(self) -> None:
+        if self._provider:
+            await self._provider.stop()
+            self._provider = None
+
+    async def invoke(self, method: str, **kwargs: Any) -> Any:
+        if self._provider is None:
+            raise RuntimeError("Executor not started")
+        with PerfTimer(Event.PROVIDER_TOTAL, method=method, exec_mode="remote"):
+            return await getattr(self._provider, method)(**kwargs)
+
+    async def invoke_stream(self, method: str, **kwargs: Any) -> AsyncIterator[Any]:
+        if self._provider is None:
+            raise RuntimeError("Executor not started")
+        with PerfTimer(Event.PROVIDER_TOTAL, method=method, exec_mode="remote") as t:
+            count = 0
+            async for item in getattr(self._provider, method)(**kwargs):
+                count += 1
+                yield item
+            t.add(items=count)
+
+    async def health_check(self) -> bool:
+        if self._provider is not None:
+            return await self._provider.health_check()
+        # Provider not started yet — instantiate temporarily to check credentials
+        if self._provider_cls is not None and self._settings is not None:
+            tmp = self._provider_cls(settings=self._settings)
+            return await tmp.health_check()
+        return False

openspeech/dispatch/executors/subprocess_exec.py

@@ -0,0 +1,446 @@
+"""SubprocessExecutor — runs provider in a worker subprocess via UDS + msgpack IPC."""
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import enum
+import importlib
+import os
+import pickle
+import struct
+import sys
+import tempfile
+import time
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Any
+
+import msgpack
+
+from openspeech.core.base import SpeechProvider
+from openspeech.core.settings import BaseSettings
+from openspeech.dispatch.executors.base import Executor
+from openspeech.telemetry.perf import Event, PerfTimer
+
+# ---------------------------------------------------------------------------
+# Wire protocol helpers
+# ---------------------------------------------------------------------------
+# Messages are length-prefixed msgpack: 4-byte big-endian uint32 + payload
+
+_HEADER = struct.Struct(">I")
+_PROXY_ENV_KEYS = (
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+)
+
+
+def _encode(obj: Any) -> bytes:
+    payload = msgpack.packb(obj, use_bin_type=True)
+    return _HEADER.pack(len(payload)) + payload
+
+
+def _decode_obj(data: bytes) -> Any:
+    return msgpack.unpackb(data, raw=False)
+
+
+async def _read_msg(reader: asyncio.StreamReader) -> Any:
+    header = await reader.readexactly(_HEADER.size)
+    (length,) = _HEADER.unpack(header)
+    payload = await reader.readexactly(length)
+    return _decode_obj(payload)
+
+
+async def _write_msg(writer: asyncio.StreamWriter, obj: Any) -> None:
+    writer.write(_encode(obj))
+    await writer.drain()
+
+
+# ---------------------------------------------------------------------------
+# Dataclass (de)serialization helpers
+# ---------------------------------------------------------------------------
+
+def _serialize_arg(value: Any) -> Any:
+    """Recursively serialize a value so it can be packed with msgpack."""
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        d = dataclasses.asdict(value)
+        return {"__dataclass__": type(value).__module__ + "." + type(value).__qualname__, "fields": d}
+    if isinstance(value, enum.Enum):
+        return {"__enum__": type(value).__module__ + "." + type(value).__qualname__, "value": value.value}
+    if isinstance(value, bytes):
+        return value  # msgpack handles bytes natively with use_bin_type=True
+    if isinstance(value, dict):
+        return {k: _serialize_arg(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_serialize_arg(i) for i in value]
+    return value
+
+
+def _deserialize_arg(value: Any) -> Any:
+    """Recursively deserialize msgpack-decoded value back to Python objects."""
+    if isinstance(value, dict):
+        if "__dataclass__" in value:
+            # Reconstruct the dataclass
+            cls = _import_dotted(value["__dataclass__"])
+            fields = {k: _deserialize_arg(v) for k, v in value["fields"].items()}
+            # Reconstruct enum fields based on type hints
+            fields = _fix_enum_fields(cls, fields)
+            return cls(**fields)
+        if "__enum__" in value:
+            cls = _import_dotted(value["__enum__"])
+            return cls(value["value"])
+        return {k: _deserialize_arg(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_deserialize_arg(i) for i in value]
+    return value
+
+
+def _import_dotted(dotted: str) -> Any:
+    """Import a dotted-path class, e.g. 'openspeech.core.enums.AudioFormat'."""
+    parts = dotted.rsplit(".", 1)
+    module_path, cls_name = parts[0], parts[1]
+    module = importlib.import_module(module_path)
+    return getattr(module, cls_name)
+
+
+def _fix_enum_fields(cls: type, fields: dict[str, Any]) -> dict[str, Any]:
+    """For a dataclass cls, coerce any str values back to their Enum type when needed."""
+    import typing
+    hints = {}
+    try:
+        hints = typing.get_type_hints(cls)
+    except Exception:
+        pass
+    result = {}
+    for field_name, field_value in fields.items():
+        hint = hints.get(field_name)
+        if hint is not None and isinstance(field_value, str):
+            # Unwrap Optional[X] → X
+            origin = getattr(hint, "__origin__", None)
+            args = getattr(hint, "__args__", ())
+            if origin is type(None):
+                pass
+            elif origin is not None and args:
+                # Handle Optional[Enum] = Union[Enum, None]
+                for arg in args:
+                    if isinstance(arg, type) and issubclass(arg, enum.Enum):
+                        try:
+                            field_value = arg(field_value)
+                        except ValueError:
+                            pass
+                        break
+            elif isinstance(hint, type) and issubclass(hint, enum.Enum):
+                try:
+                    field_value = hint(field_value)
+                except ValueError:
+                    pass
+        result[field_name] = field_value
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Worker process entry point
+# ---------------------------------------------------------------------------
+
+def _worker_main(provider_pickle: bytes, socket_path: str) -> None:
+    """Entry point for the worker subprocess. Runs the provider and serves IPC requests."""
+    asyncio.run(_worker_serve(provider_pickle, socket_path))
+
+
+async def _worker_serve(provider_pickle: bytes, socket_path: str) -> None:
+    provider: SpeechProvider = pickle.loads(provider_pickle)
+
+    async def handle_client(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            while True:
+                try:
+                    msg = await _read_msg(reader)
+                except (asyncio.IncompleteReadError, ConnectionResetError, EOFError):
+                    break
+
+                cmd = msg.get("cmd")
+
+                if cmd == "start":
+                    try:
+                        await provider.start()
+                        await _write_msg(writer, {"ok": True})
+                    except Exception as exc:
+                        await _write_msg(writer, {"ok": False, "error": str(exc)})
+
+                elif cmd == "stop":
+                    try:
+                        await provider.stop()
+                        await _write_msg(writer, {"ok": True})
+                    except Exception as exc:
+                        await _write_msg(writer, {"ok": False, "error": str(exc)})
+                    break
+
+                elif cmd == "health":
+                    try:
+                        result = await provider.health_check()
+                        await _write_msg(writer, {"ok": True, "result": result})
+                    except Exception as exc:
+                        await _write_msg(writer, {"ok": False, "error": str(exc)})
+
+                elif cmd == "invoke":
+                    method = msg["method"]
+                    raw_kwargs = msg.get("kwargs", {})
+                    kwargs = {k: _deserialize_arg(v) for k, v in raw_kwargs.items()}
+                    try:
+                        fn = getattr(provider, method)
+                        result = await fn(**kwargs)
+                        serialized = _serialize_arg(result)
+                        await _write_msg(writer, {"ok": True, "result": serialized})
+                    except Exception as exc:
+                        await _write_msg(writer, {"ok": False, "error": str(exc)})
+
+                elif cmd == "invoke_stream":
+                    method = msg["method"]
+                    raw_kwargs = msg.get("kwargs", {})
+                    kwargs = {k: _deserialize_arg(v) for k, v in raw_kwargs.items()}
+                    try:
+                        fn = getattr(provider, method)
+                        async for item in fn(**kwargs):
+                            serialized = _serialize_arg(item)
+                            await _write_msg(writer, {"ok": True, "chunk": serialized, "done": False})
+                        await _write_msg(writer, {"ok": True, "done": True})
+                    except Exception as exc:
+                        await _write_msg(writer, {"ok": False, "error": str(exc)})
+
+                else:
+                    await _write_msg(writer, {"ok": False, "error": f"Unknown command: {cmd}"})
+        finally:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    server = await asyncio.start_unix_server(handle_client, path=socket_path)
+    async with server:
+        await server.serve_forever()
+
+
+def _spawn_worker(provider_pickle: bytes, socket_path: str) -> "asyncio.subprocess.Process":
+    """Spawn the worker as a subprocess using the same Python interpreter."""
+    import openspeech
+    pkg_root = str(Path(openspeech.__file__).parent.parent)
+
+    # Build a self-contained script that imports _worker_main and runs it
+    script = (
+        "import sys, pickle\n"
+        f"sys.path.insert(0, {pkg_root!r})\n"
+        "from openspeech.dispatch.executors.subprocess_exec import _worker_main\n"
+        f"provider_pickle = {provider_pickle!r}\n"
+        f"socket_path = {socket_path!r}\n"
+        "_worker_main(provider_pickle, socket_path)\n"
+    )
+    return script
+
+
+# ---------------------------------------------------------------------------
+# SubprocessExecutor
+# ---------------------------------------------------------------------------
+
+class SubprocessExecutor(Executor):
+    """Executor that runs the provider inside a worker subprocess.
+
+    Communication uses Unix Domain Sockets with length-prefixed msgpack messages.
+    """
+
+    def __init__(self, restart_on_crash: bool = True, restart_delay_s: float = 1.0) -> None:
+        self._provider_cls: type[SpeechProvider] | None = None
+        self._settings: BaseSettings | None = None
+        self._process: asyncio.subprocess.Process | None = None
+        self._socket_path: str | None = None
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._restart_on_crash = restart_on_crash
+        self._restart_delay_s = restart_delay_s
+        self._started = False
+        self._tmpdir: tempfile.TemporaryDirectory | None = None
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self, provider_cls: type[SpeechProvider], settings: BaseSettings, *, http_client: Any = None) -> None:
+        self._provider_cls = provider_cls
+        self._settings = settings
+        self._tmpdir = tempfile.TemporaryDirectory(prefix="openspeech_")
+        self._socket_path = os.path.join(self._tmpdir.name, "worker.sock")
+        await self._launch_worker()
+        self._started = True
+
+    async def _launch_worker(self) -> None:
+        """Spawn the subprocess and establish the UDS connection."""
+        assert self._provider_cls is not None
+        assert self._settings is not None
+        assert self._socket_path is not None
+
+        # Instantiate provider (no start) and pickle it
+        provider_instance = self._provider_cls(settings=self._settings)
+        provider_pickle = pickle.dumps(provider_instance)
+
+        import openspeech
+        pkg_root = str(Path(openspeech.__file__).parent.parent)
+
+        script = (
+            "import sys, pickle\n"
+            f"sys.path.insert(0, {pkg_root!r})\n"
+            "from openspeech.dispatch.executors.subprocess_exec import _worker_main\n"
+            f"provider_pickle = {provider_pickle!r}\n"
+            f"socket_path = {self._socket_path!r}\n"
+            "_worker_main(provider_pickle, socket_path)\n"
+        )
+
+        env = dict(os.environ)
+        for key in _PROXY_ENV_KEYS:
+            env.pop(key, None)
+
+        self._process = await asyncio.create_subprocess_exec(
+            sys.executable, "-c", script,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+            env=env,
+        )
+
+        # Wait for socket to appear (worker needs a moment to bind)
+        await self._wait_for_socket(self._socket_path, timeout=10.0)
+
+        self._reader, self._writer = await asyncio.open_unix_connection(self._socket_path)
+
+        # Tell the worker to start the provider
+        await _write_msg(self._writer, {"cmd": "start"})
+        resp = await _read_msg(self._reader)
+        if not resp.get("ok"):
+            raise RuntimeError(f"Worker start failed: {resp.get('error')}")
+
+    @staticmethod
+    async def _wait_for_socket(path: str, timeout: float = 10.0) -> None:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if os.path.exists(path):
+                return
+            await asyncio.sleep(0.05)
+        raise RuntimeError(f"Worker socket did not appear at {path!r} within {timeout}s")
+
+    async def stop(self) -> None:
+        self._started = False
+        await self._close_connection(send_stop=True)
+        await self._kill_process()
+        if self._tmpdir is not None:
+            try:
+                self._tmpdir.cleanup()
+            except Exception:
+                pass
+            self._tmpdir = None
+
+    async def _close_connection(self, send_stop: bool = False) -> None:
+        if self._writer is not None:
+            try:
+                if send_stop:
+                    await _write_msg(self._writer, {"cmd": "stop"})
+                    try:
+                        await asyncio.wait_for(_read_msg(self._reader), timeout=2.0)
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+            try:
+                self._writer.close()
+                await asyncio.wait_for(self._writer.wait_closed(), timeout=1.0)
+            except Exception:
+                pass
+            self._reader = None
+            self._writer = None
+
+    async def _kill_process(self) -> None:
+        if self._process is not None:
+            try:
+                self._process.terminate()
+                await asyncio.wait_for(self._process.wait(), timeout=3.0)
+            except Exception:
+                try:
+                    self._process.kill()
+                except Exception:
+                    pass
+            self._process = None
+
+    # ------------------------------------------------------------------
+    # Crash detection & restart
+    # ------------------------------------------------------------------
+
+    async def _check_alive(self) -> bool:
+        if self._process is None:
+            return False
+        return self._process.returncode is None
+
+    async def _maybe_restart(self) -> None:
+        if not self._restart_on_crash or not self._started:
+            raise RuntimeError("Worker process crashed and restart is disabled")
+        await asyncio.sleep(self._restart_delay_s)
+        # Clean up old connection
+        await self._close_connection(send_stop=False)
+        await self._kill_process()
+        # New socket path
+        self._socket_path = os.path.join(self._tmpdir.name, f"worker_{time.monotonic_ns()}.sock")
+        await self._launch_worker()
+
+    # ------------------------------------------------------------------
+    # Operations
+    # ------------------------------------------------------------------
+
+    async def invoke(self, method: str, **kwargs: Any) -> Any:
+        if not self._started or self._writer is None:
+            raise RuntimeError("Executor not started")
+
+        if not await self._check_alive():
+            await self._maybe_restart()
+
+        with PerfTimer(Event.PROVIDER_TOTAL, method=method, exec_mode="subprocess"):
+            serialized_kwargs = {k: _serialize_arg(v) for k, v in kwargs.items()}
+            await _write_msg(self._writer, {"cmd": "invoke", "method": method, "kwargs": serialized_kwargs})
+            resp = await _read_msg(self._reader)
+            if not resp.get("ok"):
+                raise RuntimeError(resp.get("error", "Unknown error"))
+            return _deserialize_arg(resp.get("result"))
+
+    async def invoke_stream(self, method: str, **kwargs: Any) -> AsyncIterator[Any]:
+        if not self._started or self._writer is None:
+            raise RuntimeError("Executor not started")
+
+        if not await self._check_alive():
+            await self._maybe_restart()
+
+        with PerfTimer(Event.PROVIDER_TOTAL, method=method, exec_mode="subprocess") as t:
+            serialized_kwargs = {k: _serialize_arg(v) for k, v in kwargs.items()}
+            await _write_msg(self._writer, {"cmd": "invoke_stream", "method": method, "kwargs": serialized_kwargs})
+
+            count = 0
+            while True:
+                resp = await _read_msg(self._reader)
+                if not resp.get("ok"):
+                    raise RuntimeError(resp.get("error", "Unknown error"))
+                if resp.get("done"):
+                    break
+                count += 1
+                yield _deserialize_arg(resp["chunk"])
+            t.add(items=count)
+
+    async def health_check(self) -> bool:
+        if not self._started or self._writer is None:
+            return False
+        if not await self._check_alive():
+            return False
+        try:
+            await _write_msg(self._writer, {"cmd": "health"})
+            resp = await asyncio.wait_for(_read_msg(self._reader), timeout=5.0)
+            if not resp.get("ok"):
+                return False
+            return bool(resp.get("result", False))
+        except Exception:
+            return False