@camera.ui/server 2.0.3 → 2.0.5

package/dist/server/src/plugins/runtime/python/store.py

@@ -0,0 +1,513 @@
+from __future__ import annotations
+
+import asyncio
+import math
+import os
+import shutil
+import sys
+import time
+import zlib
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol
+
+import msgpack
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+STORE_FILE_NAME = "store.cui"
+
+_MAGIC = b"CUI1"
+_MAX_SAFE_INTEGER = 2**53 - 1
+_RENAME_RETRY_DELAYS_MS = (10, 25, 60, 150, 300)
+_IS_WINDOWS = sys.platform == "win32"
+
+
+class StoreLogger(Protocol):
+    def debug(self, message: str, /) -> None: ...
+
+    def warn(self, message: str, /) -> None: ...
+
+    def error(self, message: str, /) -> None: ...
+
+
+class StoreCorruptError(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"store envelope: {message}")
+
+
+def encode_envelope(payload: dict[str, Any]) -> bytes:
+    body: bytes = msgpack.packb(payload, use_bin_type=True)
+    return _MAGIC + body + zlib.crc32(body).to_bytes(4, "little")
+
+
+def decode_envelope(buf: bytes) -> dict[str, Any]:
+    if len(buf) < len(_MAGIC) + 4 or buf[: len(_MAGIC)] != _MAGIC:
+        raise StoreCorruptError("bad magic")
+
+    body = buf[len(_MAGIC) : -4]
+    if zlib.crc32(body) != int.from_bytes(buf[-4:], "little"):
+        raise StoreCorruptError("crc mismatch")
+
+    try:
+        payload = msgpack.unpackb(body, raw=False, strict_map_key=False)
+    except Exception as error:
+        raise StoreCorruptError(f"payload decode failed: {error}") from error
+
+    if not isinstance(payload, dict):
+        raise StoreCorruptError("payload is not a map")
+
+    return payload
+
+
+def _replace_with_retry(tmp_path: str, path: str) -> None:
+    for attempt, delay_ms in enumerate(_RENAME_RETRY_DELAYS_MS):
+        try:
+            os.replace(tmp_path, path)
+            return
+        except PermissionError:
+            # Windows AV scanners / the search indexer transiently hold the
+            # rename target open; the error is retryable there within a small
+            # budget (~0.5s total), nowhere else.
+            if not _IS_WINDOWS or attempt >= len(_RENAME_RETRY_DELAYS_MS) - 1:
+                raise
+            time.sleep(delay_ms / 1000)
+
+
+def _write_store_file_sync(path: str, buf: bytes) -> None:
+    tmp_path = f"{path}.tmp-{os.getpid()}"
+    try:
+        fd = os.open(tmp_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+        try:
+            os.write(fd, buf)
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        _replace_with_retry(tmp_path, path)
+    except Exception:
+        with suppress(OSError):
+            os.unlink(tmp_path)
+        raise
+
+
+async def write_store_file(path: str, payload: dict[str, Any], log: StoreLogger | None = None) -> None:
+    buf = encode_envelope(payload)
+
+    try:
+        await asyncio.to_thread(_write_store_file_sync, path, buf)
+    except Exception as error:
+        if log:
+            log.error(f"store: write {path} failed: {error}")
+        raise
+
+
+def _read_bytes(path: str) -> bytes | None:
+    try:
+        return Path(path).read_bytes()
+    except FileNotFoundError:
+        return None
+
+
+async def read_store_file(path: str, log: StoreLogger | None = None) -> dict[str, Any] | None:
+    buf = await asyncio.to_thread(_read_bytes, path)
+    if buf is None:
+        return None
+
+    try:
+        payload = decode_envelope(buf)
+        return payload
+    except StoreCorruptError as error:
+        if log:
+            log.error(f"store: {path} is corrupt ({error}) — trying backup")
+
+    bak_path = f"{path}.bak"
+    try:
+        bak_buf = await asyncio.to_thread(Path(bak_path).read_bytes)
+    except OSError:
+        bak_buf = None
+
+    if bak_buf is not None:
+        try:
+            payload = decode_envelope(bak_buf)
+        except StoreCorruptError as error:
+            if log:
+                log.error(f"store: backup {bak_path} is corrupt too ({error})")
+        else:
+            # Self-heal: replace the corrupt file immediately, otherwise the
+            # next backup refresh would clobber the only good copy.
+            await asyncio.to_thread(_write_store_file_sync, path, bak_buf)
+            if log:
+                log.warn(f"store: recovered {path} from backup ({len(bak_buf)} bytes)")
+            return payload
+
+    # A corrupt store must never silently become an empty one - that would
+    # wipe the plugin's persisted state. Recover from the backup generation or
+    # fail the open loudly.
+    raise StoreCorruptError(f"{path} unreadable and no usable backup")
+
+
+def _backup_store_file_sync(path: str) -> None:
+    # Copy to a temp sibling first - a crash mid-copy must never leave a
+    # truncated .bak, it may be the only recovery generation.
+    tmp_path = f"{path}.bak.tmp-{os.getpid()}"
+    try:
+        shutil.copyfile(path, tmp_path)
+        _replace_with_retry(tmp_path, f"{path}.bak")
+    except Exception:
+        with suppress(OSError):
+            os.unlink(tmp_path)
+        raise
+
+
+async def backup_store_file(path: str, log: StoreLogger | None = None) -> None:
+    try:
+        await asyncio.to_thread(_backup_store_file_sync, path)
+    except FileNotFoundError:
+        return
+    except OSError as error:
+        if log:
+            log.warn(f"store: backup for {path} failed: {error}")
+        return
+
+
+class _PendingFlush:
+    __slots__ = ("future", "snapshot")
+
+    def __init__(self, snapshot: dict[str, Any], future: asyncio.Future[None]) -> None:
+        self.snapshot = snapshot
+        self.future = future
+
+
+# Serializes flushes and collapses saves arriving mid-flush into one trailing
+# flush of the latest snapshot. Snapshots are whole-document states, so the
+# newest one contains every earlier caller's write - a burst of N saves costs
+# at most 2 flushes without weakening the durability guarantee.
+class CoalescingWriter:
+    def __init__(
+        self,
+        flush: Callable[[dict[str, Any]], Awaitable[None]],
+        log: StoreLogger | None = None,
+    ) -> None:
+        self._flush = flush
+        self._log = log
+        self._in_flight: asyncio.Task[None] | None = None
+        self._pending: _PendingFlush | None = None
+
+    def write(self, snapshot: dict[str, Any]) -> Awaitable[None]:
+        if self._in_flight is None:
+            self._in_flight = asyncio.ensure_future(self._run(snapshot))
+            return self._in_flight
+
+        if self._pending is not None:
+            self._pending.snapshot = snapshot
+            return self._pending.future
+
+        self._pending = _PendingFlush(snapshot, asyncio.get_running_loop().create_future())
+        return self._pending.future
+
+    async def idle(self) -> None:
+        while (in_flight := self._in_flight) is not None:
+            try:
+                await in_flight
+            except asyncio.CancelledError:
+                # Re-raise only our own cancellation; a cancelled flush task
+                # must not abort the drain loop.
+                if not in_flight.cancelled():
+                    raise
+            except Exception:
+                pass
+
+    async def _run(self, snapshot: dict[str, Any]) -> None:
+        try:
+            await self._flush(snapshot)
+        finally:
+            pending = self._pending
+            self._pending = None
+
+            if pending is not None:
+                task = asyncio.ensure_future(self._run(pending.snapshot))
+                task.add_done_callback(_settler(pending.future))
+                self._in_flight = task
+            else:
+                self._in_flight = None
+
+
+def _settler(future: asyncio.Future[None]) -> Callable[[asyncio.Task[None]], None]:
+    # Every handed-out awaitable must settle no matter how the trailing flush
+    # ends (success, error, or cancellation) - a pending future here would
+    # hang its awaiting caller forever.
+    def settle(task: asyncio.Task[None]) -> None:
+        if future.done():
+            return
+        if task.cancelled():
+            future.cancel()
+        elif (error := task.exception()) is not None:
+            future.set_exception(error)
+        else:
+            future.set_result(None)
+
+    return settle
+
+
+@dataclass(frozen=True)
+class PluginLocation:
+    pass
+
+
+@dataclass(frozen=True)
+class CameraLocation:
+    camera_id: str
+
+
+@dataclass(frozen=True)
+class SensorLocation:
+    camera_id: str
+    sensor_type: str
+    sensor_name: str
+
+
+StoreLocation = PluginLocation | CameraLocation | SensorLocation
+
+
+def read_location(config: dict[str, Any], location: StoreLocation) -> dict[str, Any] | None:
+    if isinstance(location, PluginLocation):
+        return config.get("plugin")
+    if isinstance(location, CameraLocation):
+        return (config.get("cameras") or {}).get(location.camera_id)
+    by_camera = (config.get("sensors") or {}).get(location.camera_id) or {}
+    return (by_camera.get(location.sensor_type) or {}).get(location.sensor_name)
+
+
+def write_location(config: dict[str, Any], location: StoreLocation, values: dict[str, Any]) -> None:
+    if isinstance(location, PluginLocation):
+        config["plugin"] = values
+        return
+    if isinstance(location, CameraLocation):
+        config.setdefault("cameras", {})[location.camera_id] = values
+        return
+    by_camera = config.setdefault("sensors", {}).setdefault(location.camera_id, {})
+    by_camera.setdefault(location.sensor_type, {})[location.sensor_name] = values
+
+
+def delete_location(config: dict[str, Any], location: StoreLocation) -> None:
+    if isinstance(location, PluginLocation):
+        config.pop("plugin", None)
+        return
+
+    if isinstance(location, CameraLocation):
+        cameras = config.get("cameras")
+        if isinstance(cameras, dict):
+            cameras.pop(location.camera_id, None)
+        _prune_if_empty(config, "cameras")
+        return
+
+    sensors = config.get("sensors")
+    if not isinstance(sensors, dict):
+        return
+    by_camera = sensors.get(location.camera_id)
+    if not isinstance(by_camera, dict):
+        return
+    by_type = by_camera.get(location.sensor_type)
+    if not isinstance(by_type, dict):
+        return
+
+    by_type.pop(location.sensor_name, None)
+    _prune_if_empty(by_camera, location.sensor_type)
+    _prune_if_empty(sensors, location.camera_id)
+    _prune_if_empty(config, "sensors")
+
+
+def _prune_if_empty(parent: dict[str, Any], key: str) -> None:
+    child = parent.get(key)
+    if isinstance(child, dict) and not child:
+        del parent[key]
+
+
+_CANONICAL_SECTIONS = ("plugin", "cameras", "sensors")
+_LEGACY_SENSOR_MARKER = ":sensor:"
+
+
+def is_canonical_layout(payload: dict[str, Any]) -> bool:
+    return all(key in _CANONICAL_SECTIONS for key in payload)
+
+
+# Go-SDK legacy blobs ('<pluginId>.plugin', ...) are remapped by the Go SDK
+# itself, not here: server and plugin update independently, and a plugin on
+# an old SDK must keep finding its keys untouched.
+def _is_go_legacy_layout(payload: dict[str, Any], plugin_id: str) -> bool:
+    return len(payload) > 0 and all(key.startswith(f"{plugin_id}.") for key in payload)
+
+
+def remap_legacy_layout(
+    payload: dict[str, Any], plugin_id: str, log: StoreLogger | None = None
+) -> dict[str, Any]:
+    if is_canonical_layout(payload) or _is_go_legacy_layout(payload, plugin_id):
+        return payload
+
+    canonical: dict[str, Any] = {
+        section: payload[section] for section in _CANONICAL_SECTIONS if section in payload
+    }
+
+    for key, values in payload.items():
+        if key in _CANONICAL_SECTIONS:
+            continue
+
+        if key == "storage":
+            # In a mixed legacy+canonical document the canonical section is the
+            # newer write - the legacy duplicate is stale and must never win.
+            if "plugin" in canonical:
+                if log:
+                    log.warn(
+                        f"store: legacy key 'storage' dropped — canonical 'plugin' already present ({plugin_id})"
+                    )
+                continue
+            canonical["plugin"] = values
+            continue
+
+        sensor_idx = key.find(_LEGACY_SENSOR_MARKER)
+        if sensor_idx != -1:
+            # <camId>:sensor:<type>:<pluginId>:<name> - type and pluginId contain
+            # no colons; the name keeps everything after them verbatim.
+            camera_id = key[:sensor_idx]
+            rest = key[sensor_idx + len(_LEGACY_SENSOR_MARKER) :]
+            type_end = rest.find(":")
+            plugin_end = rest.find(":", type_end + 1)
+            if type_end != -1 and plugin_end != -1:
+                sensor_type = rest[:type_end]
+                sensor_name = rest[plugin_end + 1 :]
+                by_camera = canonical.setdefault("sensors", {}).setdefault(camera_id, {})
+                if sensor_name in by_camera.get(sensor_type, {}):
+                    if log:
+                        log.warn(
+                            f"store: legacy sensor key '{key}' dropped — canonical target already present ({plugin_id})"
+                        )
+                    continue
+                by_camera.setdefault(sensor_type, {})[sensor_name] = values
+                continue
+            if log:
+                log.warn(f"store: unparsable legacy sensor key '{key}' kept under cameras ({plugin_id})")
+
+        if key in (canonical.get("cameras") or {}):
+            if log:
+                log.warn(
+                    f"store: legacy key '{key}' dropped — canonical 'cameras.{key}' already present ({plugin_id})"
+                )
+            continue
+        canonical.setdefault("cameras", {})[key] = values
+
+    return canonical
+
+
+# Values must round-trip identically through all three runtimes' msgpack
+# codecs - anything outside the shared domain is refused up front.
+def validate_store_value(key: str, value: Any) -> None:
+    _walk_value(value, key, 0)
+
+
+_MAX_VALUE_DEPTH = 64
+
+
+def _walk_value(value: Any, path: str, depth: int) -> None:
+    # Depth cap: rejects circular references (and absurd nesting) with a clear
+    # error instead of a RecursionError.
+    if depth > _MAX_VALUE_DEPTH:
+        raise ValueError(
+            f"store: value at '{path}' exceeds {_MAX_VALUE_DEPTH} nesting levels — circular reference?"
+        )
+    # bool is an int subclass, so it must be accepted before the int check.
+    if value is None or isinstance(value, bool | str):
+        return
+
+    if isinstance(value, int):
+        if abs(value) > _MAX_SAFE_INTEGER:
+            raise ValueError(f"store: value at '{path}' exceeds the float64-safe integer range (±2^53)")
+        return
+
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            raise ValueError(f"store: value at '{path}' is {value} — NaN/Infinity are not storable")
+        return
+
+    if isinstance(value, bytes | bytearray | memoryview):
+        raise ValueError(
+            f"store: value at '{path}' is binary — large artifacts belong in files under the plugin storage dir"
+        )
+
+    if isinstance(value, list | tuple):
+        for index, entry in enumerate(value):
+            _walk_value(entry, f"{path}[{index}]", depth + 1)
+        return
+
+    if isinstance(value, dict):
+        for key, entry in value.items():
+            if not isinstance(key, str):
+                raise ValueError(f"store: map key {key!r} at '{path}' is not a string")
+            _walk_value(entry, f"{path}.{key}", depth + 1)
+        return
+
+    raise ValueError(
+        f"store: value at '{path}' is a {type(value).__name__} instance — only plain objects are storable"
+    )
+
+
+class PluginStoreFile:
+    def __init__(self, volume_dir: str, plugin_id: str, log: StoreLogger | None = None) -> None:
+        self._volume_dir = volume_dir
+        self._plugin_id = plugin_id
+        self._log = log
+        self._path = str(Path(volume_dir) / STORE_FILE_NAME)
+        self._writer = CoalescingWriter(self._write_snapshot, log)
+        self._payload: dict[str, Any] = {}
+        self._closed = True
+
+    @property
+    def path(self) -> str:
+        return self._path
+
+    async def open(self) -> None:
+        await asyncio.to_thread(os.makedirs, self._volume_dir, exist_ok=True)
+        await asyncio.to_thread(self._remove_orphaned_tmp_files)
+
+        payload = await read_store_file(self._path, self._log)
+        if payload is None:
+            # Persist the initial envelope so later opens skip the legacy probe.
+            payload = {}
+            await write_store_file(self._path, payload, self._log)
+
+        remapped = remap_legacy_layout(payload, self._plugin_id, self._log)
+        if remapped is not payload:
+            await write_store_file(self._path, remapped, self._log)
+
+        self._payload = remapped
+        await backup_store_file(self._path, self._log)
+        self._closed = False
+
+    def get(self) -> dict[str, Any]:
+        return self._payload
+
+    async def put(self, payload: dict[str, Any]) -> None:
+        if self._closed:
+            # A silently "successful" no-op here would lose the write during
+            # shutdown windows. Fail loudly instead.
+            raise RuntimeError(f"store: put on closed store {self._path}")
+        self._payload = payload
+        await self._writer.write(payload)
+
+    async def close(self) -> None:
+        self._closed = True
+        await self._writer.idle()
+
+    async def _write_snapshot(self, snapshot: dict[str, Any]) -> None:
+        await write_store_file(self._path, snapshot, self._log)
+
+    def _remove_orphaned_tmp_files(self) -> None:
+        try:
+            names = os.listdir(self._volume_dir)
+        except OSError:
+            return
+        for name in names:
+            if name.startswith(STORE_FILE_NAME) and ".tmp-" in name:
+                with suppress(OSError):
+                    os.unlink(os.path.join(self._volume_dir, name))

package/dist/server/src/plugins/runtime/python/store_migrate.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from lmdbm import Lmdb
+
+from plugins.runtime.python.store import write_store_file
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from plugins.runtime.python.store import StoreLogger
+
+
+class JsonLmdb(Lmdb[Literal["config"], dict[str, Any]]):
+    def _pre_key(self, key: Literal["config"]) -> bytes:
+        return key.encode("utf-8")
+
+    def _post_key(self, key: bytes) -> Literal["config"]:
+        _key: Any = key.decode("utf-8")
+        return _key
+
+    def _pre_value(self, value: dict[str, Any]) -> bytes:
+        return json.dumps(value).encode("utf-8")
+
+    def _post_value(self, value: bytes) -> dict[str, Any]:
+        return json.loads(value.decode("utf-8"))
+
+
+def needs_lmdbm_migration(volume_dir: Path, store_path: Path) -> bool:
+    return not store_path.exists() and (volume_dir / "data.mdb").exists()
+
+
+async def migrate_legacy_lmdbm(volume_dir: Path, store_path: Path, log: StoreLogger) -> None:
+    start = time.perf_counter()
+
+    def read_legacy_config() -> dict[str, Any] | None:
+        legacy_db = cast(
+            "Lmdb[Literal['config'], dict[str, Any]]",
+            JsonLmdb.open(file=str(volume_dir), flag="c"),
+        )
+        try:
+            return cast("dict[str, Any] | None", legacy_db.get("config"))
+        finally:
+            legacy_db.close()
+
+    config = await asyncio.to_thread(read_legacy_config)
+
+    if not config:
+        return
+
+    await write_store_file(str(store_path), config, log)
+    log.warn(
+        f"store: migrated legacy lmdbm env {volume_dir} -> {store_path} "
+        f"({len(config)} top-level keys) in {(time.perf_counter() - start) * 1000:.1f}ms"
+    )

package/dist/server/src/plugins/store/coalescingWriter.d.ts

@@ -0,0 +1,7 @@
+export declare class CoalescingWriter {
+    #private;
+    private readonly flush;
+    constructor(flush: (snapshot: Record<string, any>) => Promise<void>);
+    write(snapshot: Record<string, any>): Promise<void>;
+    idle(): Promise<void>;
+}

package/dist/server/src/plugins/store/coalescingWriter.js

@@ -0,0 +1,52 @@
+// Serializes flushes and collapses saves arriving mid-flush into one trailing
+// flush of the latest snapshot. Snapshots are whole-document states, so the
+// newest one contains every earlier caller's write — a burst of N saves costs
+// at most 2 flushes without weakening the durability guarantee.
+export class CoalescingWriter {
+    flush;
+    #inFlight;
+    #pending;
+    constructor(flush) {
+        this.flush = flush;
+    }
+    write(snapshot) {
+        if (!this.#inFlight) {
+            this.#inFlight = this.#run(snapshot);
+            return this.#inFlight;
+        }
+        if (this.#pending) {
+            this.#pending.snapshot = snapshot;
+            return this.#pending.promise;
+        }
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        this.#pending = { snapshot, promise, resolve, reject };
+        return promise;
+    }
+    async idle() {
+        while (this.#inFlight) {
+            await this.#inFlight.catch(() => { });
+        }
+    }
+    async #run(snapshot) {
+        try {
+            await this.flush(snapshot);
+        }
+        finally {
+            const pending = this.#pending;
+            this.#pending = undefined;
+            if (pending) {
+                this.#inFlight = this.#run(pending.snapshot);
+                this.#inFlight.then(pending.resolve, pending.reject);
+            }
+            else {
+                this.#inFlight = undefined;
+            }
+        }
+    }
+}
+//# sourceMappingURL=coalescingWriter.js.map

