moat-link-notify 0.0.1__tar.gz

moat_link_notify-0.0.1/LICENSE.txt

@@ -0,0 +1,14 @@
+The code in this repository, and all MoaT submodules it refers to,
+is part of the MoaT project.
+
+Unless a submodule's LICENSE.txt states otherwise, all included files are
+licensed under the LGPL V3, as published by the FSF at
+https://www.gnu.org/licenses/lgpl-3.0.html .
+
+In addition to the LGPL's terms, the author(s) respectfully ask all users of
+this code to contribute any bug fixes or enhancements. Also, please link back to
+https://M-o-a-T.org.
+
+Thank you.
+
+Copyright © 2021 ff.: the MoaT contributor(s), as per the git changelog(s).

moat_link_notify-0.0.1/Makefile

@@ -0,0 +1,20 @@
+#!/usr/bin/make -f
+
+PACKAGE = moat-link-notify
+MAKEINCL ?= $(shell python3 -mmoat src path)/make/py
+
+install: installsystemd
+
+installsystemd:
+	mkdir -p $(PREFIX)/lib/systemd/system
+	cp systemd/*.service $(PREFIX)/lib/systemd/system/
+
+ifneq ($(wildcard $(MAKEINCL)),)
+include $(MAKEINCL)
+# availabe via http://github.com/smurfix/sourcemgr
+
+else
+%:
+	@echo "Please fix 'python3 -mmoat src path'."
+	@exit 1
+endif

moat_link_notify-0.0.1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: moat-link-notify
+Version: 0.0.1
+Summary: Notification gateway for MoaT-Link
+Author-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AnyIO
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.2
+Requires-Dist: asyncclick
+Requires-Dist: attrs
+Requires-Dist: httpx
+Requires-Dist: moat-util~=0.62.2
+Requires-Dist: moat-link~=0.2.46
+Dynamic: license-file
+
+# moat-link-notify
+
+Notification gateway for MoaT-Link.
+
+This package provides notification services for MoaT-Link, allowing you to send
+notifications to external services like ntfy.sh.
+
+## Installation
+
+```bash
+pip install moat-link-notify
+```
+
+## Usage
+
+The notification gateway can be configured through MoaT-Link's configuration system.
+
+## Dependencies
+
+- moat-link: Core MoaT-Link functionality
+- httpx: HTTP client for notification delivery
+
+## License
+
+This project is licensed under the same terms as MoaT.

moat_link_notify-0.0.1/README.md

@@ -0,0 +1,25 @@
+# moat-link-notify
+
+Notification gateway for MoaT-Link.
+
+This package provides notification services for MoaT-Link, allowing you to send
+notifications to external services like ntfy.sh.
+
+## Installation
+
+```bash
+pip install moat-link-notify
+```
+
+## Usage
+
+The notification gateway can be configured through MoaT-Link's configuration system.
+
+## Dependencies
+
+- moat-link: Core MoaT-Link functionality
+- httpx: HTTP client for notification delivery
+
+## License
+
+This project is licensed under the same terms as MoaT.

moat_link_notify-0.0.1/debian/.gitignore

@@ -0,0 +1,6 @@
+*.debhelper
+*.substvars
+files
+.debhelper/
+moat-link-notify/
+debhelper-build-stamp

moat_link_notify-0.0.1/debian/changelog

@@ -0,0 +1,11 @@
+moat-link-notify (0.0.1-2) unstable; urgency=medium
+
+  * New release for 25.8.6
+
+ -- Matthias Urlichs <matthias@urlichs.de>  Mon, 05 Jan 2026 16:50:07 +0100
+
+moat-link-notify (0.0.0-0) unstable; urgency=medium
+
+  * Initial release as separate package
+
+ -- Matthias Urlichs <matthias@urlichs.de>  Sun, 05 Jan 2025 13:00:00 +0100

moat_link_notify-0.0.1/debian/control

@@ -0,0 +1,26 @@
+Source: moat-link-notify
+Maintainer: Matthias Urlichs <matthias@urlichs.de>
+Section: python
+Priority: optional
+Build-Depends: dh-python, python3-all, debhelper (>= 13),
+  python3-setuptools,
+  python3-wheel,
+  moat-src,
+Standards-Version: 3.9.6
+Homepage: https://github.com/smurfix/moat
+X-DH-Compat: 13
+
+Package: moat-link-notify
+Architecture: all
+Depends: ${misc:Depends}, ${python3:Depends},
+  moat-util,
+  moat-link,
+  python3-httpx,
+  systemd (>= 241),
+Recommends:
+  python3-trio (>= 0.22),
+Description: Notification gateway for MoaT-Link
+ This package provides notification services for MoaT-Link, allowing you to
+ send notifications to external services like ntfy.sh.
+ .
+ Part of the MoaT ecosystem for distributed home automation.

moat_link_notify-0.0.1/debian/moat-link-notify.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=MoaT-Link Notification Forwarder
+
+ConditionFileNotEmpty=/etc/moat/moat.cfg
+
+[Install]
+WantedBy=multi-user.target
+
+[Service]
+Type=notify
+ExecStart=/usr/bin/moat link notify run
+
+RuntimeDirectory=moat/link
+
+User=MoaT-Link
+Group=MoaT
+
+EnvironmentFile=/usr/lib/moat/link/env
+EnvironmentFile=-/etc/moat/link.env
+
+TimeoutSec=300
+WatchdogSec=10
+Restart=always

moat_link_notify-0.0.1/debian/rules

@@ -0,0 +1,8 @@
+#!/usr/bin/make -f
+
+export PYBUILD_NAME=moat-link-notify
+%:
+	dh $@ --with python3 --buildsystem=pybuild
+
+execute_after_dh_install:
+	$(MAKE) installsystemd PREFIX=debian/moat-link-notify

moat_link_notify-0.0.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [ "setuptools", "wheel",]
+
+[project]
+classifiers = [
+	"Intended Audience :: Developers",
+	"Programming Language :: Python :: 3",
+	"Framework :: AsyncIO",
+	"Framework :: Trio",
+	"Framework :: AnyIO",
+	"Development Status :: 4 - Beta",
+	]
+dependencies = [
+	"anyio ~= 4.2",
+	"asyncclick",
+	"attrs",
+	"httpx",
+	"moat-util ~= 0.62.2",
+	"moat-link ~= 0.2.46",
+	]
+version = "0.0.1"
+keywords = [ "MoaT",]
+requires-python = ">=3.8"
+name = "moat-link-notify"
+description = "Notification gateway for MoaT-Link"
+readme = "README.md"
+
+[[project.authors]]
+name = "Matthias Urlichs"
+email = "matthias@urlichs.de"
+
+[project.urls]
+homepage = "https://m-o-a-t.org"
+repository = "https://github.com/M-o-a-T/moat"
+
+[tool.setuptools]
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.yaml"]

moat_link_notify-0.0.1/setup.cfg

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

moat_link_notify-0.0.1/src/moat/link/notify/__init__.py

@@ -0,0 +1,227 @@
+"""
+Notification package
+"""
+
+from __future__ import annotations
+
+import anyio
+import logging
+import time
+from abc import ABCMeta, abstractmethod
+from contextlib import AsyncExitStack, asynccontextmanager
+
+from moat.util import CtxObj, NotGiven, P, Path, as_service, attrdict
+from moat.lib.priomap import PrioMap
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from moat.link.client import Link
+
+    from collections.abc import AsyncIterator
+    from typing import NoReturn, Self
+
+__all__ = ["Notifier", "Notify", "get_backend"]
+
+logger = logging.getLogger(__name__)
+
+
+class Notify:
+    """
+    Notification runner.
+    """
+
+    link: Link
+
+    def __init__(self, cfg):
+        self.cfg = cfg
+        self.dropped: PrioMap[Notifier] = PrioMap()
+
+    async def run(self, link: Link, evt: anyio.Event | None = None):
+        """
+        Task that reads notifications from MoaT-Link and posts them.
+        """
+        self.link = link
+        async with AsyncExitStack() as ex:
+            backend = self.cfg.backend
+            if isinstance(backend, str):
+                backend = (backend,)
+
+            self._backends = {}
+            for name in backend:
+                cfg = self.cfg.get(name, attrdict())
+                try:
+                    notifier = await ex.enter_async_context(get_backend(name, link, cfg))
+                except Exception as exc:
+                    logger.warning("Backend %r", name, exc_info=exc)
+                else:
+                    self._backends[name] = notifier
+
+            if not self._backends:
+                raise RuntimeError("No backend worked.")
+
+            try:
+                await self._run(evt)
+            finally:
+                with anyio.move_on_after(2, shield=True):
+                    await self.send(
+                        topic="error.notify",
+                        title="Backend stopped",
+                        msg="The backend terminated.",
+                        prio="fatal",
+                    )
+
+    async def send(self, **kw) -> None:
+        """Send this notification to that topic."""
+        # reactivate dropped items
+        tm = time.monotonic()
+        retry: set[Notifier] = set()
+        error_seen = False
+
+        # Collect failed backends for retrying
+        while self.dropped:
+            b_e, t = self.dropped.peek()
+            if t > tm:
+                break
+            del self.dropped[b_e]
+            retry.add(b_e)
+
+        for name, b_e in list(self._backends.items()):
+            if b_e in self.dropped:
+                continue
+            try:
+                await b_e.send(**kw)
+            except Exception as exc:
+                # Log failed backends only once
+                if b_e in self.dropped:
+                    continue
+                error_seen = True
+
+                self.dropped[b_e] = tm + self.cfg.timeout.retry
+                await self.link.e_exc(
+                    P("run.notify.backend") / name,
+                    exc,
+                    msg=f"The notification backend {name} failed.",
+                    val=kw,
+                    level=3,
+                )
+            else:
+                if b_e in retry:
+                    # No lock because this can only happen in one branch
+                    await self.link.e_ok(P("run.notify.backend") / name)
+
+        if len(self.dropped) >= len(self._backends):
+            # This might conceivably happen in more than one branch
+            # if more than one backend fails at a time, but we don't care
+            if error_seen:
+                await self.link.e_info(
+                    P("run.notify.backend"), "All notification backends failed.", level=4
+                )
+        elif any(x not in self.dropped for x in retry):
+            await self.link.e_ok(P("run.notify.backend"))
+
+    async def _run(self, evt) -> NoReturn:
+        """
+        A bridge that monitors the MoaT-Link notify subtree.
+        """
+        async with as_service(attrdict(debug=False)) as srv:
+            try:
+                await srv.tg.start(self._keepalive)
+
+                async with self.link.d_watch(
+                    self.cfg.path, subtree=True, meta=True, state=None
+                ) as mon:
+                    srv.set()
+                    if evt is not None:
+                        evt.set()
+                    async for path, msg, meta in mon:
+                        t = time.time()
+                        if meta.timestamp < t - self.cfg.max_age:
+                            continue
+                        if isinstance(msg, NotGiven):
+                            # Treat as empty message, for now
+                            msg = {"msg": "Deleted"}  # noqa:PLW2901
+                        if isinstance(msg, dict):
+                            if "title" not in msg:
+                                msg["title"] = str(path)
+                            await self.send(topic=path, **msg)
+                        else:
+                            await self.send(topic=path, title="?", msg=str(msg))
+
+                    # not reached, loop doesn't terminate
+
+            except Exception as exc:
+                await self.send(
+                    topic=P("error.notify"), msg=repr(exc), prio="error", title="Gateway failure"
+                )
+                raise
+
+    async def _keepalive(self, *, task_status=anyio.TASK_STATUS_IGNORED) -> NoReturn:
+        "Monitor the keepalive topic"
+        bad = True
+        link = self.link
+        keep = self.cfg.keepalive
+        ok_keep = keep.ok
+
+        timeout = keep.get("timeout", link.cfg.timeout.ping.timeout)
+
+        # The main host watcher publishes on the empty path
+        async with link.d_watch(P("run.host"), state=None) as mon:
+            task_status.started()
+            mon = aiter(mon)  # noqa:PLW2901
+            while True:
+                if bad:
+                    msg = await anext(mon)
+                else:
+                    try:
+                        with anyio.fail_after(timeout):
+                            msg = await anext(mon)
+                    except TimeoutError:
+                        msg = None
+
+                if isinstance(msg, dict) and "id" in msg:
+                    async with link.d_watch(P("run.ping.id") / msg["id"]) as mon2:
+                        mon2 = aiter(mon2)  # noqa:PLW2901
+                        while True:
+                            try:
+                                with anyio.fail_after(timeout):
+                                    msg = await anext(mon2)
+                                    if not msg.get("up", False):
+                                        break
+                                    if bad and "msg" in ok_keep:
+                                        await self.send(topic="error.notify", **ok_keep)
+                                        bad = False
+                            except TimeoutError:
+                                break
+
+                await self.send(topic="error.notify", **keep)
+                bad = True
+
+
+def get_backend(name: str, link: Link, cfg: dict) -> Notify:
+    """
+    Fetch the backend named in the config and initialize it.
+    """
+    from importlib import import_module  # noqa: PLC0415
+
+    if "." not in name:
+        name = "moat.link.notify." + name
+    return import_module(name).Notifier(link, cfg)
+
+
+class Notifier(CtxObj, metaclass=ABCMeta):
+    "Base class for notification backends"
+
+    def __init__(self, link: Link, cfg: attrdict):
+        self.cfg = cfg
+        self.link = link
+
+    @asynccontextmanager
+    async def _ctx(self) -> AsyncIterator[Self]:
+        yield self
+
+    @abstractmethod
+    async def send(
+        self, topic: str | Path, title: str | None = None, msg: str | None = None, **kw
+    ):
+        """Send this notification to that topic."""

moat_link_notify-0.0.1/src/moat/link/notify/_cfg.yaml

@@ -0,0 +1,32 @@
+# Notifications are messages below :R.notify.TOPIC topic.
+keepalive:
+  # timeout: 30  # default: ping *1.5
+  #
+  # topic: my_secret_topic
+  title: Server Link down?
+  msg: |
+    The MoaT system at 'some_host' is silent. (MQTT-Keepalive)
+  prio: fatal
+  ok:
+    title: Server Link OK
+    msg: |
+      The MoaT system at 'some_host' is back up. (MQTT-Keepalive)
+    prio: info
+
+timeout:
+  retry: 300
+
+path: !P notify
+# ignore messages older than … seconds
+max_age: 30
+
+# Backends
+backend:
+  - ntfy
+ntfy:
+  # See https://docs.nfty.sh/
+
+  url: https://ntfy.sh.example/
+  # token: tk_whatever
+  # messages are posted to notify.TOPIC.WHATEVER if "topic" is not set
+  # topic: my_secret_topic

moat_link_notify-0.0.1/src/moat/link/notify/_main.py

@@ -0,0 +1,37 @@
+# command line interface
+from __future__ import annotations
+
+import asyncclick as click
+
+from moat.link.announce import announcing
+from moat.link.client import Link
+
+
+@click.group(short_help="Manage notifications.")  # pylint: disable=undefined-variable
+@click.pass_context
+async def cli(ctx):
+    """
+    Handle notifications.
+    """
+    obj = ctx.obj
+    cfg = obj.cfg["link"]
+    obj.conn = await ctx.with_async_resource(Link(cfg))
+
+
+@cli.command()
+@click.option("-b", "--backend", type=str, multiple=True, help="Restrict to this backend")
+@click.pass_obj
+async def run(obj, backend):
+    """
+    Forward notification messages.
+
+    This command monitors the 'notify' subpath and forwards messages to
+    your ntfy.sh instance.
+    """
+    from moat.link.notify import Notify  # noqa: PLC0415
+
+    cfg = obj.cfg.link.notify
+    if backend:
+        cfg.backends = backend
+    async with announcing(obj.conn) as ann:
+        await Notify(cfg).run(obj.conn, evt=ann)

moat_link_notify-0.0.1/src/moat/link/notify/ntfy.py

@@ -0,0 +1,86 @@
+"""
+This module forwards notifications to NTFY.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+
+import httpx
+
+from moat.util import P, Path
+
+from . import Notifier as BaseNotifier
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = ["Notifier"]
+
+prio_map = {
+    "debug": 1,
+    "info": 2,
+    "warning": 3,
+    "error": 4,
+    "fatal": 5,
+}
+
+
+class Notifier(BaseNotifier):  # noqa:D101
+    @asynccontextmanager
+    async def _ctx(self):
+        async with (
+            super()._ctx(),
+            httpx.AsyncClient() as self.http,
+        ):
+            yield self
+
+    async def send(
+        self,
+        topic: str | Path,
+        title: str | None = None,
+        msg: str | None = None,
+        prio: str | None = None,
+        tags: Sequence[str] = (),
+        **kw,  # noqa: ARG002
+    ):
+        "Forward a message to NTFY"
+
+        if "topic" in self.cfg:
+            top = self.cfg.topic
+        else:
+            if isinstance(topic, str):
+                topic = P(topic)
+            try:
+                top = topic[0]
+            except IndexError:
+                top = "TOP"
+            else:
+                topic = Path.build(topic[1:])
+
+        url = self.cfg.url + "/" + top
+        tags = list(tags)
+        tags.append(str(topic))
+
+        hdr = {}
+
+        if title:
+            hdr["title"] = title
+        if prio is not None:
+            try:
+                prio = prio_map[prio]
+                hdr["prio"] = str(prio)
+                if prio > 3:
+                    tags.append("warning")
+            except KeyError:
+                hdr["prio"] = "high"
+                msg += f" (prio:{prio})"
+        hdr["tags"] = ",".join(str(x) for x in tags)
+
+        if "token" in self.cfg:
+            hdr["authorization"] = f"Bearer {self.cfg['token']}"
+
+        resp = await self.http.post(url, data=msg, headers=hdr)
+        resp.raise_for_status()

moat_link_notify-0.0.1/src/moat_link_notify.egg-info/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: moat-link-notify
+Version: 0.0.1
+Summary: Notification gateway for MoaT-Link
+Author-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AnyIO
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.2
+Requires-Dist: asyncclick
+Requires-Dist: attrs
+Requires-Dist: httpx
+Requires-Dist: moat-util~=0.62.2
+Requires-Dist: moat-link~=0.2.46
+Dynamic: license-file
+
+# moat-link-notify
+
+Notification gateway for MoaT-Link.
+
+This package provides notification services for MoaT-Link, allowing you to send
+notifications to external services like ntfy.sh.
+
+## Installation
+
+```bash
+pip install moat-link-notify
+```
+
+## Usage
+
+The notification gateway can be configured through MoaT-Link's configuration system.
+
+## Dependencies
+
+- moat-link: Core MoaT-Link functionality
+- httpx: HTTP client for notification delivery
+
+## License
+
+This project is licensed under the same terms as MoaT.

moat_link_notify-0.0.1/src/moat_link_notify.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE.txt
+Makefile
+README.md
+pyproject.toml
+debian/.gitignore
+debian/changelog
+debian/control
+debian/moat-link-notify.service
+debian/rules
+src/moat/link/notify/__init__.py
+src/moat/link/notify/_cfg.yaml
+src/moat/link/notify/_main.py
+src/moat/link/notify/ntfy.py
+src/moat_link_notify.egg-info/PKG-INFO
+src/moat_link_notify.egg-info/SOURCES.txt
+src/moat_link_notify.egg-info/dependency_links.txt
+src/moat_link_notify.egg-info/requires.txt
+src/moat_link_notify.egg-info/top_level.txt
+systemd/moat-link-notify.service

moat_link_notify-0.0.1/src/moat_link_notify.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moat_link_notify-0.0.1/src/moat_link_notify.egg-info/requires.txt

@@ -0,0 +1,6 @@
+anyio~=4.2
+asyncclick
+attrs
+httpx
+moat-util~=0.62.2
+moat-link~=0.2.46

moat_link_notify-0.0.1/src/moat_link_notify.egg-info/top_level.txt

@@ -0,0 +1 @@
+moat

moat_link_notify-0.0.1/systemd/moat-link-notify.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=MoaT-Link Notification Forwarder
+
+ConditionFileNotEmpty=/etc/moat/moat.cfg
+
+[Install]
+WantedBy=multi-user.target
+
+[Service]
+Type=notify
+ExecStart=/usr/bin/moat link notify run
+
+RuntimeDirectory=moat/link
+
+User=MoaT-Link
+Group=MoaT
+
+EnvironmentFile=/usr/lib/moat/link/env
+EnvironmentFile=-/etc/moat/link.env
+
+TimeoutSec=300
+WatchdogSec=10
+Restart=always