echoact 0.1.0__py3-none-any.whl

echoact/errors.py

@@ -0,0 +1,281 @@
+"""Error catalogue shared by every access path.
+
+N-24 requires the GUI, REST, and MCP to share one set of error semantics, and
+F-57 requires each error to carry a stable code, a user-facing message, whether
+a retry can succeed, and a request identifier.  This module is the single place
+those facts are recorded; no surface invents a code of its own.
+
+Messages here are the English text.  The GUI localises through
+``echoact.ui.i18n`` keyed on ``code``; REST and MCP always answer in English so
+that F-86's display-language setting never changes an API response.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class Code(StrEnum):
+    """Stable error codes.  Values are part of the external contract."""
+
+    # -- input validation (F-03, F-32 to F-37) ---------------------------
+    INPUT_EMPTY = "INPUT_EMPTY"
+    INPUT_TOO_LONG = "INPUT_TOO_LONG"
+    FILE_TOO_LARGE = "FILE_TOO_LARGE"
+    FILE_UNSUPPORTED = "FILE_UNSUPPORTED"
+    FILE_NOT_TEXT = "FILE_NOT_TEXT"
+    FILE_ENCODING = "FILE_ENCODING"
+    FILE_CORRUPT = "FILE_CORRUPT"
+    FILE_ENCRYPTED = "FILE_ENCRYPTED"
+    FILE_PERMISSION = "FILE_PERMISSION"
+    FILE_NOT_FOUND = "FILE_NOT_FOUND"
+
+    # -- request shape (F-54, F-49, F-57) ---------------------------------
+    #: The body could not be read at all -- malformed JSON, a multipart
+    #: body whose parts do not parse.  Distinct from a body that parsed
+    #: and then failed validation, because a client can act on the
+    #: difference: one is a bug in how it encoded the request, the other
+    #: is a wrong value in it.
+    MALFORMED_REQUEST = "MALFORMED_REQUEST"
+    #: A field this version does not define.  F-54 forbids substituting an
+    #: unknown option, and silently dropping one is a substitution the
+    #: caller cannot see.
+    UNKNOWN_OPTION = "UNKNOWN_OPTION"
+    #: The same fault inside the voice settings, which Section 2.10 gives a
+    #: different status.  A separate code rather than an override on the
+    #: one above: the status is part of what a code means here, and a
+    #: per-call escape hatch would make that stop being true.
+    VOICE_SETTINGS_INVALID = "VOICE_SETTINGS_INVALID"
+    JOB_KIND_MISSING = "JOB_KIND_MISSING"
+    JOB_KIND_UNKNOWN = "JOB_KIND_UNKNOWN"
+    IDEMPOTENCY_KEY_MISSING = "IDEMPOTENCY_KEY_MISSING"
+    IDEMPOTENCY_KEY_CONFLICT = "IDEMPOTENCY_KEY_CONFLICT"
+    INPUT_AMBIGUOUS = "INPUT_AMBIGUOUS"
+
+    # -- voice settings (F-04 to F-08) -----------------------------------
+    MODEL_UNKNOWN = "MODEL_UNKNOWN"
+    VOICE_UNKNOWN = "VOICE_UNKNOWN"
+    LANGUAGE_UNKNOWN = "LANGUAGE_UNKNOWN"
+    STYLE_UNKNOWN = "STYLE_UNKNOWN"
+    TEMPO_OUT_OF_RANGE = "TEMPO_OUT_OF_RANGE"
+    VOICE_GENDER_MISMATCH = "VOICE_GENDER_MISMATCH"
+
+    # -- model preparation (F-09, F-63 to F-65, F-84) --------------------
+    MODEL_NOT_READY = "MODEL_NOT_READY"
+    MODEL_CORRUPT = "MODEL_CORRUPT"
+    MODEL_DOWNLOAD_FORBIDDEN = "MODEL_DOWNLOAD_FORBIDDEN"
+    MODEL_DOWNLOAD_FAILED = "MODEL_DOWNLOAD_FAILED"
+    MODEL_LICENSE_NOT_ACCEPTED = "MODEL_LICENSE_NOT_ACCEPTED"
+    MODEL_OVER_BUDGET = "MODEL_OVER_BUDGET"
+
+    # -- execution (F-23, F-47, N-23) ------------------------------------
+    BUSY = "BUSY"
+    RATE_LIMITED = "RATE_LIMITED"
+    INSUFFICIENT_RESOURCES = "INSUFFICIENT_RESOURCES"
+    OUT_OF_MEMORY = "OUT_OF_MEMORY"
+    GENERATION_FAILED = "GENERATION_FAILED"
+    WORKER_LOST = "WORKER_LOST"
+    RUNTIME_PROVIDER_REFUSED = "RUNTIME_PROVIDER_REFUSED"
+
+    # -- results (F-55, F-42, 4.2) ---------------------------------------
+    RESULT_NOT_READY = "RESULT_NOT_READY"
+    RESULT_EXPIRED = "RESULT_EXPIRED"
+    RESULT_MISSING = "RESULT_MISSING"
+    SEGMENT_NOT_READY = "SEGMENT_NOT_READY"
+
+    # -- access control (N-17, N-19, F-50, F-61) -------------------------
+    UNAUTHENTICATED = "UNAUTHENTICATED"
+    FORBIDDEN = "FORBIDDEN"
+    NOT_FOUND = "NOT_FOUND"
+    HOST_NOT_ALLOWED = "HOST_NOT_ALLOWED"
+    ORIGIN_NOT_ALLOWED = "ORIGIN_NOT_ALLOWED"
+    CREDENTIAL_EXPIRED = "CREDENTIAL_EXPIRED"
+    CREDENTIAL_REVOKED = "CREDENTIAL_REVOKED"
+    AUTH_LOCKED_OUT = "AUTH_LOCKED_OUT"
+    PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE"
+
+    # -- storage (N-14 to N-16, F-43, F-44) ------------------------------
+    STORAGE_FULL = "STORAGE_FULL"
+    RETENTION_LIMIT_REACHED = "RETENTION_LIMIT_REACHED"
+    DB_LOCKED = "DB_LOCKED"
+    DB_UNAVAILABLE = "DB_UNAVAILABLE"
+    BACKUP_INVALID = "BACKUP_INVALID"
+    BACKUP_INCOMPATIBLE = "BACKUP_INCOMPATIBLE"
+    BACKUP_TOO_LARGE = "BACKUP_TOO_LARGE"
+    DELETE_BLOCKED_IN_USE = "DELETE_BLOCKED_IN_USE"
+
+    # -- service lifecycle (F-52, F-79, N-31) ----------------------------
+    SERVICE_OFF = "SERVICE_OFF"
+    SERVICE_PORT_UNAVAILABLE = "SERVICE_PORT_UNAVAILABLE"
+    APP_NOT_RUNNING = "APP_NOT_RUNNING"
+    MCP_DISABLED = "MCP_DISABLED"
+    SHUTTING_DOWN = "SHUTTING_DOWN"
+
+    # -- audio (F-67, F-68) ----------------------------------------------
+    OUTPUT_DEVICE_LOST = "OUTPUT_DEVICE_LOST"
+    OUTPUT_DEVICE_UNAVAILABLE = "OUTPUT_DEVICE_UNAVAILABLE"
+
+    INTERNAL = "INTERNAL"
+
+
+# code -> (HTTP status, retryable in principle, English message)
+#
+# "Retryable" is F-57's flag: the identical request may succeed later without
+# the caller changing anything.  Every retryable rejection carries a
+# retry-after hint at the surface.
+_CATALOGUE: dict[Code, tuple[int, bool, str]] = {
+    Code.INPUT_EMPTY: (422, False, "The text is empty or contains only whitespace."),
+    Code.INPUT_TOO_LONG: (413, False, "The text exceeds the 50,000-character limit."),
+    Code.FILE_TOO_LARGE: (413, False, "The file exceeds the 2,000,000-byte limit."),
+    Code.FILE_UNSUPPORTED: (415, False, "This file format cannot be read as text."),
+    Code.FILE_NOT_TEXT: (415, False, "The file does not appear to contain text."),
+    Code.FILE_ENCODING: (415, False, "The file's text encoding could not be determined."),
+    Code.FILE_CORRUPT: (415, False, "The file appears to be damaged."),
+    Code.FILE_ENCRYPTED: (415, False, "The file is encrypted."),
+    Code.FILE_PERMISSION: (403, False, "The file cannot be read with the current permissions."),
+    Code.FILE_NOT_FOUND: (404, False, "The file no longer exists."),
+    Code.MALFORMED_REQUEST: (400, False, "The request body could not be read."),
+    Code.UNKNOWN_OPTION: (400, False, "The request names a field this version does not define."),
+    Code.VOICE_SETTINGS_INVALID: (422, False, "The voice settings are not valid."),
+    Code.JOB_KIND_MISSING: (400, False, "The request must state a job kind."),
+    Code.JOB_KIND_UNKNOWN: (400, False, "That job kind is not supported by this version."),
+    Code.IDEMPOTENCY_KEY_MISSING: (400, False, "A duplicate-prevention key is required."),
+    Code.IDEMPOTENCY_KEY_CONFLICT: (
+        409,
+        False,
+        "That key was already used with different content.",
+    ),
+    Code.INPUT_AMBIGUOUS: (400, False, "Provide either inline text or an upload, not both."),
+    Code.MODEL_UNKNOWN: (422, False, "That model is not one this version supports."),
+    Code.VOICE_UNKNOWN: (422, False, "That voice is not available for the selected model."),
+    Code.LANGUAGE_UNKNOWN: (422, False, "That language is not supported."),
+    Code.STYLE_UNKNOWN: (422, False, "That speaking style is not supported."),
+    Code.TEMPO_OUT_OF_RANGE: (422, False, "Tempo must be between 0.70x and 1.50x."),
+    Code.VOICE_GENDER_MISMATCH: (422, False, "That voice does not belong to the selected gender."),
+    Code.MODEL_NOT_READY: (409, False, "The model has not been prepared on this machine."),
+    Code.MODEL_CORRUPT: (409, False, "The model's files do not match the manifest."),
+    Code.MODEL_DOWNLOAD_FORBIDDEN: (
+        403,
+        False,
+        "The owner has not authorised downloading this model.",
+    ),
+    Code.MODEL_DOWNLOAD_FAILED: (503, True, "The model download did not complete."),
+    Code.MODEL_LICENSE_NOT_ACCEPTED: (
+        403,
+        False,
+        "The model's licence terms have not been accepted.",
+    ),
+    Code.MODEL_OVER_BUDGET: (422, False, "The model cannot run within the current resource budget."),
+    Code.BUSY: (409, True, "A generation job is already running."),
+    Code.RATE_LIMITED: (429, True, "Too many requests."),
+    Code.INSUFFICIENT_RESOURCES: (503, True, "There is not enough free memory to start."),
+    Code.OUT_OF_MEMORY: (503, True, "The job was halted because it exceeded its memory budget."),
+    Code.GENERATION_FAILED: (500, False, "Speech generation failed."),
+    Code.WORKER_LOST: (500, True, "The synthesis worker stopped unexpectedly."),
+    Code.RUNTIME_PROVIDER_REFUSED: (
+        500,
+        False,
+        "The inference runtime offered a non-local execution provider.",
+    ),
+    Code.RESULT_NOT_READY: (409, True, "The result is not finished yet."),
+    Code.RESULT_EXPIRED: (410, False, "The result's lifetime has passed."),
+    Code.RESULT_MISSING: (410, False, "The result file is missing."),
+    Code.SEGMENT_NOT_READY: (409, True, "That segment has not been generated yet."),
+    Code.UNAUTHENTICATED: (401, False, "Authentication is required."),
+    Code.FORBIDDEN: (403, False, "This credential does not carry that permission."),
+    Code.NOT_FOUND: (404, False, "No such item."),
+    Code.HOST_NOT_ALLOWED: (400, False, "Unexpected Host header."),
+    Code.ORIGIN_NOT_ALLOWED: (400, False, "Unexpected Origin header."),
+    Code.CREDENTIAL_EXPIRED: (401, False, "The credential has expired."),
+    Code.CREDENTIAL_REVOKED: (401, False, "The credential was revoked."),
+    Code.AUTH_LOCKED_OUT: (429, True, "Too many authentication failures."),
+    Code.PAYLOAD_TOO_LARGE: (413, False, "The request body exceeds 2,000,000 bytes."),
+    Code.STORAGE_FULL: (507, False, "There is not enough free disk space."),
+    Code.RETENTION_LIMIT_REACHED: (507, False, "The retention space limit has been reached."),
+    Code.DB_LOCKED: (503, True, "The local database is busy."),
+    Code.DB_UNAVAILABLE: (503, True, "The local database cannot be opened."),
+    Code.BACKUP_INVALID: (422, False, "The backup is damaged."),
+    Code.BACKUP_INCOMPATIBLE: (422, False, "The backup was made by an incompatible version."),
+    Code.BACKUP_TOO_LARGE: (413, False, "The backup exceeds the restore limits."),
+    Code.DELETE_BLOCKED_IN_USE: (409, True, "That item is in use by a running job."),
+    Code.SERVICE_OFF: (503, False, "The local service is turned off."),
+    Code.SERVICE_PORT_UNAVAILABLE: (503, False, "The local service could not bind its port."),
+    Code.APP_NOT_RUNNING: (503, False, "EchoAct is not running."),
+    Code.MCP_DISABLED: (503, False, "MCP is not enabled in EchoAct."),
+    Code.SHUTTING_DOWN: (503, False, "EchoAct is shutting down."),
+    Code.OUTPUT_DEVICE_LOST: (503, True, "The audio output device disappeared."),
+    Code.OUTPUT_DEVICE_UNAVAILABLE: (503, True, "No audio output device is available."),
+    Code.INTERNAL: (500, False, "An internal error occurred."),
+}
+
+
+def http_status(code: Code) -> int:
+    return _CATALOGUE[code][0]
+
+
+def is_retryable(code: Code) -> bool:
+    return _CATALOGUE[code][1]
+
+
+def default_message(code: Code) -> str:
+    return _CATALOGUE[code][2]
+
+
+class EchoActError(Exception):
+    """The one exception type that crosses a module boundary.
+
+    Anything raised out of a package module is either this or a programming
+    error.  Surfaces translate it; they never guess a status from its text.
+    """
+
+    def __init__(
+        self,
+        code: Code,
+        message: str | None = None,
+        *,
+        detail: dict[str, Any] | None = None,
+        retry_after_s: float | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        self.code = code
+        self.message = message or default_message(code)
+        self.detail = detail or {}
+        # Only a retryable code may carry a hint; N-23 forbids inviting a
+        # retry that cannot succeed.
+        self.retry_after_s = retry_after_s if is_retryable(code) else None
+        super().__init__(f"{code.value}: {self.message}")
+        if cause is not None:
+            self.__cause__ = cause
+
+    @property
+    def http_status(self) -> int:
+        return http_status(self.code)
+
+    @property
+    def retryable(self) -> bool:
+        return is_retryable(self.code)
+
+    def to_payload(self, request_id: str) -> dict[str, Any]:
+        """F-57's wire shape.  Never carries a path, a credential, or body text."""
+        body: dict[str, Any] = {
+            "code": self.code.value,
+            "message": self.message,
+            "retryable": self.retryable,
+            "request_id": request_id,
+        }
+        if self.detail:
+            body["detail"] = self.detail
+        if self.retry_after_s is not None:
+            body["retry_after_s"] = round(self.retry_after_s, 3)
+        return body
+
+
+@dataclass(frozen=True, slots=True)
+class Problem:
+    """A non-fatal report shown to the user, e.g. a file that would not open."""
+
+    code: Code
+    message: str
+    remedies: tuple[str, ...] = field(default_factory=tuple)

