From 51ceb9177dc4f40f9343d468e44e73e182fd28fa Mon Sep 17 00:00:00 2001
From: Catubba <40827997+catubba@users.noreply.github.com>
Date: Thu, 9 Jul 2026 19:55:27 +0200
Subject: [PATCH] docs(notify): tie the thread filter to the one-URL-per-engine
 invariant

The capture only sees the real failure reason because Apprise dispatches a
single server in the calling thread. Nothing enforced that link; a future
change batching URLs into one engine would silently blank every reason.
---
 backend/app/notify/service.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/backend/app/notify/service.py b/backend/app/notify/service.py
index a83e7ad..92915b6 100644
--- a/backend/app/notify/service.py
+++ b/backend/app/notify/service.py
@@ -67,6 +67,12 @@ class _LogCapture(logging.Handler):
     one send's failure reason from being attributed to the other's channel — do not remove
     this check as an unneeded "simplification", it is the only thing making capture
     thread-safe.
+
+    This relies on the plugin logging from the calling thread, which holds only because we
+    give each engine exactly one URL: Apprise dispatches a single server sequentially and
+    only reaches for its thread pool with two or more. Batch several URLs into one engine
+    and the reason would be logged off-thread, get dropped here, and every failure would
+    report no reason at all.
     """
 
     def __init__(self) -> None: