On this page

Session

1 Introduction

By default, Micronaut is a stateless HTTP server, however depending on your application requirements you may need the notion of HTTP sessions.

2 Breaking Changes

For Micronaut Session 5.x, HttpSessionFilter is a method-based @ServerFilter and no longer implements HttpServerFilter.

3 Http Sessions

Micronaut provides this module inspired by Spring Session that enables this which currently has two implementations:

In-Memory sessions - which you should combine with a sticky session proxy if you plan to run multiple instances.
Redis sessions - In this case Redis stores sessions, and non-blocking I/O is used to read/write sessions to Redis.

3.1 Session Filter

The core of Micronaut Session implementation is io.micronaut.session.http.HttpSessionFilter.

The following configuration options are available for the SessionFilter Filter:

3.2 Enabling Sessions

To enable support for in-memory sessions you just need the micronaut-session dependency:

implementation("io.micronaut.session:micronaut-session")

<dependency>
    <groupId>io.micronaut.session</groupId>
    <artifactId>micronaut-session</artifactId>
</dependency>

3.3 Redis Sessions

To store Session instances in Redis, use the Micronaut Redis module which includes detailed instructions.

To quickly get up and running with Redis sessions you must also have the redis-lettuce dependency in your build:

build.gradle

compile "io.micronaut-session:micronaut-session"
compile "io.micronaut.redis:micronaut-redis-lettuce"

And enable Redis sessions via configuration in the application configuration file:

Enabling Redis Sessions

redis.uri=redis://localhost:6379
micronaut.session.http.redis.enabled=true

redis:
  uri: redis://localhost:6379
micronaut:
  session:
    http:
      redis:
        enabled: true

[redis]
uri = "redis://localhost:6379"

[micronaut.session.http.redis]
enabled = true

redis {
  uri = 'redis://localhost:6379'
}
micronaut {
  session {
    http {
      redis {
        enabled = true
      }
    }
  }
}

{
  redis = {
    uri = "redis://localhost:6379"
  }
  micronaut = {
    session = {
      http = {
        redis = {
          enabled = true
        }
      }
    }
  }
}

{
  "redis": {
    "uri": "redis://localhost:6379"
  },
  "micronaut": {
    "session": {
      "http": {
        "redis": {
          "enabled": true
        }
      }
    }
  }
}

3.4 Configuring Session Resolution

Session resolution can be configured with HttpSessionConfiguration.

By default, sessions are resolved using an HttpSessionFilter that looks for session identifiers via either an HTTP header (using the Authorization-Info or X-Auth-Token headers) or via a Cookie named SESSION.

You can disable either header resolution or cookie resolution via configuration in the application configuration file:

Disabling Cookie Resolution

micronaut.session.http.cookie=false
micronaut.session.http.header=true

micronaut:
  session:
    http:
      cookie: false
      header: true

[micronaut.session.http]
cookie = false
header = true

micronaut {
  session {
    http {
      cookie = false
      header = true
    }
  }
}

{
  micronaut = {
    session = {
      http = {
        cookie = false
        header = true
      }
    }
  }
}

{
  "micronaut": {
    "session": {
      "http": {
        "cookie": false,
        "header": true
      }
    }
  }
}

The above configuration enables header resolution, but disables cookie resolution. You can also configure header and cookie names.

3.5 Working with Sessions

A Session can be retrieved with a parameter of type Session in a controller method. For example consider the following controller:

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Post;
import io.micronaut.session.Session;
import io.micronaut.session.annotation.SessionValue;
import org.jspecify.annotations.Nullable;

@Controller("/shopping")
public class ShoppingController {
    private static final String ATTR_CART = "cart"; // 

    @Post("/cart/{name}")
    Cart addItem(Session session, String name) { // 
        Cart cart = session.get(ATTR_CART, Cart.class).orElseGet(() -> { // 
            Cart newCart = new Cart();
            session.put(ATTR_CART, newCart); // 
            return newCart;
        });
        cart.getItems().add(name);
        return cart;
    }

}

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Post
import io.micronaut.session.Session
import io.micronaut.session.annotation.SessionValue

@Controller("/shopping")
class ShoppingController {

    companion object {
        private const val ATTR_CART = "cart" // 
    }

    @Post("/cart/{name}")
    internal fun addItem(session: Session, name: String): Cart { // 
        require(name.isNotBlank()) { "Name cannot be blank" }
        val cart = session.get(ATTR_CART, Cart::class.java).orElseGet { // 
            val newCart = Cart()
            session.put(ATTR_CART, newCart) // 
            newCart
        }
        cart.items.add(name)
        return cart
    }

}

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Post
import io.micronaut.session.Session
import io.micronaut.session.annotation.SessionValue