package/dist/server/src/plugins/store/coalescingWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalescingWriter.js","sourceRoot":"","sources":["../../../../../src/plugins/store/coalescingWriter.ts"],"names":[],"mappings":"AAOA,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,gEAAgE;AAChE,MAAM,OAAO,gBAAgB;IAIE;IAH7B,SAAS,CAAiB;IAC1B,QAAQ,CAAgB;IAExB,YAA6B,KAAuD;QAAvD,UAAK,GAAL,KAAK,CAAkD;IAAG,CAAC;IAEjF,KAAK,CAAC,QAA6B;QACxC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrC,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAClC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAC/B,CAAC;QAED,IAAI,OAAoB,CAAC;QACzB,IAAI,MAAiC,CAAC;QACtC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YAC7C,OAAO,GAAG,GAAG,CAAC;YACd,MAAM,GAAG,GAAG,CAAC;QACf,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACvD,OAAO,OAAO,CAAC;IACjB,CAAC;IAEM,KAAK,CAAC,IAAI;QACf,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAA6B;QACtC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC;gBAAS,CAAC;YACT,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC9B,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;YAE1B,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAC7C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YACvD,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;YAC7B,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/server/src/plugins/store/envelope.d.ts

@@ -0,0 +1,5 @@
+export declare class StoreCorruptError extends Error {
+    constructor(message: string);
+}
+export declare function encodeEnvelope(payload: Record<string, any>): Buffer;
+export declare function decodeEnvelope(buf: Buffer): Record<string, any>;

