Multi-context Session Configuration Strategy and Patterns

Aspectow, based on the Undertow engine, provides a multi-context environment where multiple web contexts can operate simultaneously. In such an environment, how user states (sessions) are managed and shared is a crucial part of the application’s architectural design.

This document describes the session management patterns that can be implemented through combinations of three core components (SessionManager, SessionConfig, SessionStore) and outlines important precautions during configuration.

For a more detailed explanation of the architecture and core components of the Aspectran Session Manager, please refer to the Aspectran Session Manager: Deep Dive document.

1. Three Patterns of Session Management

In a multi-context environment, sessions can be configured into three patterns based on the scope of sharing:

Pattern 1: Complete Isolation

Each context has its own SessionManager and SessionConfig.

• Sharing Scope: None. Each context has a different session ID, and data is managed separately.
• Characteristics: Most secure as there is no interference between contexts, and session policies (timeouts, etc.) can be set freely for each app.

Pattern 2: Session ID Sharing

Multiple contexts share the same SessionConfig (cookie settings), but each has its own SessionManager.

• Sharing Scope: Only the Session ID (cookie) is shared. The browser sends the same session cookie for all related contexts.
• Data Characteristics: Even if the session ID is the same, session data for each context is independent. That is, attributes stored in Context A cannot be read from Context B.
• Traceability: Since each manager has a unique workerName, you can track which context generated the session via the session ID suffix.

Pattern 3: Session Data Sharing

Multiple contexts share a single SessionManager instance.

• Sharing Scope: Both Session ID and session data are shared.
• Implementation: Configure multiple contexts to reference a single SessionManager bean defined at the server or parent level.
• Characteristics: A true shared session where login information in one context can be immediately accessed by another. Note that all contexts will use the same session lifecycle and storage.

2. Essential Precautions (Best Practices)

⚠️ Never Overlap Storage Paths (When using multiple managers)

When using different SessionManager instances (as in Pattern 1 or 2), they must never point to the same physical directory for their SessionStore.

• Risk: Each SessionManager has a built-in HouseKeeper that cleans up expired session files. If paths overlap, different managers will compete to delete or modify the same files, leading to data loss and file lock errors.
• Solution: Ensure a unique baseDirectory is specified for each manager/context.

⚠️ Ensure Uniqueness of workerName (Mandatory)

The session ID generated by the SessionIdGenerator includes the workerName as a suffix (.workerName). When operating multiple SessionManager instances within a single server, you must assign a unique workerName to each manager for the following reasons:

• ID Collision Prevention: Ensures the uniqueness of the generated session IDs.
• Origin Tracking: In environments where only session IDs are shared (Pattern 2), log analysis clearly reveals which context’s session manager originally created the session.
• Constraint: The workerName cannot contain a period (.).

⚠️ Default Behavior when Unconfigured

If a SessionManager is not explicitly configured for a context, Undertow’s built-in session manager will be used by default. You only need to configure Aspectran’s SessionManager for contexts that require sophisticated control (e.g., new session timeouts, clustering).

3. Configuration Example (Pattern 2: Session ID Sharing, Data Isolation)

In this pattern, session stores are separated per context to ensure data isolation, but they are configured to share the same Session ID. This is primarily used in special cases where consistent user tracking across multiple contexts is required.

<!-- Shared session cookie configuration (usually set to a top-level path) -->
<bean id="tow.server.servletSessionConfig" class="com.aspectran.undertow.server.session.TowServletSessionConfig">
    <property name="cookieConfig">
        <bean class="com.aspectran.undertow.server.session.TowSessionCookieConfig">
            <property name="path">/</property> 
        </bean>
    </property>
</bean>

<!-- SessionManager for Context A: Shares Session ID but stores data in a separate directory -->
<bean id="tow.appmon.sessionManager" class="com.aspectran.undertow.server.session.TowSessionManager">
    <property name="workerName" value="appmon"/> <!-- Unique worker name is mandatory -->
    <property name="sessionStore">
        <bean class="com.aspectran.core.component.session.FileSessionStoreFactoryBean">
            <property name="storeDir">/app/work/_sessions/appmon</property> <!-- Separate path is mandatory -->
        </bean>
    </property>
</bean>

4. Conclusion

While Aspectow’s session configuration is flexible, the principle that “one directory must be managed by only one SessionManager instance” and the “assignment of a unique workerName per manager” must be strictly followed. If session sharing is required, clearly decide whether to share only the ID (Pattern 2) or the data as well via a single manager instance (Pattern 3) during the design phase.