hugpy-platform 0.2.0a0__py3-none-any.whl

hugpy_platform/__init__.py

@@ -0,0 +1,105 @@
+"""hugpy-platform: the stdlib-first foundation every Hugpy package stands on.
+
+What lives here (and nothing above it — no engine, storage, fleet or server):
+
+    central          canonical central base URL (``HUGPY_BASE_URL`` + aliases)
+    platform_facade  OS facts (``IS_WINDOWS``/``IS_MACOS``/``IS_LINUX``) and the
+                     sanitising ``env_value`` seam over ``abstract_essentials``
+    app_dirs         per-OS data/config/cache/engine dirs and the ``~/.hugpy``
+                     runtime-file accessors
+    constants        storage roots, HF cache layout, fleet-wide defaults
+                     (import has side effects: creates dirs — import it explicitly)
+    utils            small filesystem / message / naming helpers
+    module_imports   ``get_<package>()`` lazy accessors for heavy ML libraries
+    async_runtime    one process-wide asyncio loop + sync bridges
+    client_liveness  "is the HTTP client still there" probe (Flask optional)
+    binaries / procutil / hardware   executables, process trees, RAM/GPU probes
+    compat_pydantic  pure-Python pydantic stand-in for platforms without pydantic_core
+    except_utils     ``caught`` / ``attempt`` / ``catching`` logging helpers
+    trust            Hugging Face publisher trust tiers
+    buildinfo        which build is this process: workspace version, sha/dirty,
+                     editable source, lockstep check (``/health``, ``/build``, heartbeat)
+
+This ``__init__`` re-exports only the light, side-effect-free names below; the
+heavier modules are imported by dotted path. ``buildinfo`` is exported lazily
+(``hugpy_platform.buildinfo`` resolves on first attribute access, PEP 562) so
+importing the package never pays for it.
+"""
+from __future__ import annotations
+
+from hugpy_platform.app_dirs import (
+    cache_dir,
+    config_dir,
+    data_dir,
+    engine_dir,
+    ensure_hugpy_home,
+    hugpy_config_dir,
+    hugpy_home,
+    hugpy_logs_dir,
+    hugpy_run_dir,
+    hugpy_state_dir,
+    models_root,
+)
+from hugpy_platform.central import CENTRAL_ENV_VARS, DEFAULT_CENTRAL, central_base_url
+from hugpy_platform.compat_pydantic import ensure_pydantic
+from hugpy_platform.except_utils import FAILED, attempt, catching, caught, caught_block
+from hugpy_platform.platform_facade import EXE_SUFFIX, IS_LINUX, IS_MACOS, IS_WINDOWS, env_value
+from hugpy_platform.trust import trust_label, trust_tier
+
+try:  # the installed distribution's version: the workspace tag/commit, never a literal
+    from importlib.metadata import version as _dist_version
+    __version__ = _dist_version("hugpy-platform")
+except Exception:  # noqa: BLE001 — source tree without metadata
+    __version__ = "0.0.0+unknown"
+
+_LAZY_SUBMODULES = ("buildinfo",)
+
+
+def __getattr__(name: str):
+    """Lazy submodule export: ``hugpy_platform.buildinfo`` without an import-time cost."""
+    if name in _LAZY_SUBMODULES:
+        import importlib
+        module = importlib.import_module(f"{__name__}.{name}")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "__version__",
+    # central
+    "CENTRAL_ENV_VARS",
+    "DEFAULT_CENTRAL",
+    "central_base_url",
+    # platform facts + env seam
+    "EXE_SUFFIX",
+    "IS_LINUX",
+    "IS_MACOS",
+    "IS_WINDOWS",
+    "env_value",
+    # app dirs
+    "cache_dir",
+    "config_dir",
+    "data_dir",
+    "engine_dir",
+    "ensure_hugpy_home",
+    "hugpy_config_dir",
+    "hugpy_home",
+    "hugpy_logs_dir",
+    "hugpy_run_dir",
+    "hugpy_state_dir",
+    "models_root",
+    # pydantic shim
+    "ensure_pydantic",
+    # exception helpers
+    "FAILED",
+    "attempt",
+    "catching",
+    "caught",
+    "caught_block",
+    # trust tiers
+    "trust_label",
+    "trust_tier",
+    # build identity (lazy submodule)
+    "buildinfo",
+]

hugpy_platform/app_dirs.py

