Realtime WebSocket Notifications

Production-ready Spring Boot application for real-time, user-targeted notifications over WebSocket/STOMP. Features user-specific queues, simple subscription APIs, and a minimal HTML client for testing.

Overview

• Real-time server-to-client push using WebSocket/STOMP
• Per-user delivery via /user/queue/notifications
• Simple REST endpoints to manage subscriptions and publish channel events
• MongoDB integration (repositories defined, persistence toggled in code)

Entry point: com.developersuraj.realtimenotifications.RealTimeNotificationsApplication

Architecture

• WebSocket/STOMP config: com.developersuraj.realtimenotifications.config.WebSocketConfig
  • Endpoint: /ws (SockJS enabled)
  • Broker: /topic, /queue
  • User destination prefix: /user
  • Principal mapping via STOMP login header
• REST controllers:
  • Subscriptions: com.developersuraj.realtimenotifications.controller.SubscriptionController
  • Notifications: com.developersuraj.realtimenotifications.controller.NotificationController
• Services:
  • Notifications: com.developersuraj.realtimenotifications.service.NotificationService
  • Subscriptions: com.developersuraj.realtimenotifications.service.SubscriptionService
  • WebSocket events: com.developersuraj.realtimenotifications.service.WebSocketEventListener
• Data layer:
  • com.developersuraj.realtimenotifications.repo.SubscriptionRepo
  • com.developersuraj.realtimenotifications.repo.NotificationRepository
• DTOs:
  • com.developersuraj.realtimenotifications.dto.SubscriptionRequest
  • com.developersuraj.realtimenotifications.dto.ChannelEvent
  • com.developersuraj.realtimenotifications.dto.NotificationDto
  • com.developersuraj.realtimenotifications.dto.Subscription
  • com.developersuraj.realtimenotifications.dto.Nofitication
  • com.developersuraj.realtimenotifications.dto.Channel
  • com.developersuraj.realtimenotifications.dto.User

Client UI: src/main/resources/static/index.html
Config: src/main/resources/application.properties
Build: pom.xml

Prerequisites

• Java 21
• MongoDB running at localhost:27017 (default DB: test)
• Port 8080 available

Setup

• Install dependencies offline:

  ./mvnw -q dependency:go-offline

• Configure application properties:

  • Edit src/main/resources/application.properties

Build & Run

# Windows (PowerShell / CMD)
./mvnw.cmd spring-boot:run

# macOS/Linux
./mvnw spring-boot:run

Access demo UI: http://localhost:8080/index.html
Or open src/main/resources/static/index.html directly.

How It Works

• The client connects to /ws (SockJS) and sets STOMP login header to the numeric userId.
• com.developersuraj.realtimenotifications.config.WebSocketConfig maps that header to a Principal.
• Server sends per-user messages via NotificationService.convertAndSendToUser.
• Client listens on /user/queue/notifications.

API

• Subscribe a user to a channel:

  # POST /api/subscriptions/subscribe
  curl -X POST http://localhost:8080/api/subscriptions/subscribe \
    -H "Content-Type: application/json" \
    -d '{"userId":1,"channelId":42}'

  Payload: com.developersuraj.realtimenotifications.dto.SubscriptionRequest

• Publish a channel event (broadcast to subscribers):

  # POST /api/notifications/publish
  curl -X POST http://localhost:8080/api/notifications/publish \
    -H "Content-Type: application/json" \
    -d '{"channelId":42,"videoId":"abc123","videoTitle":"Intro to WebSockets"}'

  Payload: com.developersuraj.realtimenotifications.dto.ChannelEvent

End-to-End Demo

1. Start the server.
2. Open http://localhost:8080/index.html.
3. Enter userId 1 and click “Connect.”
4. Subscribe user 1 to channel 42:
   • Use the subscribe API (see above).
5. Publish a channel event on 42:
   • Use the publish API.
6. The UI should display: "[Channel 42] New video: Intro to WebSockets".

Testing

• Basic context test: com.developersuraj.realtimenotifications.RealTimeNotificationsApplicationTests

./mvnw test

Implementation Notes

• Persistence for notifications is present but commented in com.developersuraj.realtimenotifications.service.NotificationService. Enable to record delivery state.
• Allowed origins for WebSocket are currently *. Adjust in com.developersuraj.realtimenotifications.config.WebSocketConfig.
• Mongo repositories:
  • com.developersuraj.realtimenotifications.repo.SubscriptionRepo
  • com.developersuraj.realtimenotifications.repo.NotificationRepository

Roadmap

• Authentication and session management
• Durable delivery and read receipts
• Topic-based broadcasting with fine-grained permissions
• Integration tests for WebSocket messaging