Sessions
PingGateway uses sessions to group requests from a user agent or other source, and collect information from the requests. When multiple requests are made in the same session, the requests can share the session information. Because session sharing is not thread-safe, it is not suitable for concurrent exchanges.
The following table compares stateful and stateless sessions:
| Feature | Stateful sessions | Stateless sessions |
|---|---|---|
Cookie size. |
Unlimited. |
Maximum size of the JWT session cookie is 4 KBytes, as defined by the browser. If the cookie exceeds this size, PingGateway automatically splits it into multiple cookies. |
Default name of the session cookie. |
|
|
Object types that can be stored in the session. |
All types. |
JSON-compatible types, such as strings, numbers, booleans, null, structures such as arrays, and list and maps containing only JSON-compatible types. |
Session sharing between instances of PingGateway, for load balancing and failover. |
Possible when session stickiness is configured. |
Possible because the session content is a cookie on the user agent, that can be copied to multiple instances of PingGateway. |
Risk of data inconsistency when simultaneous requests modify the content of a session. |
Low because the session content is stored on PingGateway and shared by all exchanges. Processing is not thread-safe. |
Higher because the session content is reconstructed for each request. Concurrent exchanges don’t have the same content. |
Stateful sessions
To configure stateful sessions, update the session property of
admin.json.
When a JwtSession isn’t configured for a request, stateful sessions are created
automatically. Session information is stored in the PingGateway cookie, called
IG_SESSIONID by default. When the user agent sends a request with the cookie,
the request can access the session information on PingGateway.
When a JwtSession object is configured in the route that processes a request, or
in its ascending configuration (a parent route or config.json), the
session is always stateless and can’t be stateful.
When a request enters a route without a JwtSession object in the route or its ascending configuration, a stateful session is created lazily.
Session duration is defined by the session property in
admin.json,
with a default of 30 minutes.
Even if the session is empty, the session remains usable until the timeout.
Any object type can be stored in a stateful session.
Because session content is stored on PingGateway and shared by all exchanges, when PingGateway processes simultaneous requests in a stateful session there is low risk that the data becomes inconsistent. However, sessions aren’t thread-safe; different requests can simultaneously read and modify a shared session.
Session information is available in SessionContext to downstream handlers and filters. For more information, refer to SessionContext.
Stateless sessions
Stateless sessions are provided when a JwtSession object is configured in
config.json or in a route. For more information about configuring
stateless sessions, refer to
JwtSession.
PingGateway serializes stateless session information as JSON, stores it in a JWT that can be encrypted and then signed, and places the JWT in a cookie. The cookie contains all of the information about the session, including the session attributes as JSON, and a marker for the session timeout.
The maximum size of the JWT session cookie is 4 KBytes, as defined by the browser. If the cookie exceeds this size, PingGateway automatically splits it into multiple cookies.
Only JSON-compatible object types can be stored in stateless sessions. These object types include strings, numbers, booleans, null, structures such as arrays, and list and maps containing only JSON-compatible types.
Stateless sessions are managed as follows:
-
When a request enters a route with a JwtSession object in the route or its ascending configuration, PingGateway creates the SessionContext, verifies the cookie signature, decrypts the content of the cookie, and checks that the current date is before the session timeout.
-
When the request passes through the filters and handlers in the route, the request can read and modify the session content.
-
When the request returns to the the point where the session was created, for example, at the entrance to a route or at
config.json, PingGateway updates the cookie as follows:-
If the session content has changed, PingGateway serializes the session, creates one or more new JWT session cookies with the new content, encrypts and then signs the cookies, assigns them an appropriate expiration time, and returns them in the response.
-
If the session is empty, PingGateway deletes the session, creates a new JWT session cookie with an expiration time that has already passed, and returns the cookie in the response.
-
If the session content has not changed, PingGateway does nothing.
-
Because the session content is stored in one or more JWT session cookies on the user agent, stateless sessions can be shared easily between PingGateway instances. The cookies are automatically carried over in requests, and any PingGateway instance can unpack and use the session content.
When PingGateway processes simultaneous requests in stateless sessions, there is a high risk that the data becomes inconsistent. This is because the session content is reconstructed for each exchange, and concurrent exchanges don’t have the same content.
PingGateway does not share sessions across requests. Instead, each request has its own session objects that it modifies as necessary, writing its own session to the session cookie regardless of what other requests do.
Session information is available in SessionContext to downstream handlers and filters. For more information, refer to SessionContext.
Session stickiness
Session stickiness helps to ensure that a client request goes to the server holding the original session data.
If data attached to a context must be stored on the server-side, configure session stickiness so that the load balancer sends all requests from the same client session to the same server.
The way you configure session stickiness and session replication depends on your load balancer.
Learn more from the example configuration in Share JWT sessions between multiple instances of PingGateway.