Notification Service

Implementation reference for the notification-service. For its architectural role, see Notification Service Architecture; for the domain model, see Alerting.

A Node.js / Express service. It receives candidate alert events, debounces them, resolves recipients, and delivers through two channels: an in-app event over the Redis broker and a Web Push to registered devices.

Source Layout

graph TD
    ROUTER["router.ts"] --> CTRL["controller/notificationController.ts\nthrottle, request normalisation"]
    CTRL --> NSV["services/notificationService.ts\nRedis publish"]
    CTRL --> PSV["services/pushService.ts\nWeb Push, preferences, cleanup"]
    PSV --> M1["models/webSubscription.ts"]
    PSV --> M2["models/notificationSubscription.ts"]
    NSV --> REDIS["config/redis.ts"]
    PSV --> REDIS

Configuration

Data Model

Two collections, kept separate by design (see Alerting.

// webSubscription.ts — "where can I reach this account?"
interface IWebPushSubscription {
  accountName: string;          // indexed
  endpoint: string;             // unique
  keys: { p256dh: string; auth: string };
}
// compound unique index { accountName, endpoint }

// notificationSubscription.ts — "what does this account want?"
interface INotificationSubscription {
  accountName: string;
  domainName: string;
  preferences: { notificationType: NotificationType; isSubscribed: boolean }[];
  createdAt: Date;
}
// compound unique index { accountName, domainName }

enum NotificationType { TEMPERATURE = "temperature" }

A single account may own several WebPushSubscription records (one per device) but exactly one NotificationSubscription per domain.

HTTP API

Request bodies accept the canonical domainName field and the deprecated alias domainId. The account is always taken from the verified JWT, never from a body accountName/userId or the URL param — this closed an IDOR on GET /preferences/:accountName. Preferences may be supplied as a single { type, enabled }, a types[] array with one enabled, or a granular preferences[] array.

The Temperature-Alert Throttle

The sensor-service fires on every reading (~every 10 s). To avoid a storm of identical alerts, pushTemperatureAlert debounces per room using a Redis key with a fixed TTL.

sequenceDiagram
    autonumber
    participant SS as sensor-service
    participant NS as notification-service
    participant R as Redis
    participant TW as twin-service
    SS->>NS: POST /push/temperature { buildingId, roomId, temperature }
    NS->>R: GET temp_alert:{buildingId}:{roomId}
    alt cooldown active
        R-->>NS: "1"
        NS-->>SS: 200 (silently throttled)
    else first alert / expired
        opt domain not supplied
            NS->>TW: GET /twin/domain/:buildingId
            TW-->>NS: domain names
        end
        Note over NS: publish "notifications" + Web Push to opted-in recipients
        NS->>R: SET temp_alert:{buildingId}:{roomId} "1" EX 300
        NS-->>SS: 200 (dispatched)
    end

The key is temp_alert:{buildingId}:{roomId}; the cooldown is 300 seconds. After it expires, the next breach starts a new cycle.

Recipient Resolution and Delivery

pushService separates who to notify from how to reach them.

• sendPushToDomain(payload, domainName, type) queries NotificationSubscription for records in the domain whose preferences contain an enabled entry for type ($elemMatch), reduces to a unique set of account names, and delegates to sendPushToUsers.
• sendPushToUsers(payload, accountNames) loads every WebPushSubscription for those accounts and sends the encrypted payload to each endpoint via web-push.
• The in-app channel is independent: publishNotification posts { id, message, type, timestamp, domainName? } to the Redis notifications channel, which the socket-service relays to browsers.

Preference upserts

setUserNotificationPreference is idempotent per type: it first $pulls any existing entry for that notificationType, then $pushes the new { notificationType, isSubscribed }, using $setOnInsert to create the document on first write.

Stale-subscription cleanup

When web-push returns 410 Gone or 403 Forbidden, the endpoint is permanently invalid and the subscription is deleted automatically (Subscription.deleteOne({ endpoint })). All other errors (network, 5xx) are logged but leave the subscription intact, as they may be transient.

Error Handling

The service uses the shared BaseError hierarchy and global error middleware (see Node Auth & Error Middleware. Missing accountName/domainName and malformed push payloads raise ValidationError (400); a failed twin lookup surfaces as a 500.