package/dist/server/src/plugins/store/envelope.js

@@ -0,0 +1,40 @@
+import { Packr } from 'msgpackr';
+import { crc32 } from 'node:zlib';
+// Standard msgpack only — records/string bundles are msgpackr-proprietary and
+// unreadable by the Go/Python sides; int64AsType keeps foreign integers in
+// the float64 number domain instead of surfacing as BigInt.
+const packr = new Packr({ useRecords: false, bundleStrings: false, int64AsType: 'number' });
+const MAGIC = Buffer.from('CUI1');
+export class StoreCorruptError extends Error {
+    constructor(message) {
+        super(`store envelope: ${message}`);
+        this.name = 'StoreCorruptError';
+    }
+}
+export function encodeEnvelope(payload) {
+    const body = packr.pack(payload);
+    const crc = Buffer.allocUnsafe(4);
+    crc.writeUInt32LE(crc32(body) >>> 0);
+    return Buffer.concat([MAGIC, body, crc]);
+}
+export function decodeEnvelope(buf) {
+    if (buf.length < MAGIC.length + 4 || !buf.subarray(0, MAGIC.length).equals(MAGIC)) {
+        throw new StoreCorruptError('bad magic');
+    }
+    const body = buf.subarray(MAGIC.length, buf.length - 4);
+    if (crc32(body) >>> 0 !== buf.readUInt32LE(buf.length - 4)) {
+        throw new StoreCorruptError('crc mismatch');
+    }
+    let payload;
+    try {
+        payload = packr.unpack(body);
+    }
+    catch (error) {
+        throw new StoreCorruptError(`payload decode failed: ${error instanceof Error ? error.message : error}`);
+    }
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new StoreCorruptError('payload is not a map');
+    }
+    return payload;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/server/src/plugins/store/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../../../src/plugins/store/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,8EAA8E;AAC9E,2EAA2E;AAC3E,4DAA4D;AAC5D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC;AAE5F,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAElC,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,mBAAmB,OAAO,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,UAAU,cAAc,CAAC,OAA4B;IACzD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAClC,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACrC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACxD,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,0BAA0B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1G,CAAC;IAED,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,iBAAiB,CAAC,sBAAsB,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,OAA8B,CAAC;AACxC,CAAC"}

package/dist/server/src/plugins/store/layout.d.ts

@@ -0,0 +1,2 @@
+export declare function isCanonicalLayout(payload: Record<string, any>): boolean;
+export declare function remapLegacyLayout(payload: Record<string, any>, pluginId: string): Record<string, any>;