Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(notifications): map delivery failures to webhook_failed, invalid URLs to invalid_url (#5113)

LearningCircuit985f752d7059
diff --git a/changelog.d/5110.bugfix.md b/changelog.d/5110.bugfix.md
new file mode 100644
index 0000000000..ddc2562a01
--- /dev/null
+++ b/changelog.d/5110.bugfix.md
@@ -0,0 +1,11 @@
+Notification drop reasons are now accurate for delivery failures: a
+webhook that actually fails (dead endpoint, HTTP error, network down)
+is reported as `webhook_failed` instead of the generic `exception`,
+and a service URL rejected before dispatch (unparseable, or blocked
+by URL security validation) is reported as the new `invalid_url`
+reason. `egress_denied` details now distinguish "policy refused every
+URL" from "policy could not be evaluated" (including in the
+test-notification endpoint), and the `server_disabled` detail no
+longer claims the env var "is not set" when it is explicitly
+disabled. `NotificationResult`/`NotificationReason` are exported from
+the `notifications` package.
diff --git a/docs/NOTIFICATIONS.md b/docs/NOTIFICATIONS.md
index 77d40b4c89..fb04347461 100644
--- a/docs/NOTIFICATIONS.md
+++ b/docs/NOTIFICATIONS.md
@@ -14,7 +14,7 @@ The notification system uses [Apprise](https://github.com/caronc/apprise) to sup
> LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true
> ```
>
-> Without this, every `send_notification` call returns `False` and the "Send Test Notification" button returns an error. This applies to **all** users on the deployment.
+> Without this, every `send_notification` call returns a falsy `NotificationResult` (`reason=server_disabled`) and the "Send Test Notification" button returns an error. This applies to **all** users on the deployment.
### Why?
diff --git a/docs/NOTIFICATION_FLOW.md b/docs/NOTIFICATION_FLOW.md
index 2c9483ff9f..22a3fab69f 100644
--- a/docs/NOTIFICATION_FLOW.md
+++ b/docs/NOTIFICATION_FLOW.md
@@ -120,25 +120,25 @@ def _send_research_notification(
- **Context Building**: Includes query, research_id, summary (truncated to 200 chars), full URL
- **No Session Passed**: NotificationManager gets `settings_snapshot`, NOT session (thread-safe)
-### 5. NotificationManager Checks Settings (`manager.py:91-126`)
+### 5. NotificationManager Checks Settings (`manager.py`)
```python
-# src/local_deep_research/notifications/manager.py:91-126
+# src/local_deep_research/notifications/manager.py (simplified)
def send_notification(
self,
event_type: EventType,
context: Dict[str, Any],
- user_id: Optional[str] = None,
force: bool = False,
-) -> bool:
+) -> NotificationResult:
# Check if notifications are enabled for this event type
- should_notify = self._should_notify(event_type, user_id)
+ should_notify = self._should_notify(event_type)
if not force and not should_notify:
- logger.debug(f"Notifications disabled for event type: {event_type.value}")
- return False
+ return NotificationResult(
+ sent=False, reason=NotificationReason.EVENT_DISABLED, detail="..."
+ )
# Check rate limit
- rate_limit_ok = self._rate_limiter.allow(user_id or "default")
+ rate_limit_ok = self._rate_limiter.is_allowed(self._user_id)
if not force and not rate_limit_ok:
raise RateLimitError("Notification rate limit exceeded")
@@ -146,15 +146,24 @@ def send_notification(
service_urls = self._get_setting("notifications.service_url", default="")
if not service_urls or not service_urls.strip():
- logger.debug("No notification service URLs configured")
- return False
+ return NotificationResult(
+ sent=False, reason=NotificationReason.UNCONFIGURED, detail="..."
+ )
- # Send notification with service URLs
- result = self.service.send_event(event_type, context, service_urls=service_urls)
+ # Send notification with service URLs (egress-filtered)
+ sent = self.service.send_event(event_type, context, service_urls=service_urls)
- return result
+ return NotificationResult(sent=sent, reason=..., detail=...)
```
+`send_notification` returns a `NotificationResult` dataclass (`sent`,
+`reason`, `detail`). It is truthy iff the notification was sent, so
+`if manager.send_notification(...):` keeps working. `reason` is a
+`NotificationReason` enum: `sent`, `server_disabled`, `event_disabled`,
+`unconfigured`, `egress_denied`, `invalid_url` (URL rejected before
+dispatch — unparseable, or blocked by URL security validation),
+`webhook_failed` (delivery failed after retries), or `exception`.
+
**Settings Checked (from `settings_snapshot`):**
1. **`notifications.on_research_completed`** - Is this event type enabled? (default: False for most events)
2. **Per-User Rate Limits** - Check shared rate limiter with user-specific limits:
@@ -493,7 +502,7 @@ except SendError as e:
```python
result = notification_manager.send_notification(...)
-# Returns: False (no error raised)
+# Returns: falsy NotificationResult (reason=unconfigured, no error raised)
# Log: "No notification service URLs configured for user {user_id}"
```
diff --git a/src/local_deep_research/error_handling/error_reporter.py b/src/local_deep_research/error_handling/error_reporter.py
index 585e69d179..be3c4b4001 100644
--- a/src/local_deep_research/error_handling/error_reporter.py
+++ b/src/local_deep_research/error_handling/error_reporter.py
@@ -350,7 +350,8 @@ class ErrorReporter:
)
detail = getattr(result, "detail", "") or ""
if reason_value is None:
- reason_value = "dropped" if not bool(result) else "sent"
+ # Legacy bool-returning mocks/callers carry no reason.
+ reason_value = "dropped"
message = (
f"{reason_value}: {detail}" if detail else reason_value
)
diff --git a/src/local_deep_research/notifications/__init__.py b/src/local_deep_research/notifications/__init__.py
index 595e4dfee9..33bbf251e0 100644
--- a/src/local_deep_research/notifications/__init__.py
+++ b/src/local_deep_research/notifications/__init__.py
@@ -15,7 +15,11 @@ from .exceptions import (
RateLimitError,
)
from .service import NotificationService
-from .manager import NotificationManager
+from .manager import (
+ NotificationManager,
+ NotificationReason,
+ NotificationResult,
+)
from .templates import NotificationTemplate, EventType
from .url_builder import build_notification_url
from ..security.url_validator import URLValidator, URLValidationError
@@ -34,6 +38,8 @@ __all__ = [
"RateLimitError",
"NotificationService",
"NotificationManager",
+ "NotificationReason",
+ "NotificationResult",
"NotificationTemplate",
"EventType",
"build_notification_url",
diff --git a/src/local_deep_research/notifications/exceptions.py b/src/local_deep_research/notifications/exceptions.py
index 1edc27b9d8..e5c4e4d0f1 100644
--- a/src/local_deep_research/notifications/exceptions.py
+++ b/src/local_deep_research/notifications/exceptions.py
@@ -15,6 +15,22 @@ class ServiceError(NotificationError):
pass
+class SecurityBlockError(ServiceError):
+ """A confirmed send-time SSRF/DNS-rebind block.
+
+ Raised instead of the plain ``ServiceError`` used for pre-dispatch URL
+ validation rejects. It is a ``ServiceError`` subclass so every existing
+ ``except ServiceError`` / ``pytest.raises(ServiceError)`` still catches
+ it and the non-transient INVALID_URL classification is unchanged — this
+ subclass exists only so callers that want to tell "malformed/blocked
+ URL at validation time" apart from "destination confirmed hostile at
+ send time" (e.g. to pick a more accurate user-facing message) can do so
+ without parsing exception text.
+ """
+
+ pass
+
+
class SendError(NotificationError):
"""Error occurred while sending a notification."""
diff --git a/src/local_deep_research/notifications/manager.py b/src/local_deep_research/notifications/manager.py
index 397563c66d..bc2363967b 100644
--- a/src/local_deep_research/notifications/manager.py
+++ b/src/local_deep_research/notifications/manager.py
@@ -16,7 +16,12 @@ from ..security.ssrf_validator import redact_url_for_log
from ..settings.env_registry import get_env_setting
from .service import NotificationService
from .templates import EventType
-from .exceptions import RateLimitError
+from .exceptions import (
+ RateLimitError,
+ SendError,
+ ServiceError,
+ SecurityBlockError,
+)
from ..utilities.type_utils import unwrap_setting
from ..constants import DEFAULT_SEARCH_TOOL
@@ -38,6 +43,7 @@ class NotificationReason(str, Enum):
EVENT_DISABLED = "event_disabled"
UNCONFIGURED = "unconfigured"
EGRESS_DENIED = "egress_denied"
+ INVALID_URL = "invalid_url"
WEBHOOK_FAILED = "webhook_failed"
EXCEPTION = "exception"
@@ -262,7 +268,10 @@ class NotificationManager:
return NotificationResult(
sent=False,
reason=NotificationReason.SERVER_DISABLED,
- detail="LDR_NOTIFICATIONS_ALLOW_OUTBOUND is not set",
+ detail=(
+ "outbound notifications are disabled at the server "
+ "level (LDR_NOTIFICATIONS_ALLOW_OUTBOUND)"
+ ),
)
# Check if notifications are enabled for this event type
@@ -317,15 +326,24 @@ class NotificationManager:
# scopes pass plugin schemes to the service's URL validator.
allowed_urls = self._filter_urls_by_egress_policy(service_urls)
if not allowed_urls:
+ # Distinguish "the policy was evaluated and refused every
+ # URL" (empty string) from "the policy itself could not be
+ # evaluated and we failed closed" (None) so the operator
+ # fixes the right thing — see issue #5110.
+ if allowed_urls is None:
+ detail = "egress policy could not be evaluated"
+ else:
+ detail = "all configured URLs refused by egress policy"
logger.bind(policy_audit=True).warning(
- "all notification URLs refused by egress policy",
+ "notification dropped: {}",
+ detail,
user=self._user_id,
event=event_type.value,
)
return NotificationResult(
sent=False,
reason=NotificationReason.EGRESS_DENIED,
- detail="all configured URLs refused by egress policy",
+ detail=detail,
)
# Send notification with the allowed subset.
@@ -346,23 +364,107 @@ class NotificationManager:
reason=NotificationReason.SENT,
detail="",
)
+ # A falsy return from send_event means Apprise accepted none
+ # of the URLs (temp_apprise.add() failed — unparseable or
+ # unsupported scheme). Actual delivery failures raise
+ # SendError and are handled below — see issue #5110.
logger.warning(
f"Notification failed: {event_type.value} to user "
+ f"{self._user_id} — Apprise accepted none of the "
+ f"configured service URLs"
+ )
+ return NotificationResult(
+ sent=False,
+ reason=NotificationReason.INVALID_URL,
+ detail="Apprise accepted none of the configured service URLs",
+ )
+
+ except SendError:
+ # The delivery layer raises SendError ONLY from
+ # _send_with_retry's own terminal raise once all retries are
+ # exhausted (dead webhook, HTTP 4xx/5xx, network down) — a
+ # transient, worth-retrying failure. NotificationService.send()
+ # re-raises SendError unchanged (no re-wrapping) and does NOT
+ # launder incidental/unexpected dispatch-time exceptions into
+ # SendError — those fall through to the generic
+ # ``except Exception`` branch below and get the EXCEPTION
+ # reason instead, so this branch stays reserved for genuine
+ # delivery failures. It also specifically does NOT mean a
+ # confirmed SSRF/DNS-rebind block: NotificationService.send()
+ # routes that non-retryable case through ServiceError instead
+ # (see the except clause below) precisely so it is never
+ # mislabeled as a retryable webhook failure here. Keep the
+ # detail static — SendError's message wraps the underlying
+ # error, which may contain webhook URLs with embedded tokens.
+ logger.exception(
+ f"Webhook delivery failed for {event_type.value} to user "
f"{self._user_id}"
)
return NotificationResult(
sent=False,
reason=NotificationReason.WEBHOOK_FAILED,
- detail="Apprise dispatch returned False",
+ detail="webhook delivery failed after retries",
+ )
+
+ except SecurityBlockError:
+ # A ServiceError subclass NotificationService.send() raises
+ # specifically for a confirmed send-time SSRF/DNS-rebind block
+ # (destination resolved to an internal/private/metadata
+ # address after dispatch started) — as opposed to the plain
+ # ServiceError below, raised for a pre-dispatch validation
+ # reject. Both are permanent, invalid-destination outcomes
+ # that map to the same non-transient INVALID_URL reason, but
+ # this one gets a distinct detail: the generic "check your
+ # URL/settings" text below would misleadingly suggest a
+ # config mistake when the true cause is an active security
+ # block. Static detail — no URL or resolved IP — the
+ # exception message can echo parts of the URL.
+ logger.exception(
+ f"Notification destination blocked by SSRF/egress "
+ f"protection for {event_type.value} to user "
+ f"{self._user_id}"
+ )
+ return NotificationResult(
+ sent=False,
+ reason=NotificationReason.INVALID_URL,
+ detail=(
+ "notification destination blocked by egress/SSRF protection"
+ ),
+ )
+
+ except ServiceError:
+ # The service raises ServiceError when the URL security
+ # validator rejects a URL before any dispatch is attempted
+ # (structurally invalid URLs, or valid URLs whose destination
+ # is blocked, e.g. a LAN webhook without
+ # LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS). A confirmed send-time
+ # SSRF/DNS-rebind block is caught above as SecurityBlockError
+ # (a ServiceError subclass) before reaching this branch. The
+ # detail must not claim the URL itself is malformed. Static
+ # detail: the exception message can echo parts of the URL.
+ logger.exception(
+ f"Service URL rejected for {event_type.value} to user "
+ f"{self._user_id}"
+ )
+ return NotificationResult(
+ sent=False,
+ reason=NotificationReason.INVALID_URL,
+ detail=(
+ "service URL rejected by URL security validation "
+ "(for a private/LAN webhook, check "
+ "LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS)"
+ ),
)
except Exception as exc:
- # The exception string may contain webhook URLs with embedded
- # tokens, SMTP credentials, or payload content. Log the raw
- # exception for operators via logger.exception above, but only
- # expose the exception class name (and not the message) in the
- # structured result so downstream callers can't echo it into
- # logs or UI surfaces verbatim.
+ # Reached for unexpected failures anywhere in the block above
+ # (settings read, egress filtering, or dispatch). The exception
+ # string may contain webhook URLs with embedded tokens, SMTP
+ # credentials, or payload content. Log the raw exception for
+ # operators via logger.exception, but only expose the exception
+ # class name (and not the message) in the structured result so
+ # downstream callers can't echo it into logs or UI surfaces
+ # verbatim.
logger.exception(
f"Error sending notification for {event_type.value} to user "
f"{self._user_id}"
@@ -370,7 +472,7 @@ class NotificationManager:
return NotificationResult(
sent=False,
reason=NotificationReason.EXCEPTION,
- detail=f"dispatch raised {type(exc).__name__}",
+ detail=f"unexpected {type(exc).__name__} while sending",
)
def test_service(self, url: str) -> Dict[str, Any]:
@@ -386,6 +488,16 @@ class NotificationManager:
# Egress policy precheck before forwarding to Apprise.
# /api/notifications/test-url is a user-supplied URL endpoint.
allowed = self._filter_urls_by_egress_policy(url)
+ if allowed is None:
+ # Fail-closed: the policy could not be evaluated at all, so
+ # don't tell the user their scope refused the URL.
+ return {
+ "status": "error",
+ "message": (
+ "Egress policy could not be evaluated; check the "
+ "egress policy settings (policy.egress_scope)."
+ ),
+ }
if not allowed:
return {
"status": "error",
@@ -396,12 +508,16 @@ class NotificationManager:
}
return self.service.test_service(allowed)
- def _filter_urls_by_egress_policy(self, service_urls: str) -> str:
+ def _filter_urls_by_egress_policy(self, service_urls: str) -> Optional[str]:
"""Filter an Apprise URL string by the user's egress policy.
Commas inside one service URL are preserved; commas or whitespace
- followed by another scheme delimit URLs. When no snapshot / context is
- available, return the input unchanged for backwards compatibility.
+ followed by another scheme delimit URLs. Returns the joined string
+ of allowed URLs (may be empty — every URL was refused), or ``None``
+ when the policy itself could not be evaluated and we failed closed.
+ Both are falsy; callers that care why nothing was allowed check for
+ ``None``. When no snapshot / context is available, returns the
+ input unchanged for backwards compatibility.
"""
snapshot = getattr(self, "_settings_snapshot", None)
if not snapshot:
@@ -453,7 +569,7 @@ class NotificationManager:
"not be evaluated",
reason=str(exc),
)
- return ""
+ return None
# Apprise accepts space- or comma-separated URLs and has non-HTTP
# schemes (discord://, slack://, tgram://, mailto://, msteams://,
diff --git a/src/local_deep_research/notifications/queue_helpers.py b/src/local_deep_research/notifications/queue_helpers.py
index 82b2b09a7c..7fc6a53afc 100644
--- a/src/local_deep_research/notifications/queue_helpers.py
+++ b/src/local_deep_research/notifications/queue_helpers.py
@@ -70,6 +70,11 @@ def send_queue_notification(
context=context,
)
if not result:
+ # DEBUG on purpose: notifications.on_research_queued defaults
+ # to off, so this drop is the steady state for every queued
+ # research — WARNING here would spam once per submission.
+ # Actionable causes (server gate, delivery failure) already
+ # WARN inside send_notification itself.
logger.debug(
f"Queue notification not sent for {research_id} "
f"{_format_reason(result)}"
@@ -131,6 +136,10 @@ def send_queue_failed_notification(
context=context,
)
if not result:
+ # DEBUG on purpose: the from_session wrapper around this
+ # helper already emits its own WARNING on a falsy return, so
+ # a WARNING here would double-log every drop. The reason
+ # string is still available at debug level.
logger.debug(
f"Failed-notification not sent for {research_id} "
f"{_format_reason(result)}"
diff --git a/src/local_deep_research/notifications/service.py b/src/local_deep_research/notifications/service.py
index 4562e593b1..4a9aa14986 100644
--- a/src/local_deep_research/notifications/service.py
+++ b/src/local_deep_research/notifications/service.py
@@ -17,7 +17,7 @@ from tenacity import (
retry_if_not_exception_type,
)
-from .exceptions import ServiceError, SendError
+from .exceptions import ServiceError, SendError, SecurityBlockError
from .apprise_log_utils import install_apprise_log_record_factory
from .templates import EventType, NotificationTemplate
from ..security import dns_pinning
@@ -178,17 +178,22 @@ class NotificationService:
``?redirect=yes`` cannot override the asset-level default.
Raises:
- RuntimeError: if either invariant is violated (excluded from
- Tenacity retries so it fails fast).
+ SecurityBlockError: if either invariant is violated — a
+ deliberate fail-closed security refusal, not an incidental
+ runtime error, so it is raised directly as this type
+ (rather than a generic ``RuntimeError`` a caller would have
+ to re-classify) and is excluded from Tenacity retries so it
+ fails fast. See ``send()``'s docstring for why this must
+ not be mistaken for a transient delivery failure.
"""
if getattr(apprise_instance.asset, "async_mode", True) is True:
- raise RuntimeError(
+ raise SecurityBlockError(
"Guarded notification send requires async_mode=False; "
"refusing to send (the thread-local DNS pin/block would not "
"apply to Apprise's worker-thread fan-out)."
)
if tag is not None:
- raise RuntimeError(
+ raise SecurityBlockError(
"Guarded notification send does not support tag targeting; "
"refusing to send (a tag can fan delivery out to worker "
"threads that bypass the thread-local DNS pin/block)."
@@ -322,11 +327,17 @@ class NotificationService:
# Retry transient delivery failures (SendError, connection errors,
# …) but NOT deliberate security refusals: a ValueError is a
# connect-time SSRF block (the pin's rebind-to-private/metadata catch,
- # or the block-private window's send-time refusal surfaced below) and
- # a RuntimeError is a fail-closed invariant violation (shim not
- # installed, async_mode/tag guard). A confirmed-malicious or
+ # or the block-private window's send-time refusal surfaced below); a
+ # RuntimeError (specifically
+ # ``dns_pinning.NotificationGuardUnavailableError``) is the DNS-pin
+ # shim not being installed; and a SecurityBlockError is the
+ # async_mode/tag fail-closed invariant guard
+ # (``_enforce_guarded_send_invariants``), raised directly as that
+ # type rather than a generic RuntimeError. A confirmed-malicious or
# misconfigured destination must fail fast, not be retried 3x.
- retry=retry_if_not_exception_type((ValueError, RuntimeError)),
+ retry=retry_if_not_exception_type(
+ (ValueError, RuntimeError, SecurityBlockError)
+ ),
reraise=True,
)
def _send_with_retry(
@@ -363,6 +374,13 @@ class NotificationService:
window refused a send-time resolution as an SSRF target —
a confirmed security block, raised non-retryably so it fails
fast instead of being retried.
+ SecurityBlockError: Propagated non-retryably from
+ ``_guarded_notify`` -> ``_enforce_guarded_send_invariants``
+ if the async_mode/tag fail-closed invariant is violated.
+ dns_pinning.NotificationGuardUnavailableError: Propagated
+ non-retryably (a ``RuntimeError`` subclass) from
+ ``_guarded_notify`` -> ``guard_factory`` if the DNS-pin
+ shim is not installed.
"""
logger.debug(
f"Sending notification: title='{title[:50]}...', tag={tag}"
@@ -423,7 +441,16 @@ class NotificationService:
True if notification was sent successfully to at least one service
Raises:
- SendError: If sending fails after all retry attempts
+ SendError: If sending fails after all retry attempts (transient
+ — the endpoint refused/failed the dispatch).
+ SecurityBlockError: If a send-time SSRF/DNS-rebind block
+ confirmed the destination is internal/private/metadata
+ (permanent — not worth retrying). A ``ServiceError``
+ subclass — it still satisfies ``except ServiceError`` /
+ ``pytest.raises(ServiceError)`` and shares the same
+ non-retryable signal as pre-dispatch validation rejects,
+ but is tagged distinctly so callers can give it a more
+ accurate message than "invalid URL".
Note:
Temporary Apprise instances are created for each send operation
@@ -491,12 +518,89 @@ class NotificationService:
)
return False
- except Exception as e:
- # Tenacity will retry, but if all retries fail, raise SendError
+ except SecurityBlockError:
+ # _enforce_guarded_send_invariants (called from _guarded_notify,
+ # which _send_with_retry / _dispatch call) raises this DIRECTLY
+ # — not a generic RuntimeError — for the async_mode/tag
+ # fail-closed invariant guard: a deliberate security refusal,
+ # not an incidental runtime error. It is already the precise,
+ # final exception type (see its docstring), so propagate it
+ # unchanged rather than re-wrapping: NotificationManager's
+ # ``except SecurityBlockError`` maps it to the same
+ # non-transient INVALID_URL reason as the confirmed-block paths
+ # below.
+ raise
+
+ except ValueError as e:
+ # _send_with_retry raises ValueError (excluded from Tenacity's
+ # retry predicate) ONLY for a confirmed, non-retryable send-time
+ # SSRF/DNS-rebind block — see its docstring and
+ # dns_pinning.pinned_notification_send's own rebind catch. That
+ # is a permanent, invalid-destination outcome, not a transient
+ # delivery failure, so it must NOT be re-wrapped as SendError:
+ # NotificationManager's ``except SendError`` maps to the
+ # retryable WEBHOOK_FAILED reason, which would mislabel a
+ # confirmed security block as "webhook delivery failed after
+ # retries" and could invite a caller/monitor to retry a
+ # malicious/rebinding destination. Route it through
+ # SecurityBlockError — a ServiceError subclass, so it still
+ # maps to INVALID_URL via NotificationManager's existing
+ # ``except ServiceError`` handling — but tagged distinctly so
+ # the manager can give this confirmed security block a more
+ # accurate user-facing detail than the pre-dispatch
+ # "check your URL/settings" text (see manager.py).
logger.exception(
- f"Failed to send notification after retries: '{title[:50]}...'"
+ f"Notification send blocked (SSRF/DNS-rebind): "
+ f"'{title[:50]}...'"
)
- raise SendError(f"Failed to send notification: {str(e)}")
+ raise SecurityBlockError(str(e)) from e
+
+ except dns_pinning.NotificationGuardUnavailableError as e:
+ # pinned_notification_send (via the guard_factory _dispatch
+ # builds) raises this — a RuntimeError subclass defined in
+ # security.dns_pinning, deliberately NOT imported/raised as a
+ # notifications exception there so that general-purpose
+ # security module stays free of a dependency on this
+ # higher-level package — when the getaddrinfo shim it depends
+ # on is not the active resolver. Also a deliberate fail-closed
+ # security refusal, not a transient send failure (excluded from
+ # Tenacity's retry predicate as a RuntimeError — see
+ # _send_with_retry's decorator), so route it through
+ # SecurityBlockError for the same reason as the ValueError
+ # branch above: it must not be mislabeled as a retryable
+ # WEBHOOK_FAILED.
+ logger.exception(
+ f"Notification send blocked (DNS-pin guard unavailable): "
+ f"'{title[:50]}...'"
+ )
+ raise SecurityBlockError(str(e)) from e
+
+ except SendError:
+ # _send_with_retry's own terminal raise (line ~420, once all
+ # retries are exhausted) is already the precise, final
+ # exception for a confirmed webhook delivery failure.
+ # Propagate unchanged — re-wrapping it here would just nest a
+ # second SendError around the first for no benefit, and
+ # routing it through the catch-all below would make it
+ # indistinguishable from an incidental dispatch-time bug.
+ raise
+
+ except Exception:
+ # Anything else reaching here is an incidental/unexpected
+ # error from the dispatch machinery itself (e.g. a bug in
+ # this method's call wiring, an Apprise internals exception
+ # that isn't a genuine delivery failure) — NOT a confirmed
+ # webhook delivery failure. Do NOT launder it into SendError:
+ # NotificationManager maps SendError to the retryable
+ # WEBHOOK_FAILED reason, which would mislabel an incidental
+ # bug as "webhook delivery failed after retries" and would
+ # make the manager's own ``except Exception`` -> EXCEPTION
+ # branch unreachable for dispatch-time errors. Let it
+ # propagate as-is so the manager's catch-all handles it.
+ logger.exception(
+ f"Unexpected error sending notification: '{title[:50]}...'"
+ )
+ raise
def _dispatch(
self,
diff --git a/src/local_deep_research/security/dns_pinning.py b/src/local_deep_research/security/dns_pinning.py
index 13949bd16c..015ef2af01 100644
--- a/src/local_deep_research/security/dns_pinning.py
+++ b/src/local_deep_research/security/dns_pinning.py
@@ -734,6 +734,30 @@ def pin_hosts(
pins.pop(host, None)
+class NotificationGuardUnavailableError(RuntimeError):
+ """The DNS-pin shim required for a guarded notification send is not
+ installed as the active ``socket.getaddrinfo`` resolver.
+
+ Raised ONLY by :func:`pinned_notification_send` (never by
+ :func:`pinned_request`, the general-purpose safe_get/safe_post guard,
+ which does not depend on this pre-check). This is a deliberate
+ fail-closed SECURITY REFUSAL, not an incidental runtime error: the
+ pin/block-private window cannot be guaranteed without the shim, so the
+ send is refused outright.
+
+ Subclasses ``RuntimeError`` (not just ``Exception``) so any code that
+ still generically catches ``RuntimeError`` around a guarded send
+ continues to behave the same. It is a dedicated subclass — rather than
+ a bare ``RuntimeError`` — so ``notifications.service`` can catch this
+ specific refusal and re-raise it as its own ``SecurityBlockError``
+ (non-retryable, INVALID_URL classification) without this general
+ security module importing exception types from the higher-level
+ ``notifications`` package (which would invert the module layering and
+ risk a circular import — ``notifications.service`` imports this
+ module).
+ """
+
+
@contextlib.contextmanager
def pinned_notification_send(
urls,
@@ -764,16 +788,18 @@ def pinned_notification_send(
and the block-private window.
Raises:
- RuntimeError: if the ``getaddrinfo`` shim is not the active resolver
- (see :func:`_shim_installed`). The pin/block cannot be
- guaranteed in that state, so the send is REFUSED (fail closed)
- rather than proceeding unguarded.
+ NotificationGuardUnavailableError: if the ``getaddrinfo`` shim is not
+ the active resolver (see :func:`_shim_installed`). The
+ pin/block cannot be guaranteed in that state, so the send is
+ REFUSED (fail closed) rather than proceeding unguarded. A
+ ``RuntimeError`` subclass — see its docstring for why it is
+ not a bare ``RuntimeError``.
"""
# Fail closed if our shim is not installed: without it the pin registry
# and the block-private window are never consulted, so proceeding would
# send completely unguarded (silent fail-open). Refuse instead.
if not _shim_installed():
- raise RuntimeError(
+ raise NotificationGuardUnavailableError(
"DNS pin shim is not the active socket.getaddrinfo; refusing the "
"notification send (fail closed). The resolve-vs-connect pin and "
"block-private window cannot be guaranteed — see "
diff --git a/tests/error_handling/test_error_reporter.py b/tests/error_handling/test_error_reporter.py
index 28cc394dda..879a35d8c3 100644
--- a/tests/error_handling/test_error_reporter.py
+++ b/tests/error_handling/test_error_reporter.py
@@ -389,23 +389,24 @@ class TestSendErrorNotifications:
"""When the notification is dropped, the debug log must show the
``reason.value`` string (``unconfigured``) — not the enum repr
(``NotificationReason.UNCONFIGURED``) — and must include the
- operator-facing ``detail`` so the cause is visible. See PR #5082.
+ operator-facing ``detail`` so the cause is visible. Uses the real
+ ``NotificationResult`` so the assertion is falsifiable against
+ the real enum's rendering (issue #5110). See PR #5082.
"""
+ from local_deep_research.notifications.manager import (
+ NotificationReason,
+ NotificationResult,
+ )
- class FakeReason:
- value = "unconfigured"
-
- class FakeResult:
- sent = False
- detail = "notifications.service_url is not configured"
- reason = FakeReason()
-
- def __bool__(self) -> bool:
- return self.sent
+ result = NotificationResult(
+ sent=False,
+ reason=NotificationReason.UNCONFIGURED,
+ detail="notifications.service_url is not configured",
+ )
with loguru_caplog.at_level("DEBUG"):
self._run_notification_dropped(
- error_reporter, mock_context_with_username, FakeResult()
+ error_reporter, mock_context_with_username, result
)
messages = [rec.message for rec in loguru_caplog.records]
@@ -423,21 +424,20 @@ class TestSendErrorNotifications:
"""When detail is empty, the debug log must still show the reason
value without trailing colon whitespace.
"""
+ from local_deep_research.notifications.manager import (
+ NotificationReason,
+ NotificationResult,
+ )
- class FakeReason:
- value = "event_disabled"
-
- class FakeResult:
- sent = False
- detail = ""
- reason = FakeReason()
-
- def __bool__(self) -> bool:
- return self.sent
+ result = NotificationResult(
+ sent=False,
+ reason=NotificationReason.EVENT_DISABLED,
+ detail="",
+ )
with loguru_caplog.at_level("DEBUG"):
self._run_notification_dropped(
- error_reporter, mock_context_with_username, FakeResult()
+ error_reporter, mock_context_with_username, result
)
debug_lines = [
@@ -448,3 +448,21 @@ class TestSendErrorNotifications:
assert len(debug_lines) == 1, debug_lines
assert debug_lines[0].endswith("event_disabled")
assert "NotificationReason." not in debug_lines[0]
+
+ def test_logs_dropped_for_legacy_bool_result(
+ self, error_reporter, mock_context_with_username, loguru_caplog
+ ):
+ """A legacy bool ``False`` (older callers / mocks) carries no
+ reason — the fallback must log a plain ``dropped``."""
+ with loguru_caplog.at_level("DEBUG"):
+ self._run_notification_dropped(
+ error_reporter, mock_context_with_username, False
+ )
+
+ debug_lines = [
+ rec.message
+ for rec in loguru_caplog.records
+ if "Error notification not sent" in rec.message
+ ]
+ assert len(debug_lines) == 1, debug_lines
+ assert debug_lines[0].endswith("dropped")
diff --git a/tests/notifications/test_manager.py b/tests/notifications/test_manager.py
index bd24d06b16..b090958e07 100644
--- a/tests/notifications/test_manager.py
+++ b/tests/notifications/test_manager.py
@@ -13,7 +13,12 @@ from local_deep_research.notifications.manager import (
NotificationResult,
)
from local_deep_research.notifications.templates import EventType
-from local_deep_research.notifications.exceptions import RateLimitError
+from local_deep_research.notifications.exceptions import (
+ RateLimitError,
+ SecurityBlockError,
+ SendError,
+ ServiceError,
+)
class TestNotificationManagerInit:
@@ -451,6 +456,15 @@ class TestNotificationResultSemantics:
result with a distinct :class:`NotificationReason` (issue #4877).
"""
+ @pytest.fixture(autouse=True)
+ def _fresh_rate_limiter(self):
+ """Tests here share user_id "u"; isolate them from the shared
+ class-level limiter so ordering / xdist cannot trip
+ RateLimitError (issue #5110)."""
+ NotificationManager._shared_rate_limiter = None
+ yield
+ NotificationManager._shared_rate_limiter = None
+
def test_result_is_truthy_when_sent(self):
r = NotificationResult(
sent=True, reason=NotificationReason.SENT, detail=""
@@ -474,6 +488,7 @@ class TestNotificationResultSemantics:
assert NotificationReason.EVENT_DISABLED.value == "event_disabled"
assert NotificationReason.UNCONFIGURED.value == "unconfigured"
assert NotificationReason.EGRESS_DENIED.value == "egress_denied"
+ assert NotificationReason.INVALID_URL.value == "invalid_url"
assert NotificationReason.WEBHOOK_FAILED.value == "webhook_failed"
assert NotificationReason.EXCEPTION.value == "exception"
@@ -555,7 +570,34 @@ class TestNotificationResultSemantics:
assert result.reason is NotificationReason.EGRESS_DENIED
assert "egress" in result.detail
- def test_webhook_failed(self, mocker):
+ def test_egress_policy_unevaluable(self, mocker):
+ """Policy exists but cannot be evaluated (filter fails closed,
+ returning None) → still ``egress_denied``, but the detail must
+ say the policy was unevaluable, not that it refused the URLs
+ (issue #5110)."""
+ snapshot = {
+ "notifications.service_url": "discord://x",
+ "notifications.on_research_completed": True,
+ }
+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")
+ with patch.object(
+ manager,
+ "_filter_urls_by_egress_policy",
+ return_value=None,
+ ):
+ result = manager.send_notification(
+ event_type=EventType.RESEARCH_COMPLETED,
+ context={"query": "q"},
+ force=True,
+ )
+ assert result.reason is NotificationReason.EGRESS_DENIED
+ assert "could not be evaluated" in result.detail
+ assert "refused" not in result.detail
+
+ def test_invalid_url_when_apprise_accepts_no_urls(self, mocker):
+ """A falsy return from ``send_event`` means Apprise rejected the
+ URL string at parse time (dispatch never attempted) →
+ ``invalid_url``, not ``webhook_failed`` (issue #5110)."""
snapshot = {
"notifications.service_url": "discord://x",
"notifications.on_research_completed": True,
@@ -567,7 +609,113 @@ class TestNotificationResultSemantics:
event_type=EventType.RESEARCH_COMPLETED,
context={"query": "q"},
)
+ assert result.reason is NotificationReason.INVALID_URL
+
+ def test_invalid_url_real_service_contract(self, mocker):
+ """Same as above but through the REAL NotificationService, so the
+ test breaks if the service's invalid-URL contract ever changes.
+ An unrecognized scheme fails the SSRF URL validator, which raises
+ ServiceError before any network I/O — that too must map to
+ ``invalid_url``, not ``exception``."""
+ snapshot = {
+ "notifications.service_url": "not-a-real-scheme://nope",
+ "notifications.on_research_completed": True,
+ }
+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")
+ manager._rate_limiter.is_allowed = mocker.MagicMock(return_value=True)
+ result = manager.send_notification(
+ event_type=EventType.RESEARCH_COMPLETED,
+ context={"query": "q"},
+ )
+ assert result.sent is False
+ assert result.reason is NotificationReason.INVALID_URL
+
+ def test_webhook_failed_when_delivery_raises_senderror(self, mocker):
+ """The delivery layer signals a real dispatch failure (dead
+ webhook, HTTP error, network down) by RAISING SendError — it
+ never returns False for this. That contract must map to
+ ``webhook_failed``, and the detail must not echo the exception
+ message, which wraps URLs/tokens (issue #5110)."""
+ snapshot = {
+ "notifications.service_url": "discord://x",
+ "notifications.on_research_completed": True,
+ }
+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")
+ manager.service.send_event = mocker.MagicMock(
+ side_effect=SendError(
+ "Failed to send notification: POST discord://id/secret-token"
+ )
+ )
+ manager._rate_limiter.is_allowed = mocker.MagicMock(return_value=True)
+ result = manager.send_notification(
+ event_type=EventType.RESEARCH_COMPLETED,
+ context={"query": "q"},
+ )
+ assert result.sent is False
assert result.reason is NotificationReason.WEBHOOK_FAILED
+ assert "secret-token" not in result.detail
+ assert "discord://" not in result.detail
+
+ def test_invalid_url_detail_does_not_leak_serviceerror_message(
+ self, mocker
+ ):
+ """A ServiceError from URL security validation maps to
+ ``invalid_url``. Its message wraps the offending URL (which can
+ embed a token) — the static ``detail`` must never echo it, since
+ downstream callers log ``detail`` verbatim (issue #5110)."""
+ snapshot = {
+ "notifications.service_url": "discord://x",
+ "notifications.on_research_completed": True,
+ }
+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")
+ manager.service.send_event = mocker.MagicMock(
+ side_effect=ServiceError(
+ "Invalid service URL: discord://id123/secret-token blocked"
+ )
+ )
+ manager._rate_limiter.is_allowed = mocker.MagicMock(return_value=True)
+ result = manager.send_notification(
+ event_type=EventType.RESEARCH_COMPLETED,
+ context={"query": "q"},
+ )
+ assert result.sent is False
+ assert result.reason is NotificationReason.INVALID_URL
+ assert "secret-token" not in result.detail
+ assert "id123" not in result.detail
+ assert "discord://" not in result.detail
+
+ def test_security_block_error_gets_distinct_detail(self, mocker):
+ """A ``SecurityBlockError`` (confirmed send-time SSRF/DNS-rebind
+ block — a ``ServiceError`` subclass NotificationService.send()
+ raises for that case) must still map to ``invalid_url`` like a
+ plain ``ServiceError``, but with a detail that says the
+ destination was blocked by egress/SSRF protection rather than the
+ generic "check your URL/settings" text — the latter is misleading
+ for a confirmed security block, not a config mistake."""
+ snapshot = {
+ "notifications.service_url": "discord://x",
+ "notifications.on_research_completed": True,
+ }
+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")
+ manager.service.send_event = mocker.MagicMock(
+ side_effect=SecurityBlockError(
+ "Notification send refused: a send-time DNS resolution "
+ "was blocked as internal/private/metadata (possible SSRF)"
+ )
+ )
+ manager._rate_limiter.is_allowed = mocker.MagicMock(return_value=True)
+ result = manager.send_notification(
+ event_type=EventType.RESEARCH_COMPLETED,
+ context={"query": "q"},
+ )
+ assert result.sent is False
+ assert result.reason is NotificationReason.INVALID_URL
+ assert "blocked by egress/SSRF protection" in result.detail
+ # Must not repeat the pre-dispatch-validation wording, which
+ # would misleadingly suggest a settings/URL-format mistake.
+ assert "LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS" not in result.detail
+ # And must not leak the exception message or any resolved detail.
+ assert "DNS resolution" not in result.detail
def test_exception(self, mocker):
snapshot = {
@@ -616,6 +764,19 @@ class TestNotificationResultSemantics:
assert "discord://" not in result.detail
assert "RuntimeError" in result.detail
+ def test_test_service_distinguishes_unevaluable_policy(self, mocker):
+ """test_service must not blame the egress scope when the policy
+ could not be evaluated at all (filter returned None)."""
+ snapshot = {"notifications.service_url": "discord://x"}
+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")
+ with patch.object(
+ manager, "_filter_urls_by_egress_policy", return_value=None
+ ):
+ result = manager.test_service("discord://x")
+ assert result["status"] == "error"
+ assert "could not be evaluated" in result["message"]
+ assert "refused" not in result["message"]
+
def test_rate_limit_still_raises(self, mocker):
"""Backward compat: rate-limit refusal still raises, not returned."""
snapshot = {
diff --git a/tests/notifications/test_notification_webhook_dns_pin.py b/tests/notifications/test_notification_webhook_dns_pin.py
index 6fe092f97f..f0dd05e696 100644
--- a/tests/notifications/test_notification_webhook_dns_pin.py
+++ b/tests/notifications/test_notification_webhook_dns_pin.py
@@ -37,7 +37,11 @@ from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.x509.oid import NameOID
-from local_deep_research.notifications.exceptions import SendError, ServiceError
+from local_deep_research.notifications.exceptions import (
+ SecurityBlockError,
+ SendError,
+ ServiceError,
+)
from local_deep_research.notifications.service import NotificationService
from local_deep_research.security import dns_pinning
from local_deep_research.security.notification_validator import (
@@ -342,13 +346,16 @@ def test_public_json_webhook_delivers_through_apprise():
def test_rebind_to_metadata_blocked_through_apprise():
"""Validation sees a public IP; the pin's connect-time re-validation
catches the rebind to cloud-metadata and refuses the send before any
- connection is made."""
+ connection is made. The pin's rebind catch raises a non-retryable
+ ValueError, which ``send()`` surfaces as ServiceError (a confirmed
+ security block, not a retryable SendError — see
+ ``NotificationService.send``'s docstring)."""
resolver = _Resolver(
{"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}
)
with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
with _connect_spy() as targets:
- with pytest.raises(SendError):
+ with pytest.raises(ServiceError):
_service().send(
title="t",
body="b",
@@ -363,7 +370,8 @@ def test_multi_url_batch_guards_every_host():
"""A single notify() fans out to several raw-webhook URLs. EVERY host in
the batch is pinned/checked: one host that rebinds to metadata refuses
the whole batch (fail closed) and no connection to the metadata IP is
- made — proving the guard is not applied to just the first URL."""
+ made — proving the guard is not applied to just the first URL. The
+ confirmed rebind raises ServiceError (non-retryable), not SendError."""
server, port, _hits = _start_server()
resolver = _Resolver(
{
@@ -374,7 +382,7 @@ def test_multi_url_batch_guards_every_host():
urls = f"json://a.example:{port}/x,json://b.example/y"
with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
with _connect_spy() as targets:
- with pytest.raises(SendError):
+ with pytest.raises(ServiceError):
_service().send(title="t", body="b", service_urls=urls)
try:
assert not any(addr[0] == "169.254.169.254" for addr in targets)
@@ -724,17 +732,22 @@ def test_guarded_send_refuses_async_mode_and_tag():
"""The guarded-send invariants fail closed: async_mode must be off and
tag must be None, or the thread-local pin/block would be bypassed by
Apprise's worker-thread fan-out. Teeth: drop the checks in
- ``_enforce_guarded_send_invariants`` and neither raises."""
+ ``_enforce_guarded_send_invariants`` and neither raises.
+
+ Both violations raise ``SecurityBlockError`` directly (not a generic
+ ``RuntimeError``) so ``send()`` cannot mislabel this deliberate
+ security refusal as a retryable webhook failure — see the
+ round-3 fix for #5113."""
svc = _service()
# Correct config: synchronous, no tag -> accepted.
good = svc._new_apprise()
svc._enforce_guarded_send_invariants(good, None)
# async_mode=True -> refused.
bad_async = apprise.Apprise(asset=apprise.AppriseAsset(async_mode=True))
- with pytest.raises(RuntimeError, match="async_mode"):
+ with pytest.raises(SecurityBlockError, match="async_mode"):
svc._enforce_guarded_send_invariants(bad_async, None)
# tag present -> refused.
- with pytest.raises(RuntimeError, match="tag"):
+ with pytest.raises(SecurityBlockError, match="tag"):
svc._enforce_guarded_send_invariants(good, "urgent")
@@ -743,14 +756,15 @@ def test_ssrf_block_is_not_retried():
fail fast, not be retried 3x by Tenacity. The rebind host resolves
public at validation (call #1) and metadata at the guarded pin (call
#2), which raises the SSRF ValueError; with that excluded from retries
- the guarded pin runs exactly ONCE. Teeth: restore
+ the guarded pin runs exactly ONCE. ``send()`` surfaces this confirmed,
+ non-retryable block as ServiceError, not SendError. Teeth: restore
``retry_if_exception_type((Exception,))`` and the pin is retried, so
rebind.example is resolved 4 times (1 validation + 3 pin attempts)."""
resolver = _Resolver(
{"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}
)
with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
- with pytest.raises(SendError):
+ with pytest.raises(ServiceError):
_service().send(
title="t",
body="b",
@@ -839,15 +853,16 @@ def test_block_window_block_is_not_retried():
re-raises it non-retryably. The rebind host resolves public at validation
(call #1) and metadata at the send-time window resolution (call #2), so
with the block excluded from retries the host is resolved exactly TWICE.
- Teeth: drop the ``consume_ssrf_block`` short-circuit in ``_send_with_retry``
- and the send is retried, resolving the host 4 times (1 validation + 3
- send attempts)."""
+ ``send()`` surfaces the confirmed, non-retryable block as ServiceError,
+ not SendError. Teeth: drop the ``consume_ssrf_block`` short-circuit in
+ ``_send_with_retry`` and the send is retried, resolving the host 4 times
+ (1 validation + 3 send attempts)."""
resolver = _Resolver(
{"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}
)
with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
with _connect_spy() as targets:
- with pytest.raises(SendError):
+ with pytest.raises(ServiceError):
_service().send(
title="t",
body="b",
@@ -899,12 +914,21 @@ def test_ipv6_imds_refused_by_block_window():
def test_send_with_tag_is_refused_end_to_end():
"""send(..., tag=...) is refused end-to-end: a tag can fan delivery out
to worker threads that bypass the thread-local pin/block, so the
- guarded-send invariant rejects it (RuntimeError, wrapped as SendError)
- before any connection — no socket is opened to the target."""
+ guarded-send invariant rejects it before any connection — no socket is
+ opened to the target.
+
+ The invariant guard raises ``SecurityBlockError`` directly (not a
+ generic ``RuntimeError``), and ``send()`` must propagate it unchanged
+ rather than wrap it as ``SendError``: this is a deliberate security
+ refusal, not a transient webhook failure, and NotificationManager maps
+ ``SendError`` to the RETRYABLE ``webhook_failed`` reason — retrying a
+ security refusal would be a bug. Round-3 fix for #5113 (the prior fix
+ only re-routed the ValueError SSRF-block path, leaving this
+ RuntimeError invariant-violation path mislabeled as webhook_failed)."""
resolver = _Resolver({"good.example": [["93.184.216.34"]]})
with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
with _connect_spy() as targets:
- with pytest.raises(SendError):
+ with pytest.raises(SecurityBlockError):
_service().send(
title="t",
body="b",
@@ -1050,7 +1074,8 @@ def test_ipv6_imds_rebind_refused_through_send():
``test_rebind_to_metadata_blocked_through_apprise``. The pin's connect-time
re-validation catches the rebind (the cloud-metadata block is absolute even
under allow_private_ips=True, which permits the fc00::/7 ULA the address
- sits in) and raises the SSRF ValueError, wrapped as SendError.
+ sits in) and raises the SSRF ValueError, which ``send()`` surfaces as
+ ServiceError (confirmed, non-retryable security block — not SendError).
Teeth: drop the ``is_ip_blocked`` check in
``dns_pinning._resolve_and_validate`` (or remove ``fd00:ec2::254`` from
@@ -1066,7 +1091,7 @@ def test_ipv6_imds_rebind_refused_through_send():
)
with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
with _connect_spy() as targets:
- with pytest.raises(SendError):
+ with pytest.raises(ServiceError):
_service().send(
title="t",
body="b",
@@ -1236,13 +1261,16 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition():
leaving ``is_ip_blocked`` / the validator untouched) and this test
fails — the rebind pins successfully and the connect spy sees
169.254.42.42.
+
+ The confirmed rebind raises ServiceError (non-retryable), not
+ SendError.
"""
resolver = _Resolver(
{"ll-rebind.example": [["93.184.216.34"], ["169.254.42.42"]]}
)
with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
with _connect_spy() as targets:
- with pytest.raises(SendError):
+ with pytest.raises(ServiceError):
_service().send(
title="t",
body="b",
@@ -1258,7 +1286,8 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():
public IPv6 (resolver call #1) but rebinds to a bare IPv6 link-local
address ``fe80::1`` (fe80::/10, not an always-blocked literal) at
``_dispatch``'s pin resolution (call #2). Same wiring lock —
- refused only by ``_dispatch``'s ``block_link_local=True``."""
+ refused only by ``_dispatch``'s ``block_link_local=True``. The
+ confirmed rebind raises ServiceError (non-retryable), not SendError."""
resolver = _Resolver(
{
"ll-rebind6.example": [
@@ -1269,7 +1298,7 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():
)
with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
with _connect_spy() as targets:
- with pytest.raises(SendError):
+ with pytest.raises(ServiceError):
_service().send(
title="t",
body="b",
diff --git a/tests/notifications/test_queue_helpers_extended.py b/tests/notifications/test_queue_helpers_extended.py
index 93cd9159f3..7cdbb92c35 100644
--- a/tests/notifications/test_queue_helpers_extended.py
+++ b/tests/notifications/test_queue_helpers_extended.py
@@ -539,7 +539,7 @@ class TestSendResearchFailedNotificationFromSession:
# ---------------------------------------------------------------------------
# Regression: minimal-details logging path must not double-log
-# (see PR #5082 review feedback — bug introduced in ee606c791).
+# (see PR #5082 review feedback).
# ---------------------------------------------------------------------------
@@ -754,3 +754,264 @@ class TestMinimalDetailsLoggingRegression:
assert sent_lines == [], sent_lines
assert len(warning_lines) == 1, warning_lines
assert "egress_denied" in warning_lines[0]
+
+
+# ---------------------------------------------------------------------------
+# Regression: the found-research warning paths must carry the precise
+# reason. These are the PR #5082 headline hunks that previously had no
+# coverage — reverting them to the old "(disabled)" literal must fail
+# these tests (issue #5110).
+# ---------------------------------------------------------------------------
+
+
+class TestFoundResearchReasonLogging:
+ """Log assertions for the found-research (non-minimal) paths."""
+
+ @patch(REPORT_STORAGE)
+ @patch(URL_BUILDER)
+ @patch(NOTIF_MGR)
+ def test_completed_found_failure_warns_with_reason(
+ self, mock_nm_class, mock_build_url, mock_get_storage, loguru_caplog
+ ):
+ from local_deep_research.notifications.queue_helpers import (
+ send_research_completed_notification_from_session,
+ )
+
+ mock_db = MagicMock()
+ mock_research = Mock()
+ mock_research.query = "How does AI work?"
+ mock_db.query.return_value.filter_by.return_value.first.return_value = (
+ mock_research
+ )
+ mock_build_url.return_value = "https://app.test/research/r-found"
+ mock_storage = Mock()
+ mock_storage.get_report.return_value = "Short report"
+ mock_get_storage.return_value = mock_storage
+
+ mock_nm = Mock()
+ mock_nm.send_notification.return_value = _result(
+ sent=False,
+ reason_value="unconfigured",
+ detail="notifications.service_url is not configured",
+ )
+ mock_nm_class.return_value = mock_nm
+
+ mock_settings = Mock()
+ mock_settings.get_settings_snapshot.return_value = {}
+
+ with patch(SETTINGS_MGR, return_value=mock_settings):
+ with loguru_caplog.at_level("INFO"):
+ send_research_completed_notification_from_session(
+ username="alice",
+ research_id="r-found",
+ db_session=mock_db,
+ )
+
+ warning_lines = [
+ rec.message
+ for rec in loguru_caplog.records
+ if "Completion notification not sent" in rec.message
+ ]
+ assert len(warning_lines) == 1, warning_lines
+ assert "unconfigured" in warning_lines[0]
+ assert "notifications.service_url" in warning_lines[0]
+ assert "(disabled)" not in warning_lines[0]
+
+ @patch(NOTIF_MGR)
+ def test_failed_found_failure_warns_with_reason(
+ self, mock_nm_class, loguru_caplog
+ ):
+ from local_deep_research.notifications.queue_helpers import (
+ send_research_failed_notification_from_session,
+ )
+
+ mock_db = MagicMock()
+ mock_research = Mock()
+ mock_research.query = "What is quantum computing?"
+ mock_db.query.return_value.filter_by.return_value.first.return_value = (
+ mock_research
+ )
+
+ mock_nm = Mock()
+ mock_nm.send_notification.return_value = _result(
+ sent=False,
+ reason_value="egress_denied",
+ detail="all configured URLs refused by egress policy",
+ )
+ mock_nm_class.return_value = mock_nm
+
+ mock_settings = Mock()
+ mock_settings.get_settings_snapshot.return_value = {}
+
+ with patch(SETTINGS_MGR, return_value=mock_settings):
+ with loguru_caplog.at_level("INFO"):
+ send_research_failed_notification_from_session(
+ username="alice",
+ research_id="r-found",
+ error_message="boom",
+ db_session=mock_db,
+ )
+
+ warning_lines = [
+ rec.message
+ for rec in loguru_caplog.records
+ if "Failure notification not sent" in rec.message
+ ]
+ assert len(warning_lines) == 1, warning_lines
+ assert "egress_denied" in warning_lines[0]
+ assert "(disabled)" not in warning_lines[0]
+
+
+# ---------------------------------------------------------------------------
+# Coverage for the send_queue_notification / send_queue_failed_notification
+# wrappers: drop-reason logging at DEBUG, bool coercion at the boundary, and
+# _format_reason's legacy-bool fallback (issue #5110).
+# ---------------------------------------------------------------------------
+
+
+class TestQueueWrapperHelpers:
+ """Behavior of the thin queue wrappers around send_notification."""
+
+ @patch(f"{HELPERS}.NotificationManager")
+ def test_queued_drop_returns_false_and_logs_reason_at_debug(
+ self, mock_nm_class, loguru_caplog
+ ):
+ from local_deep_research.notifications.queue_helpers import (
+ send_queue_notification,
+ )
+
+ mock_nm = Mock()
+ mock_nm.send_notification.return_value = _result(
+ sent=False,
+ reason_value="unconfigured",
+ detail="notifications.service_url is not configured",
+ )
+ mock_nm_class.return_value = mock_nm
+
+ with loguru_caplog.at_level("DEBUG"):
+ returned = send_queue_notification(
+ username="alice",
+ research_id="r-q",
+ query="q",
+ settings_snapshot={"any": "thing"},
+ )
+
+ assert returned is False
+ reason_lines = [
+ rec.message
+ for rec in loguru_caplog.records
+ if "Queue notification not sent" in rec.message
+ ]
+ assert len(reason_lines) == 1, reason_lines
+ assert "unconfigured" in reason_lines[0]
+
+ @patch(f"{HELPERS}.NotificationManager")
+ def test_queued_success_returns_true_without_warning(
+ self, mock_nm_class, loguru_caplog
+ ):
+ from local_deep_research.notifications.queue_helpers import (
+ send_queue_notification,
+ )
+
+ mock_nm = Mock()
+ mock_nm.send_notification.return_value = _result(sent=True)
+ mock_nm_class.return_value = mock_nm
+
+ with loguru_caplog.at_level("DEBUG"):
+ returned = send_queue_notification(
+ username="alice",
+ research_id="r-q",
+ query="q",
+ settings_snapshot={"any": "thing"},
+ )
+
+ assert returned is True
+ assert not [
+ rec.message
+ for rec in loguru_caplog.records
+ if "Queue notification not sent" in rec.message
+ ]
+
+ @patch(f"{HELPERS}.NotificationManager")
+ def test_queued_legacy_bool_false_logs_dropped(
+ self, mock_nm_class, loguru_caplog
+ ):
+ """Legacy mocks returning a bare bool must still coerce and log
+ via _format_reason's fallback branch."""
+ from local_deep_research.notifications.queue_helpers import (
+ send_queue_notification,
+ )
+
+ mock_nm = Mock()
+ mock_nm.send_notification.return_value = False
+ mock_nm_class.return_value = mock_nm
+
+ with loguru_caplog.at_level("DEBUG"):
+ returned = send_queue_notification(
+ username="alice",
+ research_id="r-q",
+ query="q",
+ settings_snapshot={"any": "thing"},
+ )
+
+ assert returned is False
+ reason_lines = [
+ rec.message
+ for rec in loguru_caplog.records
+ if "Queue notification not sent" in rec.message
+ ]
+ assert len(reason_lines) == 1, reason_lines
+ assert "(dropped)" in reason_lines[0]
+
+ @patch(f"{HELPERS}.NotificationManager")
+ def test_queued_legacy_bool_true_returns_true(self, mock_nm_class):
+ from local_deep_research.notifications.queue_helpers import (
+ send_queue_notification,
+ )
+
+ mock_nm = Mock()
+ mock_nm.send_notification.return_value = True
+ mock_nm_class.return_value = mock_nm
+
+ returned = send_queue_notification(
+ username="alice",
+ research_id="r-q",
+ query="q",
+ settings_snapshot={"any": "thing"},
+ )
+
+ assert returned is True
+
+ @patch(f"{HELPERS}.NotificationManager")
+ def test_failed_drop_returns_false_and_logs_reason_at_debug(
+ self, mock_nm_class, loguru_caplog
+ ):
+ from local_deep_research.notifications.queue_helpers import (
+ send_queue_failed_notification,
+ )
+
+ mock_nm = Mock()
+ mock_nm.send_notification.return_value = _result(
+ sent=False,
+ reason_value="server_disabled",
+ detail="outbound notifications are disabled at the server level",
+ )
+ mock_nm_class.return_value = mock_nm
+
+ with loguru_caplog.at_level("DEBUG"):
+ returned = send_queue_failed_notification(
+ username="alice",
+ research_id="r-f",
+ query="q",
+ error_message="boom",
+ settings_snapshot={"any": "thing"},
+ )
+
+ assert returned is False
+ reason_lines = [
+ rec.message
+ for rec in loguru_caplog.records
+ if "Failed-notification not sent" in rec.message
+ ]
+ assert len(reason_lines) == 1, reason_lines
+ assert "server_disabled" in reason_lines[0]
diff --git a/tests/security/test_egress_notifications_callsite.py b/tests/security/test_egress_notifications_callsite.py
index a5c7f18383..b6c83aa7da 100644
--- a/tests/security/test_egress_notifications_callsite.py
+++ b/tests/security/test_egress_notifications_callsite.py
@@ -153,8 +153,12 @@ def test_corrupt_scope_fails_closed():
# A garbage scope makes context_from_snapshot raise PolicyDeniedError;
# the PEP must refuse ALL urls rather than fall open to unfiltered send.
+ # None is the unevaluable-policy signal (falsy, so callers still drop
+ # everything) — distinct from "" which means "evaluated, all refused".
deny_mgr = _build_manager(_snapshot("totally-not-a-scope"))
- assert deny_mgr._filter_urls_by_egress_policy(url) == ""
+ filtered = deny_mgr._filter_urls_by_egress_policy(url)
+ assert filtered is None
+ assert not filtered
# Sanity pair: a valid permissive scope on the same input passes it.
allow_mgr = _build_manager(_snapshot("both"))