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.

47.8 KB
Raw Blame
"""
High-level notification manager with database integration.
"""

from dataclasses import dataclass
from datetime import datetime, timezone, timedelta
from enum import Enum
from typing import Dict, Optional, Any
from urllib.parse import urlunsplit
from collections import deque
import threading

from loguru import logger

from ..security.notification_validator import parse_notification_url_list
from ..constants import DEFAULT_SEARCH_TOOL
from ..security.ssrf_validator import redact_url_for_log
from ..security.notification_destination import (
    NotificationDestinationError,
    NotificationDestinationKind,
    parse_notification_destination,
)
from ..settings.env_registry import get_env_setting
from .service import NotificationService
from .templates import EventType
from .exceptions import (
    RateLimitError,
    SendError,
    ServiceError,
    SecurityBlockError,
)


class NotificationReason(str, Enum):
    """Precise reason a notification was (not) sent.

    Surfaced in :class:`NotificationResult` so callers and log lines can
    distinguish, for example, a per-user toggle being off from the
    server-level master switch being unset — see issue #4877.

    Note: rate-limit refusal is signalled via :class:`RateLimitError`
    (preserved API for callers that catch it directly) rather than as a
    ``NotificationResult`` value.
    """

    SENT = "sent"
    SERVER_DISABLED = "server_disabled"
    EVENT_DISABLED = "event_disabled"
    UNCONFIGURED = "unconfigured"
    EGRESS_DENIED = "egress_denied"
    INVALID_URL = "invalid_url"
    WEBHOOK_FAILED = "webhook_failed"
    EXCEPTION = "exception"


@dataclass(frozen=True)
class NotificationResult:
    """Structured outcome of :meth:`NotificationManager.send_notification`.

    ``sent`` keeps the legacy bool contract (``if result:`` keeps working —
    see ``__bool__``) while ``reason`` names the precise cause so the queue
    helpers and error reporter can log a useful, non-misleading line.
    ``detail`` is a short operator-facing explanation complementing reason.
    """

    sent: bool
    reason: NotificationReason
    detail: str = ""

    def __bool__(self) -> bool:
        return self.sent


