Expose a WebSocket Server in a Micronaut Application

Build a chat application by exposing a WebSocket Server with the Micronaut Framework

Authors: Dan Hollingsworth, Sergio del Amo

Micronaut Version: 5.0.0

1. Getting Started

In this guide, we will create a Micronaut application written in Groovy.

The WebSocket Protocol allows for web browsers to establish interactive sessions with a server that are event-driven. This technology is ideal for applications that need state changes without the overhead and latency of polling the server. The article "Introduction to WebSockets" explains the benefits of WebSocket in more depth, along with a discussion of the client-side WebSocket API.

This guide will take you through the creation of an event-driven chat application utilizing Micronaut WebSocket.

2. What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Download and unzip the source

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=websocket,validation,reactor \
    --build=maven \
    --lang=groovy \
    --test=spock

If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add websocket, validation, and reactor features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Diff

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Static Resources

Update application.properties to add static resource configuration:

Since Micronaut Framework 4.0, to use YAML configuration, you have to add the YAML dependency.

src/main/resources/application.properties

(1)
micronaut.router.static-resources.default.enabled=true
micronaut.router.static-resources.default.enabled.mapping=/**
micronaut.router.static-resources.default.enabled.mapping.paths=classpath:public
micronaut.router.static-resources.default.mapping=/**
micronaut.router.static-resources.default.paths=classpath:public

1	Configure the Framework to look for static resources in `src/main/resources/public`.

4.2. Front End

4.2.1. HTML

Add the HTML page to be the user interface for the chat client in the browser:

src/main/resources/public/index.html

<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>WebSocket Demo</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
<div id="chatControls">
    <input id="message" placeholder="Type your message">
    <button id="send">Send</button>
</div>
<ul id="userlist"> <!-- Built by JS --> </ul>
<div id="chat">    <!-- Built by JS --> </div>
<script src="websocketDemo.js"></script>
</body>
</html>

4.2.2. Javascript

Write JavaScript to parse the URL for the chat topic and username, handle the message body, broadcast the chat, and keep the DOM updated with the latest messages:

src/main/resources/public/websocketDemo.js

//Establish the WebSocket connection and set up event handlers
var hash = document.location.hash.split("/");

if (hash.length !== 3) {
    alert("Specify URI with a topic and username. "
    + "Example http://localhost:8080#/stuff/bob")
}

var webSocket = new WebSocket("ws://" +
    location.hostname +
    ":" +
    location.port +
    "/ws/chat/" +
    hash[1] +
    "/" +
    hash[2]);
webSocket.onmessage = function (msg) { updateChat(msg); };
webSocket.onclose = function () { alert("WebSocket connection closed") };

//Send message if "Send" is clicked
id("send").addEventListener("click", function () {
    sendMessage(id("message").value);
});

//Send message if enter is pressed in the input field
id("message").addEventListener("keypress", function (e) {
    if (e.keyCode === 13) { sendMessage(e.target.value); }
});

//Send a message if it's not empty, then clear the input field
function sendMessage(message) {
    if (message !== "") {
        webSocket.send(message);
        id("message").value = "";
    }
}

//Update the chat-panel, and the list of connected users
function updateChat(msg) {
    insert("chat", msg.data);
}

//Helper function for inserting HTML as the first child of an element
function insert(targetId, message) {
    id(targetId).insertAdjacentHTML("afterbegin", "<p>" + message + "</p>");
}

//Helper function for selecting element by id
function id(id) {
    return document.getElementById(id);
}

4.2.3. CSS

Style the page so that the messages are properly displayed:

src/main/resources/public/style.css

* {
    box-sizing: border-box;
}

html {
    overflow-y: scroll;
}

body {
    font-family: monospace;
    font-size: 14px;
    max-width: 480px;
    margin: 0 auto;
    padding: 20px;
}

input {
    width: 100%;
    padding: 5px;
    margin: 5px 0;
}

button {
    float: right;
}

li {
    margin: 5px 0;
}

#chatControls {
    overflow: auto;
    margin: 0 0 5px 0;
}

#userlist {
    position: fixed;
    left: 50%;
    list-style: none;
    margin-left: 250px;
    background: #f0f0f9;
    padding: 5px 10px;
    width: 150px;
    top: 11px;
}

#chat p {
    margin: 5px 0;
    font-weight: 300;
}

#chat .timestamp {
    position: absolute;
    top: 10px;
    right: 10px;
    font-size: 12px;
}

#chat article {
    background: #f1f1f1;
    padding: 10px;
    margin: 10px 0;
    border-left: 5px solid #aaa;
    position: relative;
    word-wrap: break-word;
}

#chat article:first-of-type {
    background: #c9edc3;
    border-left-color: #74a377;
    animation: enter .2s 1;
}

@keyframes enter {
    from { transform: none;        }
    50%  { transform: scale(1.05); }
    to   { transform: none;        }
}

4.3. Chat server

Our chat server is very simple. It merely allows you to connect and broadcast messages to subscribers of the topic. There’s also a special topic called "all" that can make announcements and receive messages from all topics.

src/main/groovy/example/micronaut/ChatServerWebSocket.groovy

package example.micronaut

import io.micronaut.websocket.WebSocketBroadcaster
import io.micronaut.websocket.WebSocketSession
import io.micronaut.websocket.annotation.OnClose
import io.micronaut.websocket.annotation.OnMessage
import io.micronaut.websocket.annotation.OnOpen
import io.micronaut.websocket.annotation.ServerWebSocket
import org.reactivestreams.Publisher
import org.slf4j.Logger
import org.slf4j.LoggerFactory

import java.util.function.Predicate

@ServerWebSocket('/ws/chat/{topic}/{username}') (1)
class ChatServerWebSocket {

    private static final Logger LOG = LoggerFactory.getLogger(ChatServerWebSocket)

    private final WebSocketBroadcaster broadcaster

    ChatServerWebSocket(WebSocketBroadcaster broadcaster) { (2)
        this.broadcaster = broadcaster
    }

    @OnOpen (3)
    Publisher<String> onOpen(String topic, String username, WebSocketSession session) {
        log('onOpen', session, username, topic)
        if (topic == 'all') { (4)
            return broadcaster.broadcast("[${username}] Now making announcements!", isValid(topic))
        }
        broadcaster.broadcast("[${username}] Joined ${topic}!", isValid(topic))
    }

    @OnMessage (5)
    Publisher<String> onMessage(String topic, String username, String message, WebSocketSession session) {
        log('onMessage', session, username, topic)
        broadcaster.broadcast("[${username}] ${message}", isValid(topic))
    }

    @OnClose (6)
    Publisher<String> onClose(String topic, String username, WebSocketSession session) {
        log('onClose', session, username, topic)
        broadcaster.broadcast("[${username}] Leaving ${topic}!", isValid(topic))
    }

    private void log(String event, WebSocketSession session, String username, String topic) {
        LOG.info('* WebSocket: {} received for session {} from \'{}\' regarding \'{}\'',
                event, session.id, username, topic)
    }

    private Predicate<WebSocketSession> isValid(String topic) { (7)
        { s ->
            topic == 'all' //broadcast to all users
                    || 'all' == s.uriVariables.get('topic', String, null) //"all" subscribes to every topic
                    || topic.equalsIgnoreCase(s.uriVariables.get('topic', String, null)) //intra-topic chat
        } as Predicate<WebSocketSession>
    }
}

1	The `@ServerWebSocket` annotation defines the path the WebSocket is mapped under. The URI can be a URI template.
2	Use constructor injection to inject a bean of type `ChatServerWebSocket`.
3	The `@OnOpen` annotation declares the method to invoke when the WebSocket is opened.
4	Our chat server has a special topic called "all" that can make announcements and receive messages from all topics
5	The `@OnMessage` annotation declares the method to invoke when a message is received.
6	The `@OnClose` annotation declares the method to invoke when the WebSocket is closed.
7	A predicate to keep messages within topics yet also enable the special "all" topic

4.4. Test

To test asynchronous code, use Awaitility:

Awaitility is a DSL that allows you to express expectations of an asynchronous system in a concise and easy to read manner.

Micronaut Launch/CLI feature awaitility adds the following dependency:

pom.xml

<dependency>
    <groupId>org.awaitility</groupId>
    <artifactId>awaitility</artifactId>
    <version>4.3.0</version>
    <scope>test</scope>
</dependency>

The Micronaut framework eases the creation of WebSocket servers and clients.

Write a test that uses ClientWebSocket to test the application.

src/test/groovy/example/micronaut/ChatServerWebSocketSpec.groovy

package example.micronaut

import io.micronaut.context.BeanContext
import io.micronaut.context.annotation.Property
import io.micronaut.context.annotation.Requires
import io.micronaut.core.annotation.NonNull
import io.micronaut.core.util.CollectionUtils
import io.micronaut.http.uri.UriBuilder
import io.micronaut.runtime.server.EmbeddedServer
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import io.micronaut.websocket.WebSocketClient
import io.micronaut.websocket.annotation.ClientWebSocket
import io.micronaut.websocket.annotation.OnMessage
import jakarta.inject.Inject
import jakarta.validation.constraints.NotBlank
import org.reactivestreams.Publisher
import reactor.core.publisher.Flux
import spock.lang.Specification
import spock.util.concurrent.PollingConditions

import java.util.concurrent.ConcurrentLinkedDeque

@Property(name = 'spec.name', value = 'ChatWebSocketTest') (1)
@MicronautTest (2)
class ChatServerWebSocketSpec extends Specification {

    @Inject
    BeanContext beanContext

    @Inject
    EmbeddedServer embeddedServer

    @Requires(property = 'spec.name', value = 'ChatWebSocketTest') (1)
    @ClientWebSocket (3)
    static abstract class TestWebSocketClient implements AutoCloseable { (4)

        private final Deque<String> messageHistory = new ConcurrentLinkedDeque<>()

        String getLatestMessage() {
            messageHistory.peekLast()
        }

        List<String> getMessagesChronologically() {
            new ArrayList<>(messageHistory)
        }

        @OnMessage (5)
        void onMessage(String message) {
            messageHistory.add(message)
        }

        abstract void send(@NonNull @NotBlank String message) (6)
    }

    private TestWebSocketClient createWebSocketClient(int port, String username, String topic) {
        WebSocketClient webSocketClient = beanContext.getBean(WebSocketClient)
        URI uri = UriBuilder.of('ws://localhost')
                .port(port)
                .path('ws')
                .path('chat')
                .path('{topic}')
                .path('{username}')
                .expand(CollectionUtils.mapOf('topic', topic, 'username', username))
        Publisher<TestWebSocketClient> client = webSocketClient.connect(TestWebSocketClient, uri) (7)
        Flux.from(client).blockFirst()
    }

    void 'test websocket server'() {
        given:
        PollingConditions conditions = new PollingConditions(timeout: 10)

        when:
        TestWebSocketClient adam = createWebSocketClient(embeddedServer.port, 'adam', 'Cats & Recreation') (8)

        then:
        conditions.eventually { (9)
            adam.messagesChronologically == ['[adam] Joined Cats & Recreation!']
        }

        when:
        TestWebSocketClient anna = createWebSocketClient(embeddedServer.port, 'anna', 'Cats & Recreation')

        then:
        conditions.eventually { (9)
            anna.messagesChronologically == ['[anna] Joined Cats & Recreation!']
        }
        conditions.eventually { (9)
            adam.messagesChronologically == ['[adam] Joined Cats & Recreation!', '[anna] Joined Cats & Recreation!']
        }

        when:
        TestWebSocketClient ben = createWebSocketClient(embeddedServer.port, 'ben', 'Fortran Tips & Tricks')

        then:
        conditions.eventually { (9)
            ben.messagesChronologically == ['[ben] Joined Fortran Tips & Tricks!']
        }

        when:
        TestWebSocketClient zach = createWebSocketClient(embeddedServer.port, 'zach', 'all')

        then:
        conditions.eventually { (9)
            zach.messagesChronologically == ['[zach] Now making announcements!']
        }

        when:
        TestWebSocketClient cienna = createWebSocketClient(embeddedServer.port, 'cienna', 'Fortran Tips & Tricks')

        then:
        conditions.eventually { (9)
            cienna.messagesChronologically == ['[cienna] Joined Fortran Tips & Tricks!']
        }
        conditions.eventually { (9)
            ben.messagesChronologically == ['[ben] Joined Fortran Tips & Tricks!', '[zach] Now making announcements!', '[cienna] Joined Fortran Tips & Tricks!'] (10)
        }

        when: // should broadcast message to all users inside the topic (11)
        String adamsGreeting = "Hello, everyone. It's another purrrfect day :-)"
        String expectedGreeting = "[adam] $adamsGreeting"
        adam.send(adamsGreeting)

        then:
        //subscribed to "Cats & Recreation"
        conditions.eventually { adam.latestMessage == expectedGreeting } (9)
        //subscribed to "Cats & Recreation"
        conditions.eventually { anna.latestMessage == expectedGreeting } (9)
        //NOT subscribed to "Cats & Recreation"
        ben.latestMessage != expectedGreeting
        //subscribed to the special "all" topic
        conditions.eventually { zach.latestMessage == expectedGreeting } (9)
        //NOT subscribed to "Cats & Recreation"
        cienna.latestMessage != expectedGreeting

        when: // should broadcast message when user disconnects from the chat (12)
        anna.close()
        String annaLeaving = '[anna] Leaving Cats & Recreation!'

        then:
        conditions.eventually { adam.latestMessage == annaLeaving } (9)
        //subscribed to "Cats & Recreation"
        adam.latestMessage == annaLeaving
        //Anna already left and therefore won't see the message about her leaving
        anna.latestMessage != annaLeaving
        //NOT subscribed to "Cats & Recreation"
        ben.latestMessage != annaLeaving
        //subscribed to the special "all" topic
        zach.latestMessage == annaLeaving
        //NOT subscribed to "Cats & Recreation"
        cienna.latestMessage != annaLeaving

        cleanup:
        adam.close()
        ben.close()
        zach.close()
        cienna.close()
    }
}

1	Combine `@Requires` and properties (either via the `@Property` annotation or by passing properties when starting the context) to avoid bean pollution.
2	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. More info.
3	You can create Websocket clients by annotating interfaces or abstract classes with `@ClientWebSocket`.
4	The client must implement `AutoCloseable`, and you should ensure that the connection is closed at some point.
5	The `@OnMessage` annotation declares the method to invoke when a message is received.
6	Any method name that starts with (or equals) "broadcast" or "send" will be used to broadcast messages, as long as the parameter is a String or a bean
7	Once you have defined a client class, you can connect to the client socket and start sending messages.
8	Set up WebSocket clients for multiple users
9	Use Awaitility to test asynchronous code. By default, `Awaitility` waits for 10 seconds and if the condition is not fulfilled during this time, it throws a `ConditionTimeoutException` failing the test.
10	Test that the correct messages are automatically sent when users join topics
11	Test that chats are sent within a topic and not outside of it, with the exception of those sent using the special "all" topic
12	Test that the correct messages are automatically sent when users leave topics

5. Testing the Application

To run the tests:

./mvnw test

6. Running the Application

To run the application, use the ./mvnw mn:run command, which starts the application on port 8080.

Open a browser and visit a URL such as http://localhost:8080/#/java/Joe. Then in another browser tab, open http://localhost:8080/\#/java/Moka. You can then try sending chats as Joe and Moka.

7. Next Steps

8. License

All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).

Table of Contents