Notification Connection Modes

The notification system supports two transport modes for delivering in-app notifications: WebSocket subscriptions (primary) and HTTP polling (fallback). The notificationStore automatically attempts WebSocket first and degrades gracefully to polling if the subscription server is unreachable.

Architecture Overview

┌─────────────┐  graphql-ws   ┌──────────────────┐
│  Frontend   │ ◄════════════►│  Hive Gateway    │
│  NotifStore │  onNotification│  (port 30000)    │
│             │  (Subscription)│  GraphQL Yoga    │
│  🟢 live    │               └────────┬─────────┘
└──────┬──────┘                        │
       │                          federation
       │ HTTP queries/mutations        │
       │                               ▼
       │                        ┌──────────────────┐
       │                        │ Alerts Subgraph  │
       │                        │ (port 3025)      │
       └───────────────────────►│ YogaFederation   │
                                │   Driver         │
                                └──────────────────┘

Unified Server Architecture

With the migration to Hive Gateway and the YogaFederationDriver, GraphQL subscriptions are natively supported through the federated subgraph. The previous dual-server architecture (federation on port 3025 + standalone WS on port 3027) has been eliminated.

The frontend connects to the same /graphql endpoint for both HTTP queries and WebSocket subscriptions. The Vite dev proxy forwards both protocols to the gateway on port 30000.

Primary Mode: WebSocket Subscriptions

Backend: PubSub Pipeline

When AlertDeliveryService.sendInApp() creates an IN_APP notification:

// alert-delivery.service.ts
await this.dlqService.markDelivered(log.id);

// Publish to WebSocket subscribers for real-time delivery
const enrichedLog = await this.dlqService.findById(log.id);
if (enrichedLog) {
  notificationPubSub.publish(NOTIFICATION_ADDED, {
    onNotification: enrichedLog,
  });
}

The notificationPubSub is an in-process PubSub instance from graphql-subscriptions. The subscription resolver on the WS server filters events by userId:

// notification-subscription.resolver.ts
@Subscription(() => AlertLog, {
  filter: (payload, _variables, context) => {
    const subscribedUserId = context.req?.headers?.['x-user-id'];
    return payload.onNotification.userId === subscribedUserId;
  },
})
onNotification(): AsyncIterator<AlertLog> {
  return notificationPubSub.asyncIterator(NOTIFICATION_ADDED);
}

Frontend: graphql-ws Client

The notificationStore connects to the gateway via the standard GraphQL endpoint. No explicit auth configuration is needed — the browser automatically sends the session cookie on the WebSocket upgrade request:

// WS through the same /graphql endpoint as queries
const WS_URL = `ws://${window.location.host}/graphql`;

const wsClient = createClient({
  url: WS_URL,
  // No connectionParams needed — session cookie is sent automatically
  // on same-origin WebSocket upgrade requests
  retryAttempts: MAX_WS_RETRIES, // 3
  retryWait: async (retries) => {
    const delay = Math.min(1000 * Math.pow(2, retries), 30_000);
    await new Promise((r) => setTimeout(r, delay));
  },
});

When a notification arrives via the subscription, it is immediately prepended to the local notifications array with deduplication by ID.

Subscription Document

subscription OnNotification {
  onNotification {
    id
    title
    subject
    eventType
    href
    readAt
    createdAt
    payload
  }
}

Fallback Mode: HTTP Polling

If the WebSocket connection fails after 3 retries, the store degrades to 30-second HTTP polling:

startPolling()
  → fetchNotifications() (initial)
  → upgradeToWebSocket()
    → SUCCESS → connectionMode = 'websocket', stop polling
    → FAIL (3 retries) → fallbackToPolling()
      → connectionMode = 'polling'
      → setInterval(fetchUnreadCount, 30_000)

Connection State Machine

type ConnectionMode = 'polling' | 'websocket';
type ConnectionStatus = 'connected' | 'disconnected' | 'reconnecting';

          startPolling()        upgradeToWebSocket()
              │                        │
              ▼                        ▼
  ┌───────────────────┐    ┌───────────────────┐
  │  polling +        │    │  websocket +      │
  │  connected        │◄───│  connected        │
  └───────────────────┘    └───────────────────┘
              ▲                   │    ▲
   fallbackToPolling()       ws error  │ reconnect
                                 │    │
                                 ▼    │
                          ┌───────────────────┐
                          │  websocket +      │
                          │  reconnecting     │
                          └───────────────────┘
                                 │
                          max retries (3)
                                 │
                                 ▼
                          fallbackToPolling()

Authentication Model

How It Works

1. The browser sends the session cookie automatically on the WebSocket upgrade request (same-origin)
2. The gateway's onConnect hook (ws-auth.ts) extracts the cookie header from the initial HTTP upgrade request
3. The cookie is validated against the auth service (POST /auth/validate)
4. Valid session → connection accepted, user identity stored in ctx.extra.user
5. Invalid/missing session → connection rejected at the transport layer (4403 Forbidden)

The subscription resolver then filters events using the x-user-id header, which is populated by the gateway's auth context from the validated session — identical to the HTTP GraphQL auth flow.

// ws-auth.ts — onConnect hook
onConnect: async (ctx) => {
  const cookie = ctx.extra?.request?.headers?.cookie;
  if (!cookie) return false; // reject: no cookie

  const user = await validateWsSession(cookie, authBaseUrl);
  if (!user) return false; // reject: invalid session

  ctx.extra.user = user; // store for subscription context
  return true;
}

Scaling Path

The current in-process PubSub works for a single alerts instance. For horizontal scaling (multiple replicas):

1. Replace graphql-subscriptions PubSub with graphql-redis-subscriptions
2. Point it at the existing Redis infra (REDIS_URL)
3. All instances will share the event bus

UI: Connection Indicator

The NotificationCenter.svelte dropdown footer displays a connection mode badge:

Feature Flag

// notificationStore.svelte.ts
export const WEBSOCKET_READY = true;

To disable WebSocket mode (e.g., during debugging), set WEBSOCKET_READY = false. The store will immediately fall back to HTTP polling.

Testing

Migration History

The original architecture (pre-April 2026) used a dual-server topology because Apollo Federation Driver (@nestjs/apollo ApolloFederationDriver) did not support GraphQL subscriptions. A separate non-federated WS server ran on port 3027 using the standard ApolloDriver.

With the migration to Hive Gateway + YogaFederationDriver, subscriptions are natively supported through the federated subgraph, and the standalone WS server has been retired. See Gateway (Hive Gateway) for the full migration details.

Related

• Mobile Push Infrastructure — In-house APNs/FCM push dispatch and native push registration flows
• Alerts Resilience — Backend DLQ, AlertLog entity, and delivery orchestration
• Alerts & Notifications — Notification center UI, toast system, and preference management
• Invite Notification Pipeline — Organization invite → notification flow