class NotificationManager:
    """
    High-level notification manager that uses settings snapshots for
    thread-safe access to user settings.

    This manager is designed to be used from background threads (e.g., queue
    processors) by passing a settings_snapshot dictionary captured from the
    main thread.

    **Per-User Rate Limiting:**
    The rate limiter is shared across ALL NotificationManager instances as a
    singleton, but supports per-user rate limit configuration. Each user has
    their own rate limits based on their settings, which are configured when
    the NotificationManager is initialized with the required user_id parameter.

    **How It Works:**
    - The first NotificationManager instance creates the shared RateLimiter
      with default limits
    - Each instance configures user-specific limits by passing user_id to __init__
    - The rate limiter maintains separate counters and limits for each user
    - Users are completely isolated - one user's limit doesn't affect others

    Example:
        >>> # User A with conservative limits
        >>> snapshot_a = {"notifications.rate_limit_per_hour": 5}
        >>> manager_a = NotificationManager(snapshot_a, user_id="user_a")
        >>> # ✅ user_a gets 5/hour
        >>>
        >>> # User B with generous limits (doesn't affect User A!)
        >>> snapshot_b = {"notifications.rate_limit_per_hour": 20}
        >>> manager_b = NotificationManager(snapshot_b, user_id="user_b")
        >>> # ✅ user_b gets 20/hour, user_a still has 5/hour
    """

    # Shared rate limiter instance across all NotificationManager instances
    # This ensures rate limits are enforced correctly even when multiple
    # NotificationManager instances are created
    _shared_rate_limiter: Optional["RateLimiter"] = None
    _rate_limiter_lock = threading.Lock()

    def __init__(self, settings_snapshot: Dict[str, Any], user_id: str):
        """
        Initialize the notification manager.

        Args:
            settings_snapshot: Dictionary of settings key-value pairs captured
                             from SettingsManager.get_settings_snapshot().
                             This allows thread-safe access to user settings
                             from background threads.
            user_id: User identifier for per-user rate limiting. The rate limits
                    from settings_snapshot will be configured for this user.

        Example:
            >>> # In main thread with database session
            >>> settings_manager = SettingsManager(session)
            >>> snapshot = settings_manager.get_settings_snapshot()
            >>>
            >>> # In background thread (thread-safe)
            >>> notification_manager = NotificationManager(
            ...     settings_snapshot=snapshot,
            ...     user_id="user123"
            ... )
            >>> notification_manager.send_notification(...)
        """
        # Store settings snapshot for thread-safe access
        self._settings_snapshot = settings_snapshot
        self._user_id = user_id

        # Security: read from server-side environment variable only — never from
        # user-writable DB settings.  Previously this was read via
        # _get_setting("notifications.allow_private_ips"), which allowed any
        # user to bypass SSRF protection through the settings API.
        # Registered as env-only in settings/env_definitions/security.py
        # so SettingsManager will always read LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS
        # from the environment, never from the database.
        allow_private_ips = get_env_setting(
            "notifications.allow_private_ips", False
        )

        # Server-level master switch (env-only). Distinct from the per-user
        # notifications.enabled toggle in the UI: this gate is set by the
        # deployment operator and cannot be flipped via the user-writable
        # settings API. Disabled by default; enabling it accepts the
        # documented DNS-rebinding TOCTOU residual risk
        # (see SECURITY.md "Notification Webhook SSRF").
        self._outbound_allowed = bool(
            get_env_setting("notifications.allow_outbound", False)
        )

        self.service = NotificationService(
            allow_private_ips=allow_private_ips,
            outbound_allowed=self._outbound_allowed,
        )

        # Initialize shared rate limiter on first use
        # The shared rate limiter now supports per-user limits, so each user's
        # settings are respected regardless of initialization order.
        with NotificationManager._rate_limiter_lock:
            if NotificationManager._shared_rate_limiter is None:
                # Create shared rate limiter with default limits
                # (individual users can have different limits)
                default_max_per_hour = self._get_setting(
                    "notifications.rate_limit_per_hour", default=10
                )
                default_max_per_day = self._get_setting(
                    "notifications.rate_limit_per_day", default=50
                )

                logger.info(
                    f"Initializing shared rate limiter with defaults: "
                    f"{default_max_per_hour}/hour, {default_max_per_day}/day"
                )

                NotificationManager._shared_rate_limiter = RateLimiter(
                    max_per_hour=default_max_per_hour,
                    max_per_day=default_max_per_day,
                )

            # Use the shared instance
            self._rate_limiter = NotificationManager._shared_rate_limiter

            # Configure per-user rate limits
            max_per_hour = self._get_setting(
                "notifications.rate_limit_per_hour", default=10
            )
            max_per_day = self._get_setting(
                "notifications.rate_limit_per_day", default=50
            )

            self._rate_limiter.set_user_limits(
                user_id, max_per_hour, max_per_day
            )
            logger.debug(
                f"Configured rate limits for user {user_id}: "
                f"{max_per_hour}/hour, {max_per_day}/day"
            )

    def _get_setting(self, key: str, default: Any = None) -> Any:
        """
        Get a setting value from snapshot.

        Args:
            key: Setting key
            default: Default value if not found

        Returns:
            Setting value or default
        """
        return self._settings_snapshot.get(key, default)

    def send_notification(
        self,
        event_type: EventType,
        context: Dict[str, Any],
        force: bool = False,
    ) -> NotificationResult:
        """
        Send a notification for an event.

        Uses the user_id that was provided during initialization for
        rate limiting and user preferences.

        Args:
            event_type: Type of event
            context: Context data for the notification
            force: If True, bypass rate limiting

        Returns:
            :class:`NotificationResult` describing the outcome. The
            dataclass is truthy iff the notification was actually sent,
            so legacy ``if manager.send_notification(...):`` callers
            continue to work without source changes.

        Raises:
            RateLimitError: If rate limit is exceeded and force=False
        """
        logger.debug(
            f"Sending notification: event_type={event_type.value}, "
            f"user_id={self._user_id}, force={force}"
        )
        logger.debug(f"Context keys: {list(context.keys())}")

        # Server-level master switch (env-only). Disabled by default;
        # flipping it on is the operator's acknowledgement of the
        # documented SSRF rebinding residual risk. force=True does NOT
        # bypass this — it bypasses the per-user event-type and
        # rate-limit toggles only. WARNING level so an operator wondering
        # "why aren't notifications firing?" sees the actionable signal
        # at default log level.
        if not self._outbound_allowed:
            logger.warning(
                "Notification refused: outbound notifications are disabled "
                "at the server level. Set "
                "LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true to enable. See "
                "SECURITY.md 'Notification Webhook SSRF' for the rationale "
                "and residual risk. (event={}, user={})",
                event_type.value,
                self._user_id,
            )
            return NotificationResult(
                sent=False,
                reason=NotificationReason.SERVER_DISABLED,
                detail=(
                    "outbound notifications are disabled at the server "
                    "level (LDR_NOTIFICATIONS_ALLOW_OUTBOUND)"
                ),
            )

        # Check if notifications are enabled for this event type
        should_notify = self._should_notify(event_type)
        logger.debug(
            f"Notification enabled check for {event_type.value}: "
            f"{should_notify}"
        )

        if not force and not should_notify:
            logger.debug(
                f"Notifications disabled for event type: "
                f"{event_type.value} (user: {self._user_id})"
            )
            return NotificationResult(
                sent=False,
                reason=NotificationReason.EVENT_DISABLED,
                detail=f"notifications.on_{event_type.value} is off",
            )

        # Check rate limit using the manager's user_id
        rate_limit_ok = self._rate_limiter.is_allowed(self._user_id)
        logger.debug(f"Rate limit check for {self._user_id}: {rate_limit_ok}")

        if not force and not rate_limit_ok:
            logger.warning(f"Rate limit exceeded for user {self._user_id}")
            raise RateLimitError(
                "Notification rate limit exceeded. "
                "Please wait before sending more notifications."
            )

        try:
            # Get service URLs from settings (snapshot or database)
            service_urls = self._get_setting(
                "notifications.service_url", default=""
            )

            if not service_urls or not service_urls.strip():
                logger.debug(
                    f"No notification service URLs configured for user "
                    f"{self._user_id}"
                )
                return NotificationResult(
                    sent=False,
                    reason=NotificationReason.UNCONFIGURED,
                    detail="notifications.service_url is not configured",
                )

            # Reject an unparseable service URL (missing scheme, or a
            # scheme-less fragment trailing a valid one) before consulting
            # the egress policy at all. `_filter_urls_by_egress_policy`
            # also refuses this case (returns ""), which — if reported
            # here as EGRESS_DENIED — would falsely claim the policy was
            # consulted and refused it, when it was never evaluated. This
            # is a genuinely invalid configuration, not a policy denial —
            # see issue #5110.
            url_entries, invalid_fragment = parse_notification_url_list(
                service_urls
            )
            if invalid_fragment is not None:
                # Log NOTHING derived from the fragment's content — not
                # even a redacted form. ``redact_url_for_log`` keeps
                # ``scheme://host``, but for the token-in-authority
                # Apprise schemes the first authority segment IS the
                # secret (``slack://xoxb-SECRET/T00/B00`` redacts to
                # ``slack://xoxb-SECRET``), and a fragment can be the
                # whole entry when the illegal character only trails it.
                # The fragment's length and the parsed-entry count are
                # enough to diagnose the misconfiguration. They are
                # rendered into the message with positional placeholders:
                # loguru kwargs with no template placeholder reach no
                # production sink (stderr, log file, database) — #5619.
                # The user id and event type are rendered too; this module
                # already renders both in its other warnings.
                logger.bind(policy_audit=True).warning(
                    "notification dropped: unparseable service URL "
                    "fragment (fragment_length={}, entries_parsed={}, "
                    "user={}, event={})",
                    len(invalid_fragment),
                    len(url_entries),
                    self._user_id,
                    event_type.value,
                )
                return NotificationResult(
                    sent=False,
                    reason=NotificationReason.INVALID_URL,
                    detail=(
                        "a configured service URL could not be parsed "
                        "(missing scheme, or an unencoded space, "
                        "backslash or control character)"
                    ),
                )

            if not url_entries:
                # A nonempty setting that parses to zero URLs —
                # separator characters only, e.g. "," — never reaches
                # the policy's per-URL loop, so the egress branch below
                # would report "all configured URLs refused" for a
                # refusal that never happened. Invalid configuration,
                # same class as a scheme-less fragment — issue #5110.
                logger.bind(policy_audit=True).warning(
                    "notification dropped: service URL setting contains "
                    "no parseable URLs",
                    user=self._user_id,
                    event=event_type.value,
                )
                return NotificationResult(
                    sent=False,
                    reason=NotificationReason.INVALID_URL,
                    detail=(
                        "notifications.service_url contains no parseable URLs"
                    ),
                )

            # Egress policy: each URL is classified by the endpoint Apprise
            # will contact. HTTP URLs and authority-bearing plugins are
            # checked with evaluate_url against that host; fixed vendor
            # endpoints (Matrix t2bot included) are refused under
            # PRIVATE_ONLY only, and mailto plus Matrix homeserver/webhook
            # modes under PRIVATE_ONLY and STRICT (see
            # _filter_urls_by_egress_policy).
            # No separator is passed here, so this parses/rejoins with the
            # default ",". If a non-default separator is ever exposed to
            # callers, it must be passed here too and to service.send_event
            # below — otherwise the two calls disagree on where one URL
            # ends and the next begins, and the joined output the service
            # re-parses merges two entries into one (losing a destination,
            # not gaining one).
            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(
                    "notification dropped: {}",
                    detail,
                    user=self._user_id,
                    event=event_type.value,
                )
                return NotificationResult(
                    sent=False,
                    reason=NotificationReason.EGRESS_DENIED,
                    detail=detail,
                )

            # Send notification with the allowed subset. No separator is
            # passed here either, so this must keep agreeing with the
            # default "," used above to build allowed_urls — see the
            # comment on the _filter_urls_by_egress_policy call.
            logger.debug(f"Calling service.send_event for {event_type.value}")
            sent = self.service.send_event(
                event_type, context, service_urls=allowed_urls
            )

            # Log to database if enabled
            if sent:
                self._log_notification(event_type, context)
                logger.info(
                    f"Notification sent: {event_type.value} to user "
                    f"{self._user_id}"
                )
                return NotificationResult(
                    sent=True,
                    reason=NotificationReason.SENT,
                    detail="",
                )
            # A falsy return from send_event means Apprise rejected a
            # service URL (temp_apprise.add() failed — unparseable or
            # unsupported scheme) in one of the scheme partitions
            # NotificationService._dispatch builds. NOT "none of the
            # URLs": _dispatch returns False on the FIRST partition whose
            # add() fails, before attempting any later partition — so a
            # mixed configuration (e.g. one malformed http(s) URL plus a
            # valid json:// URL) is reported here even though the valid
            # partition was never tried. 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 rejected a configured "
                f"service URL before dispatch completed"
            )
            return NotificationResult(
                sent=False,
                reason=NotificationReason.INVALID_URL,
                detail=(
                    "Apprise rejected a configured service URL before "
                    "dispatch completed"
                ),
            )

        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 regardless: SendError's own raise site
            # (NotificationService._send_with_retry) uses a fixed message
            # with no interpolated URL/token today, but this except clause
            # also logs the exception via logger.exception above — a
            # static, non-interpolated detail here keeps that guarantee
            # independent of what any future SendError raise site puts in
            # its message.
            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="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:
            # 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}"
            )
            return NotificationResult(
                sent=False,
                reason=NotificationReason.EXCEPTION,
                detail=f"unexpected {type(exc).__name__} while sending",
            )

    def test_service(self, url: str) -> Dict[str, Any]:
        """
        Test a notification service.

        Args:
            url: Service URL to test

        Returns:
            Dict with test results

        Note:
            Nothing in ``src/`` currently calls this method — the live
            ``POST /api/notifications/test-url`` route constructs a
            ``NotificationService`` directly and never goes through
            ``NotificationManager``, so the egress-policy precheck below
            is not applied to that endpoint (see issue #5110 follow-up
            discussion). Only test suites exercise this method today.
        """
        # Classify an unusable URL the same way ``send_notification``
        # now does, BEFORE consulting the egress policy.
        # ``_filter_urls_by_egress_policy`` returns ``""`` for three
        # different things — an unparseable fragment, zero parseable
        # entries, and a genuine per-URL policy refusal — so mapping
        # every ``""`` onto the "Set Egress Scope to 'Unprotected'"
        # remediation tells the operator to widen a policy that was
        # never consulted (issue #5110 / #5113 follow-up). Parse here so
        # the first two are reported as invalid configuration and the
        # egress message is reserved for a real refusal.
        url_entries, invalid_fragment = parse_notification_url_list(url)
        if invalid_fragment is not None:
            # Log NOTHING derived from the fragment's content, not even
            # a redacted form — see the identical branch in
            # ``send_notification`` for why ``scheme://host`` is still
            # the secret for token-in-authority Apprise schemes. The
            # content-free diagnostics are rendered into the message, as
            # there (#5619).
            logger.bind(policy_audit=True).warning(
                "test notification refused: unparseable service URL "
                "fragment (fragment_length={}, entries_parsed={})",
                len(invalid_fragment),
                len(url_entries),
            )
            return {
                "status": "error",
                "message": (
                    "Service URL could not be parsed (missing scheme, or "
                    "an unencoded space, backslash or control character)."
                ),
            }
        if not url_entries:
            return {
                "status": "error",
                "message": "Service URL contains no parseable URLs.",
            }

        # Egress policy precheck before forwarding to Apprise. NOT
        # currently reached by any live route — see the Note above.
        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 — the
            # "Set Egress Scope to 'Unprotected'" remediation below
            # fixes the wrong thing. Same distinction send_notification
            # draws between "refused every URL" and "could not be
            # evaluated".
            return {
                "status": "error",
                "message": (
                    "Egress policy could not be evaluated; check the "
                    "egress policy settings (policy.egress_scope)."
                ),
            }
        if not allowed:
            # Reached only for a real per-URL refusal now: the fragment
            # and zero-entry cases returned above.
            return {
                "status": "error",
                "message": (
                    "URL refused by egress policy. Set Egress Scope to "
                    "'Unprotected' (or pick a local webhook) to test this URL."
                ),
            }
        return self.service.test_service(allowed)

    def _filter_urls_by_egress_policy(
        self, service_urls: str, separator: str = ","
    ) -> Optional[str]:
        """Filter an Apprise URL string by the user's egress policy.

        Default comma input preserves commas inside one service URL and is
        canonicalized to whitespace-separated output. Custom-separated input
        retains its caller-provided separator for the service to consume.
        Returns the joined allowed URLs (possibly empty if every URL was
        refused), or ``None`` when the policy 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,
        return the input unchanged for backwards compatibility.
        """
        if not isinstance(separator, str) or not separator:
            raise ValueError("separator must be a non-empty string")
        snapshot = getattr(self, "_settings_snapshot", None)
        if not snapshot:
            return service_urls

        url_entries, invalid_fragment = parse_notification_url_list(
            service_urls, separator
        )
        if invalid_fragment is not None:
            # Same rule as the identical branches in
            # ``send_notification`` and ``test_service`` (both parse
            # first and return before calling this method, so this
            # branch only fires for a direct caller): never log anything
            # derived from the fragment's content. Even the redacted
            # ``scheme://host`` form leaks the secret for token-in-
            # authority Apprise schemes, and the fragment may be the
            # entire entry. The content-free diagnostics are rendered
            # into the message with positional placeholders, as at those
            # sites — loguru kwargs with no template placeholder never
            # appear in any production sink's output (#5619).
            logger.bind(policy_audit=True).warning(
                "all notification URLs refused: unparseable URL "
                "fragment (fragment_length={}, entries_parsed={})",
                len(invalid_fragment),
                len(url_entries),
            )
            return ""

        try:
            from ..security.egress.policy import (
                EgressScope,
                PolicyDeniedError,
                context_from_snapshot,
                evaluate_url,
                resolve_run_primary_engine,
            )
        except ImportError:
            logger.debug(
                "egress_policy unavailable in notifications manager; "
                "URLs will not be scope-gated"
            )
            return service_urls

        try:
            ctx = context_from_snapshot(
                snapshot,
                resolve_run_primary_engine(
                    snapshot, default=DEFAULT_SEARCH_TOOL
                ),
                # Queue snapshots need not carry identity metadata. Resolve
                # private retrievers in the notification owner's namespace.
                username=self._user_id,
            )
        except (PolicyDeniedError, ValueError) as exc:
            # Snapshot present but policy cannot be evaluated. The
            # previous bare-except dropped to "return service_urls"
            # here, which dispatched every URL unfiltered — fail-open
            # on a misconfigured policy. Now refuse all URLs instead
            # so an Apprise dispatch with no scope check is impossible.
            logger.bind(policy_audit=True).warning(
                "all notification URLs refused: egress policy could "
                "not be evaluated",
                reason=str(exc),
            )
            return None

        # Classify the endpoint Apprise will contact. Authority-bearing
        # plugins must obey the same user egress scope as an HTTP webhook;
        # token-based vendor plugins (Matrix t2bot and ntfy cloud included)
        # are refused in PRIVATE_ONLY and pass every other scope.
        parts = []
        for url_entry in url_entries:
            try:
                destination = parse_notification_destination(url_entry)
            except NotificationDestinationError:
                # Preserve the invalid-URL outcome: the service validator
                # will reject this entry before Apprise sees it. Dropping it
                # here would misreport a malformed URL as an egress refusal.
                parts.append(url_entry)
                continue
            if destination.kind is NotificationDestinationKind.VENDOR_PLUGIN:
                if ctx.scope == EgressScope.PRIVATE_ONLY:
                    logger.bind(policy_audit=True).warning(
                        "notification vendor destination refused under "
                        "PRIVATE_ONLY egress scope"
                    )
                    continue
                parts.append(url_entry)
                continue
            # Mail and Matrix homeserver/webhook URLs are refused under
            # PRIVATE_ONLY and STRICT whatever their host. Apprise's mail
            # plugin can connect to a built-in provider's fixed SMTP host
            # instead of the URL authority. The Matrix refusal is
            # conservative: Apprise runs server discovery only for
            # ``matrixs://``, which the classifier rejects, so ``matrix://``
            # sends to its URL host. Matrix t2bot is a VENDOR_PLUGIN and was
            # handled above (refused only under PRIVATE_ONLY).
            scheme = url_entry.split(":", 1)[0].lower()
            if scheme in {"matrix", "mailto"} and ctx.scope in {
                EgressScope.PRIVATE_ONLY,
                EgressScope.STRICT,
            }:
                logger.bind(policy_audit=True).warning(
                    "notification destination refused: dynamic endpoint "
                    "cannot be verified local",
                    scheme=scheme,
                )
                continue
            if destination.kind is NotificationDestinationKind.HTTP:
                policy_url = url_entry
            else:
                effective_host = destination.effective_host
                if not effective_host:
                    continue
                policy_host = (
                    f"[{effective_host}]"
                    if ":" in effective_host
                    else effective_host
                )
                policy_url = urlunsplit(("http", policy_host, "", "", ""))
            try:
                decision = evaluate_url(policy_url, ctx)
            except (
                AttributeError,
                ImportError,
                RuntimeError,
                TypeError,
                ValueError,
            ) as exc:
                logger.bind(policy_audit=True).warning(
                    "notification URL refused: egress policy evaluation failed",
                    reason=type(exc).__name__,
                )
                continue
            if decision.allowed:
                parts.append(url_entry)
            else:
                audit = logger.bind(policy_audit=True)
                if destination.kind is NotificationDestinationKind.HTTP:
                    audit = audit.bind(url=redact_url_for_log(url_entry))
                audit.warning(
                    "notification URL refused by egress policy",
                    scope=ctx.scope.value,
                    reason=decision.reason,
                )
        # Rejoin with the caller's separator so the filtered output stays
        # parseable by the same rule it was parsed with. If a non-default
        # separator is ever exposed to callers, it must be threaded through
        # every call site that reaches this method (see send_notification's
        # _filter_urls_by_egress_policy call and its service.send_event call
        # above) — a desync here does not add a destination, it MERGES two
        # entries into one unparseable one and silently loses a destination.
        joiner = " " if separator == "," else separator
        return joiner.join(parts)

    def _should_notify(self, event_type: EventType) -> bool:
        """
        Check if notifications should be sent for this event type.

        Uses the manager's settings snapshot to determine if the event type
        is enabled for the user.

        Args:
            event_type: Event type to check

        Returns:
            True if notifications should be sent
        """
        try:
            # Check event-specific setting (from snapshot or database)
            setting_key = f"notifications.on_{event_type.value}"
            enabled = self._get_setting(setting_key, default=False)

            return bool(enabled)

        except Exception:
            logger.warning("Error checking notification preferences")
            # Default to disabled on error to avoid infinite loops during login
            return False

    def _log_notification(
        self, event_type: EventType, context: Dict[str, Any]
    ) -> None:
        """
        Log a sent notification (simplified logging to application logs only).

        Uses the manager's user_id for logging.

        Args:
            event_type: Event type
            context: Notification context
        """
        try:
            title = (
                context.get("query")
                or context.get("subscription_name")
                or "Unknown"
            )
            logger.info(
                f"Notification sent: {event_type.value} - {title} "
                f"(user: {self._user_id})"
            )
        except Exception as e:
            logger.debug(f"Failed to log notification: {e}")


