NotiFlow

Features

Everything you need for real-time notifications

One dependency, one annotation. Every component has a sensible default and can be swapped by declaring your own @Bean.

⚡

Send to Users, Topics, or All

Target individual users, topic subscribers, or broadcast to every connected client with a single method call.

📦

Offline Queueing

Notifications for offline users are stored with configurable TTL and per-user capacity. Delivered automatically on reconnect.

✓

ACK-Based Delivery Tracking

Confirm delivery with client acknowledgments. Unacknowledged notifications are retried automatically with configurable intervals.

🔁

Heartbeat Detection

Built-in ping/pong mechanism detects stale connections and closes them gracefully to keep your session registry clean.

🔌

Pluggable Architecture

Every component follows the interface + implementation pattern. Swap session storage, queue, authentication, or any other component.

⚙

@ConditionalOnMissingBean

Every auto-configured bean backs off the moment you declare your own. Swap any component — authentication, queue, delivery tracking — with a single @Component.

Quick Start

Up and running in minutes

Add the dependency, wire the components, and start sending notifications.

Add the dependency

One entry in your pom.xml. The starter brings spring-boot-starter-websocket and notiflow-core transitively.

pom.xml

<dependency>
    <groupId>pl.notiflow</groupId>
    <artifactId>notiflow-spring-boot-starter</artifactId>
    <version>1.1.2</version>
</dependency>

Enable NotiFlow (Spring Boot)

Add the annotation and you're done. A WebSocket endpoint is available at /notifications with sensible defaults.

MyApplication.java

@SpringBootApplication
@EnableNotiflow
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Send notifications

Inject NotificationService and start sending to users, topics, or everyone.

AlertService.java

Notification notification = Notification.builder()
        .type("alert")
        .title("New message")
        .message("You have a new message")
        .priority(Priority.HIGH)
        .build();
// Send to a single user
notificationService.sendToUser("user-123", notification);
// Send to all subscribers of a topic
notificationService.sendToTopic("sports", notification);
// Broadcast to everyone
notificationService.broadcast(notification);

Connect from the client

Standard WebSocket connection. Handle notifications and respond to pings.

Development only. This example uses the default NoOpAuthenticator which accepts every connection without any token check. Before going to production, replace it with a token-based authenticator — see Custom Authenticator in the documentation.

client.js

const ws = new WebSocket('ws://localhost:8080/notifications?userId=user-123');
ws.onmessage = (event) => {
    const envelope = JSON.parse(event.data);
    switch (envelope.type) {
        case 'NOTIFICATION':
        case 'QUEUED':
            console.log('Received:', envelope.payload);
            // Send ACK to confirm receipt
            ws.send(JSON.stringify({
                type: 'ACK',
                payload: { notificationId: envelope.payload.id }
            }));
            break;
        case 'PING':
            ws.send(JSON.stringify({ type: 'PONG' }));
            break;
    }
};