devman-runtime 0.1.0__tar.gz

devman_runtime-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenji Shu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devman_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: devman-runtime
+Version: 0.1.0
+Summary: Python runtime (protocol, client, server core) for devman-gen generated device-manager bridges
+Author: Kenji Shu
+License-Expression: MIT
+Project-URL: Repository, https://github.com/kenji0923/devman-runtime
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# devman-runtime
+
+Python runtime library for bridges generated by [devman-gen](https://github.com/kenji0923/devman-gen).
+
+devman-gen is a language-agnostic generator that wraps a device-control
+library (e.g. `caen_libs` for CAEN HV crates) in a client/server pair with
+resource-ownership management. This package is the Python-side runtime that
+those generated packages import, so runtime fixes reach every bridge through
+a normal dependency upgrade instead of regeneration.
+
+## Contents
+
+- `devman_runtime.protocol` — length-prefixed JSON over TCP.
+- `devman_runtime.client` — `ManagerClient`: sessions, `acquire`/`release`
+  resource ownership, `invoke`, link-group registration
+  (`set_link_groups` / `list_link_groups`).
+- `devman_runtime.server` — `ManagerCore` and `serve_manager`: request
+  dispatch with ownership enforcement, device lifecycle/periodic hooks,
+  `TripWatchdog` (powers off linked partners when a channel trips, with
+  lease-based stale-group janitoring).
+- `devman_runtime.db` — SQLite-backed ownership and link-group registry.
+
+## Server features
+
+- `trip_watchdog_interval` / `--trip-watchdog-interval`: poll registered
+  link groups and power off partners of a tripped channel, even when the
+  registering client is offline.
+- `client_lease_sec` / `--client-lease-sec`: any authenticated request
+  renews a client lease; groups of lease-expired clients are janitored when
+  all their channels are off, and kept protected while energized.
+- Periodic hook (`periodic_file` / `periodic_function` +
+  `periodic_interval_sec`): run a user callback on an interval with access
+  to the device singleton.
+
+This package is used by, e.g., `caenhv-devman-client`.

devman_runtime-0.1.0/README.md

@@ -0,0 +1,35 @@
+# devman-runtime
+
+Python runtime library for bridges generated by [devman-gen](https://github.com/kenji0923/devman-gen).
+
+devman-gen is a language-agnostic generator that wraps a device-control
+library (e.g. `caen_libs` for CAEN HV crates) in a client/server pair with
+resource-ownership management. This package is the Python-side runtime that
+those generated packages import, so runtime fixes reach every bridge through
+a normal dependency upgrade instead of regeneration.
+
+## Contents
+
+- `devman_runtime.protocol` — length-prefixed JSON over TCP.
+- `devman_runtime.client` — `ManagerClient`: sessions, `acquire`/`release`
+  resource ownership, `invoke`, link-group registration
+  (`set_link_groups` / `list_link_groups`).
+- `devman_runtime.server` — `ManagerCore` and `serve_manager`: request
+  dispatch with ownership enforcement, device lifecycle/periodic hooks,
+  `TripWatchdog` (powers off linked partners when a channel trips, with
+  lease-based stale-group janitoring).
+- `devman_runtime.db` — SQLite-backed ownership and link-group registry.
+
+## Server features
+
+- `trip_watchdog_interval` / `--trip-watchdog-interval`: poll registered
+  link groups and power off partners of a tripped channel, even when the
+  registering client is offline.
+- `client_lease_sec` / `--client-lease-sec`: any authenticated request
+  renews a client lease; groups of lease-expired clients are janitored when
+  all their channels are off, and kept protected while energized.
+- Periodic hook (`periodic_file` / `periodic_function` +
+  `periodic_interval_sec`): run a user callback on an interval with access
+  to the device singleton.
+
+This package is used by, e.g., `caenhv-devman-client`.

devman_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "devman-runtime"
+version = "0.1.0"
+description = "Python runtime (protocol, client, server core) for devman-gen generated device-manager bridges"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kenji Shu" }]
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Repository = "https://github.com/kenji0923/devman-runtime"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

devman_runtime-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

devman_runtime-0.1.0/src/devman_runtime/__init__.py

@@ -0,0 +1,23 @@
+"""Python runtime library for devman-gen generated bridges.
+
+Generated client packages use ManagerClient; generated server packages use
+serve_manager / ManagerCore. The generator itself (devman-gen) is language
+agnostic and is not required at runtime.
+"""
+
+from .client import ManagerClient, ManagerError
+from .db import OwnershipDB
+from .server import ManagerCore, RuntimeFunctionSpec, TripWatchdog, serve_manager
+from .telegraf import TelegrafSender, build_line
+
+__all__ = [
+    "ManagerClient",
+    "ManagerError",
+    "ManagerCore",
+    "OwnershipDB",
+    "RuntimeFunctionSpec",
+    "TelegrafSender",
+    "TripWatchdog",
+    "build_line",
+    "serve_manager",
+]

devman_runtime-0.1.0/src/devman_runtime/client.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import socket
+from typing import Any
+
+from .protocol import recv_message, send_message
+
+
+class ManagerError(RuntimeError):
+    pass
+
+
+class ManagerClient:
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        client_name: str,
+        timeout: float = 5.0,
+    ) -> None:
+        self.host = host
+        self.port = int(port)
+        self.client_name = str(client_name).strip()
+        if not self.client_name:
+            raise ValueError("client_name is required")
+        self.timeout = timeout
+        self._session: str | None = None
+
+    def _request(self, payload: dict[str, Any]) -> dict[str, Any]:
+        with socket.create_connection((self.host, self.port), timeout=self.timeout) as sock:
+            send_message(sock, payload)
+            response = recv_message(sock)
+
+        if response.get("status") != "ok":
+            error = response.get("error", "unknown manager error")
+            raise ManagerError(str(error))
+        return response
+
+    def connect(self, force: bool = False) -> None:
+        if self._session:
+            return
+        response = self._request({"op": "connect", "client": self.client_name, "force": bool(force)})
+        session = response.get("session")
+        if not session:
+            raise ManagerError("manager did not return a session token")
+        self._session = str(session)
+
+    def disconnect(self) -> None:
+        if not self._session:
+            return
+        session = self._session
+        self._session = None
+        self._request(
+            {
+                "op": "disconnect",
+                "client": self.client_name,
+                "session": session,
+            }
+        )
+
+    def close(self) -> None:
+        self.disconnect()
+
+    def __enter__(self) -> "ManagerClient":
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.disconnect()
+
+    def _with_session(self, payload: dict[str, Any]) -> dict[str, Any]:
+        self.connect()
+        assert self._session is not None
+        data = dict(payload)
+        data["client"] = self.client_name
+        data["session"] = self._session
+        return data
+
+    def acquire(self, resource: str) -> bool:
+        response = self._request(self._with_session({"op": "acquire", "resource": resource}))
+        return bool(response.get("acquired", False))
+
+    def release(self, resource: str) -> bool:
+        response = self._request(self._with_session({"op": "release", "resource": resource}))
+        return bool(response.get("released", False))
+
+    def owner_of(self, resource: str) -> str | None:
+        response = self._request(self._with_session({"op": "owner_of", "resource": resource}))
+        owner = response.get("owner")
+        if owner is None:
+            return None
+        return str(owner)
+
+    def owners_of(self, resources: list[str]) -> dict[str, str | None]:
+        response = self._request(self._with_session({"op": "owners_of", "resources": list(resources)}))
+        owners = response.get("owners")
+        if not isinstance(owners, dict):
+            return {}
+        result: dict[str, str | None] = {}
+        for key, value in owners.items():
+            if value is None:
+                result[str(key)] = None
+            else:
+                result[str(key)] = str(value)
+        return result
+
+    def set_link_groups(self, groups: list[list[str]]) -> int:
+        response = self._request(
+            self._with_session({"op": "set_link_groups", "groups": [list(g) for g in groups]})
+        )
+        return int(response.get("groups", 0))
+
+    def list_link_groups(self) -> dict[str, list[list[str]]]:
+        response = self._request(self._with_session({"op": "list_link_groups"}))
+        registered = response.get("link_groups")
+        return registered if isinstance(registered, dict) else {}
+
+    def invoke(
+        self,
+        function: str,
+        args: list[Any],
+        kwargs: dict[str, Any],
+        resources: list[str],
+        handle: str | None = None,
+    ) -> Any:
+        payload = self._with_session(
+            {
+                "op": "call",
+                "function": function,
+                "args": args,
+                "kwargs": kwargs,
+                "resources": resources,
+            }
+        )
+        if handle is not None:
+            payload["handle"] = handle
+        response = self._request(payload)
+        return response.get("result")

devman_runtime-0.1.0/src/devman_runtime/db.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+class OwnershipDB:
+    def __init__(self, db_path: str | Path) -> None:
+        self.db_path = str(db_path)
+        self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        self._conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS ownership (
+                resource TEXT PRIMARY KEY,
+                owner TEXT NOT NULL,
+                updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+            )
+            """
+        )
+        self._conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS link_groups (
+                client TEXT NOT NULL,
+                group_idx INTEGER NOT NULL,
+                resource TEXT NOT NULL,
+                updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (client, group_idx, resource)
+            )
+            """
+        )
+        self._conn.commit()
+
+    def owner_of(self, resource: str) -> str | None:
+        row = self._conn.execute(
+            "SELECT owner FROM ownership WHERE resource = ?", (resource,)
+        ).fetchone()
+        if row is None:
+            return None
+        return str(row[0])
+
+    def acquire(self, resource: str, owner: str) -> bool:
+        current = self.owner_of(resource)
+        if current is None:
+            self._conn.execute(
+                "INSERT INTO ownership(resource, owner) VALUES(?, ?)", (resource, owner)
+            )
+            self._conn.commit()
+            return True
+        if current == owner:
+            return True
+        return False
+
+    def release(self, resource: str, owner: str) -> bool:
+        current = self.owner_of(resource)
+        if current != owner:
+            return False
+        self._conn.execute("DELETE FROM ownership WHERE resource = ?", (resource,))
+        self._conn.commit()
+        return True
+
+    def release_all_by_owner(self, owner: str) -> int:
+        cur = self._conn.execute("DELETE FROM ownership WHERE owner = ?", (owner,))
+        self._conn.commit()
+        return int(cur.rowcount)
+
+    def set_link_groups(self, client: str, groups: list[list[str]]) -> int:
+        """Replace all link groups registered by a client.
+
+        Groups persist across client disconnects so a server-side watchdog
+        can keep protecting them while the client application is closed.
+        """
+        self._conn.execute("DELETE FROM link_groups WHERE client = ?", (client,))
+        count = 0
+        for idx, group in enumerate(groups):
+            members = sorted({str(resource) for resource in group})
+            if len(members) < 2:
+                continue
+            for resource in members:
+                self._conn.execute(
+                    "INSERT OR REPLACE INTO link_groups(client, group_idx, resource) VALUES(?, ?, ?)",
+                    (client, idx, resource),
+                )
+            count += 1
+        self._conn.commit()
+        return count
+
+    def link_groups_by_idx(self) -> dict[str, dict[int, list[str]]]:
+        rows = self._conn.execute(
+            "SELECT client, group_idx, resource FROM link_groups ORDER BY client, group_idx, resource"
+        ).fetchall()
+        grouped: dict[str, dict[int, list[str]]] = {}
+        for client, group_idx, resource in rows:
+            grouped.setdefault(str(client), {}).setdefault(int(group_idx), []).append(str(resource))
+        return grouped
+
+    def all_link_groups(self) -> dict[str, list[list[str]]]:
+        return {
+            client: [members for _idx, members in sorted(groups.items())]
+            for client, groups in self.link_groups_by_idx().items()
+        }
+
+    def remove_link_group(self, client: str, group_idx: int) -> int:
+        cur = self._conn.execute(
+            "DELETE FROM link_groups WHERE client = ? AND group_idx = ?",
+            (client, int(group_idx)),
+        )
+        self._conn.commit()
+        return int(cur.rowcount)
+
+    def close(self) -> None:
+        self._conn.close()