echoact/instance.py

@@ -0,0 +1,172 @@
+"""One instance per user account, per F-85.
+
+A second launch must surface the window that already exists rather than
+start a second engine, a second database session, or a second REST
+listener -- and above all it must never create a second generation slot,
+which F-47 makes an app-wide singleton.
+
+The mechanism is a lock file holding the first instance's activation port
+and a random token, plus a loopback listener that accepts exactly one
+message.  Two details are deliberate:
+
+* The listener is not the REST service and shares nothing with it.  It
+  binds an ephemeral port, speaks one word, and does nothing else, so a
+  bind failure here cannot affect F-79's separate story about the REST
+  port -- and the REST service being turned off does not stop a second
+  launch from finding the first window.
+* A stale lock file is taken over rather than treated as a running app.
+  A forced termination leaves one behind, and refusing to start after a
+  crash would be worse than the problem the lock solves.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import socket
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from .paths import ensure_tree, lock_path
+from .util.logging import get_logger
+
+log = get_logger("instance")
+
+_ACTIVATE = "echoact-activate"
+_CONNECT_TIMEOUT_S = 1.5
+
+
+@dataclass(frozen=True, slots=True)
+class LockInfo:
+    pid: int
+    port: int
+    token: str
+
+
+class AlreadyRunning(Exception):
+    """Raised by :func:`acquire` when another instance answered."""
+
+
+class InstanceLock:
+    """Held for the life of the application process."""
+
+    def __init__(self, on_activate: Callable[[], None] | None = None) -> None:
+        self._on_activate = on_activate
+        self._server: socket.socket | None = None
+        self._thread: threading.Thread | None = None
+        self._token = secrets.token_urlsafe(24)
+        self._stop = threading.Event()
+
+    @property
+    def port(self) -> int:
+        return self._server.getsockname()[1] if self._server else 0
+
+    def start(self) -> None:
+        self._server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 0)
+        self._server.bind(("127.0.0.1", 0))
+        self._server.listen(4)
+        self._server.settimeout(0.5)
+        self._thread = threading.Thread(target=self._serve, name="echoact-instance", daemon=True)
+        self._thread.start()
+        _write_lock(LockInfo(pid=os.getpid(), port=self.port, token=self._token))
+
+    def release(self) -> None:
+        self._stop.set()
+        if self._server is not None:
+            try:
+                self._server.close()
+            except OSError:
+                pass
+            self._server = None
+        if self._thread is not None:
+            self._thread.join(timeout=1.5)
+            self._thread = None
+        try:
+            path = lock_path()
+            info = _read_lock()
+            # Only remove our own lock: a lock written by a later instance
+            # after we were killed is not ours to delete.
+            if info is None or info.pid == os.getpid():
+                path.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+    def _serve(self) -> None:
+        while not self._stop.is_set() and self._server is not None:
+            try:
+                conn, _ = self._server.accept()
+            except TimeoutError:
+                continue
+            except OSError:
+                return
+            with conn:
+                try:
+                    conn.settimeout(1.0)
+                    payload = conn.recv(256).decode("utf-8", "replace").strip()
+                except OSError:
+                    continue
+                want = f"{_ACTIVATE} {self._token}"
+                if payload != want:
+                    # Not our second launch.  Say nothing: an unauthenticated
+                    # caller learns neither that this is EchoAct nor why it
+                    # was refused.
+                    continue
+                try:
+                    conn.sendall(b"ok\n")
+                except OSError:
+                    pass
+                if self._on_activate:
+                    try:
+                        self._on_activate()
+                    except Exception as exc:  # noqa: BLE001
+                        log.warning("activation handler failed: %s", type(exc).__name__)
+
+
+def _write_lock(info: LockInfo) -> None:
+    ensure_tree()
+    path = lock_path()
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(
+        json.dumps({"pid": info.pid, "port": info.port, "token": info.token}),
+        encoding="utf-8",
+    )
+    os.replace(tmp, path)
+
+
+def _read_lock() -> LockInfo | None:
+    try:
+        data = json.loads(lock_path().read_text(encoding="utf-8"))
+        return LockInfo(pid=int(data["pid"]), port=int(data["port"]), token=str(data["token"]))
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def notify_existing() -> bool:
+    """Ask a running instance to show itself.  True if one answered.
+
+    A lock file whose listener does not answer is stale -- the usual cause
+    is the forced termination F-45 already has to recover from -- so the
+    caller starts normally and overwrites it.
+    """
+    info = _read_lock()
+    if info is None or info.port <= 0:
+        return False
+    try:
+        with socket.create_connection(("127.0.0.1", info.port), _CONNECT_TIMEOUT_S) as s:
+            s.settimeout(_CONNECT_TIMEOUT_S)
+            s.sendall(f"{_ACTIVATE} {info.token}".encode())
+            return s.recv(16).strip() == b"ok"
+    except OSError:
+        return False
+
+
+def acquire(on_activate: Callable[[], None] | None = None) -> InstanceLock:
+    """Become the single instance, or raise :class:`AlreadyRunning`."""
+    if notify_existing():
+        raise AlreadyRunning
+    lock = InstanceLock(on_activate)
+    lock.start()
+    return lock