# Connection Isolation Architecture
## Overview
Starting from version 1.1.10, the `mcp-abap-adt` server implements per-session connection isolation to prevent data mixing between different clients. This ensures that when multiple clients connect to different SAP systems, each client receives only its own data.
## Problem Statement
In previous versions, the server used a global connection cache that could be overwritten by concurrent requests from different clients. This created a race condition where:
1. Client A connects to SAP System A
2. Client B connects to SAP System B (overwrites global config)
3. Client A's next request uses Client B's connection → **Data Leakage**
## Solution: Session-Based Connection Isolation
### Architecture
Each client session now maintains its own isolated SAP connection based on:
- **Session ID**: Unique identifier for each client session
- **Configuration Hash**: SHA-256 hash of `sapUrl` + authentication parameters
### Implementation Details
#### 1. Connection Cache Key Generation
```typescript
function generateConnectionCacheKey(sessionId: string, configSignature: string): string {
const hash = crypto.createHash('sha256');
hash.update(sessionId);
hash.update(configSignature);
return hash.digest('hex');
}
```
The cache key ensures that:
- Same session + same config = same connection (reused)
- Different session or different config = different connection (isolated)
#### 2. AsyncLocalStorage Context
The server uses Node.js `AsyncLocalStorage` to pass session context to handlers:
```typescript
await sessionContext.run(
{
sessionId: session.sessionId,
sapConfig: sessionSapConfig,
},
async () => {
// All handlers in this context can access sessionId and sapConfig
await transport.handleRequest(req, res, body);
}
);
```
#### 3. Connection Retrieval
`getManagedConnection()` checks AsyncLocalStorage first:
```typescript
export function getManagedConnection(): AbapConnection {
const context = sessionContext.getStore();
if (context?.sessionId && context?.sapConfig) {
// Use session-specific connection
return getConnectionForSession(context.sessionId, context.sapConfig);
}
// Fallback to global cache (for backward compatibility)
// ...
}
```
### Session Lifecycle
1. **Session Creation**: When a new client connects, a unique `sessionId` is generated
2. **Config Storage**: SAP configuration from HTTP headers is stored in the session object
3. **Connection Creation**: First request creates a connection with unique `sessionId` for the `AbapConnection`
4. **Connection Reuse**: Subsequent requests from the same session reuse the cached connection
5. **Session Cleanup**: When session closes, associated connection is removed from cache
### Benefits
1. **Security**: Prevents data leakage between clients
2. **Performance**: Connections are cached per session, reducing overhead
3. **Multi-Tenancy**: Supports multiple clients connecting to different SAP systems simultaneously
4. **Backward Compatibility**: Falls back to global cache for non-HTTP transports (stdio)
## Non-Local Connection Restrictions
### SSE Transport
SSE transport is **always** restricted to localhost connections only:
- Allowed: `127.0.0.1`, `::1`, `localhost`
- Rejected: Any other IP address (403 Forbidden)
This restriction ensures SSE is only used for local development/testing.
### HTTP Transport
HTTP transport has conditional restrictions based on `.env` file presence:
**When `.env` file exists:**
- Local connections: Always allowed
- Non-local connections: Allowed only if SAP headers are provided (`x-sap-url`, `x-sap-auth-type`)
**When `.env` file does not exist:**
- All connections: Allowed (enables multi-tenant scenarios)
### Rationale
- **With `.env` file**: Server is configured for a specific SAP system. Non-local connections without headers could be unauthorized access attempts.
- **Without `.env` file**: Server expects configuration via headers. All connections are allowed to support multi-tenant scenarios.
## Connection Cache Management
### Automatic Cleanup
The connection cache automatically removes old entries:
- **Max Age**: 1 hour
- **Trigger**: When cache size exceeds 100 entries
- **Method**: Iterates through cache and removes entries older than max age
### Manual Cleanup
Connections are also removed when:
- Session is closed (client disconnects)
- Connection is explicitly invalidated
## Example Flow
```
Client A (SAP System A):
Request 1 → Session A created → Connection A created (cache key: hash(sessionA + configA))
Request 2 → Session A found → Connection A reused
Request 3 → Session A found → Connection A reused
Client B (SAP System B) - Concurrent:
Request 1 → Session B created → Connection B created (cache key: hash(sessionB + configB))
Request 2 → Session B found → Connection B reused
✅ No data mixing: Client A always uses Connection A, Client B always uses Connection B
```
## Related Documentation
- [Client Configuration Guide](../user-guide/CLIENT_CONFIGURATION.md)
- [Stateful Session Guide](./STATEFUL_SESSION_GUIDE.md)
