public class ClientSideSessionsModule extends ConfigurableModule<ClientSideSessionsModule.Config> implements HandlerDecoratingModule
SessionStorage
- deserialized from the client's cookie
This module decorates the handler to make
the SessionStorage
available during request processing.
import ratpack.handling.*; import ratpack.session.store.SessionStorage; class MyHandler implements Handler { void handle(Context ctx) { SessionStorage session = ctx.getRequest().get(SessionStorage.class); String value = session.get("value"); ctx.render(value); } }
This module also provides a programmatic configurable object that helps customize various elements.
sessionName | The name of the cookie in which the session is stored. Defaults to ratpack_session. |
---|---|
secretToken | The token used to sign the serialized session to prevent tampering. If not set, this is set to a time based value |
macAlgorithm | The Mac algorithm used to sign the serialized session with the secretToken. |
secretKey | The secret key used in the symmetric-key encyrption/decryption with the serialized session. |
cipherAlgorithm | The Cipher algorithm used to encrypt/decrypt the serialized session, e.g. AES/CBC/PKCS5Padding which is also the default value. |
import ratpack.guice.Guice;
import ratpack.http.client.ReceivedResponse;
import ratpack.session.clientside.ClientSideSessionsModule;
import ratpack.session.store.SessionStorage;
import ratpack.test.embed.EmbeddedApp;
import static org.junit.Assert.*;
public class ClientSideSessionsModuleConfigExample {
public static void main(String[] args) {
EmbeddedApp.fromHandlerFactory(launchConfig ->
Guice.builder(launchConfig)
.bindings(b -> b.add(ClientSideSessionsModule.class, config -> {
config.setSessionName("session-name");
config.setSecretToken("your token for signing");
// config.setSecretKey("key for cipher");
// config.setMacAlgorithm("MAC algorithm for signing");
// config.setCipherAlgorithm("Cipher Algorithm");
}))
.build(chain ->
chain.get(ctx -> {
SessionStorage sessionStorage = ctx.getRequest().get(SessionStorage.class);
ctx.render(sessionStorage.getOrDefault("value", "not set"));
}).get("set/:value", ctx -> {
SessionStorage sessionStorage = ctx.getRequest().get(SessionStorage.class);
String value = ctx.getPathTokens().get("value");
sessionStorage.put("value", value);
ctx.render(value);
}))
).test(client -> {
ReceivedResponse response = client.get();
assertEquals("not set", response.getBody().getText());
assertFalse("No cookies should be set", response.getHeaders().contains("Set-Cookie"));
response = client.get("set/foo");
assertEquals("foo", response.getBody().getText());
assertTrue("We set a value", response.getHeaders().contains("Set-Cookie"));
assertTrue("Session uses our session name", response.getHeaders().get("Set-Cookie").contains("session-name"));
response = client.get();
assertEquals("foo", response.getBody().getText());
assertFalse("We did not update session", response.getHeaders().contains("Set-Cookie"));
});
}
}
Because the session is serialized to the client, all key value pairs in the session are String based. The max cookie size for a client is 4k so it's important to keep this in mind when using the ClientSideSessionsModule.
By default your session will be signed but not encrypted. This is because the secretKey is not set by default. That is, your users will not be able to tamper with the cookie but they can still read the key value pairs that you have set. If you want to render the entire cookie unreadable make sure you set a secretKey
When setting your own secretKey and cipherAlgorithm make sure that the key length is acceptable according to the algorithm you have chosen.
Modifier and Type | Class and Description |
---|---|
static class |
ClientSideSessionsModule.Config |
Constructor and Description |
---|
ClientSideSessionsModule() |
Modifier and Type | Method and Description |
---|---|
protected void |
configure() |
Handler |
decorate(Injector injector,
Handler handler)
Makes
SessionStorage available in the context registry. |
configure, createConfig, defaultConfig
addError, addError, addError, bind, bind, bind, bindConstant, binder, bindInterceptor, bindListener, bindListener, bindScope, configure, convertToTypes, currentStage, getMembersInjector, getMembersInjector, getProvider, getProvider, install, requestInjection, requestStaticInjection, requireBinding, requireBinding
protected void configure()
configure
in class AbstractModule
public Handler decorate(Injector injector, Handler handler)
SessionStorage
available in the context registry.decorate
in interface HandlerDecoratingModule
injector
- The injector created from all the application moduleshandler
- The application handlerSessionStorage
impl in the context registry