class RateLimiter:
    """
    Simple in-memory rate limiter for notifications with per-user limit support.

    This rate limiter tracks notification counts per user and enforces
    configurable rate limits. Each user can have their own rate limits,
    which are stored separately from the notification counts.

    **Per-User Limits:**
    Rate limits can be configured per-user using `set_user_limits()`.
    If no user-specific limits are set, the default limits (passed to
    __init__) are used.

    **Memory Storage:**
    This implementation stores rate limits in memory only, which means
    limits are reset when the server restarts. This is acceptable for normal
    users since they cannot restart the server. If an admin restarts the server,
    rate limits reset which is reasonable behavior.

    **Thread Safety:**
    This implementation is thread-safe using threading.Lock() for concurrent
    requests from the same user.

    **Multi-Worker Limitation:**
    In multi-worker deployments, each worker process maintains its own rate
    limit counters. Users could potentially bypass rate limits by distributing
    requests across different workers, getting up to N × max_per_hour
    notifications (where N = number of workers). For single-worker deployments
    (the default for LDR), this is not a concern. For production multi-worker
    deployments, consider implementing Redis-based rate limiting.

    Example:
        >>> limiter = RateLimiter(max_per_hour=10, max_per_day=50)
        >>> # Set custom limits for specific user
        >>> limiter.set_user_limits("user_a", max_per_hour=5, max_per_day=25)
        >>> limiter.set_user_limits("user_b", max_per_hour=20, max_per_day=100)
        >>> # Users get their configured limits
        >>> limiter.is_allowed("user_a")  # Limited to 5/hour
        >>> limiter.is_allowed("user_b")  # Limited to 20/hour
        >>> limiter.is_allowed("user_c")  # Uses defaults: 10/hour
    """

    def __init__(
        self,
        max_per_hour: int = 10,
        max_per_day: int = 50,
        cleanup_interval_hours: int = 24,
    ):
        """
        Initialize rate limiter with default limits.

        Args:
            max_per_hour: Default maximum notifications per hour per user
            max_per_day: Default maximum notifications per day per user
            cleanup_interval_hours: How often to run cleanup of inactive users (hours)
        """
        # Default limits used when no user-specific limits are set
        self.max_per_hour = max_per_hour
        self.max_per_day = max_per_day
        self.cleanup_interval_hours = cleanup_interval_hours

        # Per-user rate limit configuration (user_id -> (max_per_hour, max_per_day))
        self._user_limits: Dict[str, tuple[int, int]] = {}

        # Per-user notification counts
        self._hourly_counts: Dict[str, deque] = {}
        self._daily_counts: Dict[str, deque] = {}

        self._last_cleanup = datetime.now(timezone.utc)
        self._lock = threading.Lock()  # Thread safety for all operations

    def set_user_limits(
        self, user_id: str, max_per_hour: int, max_per_day: int
    ) -> None:
        """
        Set rate limits for a specific user.

        This allows each user to have their own rate limit configuration.
        If not set, the user will use the default limits passed to __init__.

        Args:
            user_id: User identifier
            max_per_hour: Maximum notifications per hour for this user
            max_per_day: Maximum notifications per day for this user

        Example:
            >>> limiter = RateLimiter(max_per_hour=10, max_per_day=50)
            >>> limiter.set_user_limits("power_user", max_per_hour=20, max_per_day=100)
            >>> limiter.set_user_limits("limited_user", max_per_hour=5, max_per_day=25)
        """
        with self._lock:
            self._user_limits[user_id] = (max_per_hour, max_per_day)
            logger.debug(
                f"Set rate limits for user {user_id}: "
                f"{max_per_hour}/hour, {max_per_day}/day"
            )

    def get_user_limits(self, user_id: str) -> tuple[int, int]:
        """
        Get the effective rate limits for a user.

        Returns the user-specific limits if set, otherwise returns defaults.

        Args:
            user_id: User identifier

        Returns:
            Tuple of (max_per_hour, max_per_day)
        """
        with self._lock:
            return self._user_limits.get(
                user_id, (self.max_per_hour, self.max_per_day)
            )

    def is_allowed(self, user_id: str) -> bool:
        """
        Check if a notification is allowed for a user.

        Uses per-user rate limits if configured via set_user_limits(),
        otherwise uses the default limits from __init__.

        Args:
            user_id: User identifier

        Returns:
            True if notification is allowed, False if rate limit exceeded
        """
        with self._lock:
            now = datetime.now(timezone.utc)

            # Periodic cleanup of inactive users
            self._cleanup_inactive_users_if_needed(now)

            # Initialize queues for user if needed
            if user_id not in self._hourly_counts:
                self._hourly_counts[user_id] = deque()
                self._daily_counts[user_id] = deque()

            # Clean old entries
            self._clean_old_entries(user_id, now)

            # Get user-specific limits or defaults
            max_per_hour, max_per_day = self._user_limits.get(
                user_id, (self.max_per_hour, self.max_per_day)
            )

            # Check limits
            hourly_count = len(self._hourly_counts[user_id])
            daily_count = len(self._daily_counts[user_id])

            if hourly_count >= max_per_hour:
                logger.warning(
                    f"Hourly rate limit exceeded for user {user_id}: "
                    f"{hourly_count}/{max_per_hour}"
                )
                return False

            if daily_count >= max_per_day:
                logger.warning(
                    f"Daily rate limit exceeded for user {user_id}: "
                    f"{daily_count}/{max_per_day}"
                )
                return False

            # Record this notification
            self._hourly_counts[user_id].append(now)
            self._daily_counts[user_id].append(now)

            return True

    def _clean_old_entries(self, user_id: str, now: datetime) -> None:
        """
        Remove old entries from rate limit counters.

        Args:
            user_id: User identifier
            now: Current time
        """
        hour_ago = now - timedelta(hours=1)
        day_ago = now - timedelta(days=1)

        # Clean hourly queue
        while (
            self._hourly_counts[user_id]
            and self._hourly_counts[user_id][0] < hour_ago
        ):
            self._hourly_counts[user_id].popleft()

        # Clean daily queue
        while (
            self._daily_counts[user_id]
            and self._daily_counts[user_id][0] < day_ago
        ):
            self._daily_counts[user_id].popleft()

    def reset(self, user_id: Optional[str] = None) -> None:
        """
        Reset rate limits for a user or all users.

        Args:
            user_id: User to reset, or None for all users
        """
        with self._lock:
            if user_id:
                self._hourly_counts.pop(user_id, None)
                self._daily_counts.pop(user_id, None)
            else:
                self._hourly_counts.clear()
                self._daily_counts.clear()

    def _cleanup_inactive_users_if_needed(self, now: datetime) -> None:
        """
        Periodically clean up data for inactive users to prevent memory leaks.

        Args:
            now: Current timestamp
        """
        # Check if cleanup is needed
        if now - self._last_cleanup < timedelta(
            hours=self.cleanup_interval_hours
        ):
            return

        logger.debug("Running periodic cleanup of inactive notification users")

        # Define inactive threshold (users with no activity for 7 days)
        inactive_threshold = now - timedelta(days=7)

        inactive_users = []

        # Find users with no recent activity
        # Convert to list to avoid "dictionary changed size during iteration" error
        for user_id in list(self._hourly_counts.keys()):
            # Check if user has any recent entries
            hourly_entries: list = list(self._hourly_counts.get(user_id, []))
            daily_entries: list = list(self._daily_counts.get(user_id, []))

            # If no entries or all entries are old, mark as inactive
            has_recent_activity = False
            for entry in hourly_entries + daily_entries:
                if entry > inactive_threshold:
                    has_recent_activity = True
                    break

            if not has_recent_activity:
                inactive_users.append(user_id)

        # Remove inactive users
        for user_id in inactive_users:
            self._hourly_counts.pop(user_id, None)
            self._daily_counts.pop(user_id, None)
            logger.debug(
                f"Cleaned up inactive user {user_id} from rate limiter"
            )

        if inactive_users:
            logger.info(
                f"Cleaned up {len(inactive_users)} inactive users from rate limiter"
            )

        self._last_cleanup = now