WebSockets Support: Tyrus Integration

Introduction

This document describes a prototype integration of Tyrus and Helidon.

What is Tyrus?

Tyrus is the reference implementation of JSR 356: Java API for WebSocket. It provides both a client and a server API to communicate using WebSockets using Java. In addition, the JSR defines an SPI to integrate implementations with HTTP containers/connectors.

A WebSocket connection starts as a normal HTTP connection that is subsequently upgraded to use WebSockets, essentially turning an HTTP connection into a plain TCP connection. JSR 356 provides an API to not only send and received messages over a WebSockets connection but also an API to intercept the HTTP upgrade request and potentially alter its outcome --all JSR implementations provided a default upgrade handler.

Doesn't Netty already support WebSockets?

Yes, Netty has support for WebSockets. However, there's an overlap between this support in Netty and what Tyrus provides. For example, both the Netty's handlers and Tyrus provide support for protocol upgrades and both handle encoders for different types of messages.

In order to support JSR 356 in Helidon, we need limit Netty's involvement in handling connections to a minimum and let Tyrus do its work. In particular, we need protocol upgrade to be handled by Tyrus (or the application handler as supported by the JSR 356 API) and for Netty to simply, and most importantly opaquely, relay WebSocket messages to connection peers.

Challenges

Prototype Location