devman_runtime-0.1.0/src/devman_runtime/protocol.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from enum import Enum
+import json
+import socket
+import struct
+from typing import Any
+
+
+class ProtocolError(RuntimeError):
+    pass
+
+
+def _json_default(value: Any) -> Any:
+    if is_dataclass(value):
+        return asdict(value)
+    if isinstance(value, Enum):
+        return value.name
+    if isinstance(value, (bytes, bytearray)):
+        return value.decode("utf-8", errors="replace")
+    if hasattr(value, "__dict__"):
+        return vars(value)
+    return str(value)
+
+
+def send_message(sock: socket.socket, payload: dict[str, Any]) -> None:
+    body = json.dumps(payload, default=_json_default, separators=(",", ":")).encode("utf-8")
+    sock.sendall(struct.pack("!I", len(body)))
+    sock.sendall(body)
+
+
+def _recv_exact(sock: socket.socket, size: int) -> bytes:
+    chunks: list[bytes] = []
+    remaining = size
+    while remaining > 0:
+        chunk = sock.recv(remaining)
+        if not chunk:
+            raise ProtocolError("unexpected EOF while reading message")
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+def recv_message(sock: socket.socket) -> dict[str, Any]:
+    header = _recv_exact(sock, 4)
+    (size,) = struct.unpack("!I", header)
+    raw = _recv_exact(sock, size)
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ProtocolError(f"invalid message JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ProtocolError("message must be a JSON object")
+    return data