import jakarta.annotation.Nullable

@Controller("/shopping")
class ShoppingController {
    private static final String ATTR_CART = "cart" // 

    @Post("/cart/{name}")
    Cart addItem(Session session, String name) { // 
        Cart cart = session.get(ATTR_CART, Cart).orElseGet({ -> // 
            Cart newCart = new Cart()
            session.put(ATTR_CART, newCart) // 
            newCart
        })
        cart.items << name
        cart
    }

}

ShoppingController declares a Session attribute named cart
The Session is declared as a method parameter
The cart attribute is retrieved
Otherwise a new Cart instance is created and stored in the session

Note that because the Session is declared as a required parameter, to execute the controller action a Session will be created and saved to the SessionStore.

If you don’t want to create unnecessary sessions, declare the Session as @Nullable in which case a session will not be created and saved unnecessarily. For example:

Using @Nullable with Sessions

@Post("/cart/clear")
void clearCart(@Nullable Session session) {
    if (session != null) {
        session.remove(ATTR_CART);
    }
}

@Post("/cart/clear")
internal fun clearCart(session: Session?) {
    session?.remove(ATTR_CART)
}

@Post("/cart/clear")
void clearCart(@Nullable Session session) {
    session?.remove(ATTR_CART)
}

The above method only injects a new Session if one already exists.

3.6 Session Clients

If the client is a web browser, sessions should work if cookies are enabled. However, for programmatic HTTP clients you need to propagate the session ID between HTTP calls.

For example, when invoking the viewCart method of the StoreController in the previous example, the HTTP client receives by default a AUTHORIZATION_INFO header. The following example demonstrates this:

Retrieving the AUTHORIZATION_INFO header

when: "The shopping cart is retrieved"
HttpResponse<Cart> response = client.exchange(HttpRequest.GET('/shopping/cart'), Cart) // 
                                        .blockFirst()
Cart cart = response.body()

then: "The shopping cart is present as well as a session id header"
response.header(HttpHeaders.AUTHORIZATION_INFO) != null // 
cart != null
cart.items.isEmpty()

A request is made to /shopping/cart
The AUTHORIZATION_INFO header is present in the response

You can then pass this AUTHORIZATION_INFO in subsequent requests to reuse the existing Session:

Sending the AUTHORIZATION_INFO header

String sessionId = response.header(HttpHeaders.AUTHORIZATION_INFO) // 

response = client.exchange(HttpRequest.POST('/shopping/cart/Apple', "")
                 .header(HttpHeaders.AUTHORIZATION_INFO, sessionId), Cart) // 
                 .blockFirst()
cart = response.body()

The AUTHORIZATION_INFO is retrieved from the response
And then sent as a header in the subsequent request

3.7 Using @SessionValue

Rather than explicitly injecting the Session into a controller method, you can instead use @SessionValue. For example:

Using @SessionValue

@Get("/cart")
@SessionValue(ATTR_CART) // 
Cart viewCart(@SessionValue @Nullable Cart cart) { // 
    if (cart == null) {
        cart = new Cart();
    }
    return cart;
}

@Get("/cart")
@SessionValue(ATTR_CART) // 
internal fun viewCart(@SessionValue cart: Cart?): Cart { // 
    return cart ?: Cart()
}

@Get("/cart")
@SessionValue("cart") // 
Cart viewCart(@SessionValue @Nullable Cart cart) { // 
    cart ?: new Cart()
}

@SessionValue is declared on the method resulting in the return value being stored in the Session. Note that you must specify the attribute name when used on a return value
@SessionValue is used on a @Nullable parameter which results in looking up the value from the Session in a non-blocking way and supplying it if present. In the case a value is not specified to @SessionValue resulting in the parameter name being used to lookup the attribute.

3.8 Session Events

You can register ApplicationEventListener beans to listen for Session related events located in the io.micronaut.session.event package.

The following table summarizes the events:

Table 1. Session Events
Type	Description
SessionCreatedEvent	Fired when a Session is created
SessionDeletedEvent	Fired when a Session is deleted
SessionExpiredEvent	Fired when a Session expires
SessionDestroyedEvent	Parent of both `SessionDeletedEvent` and `SessionExpiredEvent`

4 Release History

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-session/releases

5 Repository

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-session