diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/chapter.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/chapter.adoc index cf8e60419dc..ee80d385f01 100644 --- a/jetty-documentation/src/main/asciidoc/administration/sessions/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/sessions/chapter.adoc @@ -24,6 +24,7 @@ If you need a session manager that can work in a clustered scenario with multipl Jetty also offers more niche session managers that leverage backends such as MongoDB, Inifinispan, or even Google's Cloud Data Store. include::session-hierarchy.adoc[] +include::sessions-details.adoc[] include::session-configuration-file-system.adoc[] include::session-configuration-jdbc.adoc[] include::session-configuration-mongodb.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc index 7142a78da0c..91d6f3e345d 100644 --- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc @@ -46,7 +46,7 @@ There is only one (1) `SessionDataStore` per `SessionCache`. // Null cache, memcache, non-sticky load-balancer // in-memory caching -Visually the Session Hierarchy can be represented like this: +Visually the session architecture can be represented like this: image::images/SessionsHierarchy.png[] diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/sessions-details.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/sessions-details.adoc new file mode 100644 index 00000000000..693a2706cf6 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/administration/sessions/sessions-details.adoc @@ -0,0 +1,131 @@ +// ======================================================================== +// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd. +// ======================================================================== +// All rights reserved. This program and the accompanying materials +// are made available under the terms of the Eclipse Public License v1.0 +// and Apache License v2.0 which accompanies this distribution. +// +// The Eclipse Public License is available at +// http://www.eclipse.org/legal/epl-v10.html +// +// The Apache License v2.0 is available at +// http://www.opensource.org/licenses/apache2.0.php +// +// You may elect to redistribute this code under either of these licenses. +// ======================================================================== + +[[sessions-details]] +=== Session Configuration and Use Cases + +==== Configuration + +===== SessionIdManager + +There is a maximum of 1 SessionIdManager per jetty Server instance. Its purpose is to generate fresh, unique session ids and to coordinate the re-use of session ids amongst co-operating contexts. + +Unlike in previous versions of jetty, the SessionIdManager is agnostic with respect to the type of clustering technology chosen. + +Jetty provides a default implementation - the DefaultSessionIdManager - which should meet most users' needs. +If you do not explicitly enable one of the session modules, or otherwise configure a SessionIdManager, the DefaultSessionIdManager will be used. + +If the DefaultSessionIdManager does not meet your needs, you can extend the org.eclipse.jetty.server.session.AbstractSessionIdManager or do a fresh implementation of the org.eclipse.jetty.server.session.SessionIdManager interface. + +===== HouseKeeper + +There is a maximum of 1 HouseKeeper per SessionIdManager. Its purpose is to periodically poll the SessionHandlers to clean out expired sessions. + +By default the HouseKeeper will poll the SessionHandlers every 10 mins to find and delete expired sessions, although this interval is configurable. + + +===== SessionCache + +There is 1 SessionCache per context. Its purpose is to provide an L1 cache of Session objects. +Having a working set of Session objects in memory allows multiple simultaneous requests for the same session to share the same Session object. + +Jetty provides 2 SessionCache implementations: the DefaultSessionCache and the NullSessionCache. +The DefaultSessionCache retains Session objects in memory in a cache and has a number of configuration options to control cache behaviour. +It is the default that is used if no other SessionCache has been configured. +It is suitable for non-clustered and clustered deployments with a sticky load balancer, as well as clustered deployments with a non-sticky load balancer, with some caveats. +The NullSessionCache does not actually cache any objects: each request uses a fresh Session object. +It is suitable for clustered deployments without a sticky load balancer and non-clustered deployments when purely minimal support for sessions is needed. + +SessionCaches always write out a Session to the SessionDataStore whenever the last request for the Session exits. + +They can also be configured to do an immediate, eager write of a freshly created session. +This can be useful if you are likely to experience multiple, near simultaneous requests referencing the same session, eg with HTTP2 and you don't have a sticky load balancer. +Alternatively, if the eager write is not done, application paths which create and then invalidate a session within a single request never incur the cost of writing to persistent storage. + +Additionally, if the EVICT_ON_INACTIVITY eviction policy is in use, you can configure the DefaultSessionCache to force a write of the Session to the SessionDataStore just before the Session is evicted. + +===== SessionDataStore + +There is 1 SessionDataStore per context. Its purpose is to handle all persistance related operations on sessions. + +The common characteristics for all SessionDataStores are whether or not they support passivation, and the length of the grace period. + +Supporting passivation means that session data is serialized. +Some persistence mechanisms serialize, such as JDBC, GCloud Datastore etc, whereas others may store an object in shared memory eg Infinispan when configured with a local cache. + +Whether or not a clustering technology entails passivation controls whether or not the session passivation/activation listeners will be called. + +The grace period is an interval, configured in seconds, that attempts to deal with the non-transactional nature of sessions with regard to finding sessions that have expired. +Due to the lack of transactionality, in a clustered configuration, even with a sticky load balancer, it is always possible that a Session is live on a node but has not yet been updated in the persistent store. +When SessionDataStores search their persistant store to find sessions that have expired, they typically perform a few sequential searches: +. the first verifies the expiration of a list of candidate session ids suggested by the SessionCache +. the second finds sessions in the store that have expired which were last live on the current node +. the third finds sessions that expired a "while" ago, irrespective of on which node they were last used: the definition of "a while" is based on the grace period. + + +===== CachingSessionDataStore + +The CachingSessionDataStore is a special type of SessionDataStore that inserts an L2 cache of SessionData - the SessionDataMap - in front of a delegate SessionDataStore. +The SessionDataMap is preferentially consulted before the actual SessionDataStore on reads. +This can improve the performance of slow stores. + +At the time of writing, jetty provides one implementation of the this L2 cache based on Memcached, the MemcachedSessionDataMap. + + +==== Use Cases + +===== Clustering with a Sticky Load Balancer + +Preferably, your cluster will utilize a sticky load balancer. +This will route requests for the same session to the same jetty instance. +In this case, the DefaultSessionCache can be used to keep in-use Session objects in memory. +You can fine-tune the cache by controlling how long Session objects remain in memory with the eviction policy settings. + +If you have a large number of Sessions or very large Session objects, then you might want to manage your memory allocation by controlling the amount of time Session objects spend in the cache. +The EVICT_ON_SESSION_EXIT eviction policy will remove a Session object from the cache as soon as the last simultaneous request referencing it exits. +Alternatively, the EVICT_ON_INACTIVITY policy will remove a Session object from the cache after a configurable amount of time has passed without a request referencing it. + +If your Sessions are very long lived and infrequently referenced, you might use the EVICT_ON_INACTIVITY_POLICY to control the size of the cache. + +If your Sessions are small, or relatively few or stable in number or they are read-mostly, then you might select the NEVER_EVICT policy. +With this policy, Session objects will remain in the cache until they either expire or are explicitly invalidated. + +If you have a high likelihood of simultaneous requests for the same session object, then the EVICT_ON_SESSION_EXIT policy will ensure the Session object stays in the cache as long as it is needed. + + +===== Clustering without a Sticky Load Balancer + +Without a sticky load balancer requests for the same session may arrive on any node in the cluster. +This means it is likely that the copy of the Session object in any SessionCache is likely to be out-of-date, as the Session was probably last accessed on a different node. +In this case, your choices are to use either the NullSessionCache or to de-tuned the DefaultSessionCache. +If you use the NullSessionCache all Session object caching is avoided. +This means that every time a request references a session it must be brought in from persistent storage. +It also means that there can be no sharing of Session objects for multiple requests for the same session: each will have their own Session object. +Furthermore, the outcome of session writes are indeterminate because the Servlet Specification does not mandate ACID transactions for sessions. + +If you use the DefaultSessionCache, there is a risk that the caches on some nodes will contain out-of-date session information as simultaneous requests for the same session are scattered over the cluster. +To mitigate this somewhat you can use the EVICT_ON_SESSION_EXIT eviction policy: this will ensure that the Session is removed from the cache as soon as the last simultaneous request for it exits. +Again, due to the lack of session transactionality, the ordering outcome of write operations cannot be guaranteed. +As the Session is cached while at least one request is accessing it, it is possible for multiple simultaneous requests to share the same Session object. + + +===== Handling corrupted or unloadable session data + +For various reasons it might not be possible for the SessionDataStore to re-read a stored session. +One scenario is that the session stores a serialized object in it's attributes, and after a redeployment there in an incompatible class change. +Using the setter SessionCache.setRemoveUnloadableSessions(true) will allow the SessionDataStore to delete the unreadable session from persistent storage. +This can be useful from preventing the scavenger from continually erroring on the same expired, but unrestorable session. +