Session Lifecycle

When a new socket connection is made, a Session will step through several states.


The Connection: Upgrade directive is processed, and the initial HTTP connection will be upgraded to the web-socket protocol.


Once the connection has been upgraded, but before the application is notified of the new session, the session must be validated. Babl allows a user-defined strategy to perform validation (for example an authentication operation).

As part of the validation step, all HTTP request headers are propagated from the connection upgrade request. To use custom validation, implement the ConnectionValidator interface:

public interface ConnectionValidator
    void validateConnection(
        ValidationResult validationResult,
        Consumer<BiConsumer<CharSequence, CharSequence>> headerProvider,
        ValidationResultPublisher validationResultPublisher);

The validation will be invoked on the event-loop thread, so it is vital that any implementation of this interface does not block.

The recommended approach is to copy the supplied parameters to a queue, and perform the validation work on a separate thread.

Validator implementations must respect the following:

Publishing the validation result

Validation is either successful:

public void validateConnection(...) {
    while (!validationResultPublisher.publishResult(validationResult)) {
        // result queue full, need to retry after a short wait

or unsuccessful:

// Valid user codes are 4000-4999
static final short AUTHENTICATION_FAILED = 4007;

public void validateConnection(...) {
    while (!validationResultPublisher.publishResult(validationResult)) {
        // result queue full, need to retry after a short wait

On validation success, the session will transition to the CONNECTED state and the application will be notified.

On validation failure, the connection will be closed.

The result code passed to validationFailure will be propagated to the web-socket client as the close reason.


Normal operation, web-socket messages will be passed to the application as they are received.

Messages sent to the Session will be framed and transmitted to the remote peer.


Close has been requested by the application or the session container. The close frame will be sent to the remote peer.


The session is no longer connected.