@@ -0,0 +1,305 @@
+"""Per-OS application directories — one source of truth.
+
+Replaces the scattered hardcoded ``/srv/abstractendeavors/...``,
+``~/.local/share/hugpy``, ``/etc/llama-swap``, and ``/mnt/llm_storage`` literals.
+Every path is overridable by the same env vars the code already honoured, so
+existing Linux deployments are unaffected; only the *defaults* become per-OS:
+
+    data_dir()    Linux ~/.local/share/hugpy   macOS ~/Library/Application Support/hugpy   Windows %LOCALAPPDATA%\\hugpy
+    config_dir()  Linux ~/.config/hugpy        macOS ~/Library/Application Support/hugpy   Windows %LOCALAPPDATA%\\hugpy
+    cache_dir()   Linux ~/.cache/hugpy         macOS ~/Library/Caches/hugpy                Windows %LOCALAPPDATA%\\hugpy\\Cache
+    engine_dir()  data_dir()/engine            — where the fetched llama.cpp binary lands
+    models_root() DEFAULT_ROOT or data_dir()/llm_storage
+
+We use ``platformdirs`` when available (added to base deps) and fall back to a
+hand-rolled per-OS layout so this module never hard-fails on import.
+"""
+from __future__ import annotations
+
+import os
+
+from hugpy_platform.platform_facade import IS_MACOS, IS_WINDOWS, env_value
+
+_APP = "hugpy"
+
+
+def _home(*parts: str) -> str:
+    return os.path.join(os.path.expanduser("~"), *parts)
+
+
+def _fallback_data() -> str:
+    if IS_WINDOWS:
+        base = os.environ.get("LOCALAPPDATA") or _home("AppData", "Local")
+        return os.path.join(base, _APP)
+    if IS_MACOS:
+        return _home("Library", "Application Support", _APP)
+    return os.path.join(os.environ.get("XDG_DATA_HOME") or _home(".local", "share"), _APP)
+
+
+def _fallback_config() -> str:
+    if IS_WINDOWS:
+        base = os.environ.get("LOCALAPPDATA") or _home("AppData", "Local")
+        return os.path.join(base, _APP)
+    if IS_MACOS:
+        return _home("Library", "Application Support", _APP)
+    return os.path.join(os.environ.get("XDG_CONFIG_HOME") or _home(".config"), _APP)
+
+
+def _fallback_cache() -> str:
+    if IS_WINDOWS:
+        base = os.environ.get("LOCALAPPDATA") or _home("AppData", "Local")
+        return os.path.join(base, _APP, "Cache")
+    if IS_MACOS:
+        return _home("Library", "Caches", _APP)
+    return os.path.join(os.environ.get("XDG_CACHE_HOME") or _home(".cache"), _APP)
+
+
+def _dirs():
+    try:
+        import platformdirs
+
+        return platformdirs.PlatformDirs(_APP, appauthor=False)
+    except Exception:
+        return None
+
+
+def data_dir() -> str:
+    override = env_value("HUGPY_DATA_DIR")
+    if override:
+        return _ensure(override)
+    d = _dirs()
+    return _ensure(d.user_data_dir if d else _fallback_data())
+
+
+def config_dir() -> str:
+    override = env_value("HUGPY_CONFIG_DIR")
+    if override:
+        return _ensure(override)
+    d = _dirs()
+    return _ensure(d.user_config_dir if d else _fallback_config())
+
+
+def cache_dir() -> str:
+    override = env_value("HUGPY_CACHE_DIR")
+    if override:
+        return _ensure(override)
+    d = _dirs()
+    return _ensure(d.user_cache_dir if d else _fallback_cache())
+
+
+def engine_dir() -> str:
+    """Where ``hugpy install-engine`` unpacks the native llama.cpp binaries."""
+    override = env_value("HUGPY_ENGINE_DIR") or env_value("LLAMA_CPP_DIR")
+    if override:
+        return _ensure(override)
+    return _ensure(os.path.join(data_dir(), "engine"))
+
+
+def models_root() -> str:
+    """Model/upload/dataset storage root.
+
+    Honours the legacy ``DEFAULT_ROOT``/``MODELS_HOME`` env vars first — but only
+    if that path can actually be created and written. A stale/un-writable override
+    (e.g. ``DEFAULT_ROOT=/mnt/llm_storage`` carried in a server ``.env`` onto a
+    worker or a phone where ``/mnt`` is read-only) is ignored in favour of a
+    per-user dir under ``data_dir()``, so storage never lands on a dead path.
+    """
+    override = env_value("DEFAULT_ROOT")
+    if override and _usable(override):
+        return override
+    # Preserve the historical Linux mount when it exists and is writable.
+    legacy = "/mnt/llm_storage"
+    try:
+        if os.path.isdir(legacy) and os.access(legacy, os.W_OK):
+            return legacy
+    except OSError:
+        pass
+    return _ensure(os.path.join(data_dir(), "llm_storage"))
+
+
+def demo_media_base() -> str:
+    """Base URL the video arm's canned demo loads its sample media from."""
+    return env_value("HUGPY_DEMO_MEDIA_BASE") or "https://hugpy.ai/demo-media"
+
+
+def demo_media_dir() -> str:
+    """Local demo-media tree to serve at ``/demo-media/`` (self-hosters).
+
+    Empty string means "not configured" — deliberately NO default and NO
+    directory creation; the ``/demo-media/`` route only exists when this is set.
+    """
+    return env_value("HUGPY_DEMO_MEDIA_DIR") or ""
+
+
+def _usable(path: str) -> bool:
+    """True only if *path* exists (or can be created) AND is writable."""
+    try:
+        os.makedirs(path, exist_ok=True)
+        return os.path.isdir(path) and os.access(path, os.W_OK)
+    except OSError:
+        return False
+
+
+def _ensure(path: str) -> str:
+    try:
+        os.makedirs(path, exist_ok=True)
+    except OSError:
+        pass
+    return path
+
+
+# ---------------------------------------------------------------------------
+# hugpy runtime "mechanic" files  (HUGPY_HOME, default ~/.hugpy)
+# ---------------------------------------------------------------------------
+# Historically these state/config/log files were written straight into $HOME
+# (``~/todo.json``, ``~/steward-state.json``, ``~/.abstract_hugpy_worker.json``,
+# ``~/model_metadata.db`` …), strewing the home directory. They now live under a
+# single base dir — ``HUGPY_HOME`` (default ``~/.hugpy``) — split into::
+#
+#     state/   todo.json, steward-state.json, model_metadata.db, flow.json, …
+#     config/  abstract_hugpy_worker.json (+ .settings.json/.update.json)
+#     logs/    bridge-mail.jsonl, bugreport.json
+#     run/     *.lock
+#
+# Each named accessor MIGRATES a legacy ``~/<name>`` file into its new home the
+# first time it is resolved (atomic same-fs rename, cross-fs copy fallback), so
+# upgrades are seamless and idempotent — no flag-day, no data loss. Every path
+# stays overridable so existing deployments and tests can pin locations.
+#
+# NOTE: standalone station-stack scripts (keeper_relay.py, bugreport/scanner.py)
+# run under the system interpreter and cannot import this package; they carry a
+# byte-identical inline resolver. Keep the two in sync — this module is the spec.
+
+def hugpy_home() -> str:
+    """Single base directory for hugpy's runtime files. Default ``~/.hugpy``."""
+    return _ensure(env_value("HUGPY_HOME") or _home(".hugpy"))
+
+
+def hugpy_state_dir() -> str:
+    return _ensure(os.path.join(hugpy_home(), "state"))
+
+
+def hugpy_config_dir() -> str:
+    return _ensure(os.path.join(hugpy_home(), "config"))
+
+
+def hugpy_logs_dir() -> str:
+    return _ensure(os.path.join(hugpy_home(), "logs"))
+
+
+def hugpy_run_dir() -> str:
+    return _ensure(os.path.join(hugpy_home(), "run"))
+
+
+def _relocate(new_path: str, *legacy_names: str) -> str:
+    """Return *new_path*, first migrating a legacy ``~/<name>`` into it once.
+
+    Idempotent and safe: if *new_path* already exists nothing moves. Uses an
+    atomic rename on the same filesystem and falls back to a copy+unlink across
+    filesystems. Any failure leaves the legacy file untouched and returns the
+    new path anyway (a fresh file is then created there).
+    """
+    try:
+        if os.path.exists(new_path):
+            return new_path
+        for name in legacy_names:
+            old = _home(name)
+            if not os.path.exists(old):
+                continue
+            if os.path.abspath(old) == os.path.abspath(new_path):
+                continue
+            try:
+                os.replace(old, new_path)          # atomic, same filesystem
+            except OSError:
+                import shutil
+                shutil.move(old, new_path)          # cross-filesystem fallback
+            break
+    except OSError:
+        pass
+    return new_path
+
+
+# --- named accessors --------------------------------------------------------
+
+def worker_id_file() -> str:
+    """``config/abstract_hugpy_worker.json`` — the worker identity file.
+
+    Honors an explicit ``WORKER_ID_FILE`` override (used by tests / multi-worker
+    hosts); otherwise migrates the legacy ``~/.abstract_hugpy_worker.json`` plus
+    its ``.settings.json`` / ``.update.json`` sidecars into ``config/``.
+    """
+    override = env_value("WORKER_ID_FILE")
+    if override:
+        return override
+    new = os.path.join(hugpy_config_dir(), "abstract_hugpy_worker.json")
+    _relocate(new, ".abstract_hugpy_worker.json")
+    for suffix in (".settings.json", ".update.json"):
+        _relocate(new + suffix, ".abstract_hugpy_worker.json" + suffix)
+    return new
+
+
+def gguf_worker_id_file() -> str:
+    """``config/gguf_worker.json`` — sibling worker identity (same pattern)."""
+    override = env_value("WORKER_ID_FILE")
+    if override:
+        return override
+    new = os.path.join(hugpy_config_dir(), "gguf_worker.json")
+    return _relocate(new, ".gguf_worker.json")
+
+
+def todo_file() -> str:
+    return _relocate(os.path.join(hugpy_state_dir(), "todo.json"), "todo.json")
+
+
+def todo_history_file() -> str:
+    return _relocate(
+        os.path.join(hugpy_state_dir(), "todo-history.jsonl"), "todo-history.jsonl"
+    )
+
+
+def todo_lock() -> str:
+    return _relocate(os.path.join(hugpy_run_dir(), "todo.lock"), ".todo.lock")
+
+
+def steward_config() -> str:
+    return _relocate(os.path.join(hugpy_config_dir(), "steward.json"), "steward.json")
+
+
+def steward_state() -> str:
+    return _relocate(
+        os.path.join(hugpy_state_dir(), "steward-state.json"), "steward-state.json"
+    )
+
+
+def model_metadata_db() -> str:
+    return _relocate(
+        os.path.join(hugpy_state_dir(), "model_metadata.db"), "model_metadata.db"
+    )
+
+
+def model_physical_json() -> str:
+    # The ``.lock`` sidecar is derived by callers as ``path + ".lock"`` and rides
+    # along in state/ next to the file — intentionally not split into run/.
+    return _relocate(
+        os.path.join(hugpy_state_dir(), "model_physical.json"), "model_physical.json"
+    )
+
+
+def flow_json() -> str:
+    return _relocate(os.path.join(hugpy_state_dir(), "flow.json"), "flow.json")
+
+
+def bridge_mail() -> str:
+    return _relocate(
+        os.path.join(hugpy_logs_dir(), "bridge-mail.jsonl"), ".bridge-mail.jsonl"
+    )
+
+
+def bugreport_json() -> str:
+    return _relocate(os.path.join(hugpy_logs_dir(), "bugreport.json"), "bugreport.json")
+
+
+def ensure_hugpy_home() -> str:
+    """Create the full ``HUGPY_HOME`` skeleton. Called by installers/postinst."""
+    hugpy_state_dir(); hugpy_config_dir(); hugpy_logs_dir(); hugpy_run_dir()
+    return hugpy_home()

