ser2netweb 3.0.0__py3-none-any.whl

ser2netweb/sdnotify.py

@@ -0,0 +1,85 @@
+"""systemd's notification protocol (sd_notify), standard library only.
+
+Under a unit with Type=notify (the optional drop-in systemd/ser2netweb.service.d/notify.conf)
+systemd waits for READY=1 before it counts ser2netweb as started, and with WatchdogSec= it
+restarts ser2netweb when the WATCHDOG=1 pings stop (they come from the event loop, so a
+loop that is stuck stops them). Everything here does nothing without $NOTIFY_SOCKET, so
+the default unit (Type=simple), Docker, Windows and a start by hand are not affected.
+"""
+from __future__ import annotations
+
+import os
+import socket
+import sys
+import time
+from typing import Mapping, Optional
+
+
+def _address(env: Mapping[str, str]) -> Optional[str]:
+    addr = env.get("NOTIFY_SOCKET") or ""
+    if not addr or not hasattr(socket, "AF_UNIX"):
+        return None
+    if addr.startswith("@"):  # an abstract socket (Linux)
+        return "\0" + addr[1:]
+    return addr if addr.startswith("/") else None
+
+
+def notify(*fields: str, env: Optional[Mapping[str, str]] = None) -> bool:
+    """Send ``fields`` ("READY=1", "STATUS=..."), one per line, to systemd. True when sent;
+    False without $NOTIFY_SOCKET or when it can't be (never raises). It never waits: this
+    runs on the event loop, and a socket whose queue is full (nobody reads it) would hold
+    it up; that message is lost instead."""
+    addr = _address(os.environ if env is None else env)
+    if addr is None or sys.platform == "win32":  # (no systemd there)
+        return False
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as s:
+            s.setblocking(False)
+            s.connect(addr)
+            s.sendall("\n".join(fields).encode("utf-8", "replace"))
+    except OSError:
+        return False
+    return True
+
+
+def ready(status: str = "", env: Optional[Mapping[str, str]] = None) -> bool:
+    """ser2netweb has started: its mappings run and its admin UI listens."""
+    return notify("READY=1", *([f"STATUS={status}"] if status else []), env=env)
+
+
+def reloading(env: Optional[Mapping[str, str]] = None) -> bool:
+    """ser2netweb reads config.json again (systemctl reload, SIGHUP); ready() follows when it
+    is done (also what Type=notify-reload waits for)."""
+    fields = ["RELOADING=1"]
+    if sys.platform != "win32":  # (no CLOCK_MONOTONIC on Windows, which has no systemd)
+        try:
+            fields.append(f"MONOTONIC_USEC={time.clock_gettime_ns(time.CLOCK_MONOTONIC) // 1000}")
+        except (AttributeError, OSError):
+            pass
+    return notify(*fields, env=env)
+
+
+def stopping(env: Optional[Mapping[str, str]] = None) -> bool:
+    return notify("STOPPING=1", env=env)
+
+
+def watchdog(env: Optional[Mapping[str, str]] = None) -> bool:
+    return notify("WATCHDOG=1", env=env)
+
+
+def watchdog_interval(env: Optional[Mapping[str, str]] = None) -> Optional[float]:
+    """How often to send WATCHDOG=1 (half of WatchdogSec=, as systemd advises), or None
+    when systemd doesn't watch this process."""
+    env = os.environ if env is None else env
+    if _address(env) is None:
+        return None
+    # meant for this process: its pid, or its parent's when that is the standalone
+    # binary's launcher, which runs ser2netweb in a child process (NotifyAccess=all)
+    pid = (env.get("WATCHDOG_PID") or "").strip()
+    if pid and pid not in (str(os.getpid()), str(os.getppid())):
+        return None
+    try:
+        usec = int((env.get("WATCHDOG_USEC") or "").strip())
+    except ValueError:
+        return None
+    return usec / 2e6 if usec > 0 else None