hugpy_platform/async_runtime.py

@@ -0,0 +1,226 @@
+"""Process-wide async runtime — ONE long-lived event loop in a daemon thread.
+
+Replaces the per-request ``asyncio.new_event_loop()`` pattern every SSE / one-shot
+endpoint used. That pattern caused two problems:
+
+  * Loop-binding crashes — an asyncio sync primitive (Semaphore/Lock/Event)
+    cached on a process singleton binds to the FIRST request's loop and then
+    raises "bound to a different event loop" on the next request. With one
+    persistent loop, cached primitives stay valid for the life of the process.
+  * Per-request loop churn — creating/closing a loop per request and pinning a
+    thread in run_until_complete for the whole stream. The shared loop interleaves
+    many streams cooperatively; blocking model work runs in the default executor
+    (asyncio.to_thread), so the loop stays responsive.
+
+Sync callers submit coroutines via ``run()`` / ``iter_sync()``; the loop runs them
+and the caller blocks on a ``concurrent.futures.Future``. All entry points are
+thread-safe (``run_coroutine_threadsafe``). Usable from both central (gunicorn
+threads) and the worker agent (its request threads).
+
+ABANDON-ON-DISCONNECT (2026-07-27). These two functions are the ONE place a WSGI
+thread parks while the loop works, so they are also the only place that can hand
+the thread back when the caller gives up. Instead of blocking forever on
+``fut.result()`` they wake every ``client_liveness.poll_s()`` and ask the
+request's socket probe whether the client is still there; on a definite
+disconnect they cancel the in-flight coroutine (CancelledError unwinds its
+``finally`` blocks, releasing relay slots / cold-hold permits / httpx streams)
+and give the request slot back. With no probe bound — a background thread, an
+internal drain, a WSGI server that publishes no socket — ``alive`` is None and
+the behaviour is byte-identical to before.
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+import logging
+import concurrent.futures as _cf
+
+from hugpy_platform import client_liveness
+
+logger = logging.getLogger(__name__)
+
+_loop: "asyncio.AbstractEventLoop | None" = None
+_thread: "threading.Thread | None" = None
+_start_lock = threading.Lock()
+
+
+def loop() -> "asyncio.AbstractEventLoop":
+    """The shared event loop, starting its daemon thread on first use."""
+    global _loop, _thread
+    lp = _loop
+    if lp is not None and lp.is_running():
+        return lp
+    with _start_lock:
+        if _loop is not None and _loop.is_running():
+            return _loop
+        lp = asyncio.new_event_loop()
+        ready = threading.Event()
+
+        def _run():
+            asyncio.set_event_loop(lp)
+            ready.set()
+            lp.run_forever()
+
+        t = threading.Thread(target=_run, name="hugpy-async-runtime", daemon=True)
+        t.start()
+        ready.wait(5)
+        _loop, _thread = lp, t
+        logger.info("async runtime started (thread=%s)", t.name)
+        return _loop
+
+
+def submit(coro) -> "_cf.Future":
+    """Schedule a coroutine on the shared loop; return its concurrent Future."""
+    return asyncio.run_coroutine_threadsafe(coro, loop())
+
+
+def _client_gone(alive) -> bool:
+    """Ask a liveness checker, treating ANY failure as "still connected"."""
+    if alive is None:
+        return False
+    try:
+        return bool(alive())
+    except Exception:       # noqa: BLE001 — never abandon a caller on doubt
+        return False
+
+
+def _abandon(fut) -> None:
+    """Cancel an in-flight step and let its ``finally`` blocks unwind."""
+    if fut is None or fut.done():
+        return
+    fut.cancel()
+    try:
+        fut.result(5)
+    except BaseException:   # noqa: BLE001 — cancellation is the expected outcome
+        pass
+
+
+def run(coro, *, alive=None):
+    """Run a coroutine on the shared loop from a sync thread; block for its result.
+
+    ``alive`` is a zero-arg "is my caller still connected?"; it defaults to the
+    probe this thread's Flask request bound (see _platform.client_liveness). When
+    one is available and reports a disconnect, the coroutine is CANCELLED and
+    ``ClientGone`` is raised — the WSGI thread is returned to the pool instead of
+    sitting out (up to) a 25-minute cold hold for a caller who left. No probe ⇒
+    plain blocking ``.result()``, exactly as before.
+    """
+    if not asyncio.iscoroutine(coro):
+        # Tolerate already-resolved values (callers that may pass a plain result).
+        return coro
+    if alive is None:
+        alive = client_liveness.current_checker()
+    fut = submit(coro)
+    if alive is None:
+        return fut.result()
+    poll = client_liveness.poll_s()
+    while True:
+        try:
+            return fut.result(poll)
+        except _cf.TimeoutError:
+            if not _client_gone(alive):
+                continue
+            _abandon(fut)
+            logger.info("client disconnected — abandoned in-flight work "
+                        "and released the request slot")
+            raise client_liveness.ClientGone(
+                "the client disconnected before the reply was ready; the "
+                "in-flight work was cancelled and its slot released")
+
+
+def await_sync(value):
+    """Resolve an awaitable on the process loop or return a plain value."""
+    if not inspect.isawaitable(value):
+        return value
+    return run(value)
+
+
+def call_soon_threadsafe(callback, *args) -> None:
+    """Schedule a plain callback on the shared loop (e.g. ``Event.set`` from
+    another thread, which is otherwise unsafe to call cross-loop)."""
+    loop().call_soon_threadsafe(callback, *args)
+
+
+def _step_wait(heartbeat, heartbeat_secs: float, poll, waited: float):
+    """How long to block on the current step: whichever of the heartbeat tick and
+    the disconnect poll comes first. None (block forever) only when neither
+    applies — the pre-existing internal-drain behaviour."""
+    hb = (heartbeat_secs - waited) if heartbeat is not None else None
+    if hb is not None and hb <= 0:
+        hb = heartbeat_secs
+    if poll is None:
+        return hb
+    if hb is None:
+        return poll
+    return max(0.01, min(hb, poll))
+
+
+def iter_sync(agen, heartbeat: "bytes | None" = None, heartbeat_secs: float = 15.0,
+              alive=None):
+    """Drive an async generator from a sync (WSGI) thread on the SHARED loop.
+
+    Mirrors the old per-request driver semantics:
+      * With ``heartbeat`` bytes, each step waits at most ``heartbeat_secs`` and
+        yields the keepalive on timeout while the SAME step keeps running — so a
+        slow first token can't trip an upstream proxy, and every keepalive write
+        lets the WSGI server notice a dead client and trigger teardown.
+      * ``heartbeat=None`` blocks for each real event (internal/worker drains).
+      * On teardown the in-flight step is cancelled, then ``aclose()`` cascades
+        GeneratorExit through every ``async for`` / ``async with`` so a relayed
+        worker's httpx stream is released rather than leaked.
+
+    ABANDON-ON-DISCONNECT: when a client probe is available (``alive``, defaulting
+    to this request thread's), the step wait is additionally bounded by the poll
+    interval and a definite disconnect ends the drain — teardown below then
+    cancels and acloses exactly as it does for any other early exit. This is what
+    covers ``heartbeat=None`` drains such as the /v1 non-streaming completion,
+    which never writes to the client and so can never learn of a disconnect from
+    a failed write.
+    """
+    lp = loop()
+    if alive is None:
+        alive = client_liveness.current_checker()
+    poll = client_liveness.poll_s() if alive is not None else None
+    fut = None
+    waited = 0.0
+    try:
+        while True:
+            if fut is None:
+                fut = asyncio.run_coroutine_threadsafe(agen.__anext__(), lp)
+                waited = 0.0
+            step = _step_wait(heartbeat, heartbeat_secs, poll, waited)
+            try:
+                item = fut.result(step)
+                fut = None
+            except _cf.TimeoutError:
+                waited += step or 0.0
+                if _client_gone(alive):
+                    logger.info("client disconnected mid-drain — abandoning the "
+                                "stream and releasing the request slot")
+                    break
+                # Next event still cooking — keep the connection warm, keep
+                # awaiting the SAME step (it's still running on the loop).
+                if heartbeat is not None and waited >= heartbeat_secs - 1e-9:
+                    waited = 0.0
+                    yield heartbeat
+                continue
+            except StopAsyncIteration:
+                fut = None
+                break
+            if isinstance(item, str):
+                item = item.encode("utf-8")
+            yield item
+    finally:
+        try:
+            # Cancel the in-flight step first: CancelledError unwinds the
+            # chain's `async with` blocks (closing the worker httpx stream),
+            # after which aclose() can finalize without "already running".
+            _abandon(fut)
+            closer = asyncio.run_coroutine_threadsafe(agen.aclose(), lp)
+            try:
+                closer.result(10)
+            except BaseException:
+                pass
+        except Exception:
+            pass

hugpy_platform/atomic_json.py

@@ -0,0 +1,28 @@
+"""Atomic JSON writes for the small shared state files."""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+
+
+def read_json_dict(path: str) -> dict | None:
+    """Read a JSON object, returning None for absent or malformed files."""
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except Exception:  # noqa: BLE001 — unreadable and malformed are both absent
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def save_json(path: str, data: dict) -> None:
+    """Write JSON with a unique temporary file and an atomic replacement."""
+    parent = os.path.dirname(path)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    tmp = f"{path}.{os.getpid()}.{secrets.token_hex(4)}.tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, sort_keys=True)
+    os.replace(tmp, path)