npm - @contrail/flexplm - Versions diffs - 1.7.7-alpha.9292891 → 1.7.7-alpha.99f62a7 - Mend

@contrail/flexplm 1.7.7-alpha.9292891 → 1.7.7-alpha.99f62a7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/lib/interfaces/interfaces.d.ts +13 -1
package/lib/util/flexplm-connect.d.ts +5 -13
package/lib/util/flexplm-connect.js +94 -114
package/lib/util/flexplm-connect.spec.js +377 -27
package/lib/util/flexplm-session-manager.d.ts +40 -0
package/lib/util/flexplm-session-manager.js +192 -0
package/lib/util/flexplm-session-manager.spec.d.ts +1 -0
package/lib/util/flexplm-session-manager.spec.js +70 -0
package/package.json +1 -1

package/lib/interfaces/interfaces.d.ts CHANGED Viewed

@@ -1,3 +1,15 @@
+export interface SessionReuseConfig {
+    enabled?: boolean | string;
+    ttlSeconds?: number | string;
+    cookieName?: string;
+    retryStatuses?: number | number[] | string;
+}
+export interface FlexPLMConnectConfig {
+    staticHeaders?: {
+        [key: string]: string;
+    };
+    sessionReuse?: SessionReuseConfig;
+}
 export interface FCConfig {
     apiKey?: string;
     orgSlug?: string;
@@ -5,7 +17,7 @@ export interface FCConfig {
     configFile?: string;
     eventObjectClassParam?: string;
     eventFlexTypePathParam?: string;
-    flexplmConnect?: any;
+    flexplmConnect?: FlexPLMConnectConfig;
     taskId?: string;
     apiHost: string;
     userName(): string;

package/lib/util/flexplm-connect.d.ts CHANGED Viewed

@@ -1,24 +1,16 @@
 import { FCConfig, FlexPLMResponseData, PayloadType } from '../interfaces/interfaces';
 export declare class FlexPLMConnect {
     private config;
+    private sessions;
     private vibeEventEndpoint;
     private staticHeaders;
     payloadSendAsArray: boolean;
     constructor(_config: FCConfig, endPoint?: any, payloadAsArray?: any);
-    private get sessionOptions();
-    private getSessionKey;
-    private getCachedSession;
-    private storeSession;
-    private clearSession;
-    /** Returns the session cookie value Windchill issued on this response, if any (last one wins). */
-    private extractSessionCookie;
-    private cookieHeader;
+    /** Releases the connection of a rejected response before it is replaced by a retry. */
+    private discardBody;
     private getRequestOptions;
-    getCSRF(getNewSession?: boolean): Promise<{
-        nonce_key: any;
-        nonce: any;
-        sessionCookie: string;
-    }>;
+    getCSRF(getNewSession?: boolean, rejectedCookie?: string): any;
+    private fetchCSRF;
     sendRequest(csrf: any, payload: any): Promise<Response>;
     protected processRequest(payload: any): Promise<FlexPLMResponseData>;
     sendToFlexPLM(payload: PayloadType): Promise<FlexPLMResponseData>;

package/lib/util/flexplm-connect.js CHANGED Viewed

@@ -2,15 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlexPLMConnect = void 0;
 const app_framework_1 = require("@contrail/app-framework");
-// Module-level on purpose: a new FlexPLMConnect is constructed for every event. Declaring for Session reusing use case.
-const sessionCache = new Map();
-// Added for Session reuse - ET-390 - Ends
+const flexplm_session_manager_1 = require("./flexplm-session-manager");
+// Cookie values carry the session id: mask them in logs whatever the header-name casing.
+const maskCookieHeaders = (headers) => {
+    if (!headers)
+        return;
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === 'cookie' && headers[key])
+            headers[key] = '***masked***';
+    }
+};
 class FlexPLMConnect {
     constructor(_config, endPoint = undefined, payloadAsArray = undefined) {
         this.vibeEventEndpoint = '';
         this.staticHeaders = undefined;
         this.payloadSendAsArray = true;
         this.config = _config;
+        this.sessions = new flexplm_session_manager_1.FlexPLMSessionManager(_config);
         this.vibeEventEndpoint = (endPoint)
             ? endPoint
             : this.config.vibeEventEndpoint;
@@ -21,87 +29,18 @@ class FlexPLMConnect {
             this.staticHeaders = this.config?.flexplmConnect?.staticHeaders;
         }
     }
-    /////////////////////////////////////////////////////////////////////////////
-    ///////// ET-390 - Session reuse: start
-    /////////////////////////////////////////////////////////////////////////////
-    /*
-    private get sessionOptions() {
-      const sessReuseBool = this.config?.flexplmConnect?.sessionReuse;
-      console.info('sessReuseBool value is --> ' + sessReuseBool);
-      console.info('enabled value is --> ' + sessReuseBool?.enabled);
-      return {
-        enabled: sessReuseBool?.enabled === true || String(sessReuseBool?.enabled).toLowerCase() === 'true',
-        ttlMs: (sessReuseBool?.ttlSeconds ?? 900) * 1000,
-        cookieName: sessReuseBool?.cookieName ?? 'JSESSIONID',
-        retryStatuses: (sessReuseBool?.retryStatuses ?? [401, 403]) as number[],
-      };
-    }
-     */
-    get sessionOptions() {
-        const cfg = this.config ?? {};
-        const sessReuseEntries = (name) => cfg[`flexplmConnect.sessionReuse.${name}`];
-        const enabled = sessReuseEntries('enabled');
-        return {
-            enabled: enabled === true || String(enabled).toLowerCase() === 'true',
-            ttlMs: (sessReuseEntries('ttlSeconds') ?? 900) * 1000,
-            cookieName: sessReuseEntries('cookieName') ?? 'JSESSIONID',
-            retryStatuses: (sessReuseEntries('retryStatuses') ?? [401, 403]),
-        };
-    }
-    getSessionKey() {
-        return [this.config.apiHost, this.config.urlContext, this.config.userName(), this.config.plmEnviornment].join('|');
-    }
-    getCachedSession() {
-        if (!this.sessionOptions.enabled)
-            return undefined;
-        const key = this.getSessionKey();
-        const cachedSessValue = sessionCache.get(key);
-        if (!cachedSessValue)
-            return undefined;
-        if (cachedSessValue.expiresAt <= Date.now()) {
-            sessionCache.delete(key);
-            return undefined;
-        }
-        return cachedSessValue.cookie;
-    }
-    storeSession(cookie) {
-        // sliding expiry: Windchill's session timeout is also sliding
-        sessionCache.set(this.getSessionKey(), { cookie, expiresAt: Date.now() + this.sessionOptions.ttlMs });
-    }
-    clearSession() {
-        sessionCache.delete(this.getSessionKey());
-    }
-    /** Returns the session cookie value Windchill issued on this response, if any (last one wins). */
-    extractSessionCookie(response) {
-        const respHeader = response?.headers;
-        if (!respHeader)
-            return undefined;
-        let raw = [];
-        if (typeof respHeader.getSetCookie === 'function') {
-            raw = respHeader.getSetCookie();
-        }
-        else if (typeof respHeader.get === 'function' && respHeader.get('set-cookie')) {
-            raw = [respHeader.get('set-cookie')];
+    // ET-390 - Session reuse
+    /** Releases the connection of a rejected response before it is replaced by a retry. */
+    async discardBody(response) {
+        try {
+            if (typeof response?.body?.cancel === 'function')
+                await response.body.cancel();
         }
-        const name = this.sessionOptions.cookieName;
-        const regexFilter = new RegExp('(?:^|[,\\s])' + name + '=([^;,\\s]+)', 'g');
-        let jSession;
-        for (const line of raw) {
-            let cookieNameMatcher = regexFilter.exec(line);
-            while (cookieNameMatcher !== null) {
-                jSession = cookieNameMatcher[1];
-                cookieNameMatcher = regexFilter.exec(line);
-            }
+        catch (e) {
+            // best effort: nothing to do if the body is already consumed or locked
         }
-        return jSession;
-    }
-    cookieHeader(sessionCookie) {
-        return sessionCookie ? `${this.sessionOptions.cookieName}=${sessionCookie}` : undefined;
     }
     /////////////////////////////////////////////////////////////////////////////
-    ///////// ET-390 - Session reuse: end
-    /////////////////////////////////////////////////////////////////////////////
-    /////////////////////////////////////////////////////////////////////////////
     ///////// Custom getRequestOptions: start
     /////////////////////////////////////////////////////////////////////////////
     // ET-390 - adding a new parameter sessionCookie to the getRequestOptions function
@@ -118,17 +57,21 @@ class FlexPLMConnect {
             Object.assign(csrfOptions.headers, this.staticHeaders);
         }
         // Added for Session reuse - ET-390 - Starts
-        const cookie = this.cookieHeader(sessionCookie);
+        // Merge with a configured static Cookie header (any header-name casing) instead of replacing it.
+        const headers = csrfOptions.headers;
+        const staticCookieKeys = Object.keys(headers).filter(key => key.toLowerCase() === 'cookie');
+        const staticCookie = staticCookieKeys.map(key => headers[key]).join('; ');
+        const cookie = this.sessions.buildCookieHeader(staticCookie, sessionCookie);
+        staticCookieKeys.forEach(key => delete headers[key]);
         if (cookie) {
-            csrfOptions.headers['Cookie'] = cookie;
+            headers['Cookie'] = cookie;
         }
         // Added for Session reuse - ET-390 - Ends
         if (app_framework_1.Logger.isInfoOn()) {
             const logOptions = JSON.parse(JSON.stringify(csrfOptions));
             logOptions['headers']['Authorization'] = logOptions?.headers?.Authorization.substring(0, 9);
             // Added for Session reuse - ET-390 - Starts
-            if (logOptions.headers['Cookie'])
-                logOptions.headers['Cookie'] = '***masked***';
+            maskCookieHeaders(logOptions.headers);
             // Added for Session reuse - ET-390 - Ends
             console.info('csrfOptions: ' + JSON.stringify(logOptions));
         }
@@ -139,26 +82,48 @@ class FlexPLMConnect {
     /////////////////////////////////////////////////////////////////////////////
     // ET-390 - adding a new parameter getNewSession to the getCSRF function
     // Whenever a getCSRF is called without getNewSession, the default value of false will be used
-    async getCSRF(getNewSession = false) {
+    // rejectedCookie: the cookie that was rejected by the caller, so a refresh already done by a concurrent event is not thrown away
+    async getCSRF(getNewSession = false, rejectedCookie) {
+        // Added for Session reuse - ET-390 - Starts
+        if (!this.sessions.options.enabled)
+            return this.fetchCSRF(undefined);
+        for (let wait = this.sessions.waitForInFlightAcquisition(); wait; wait = this.sessions.waitForInFlightAcquisition())
+            await wait;
+        if (getNewSession) {
+            const current = this.sessions.getCachedSession();
+            if (rejectedCookie === undefined || !current || current === rejectedCookie)
+                this.sessions.clearSession();
+        }
+        const cached = this.sessions.getCachedSession();
+        if (cached) {
+            try {
+                return await this.fetchCSRF(cached);
+            }
+            catch (e) {
+                if (!(e instanceof flexplm_session_manager_1.SessionRejectedError))
+                    throw e;
+                // if the cached cookie is rejected (401/403), drop it and acquire a new session (serialized)
+                if (this.sessions.getCachedSession() === cached)
+                    this.sessions.clearSession();
+                return this.getCSRF();
+            }
+        }
+        return this.sessions.runColdAcquisition(() => this.fetchCSRF(undefined));
+        // Added for Session reuse - ET-390 - Ends
+    }
+    async fetchCSRF(sentCookie) {
         const urlContext = this.config.urlContext;
         const csrfEndpoint = this.config.csrfEndpoint;
         const csrfURL = this.config.apiHost + urlContext + csrfEndpoint;
         console.info('csrfURL: ' + csrfURL);
-        // Added for Session reuse - ET-390 - Starts
-        if (getNewSession)
-            this.clearSession();
-        let sentCookie = this.getCachedSession();
         // getRequestOptions will be called with additional sentCookie parameter
         const csrfOptions = this.getRequestOptions('GET', sentCookie);
-        // Added for Session reuse - ET-390 - Ends
-        let response = await fetch(csrfURL, csrfOptions);
+        const response = await fetch(csrfURL, csrfOptions);
         // Added for Session reuse - ET-390 - Starts
-        // if the response status is 401 or 403, then get a new session id
-        if (sentCookie && this.sessionOptions.retryStatuses.includes(response.status)) {
+        if (sentCookie && this.sessions.options.retryStatuses.includes(response.status)) {
             console.warn('Cached FlexPLM session rejected on csrf call (status ' + response.status + '). Retrying with a new session.');
-            this.clearSession();
-            sentCookie = undefined;
-            response = await fetch(csrfURL, this.getRequestOptions('GET'));
+            await this.discardBody(response);
+            throw new flexplm_session_manager_1.SessionRejectedError();
         }
         // Added for Session reuse - ET-390 - Ends
         if (response.status >= 300) {
@@ -172,10 +137,10 @@ class FlexPLMConnect {
         // Added for Session reuse - ET-390 - Starts
         // If the cookie we sent was invalid, Windchill answers with a fresh Set-Cookie --> replace the cache.
         let sessionCookie = sentCookie;
-        if (this.sessionOptions.enabled) {
-            sessionCookie = this.extractSessionCookie(response) ?? sentCookie;
+        if (this.sessions.options.enabled) {
+            sessionCookie = this.sessions.extractSessionCookie(response) ?? sentCookie;
             if (sessionCookie)
-                this.storeSession(sessionCookie);
+                this.sessions.storeSession(sessionCookie, sentCookie);
         }
         // Added for Session reuse - ET-390 - Ends
         try {
@@ -211,8 +176,7 @@ class FlexPLMConnect {
             const logOptions = JSON.parse(JSON.stringify(xferOptions));
             if (logOptions?.headers?.Authorization)
                 logOptions.headers.Authorization = logOptions?.headers?.Authorization.substring(0, 9);
-            if (logOptions?.headers?.Cookie)
-                logOptions.headers.Cookie = '***masked***';
+            maskCookieHeaders(logOptions?.headers);
             if (csrf?.nonce_key)
                 logOptions.headers[csrf.nonce_key] = csrf.nonce ? `***masked(length:${csrf.nonce.length})***` : '***masked(empty)***';
             console.info('csrfOptions: ' + JSON.stringify(logOptions));
@@ -239,9 +203,10 @@ class FlexPLMConnect {
         /// Added for Session reuse - ET-390 - Starts
         // const response = await this.sendRequest(csrf, payload);
         let response = await this.sendRequest(csrf, payload);
-        if (csrf.sessionCookie && this.sessionOptions.retryStatuses.includes(response.status)) {
+        if (csrf.sessionCookie && this.sessions.options.retryStatuses.includes(response.status)) {
             console.warn('FlexPLM rejected session/nonce (status ' + response.status + '). Getting a new session and retrying once.');
-            csrf = await this.getCSRF(true);
+            await this.discardBody(response);
+            csrf = await this.getCSRF(true, csrf.sessionCookie);
             response = await this.sendRequest(csrf, payload);
         }
         // Added for Session reuse - ET-390 - Ends
@@ -298,17 +263,32 @@ class FlexPLMConnect {
         const path = urlPath || ('/servlet/rest' + this.vibeEventEndpoint);
         const vibeEventsURL = this.config.apiHost + urlContext + path;
         // Added for Session reuse - ET-390 - Starts
-        const cached = this.getCachedSession();
-        const csrfOptions = this.getRequestOptions('GET', cached);
-        let response = await fetch(vibeEventsURL, csrfOptions);
-        if (cached && this.sessionOptions.retryStatuses.includes(response.status)) {
-            this.clearSession();
-            response = await fetch(vibeEventsURL, this.getRequestOptions('GET'));
-        }
-        if (this.sessionOptions.enabled) {
-            const cachedCookie = this.extractSessionCookie(response) ?? cached;
-            if (cachedCookie)
-                this.storeSession(cachedCookie);
+        const attempt = async () => {
+            if (!this.sessions.options.enabled) {
+                return { response: await fetch(vibeEventsURL, this.getRequestOptions('GET')), sent: undefined };
+            }
+            for (let wait = this.sessions.waitForInFlightAcquisition(); wait; wait = this.sessions.waitForInFlightAcquisition())
+                await wait;
+            const sent = this.sessions.getCachedSession();
+            const call = async () => {
+                const res = await fetch(vibeEventsURL, this.getRequestOptions('GET', sent));
+                // A rejected cookie must not be stored again; only keep a cookie that was accepted or newly issued.
+                if (!(sent && this.sessions.options.retryStatuses.includes(res.status))) {
+                    const cookie = this.sessions.extractSessionCookie(res) ?? sent;
+                    if (cookie)
+                        this.sessions.storeSession(cookie, sent);
+                }
+                return { response: res, sent };
+            };
+            return sent ? call() : this.sessions.runColdAcquisition(call);
+        };
+        const first = await attempt();
+        let response = first.response;
+        if (first.sent && this.sessions.options.retryStatuses.includes(response.status)) {
+            await this.discardBody(response);
+            if (this.sessions.getCachedSession() === first.sent)
+                this.sessions.clearSession();
+            response = (await attempt()).response;
         }
         // Added for Session reuse - ET-390 - Ends
         if (response.status >= 300) {

package/lib/util/flexplm-connect.spec.js CHANGED Viewed

@@ -39,12 +39,8 @@ const resp = (status, setCookie = [], json = csrfBody) => ({
 });
 let userCounter = 0;
 const uniqueUser = () => 'sess-user-' + (++userCounter);
-// The connector config is flat: keys look like 'flexplmConnect.sessionReuse.enabled'
-const sessionConfig = (user, sessionReuse = { enabled: true }) => {
-    const flat = {};
-    Object.entries(sessionReuse).forEach(([k, v]) => { flat[`flexplmConnect.sessionReuse.${k}`] = v; });
-    return createConfig({ userName: () => user, ...flat });
-};
+// Session options are nested: { flexplmConnect: { sessionReuse: { enabled, ... } } }
+const sessionConfig = (user, sessionReuse = { enabled: true }) => createConfig({ userName: () => user, flexplmConnect: { sessionReuse } });
 const fetchMock = () => global.fetch;
 const callHeaders = (i) => fetchMock().mock.calls[i][1].headers;
 const callMethod = (i) => fetchMock().mock.calls[i][1].method;
@@ -145,7 +141,7 @@ describe('FlexPLMConnect.sendRequest', () => {
 // Added for Session reuse - ET-390 - Starts
 describe('FlexPLMConnect session reuse', () => {
     const payload = { id: '123' };
-    it('should capture JSESSIONID from the csrf GET and sends it on the POST', async () => {
+    it('should capture JSESSIONID from the CSRF GET and send it on the POST', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1; Path=/; HttpOnly']))
@@ -156,7 +152,7 @@ describe('FlexPLMConnect session reuse', () => {
         expect(callHeaders(1).Cookie).toBe('JSESSIONID=abc.tomcat1');
         expect(callHeaders(1).CSRF_NONCE).toBe('n1');
     });
-    it('reuses the cached session on the next event (new FlexPLMConnect instance)', async () => {
+    it('should reuse the cached session on the next event (new FlexPLMConnect instance)', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1; Path=/'])) // event 1 GET
@@ -168,7 +164,7 @@ describe('FlexPLMConnect session reuse', () => {
         expect(callHeaders(2).Cookie).toBe('JSESSIONID=abc.tomcat1'); // GET reuses it
         expect(callHeaders(3).Cookie).toBe('JSESSIONID=abc.tomcat1'); // POST reuses it
     });
-    it('replaces the cached session when Windchill answers the GET with a new Set-Cookie', async () => {
+    it('should replace the cached session when Windchill answers the GET with a new Set-Cookie', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1; Path=/']))
@@ -185,7 +181,7 @@ describe('FlexPLMConnect session reuse', () => {
         expect(callHeaders(3).Cookie).toBe('JSESSIONID=new.tomcat1'); // POST uses the replacement
         expect(callHeaders(4).Cookie).toBe('JSESSIONID=new.tomcat1'); // event 3 GET sends the replacement
     });
-    it('retries once with a new session when the POST is rejected with 403', async () => {
+    it('should retry once with a new session when the POST is rejected with 403', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1; Path=/'])) // GET
@@ -199,7 +195,7 @@ describe('FlexPLMConnect session reuse', () => {
         expect(result.status).toBe(200);
         expect(result.data).toEqual({ ok: true });
     });
-    it('also retries on 401', async () => {
+    it('should also retry on 401', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1']))
@@ -209,7 +205,7 @@ describe('FlexPLMConnect session reuse', () => {
         await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).sendToFlexPLM(payload);
         expect(fetchMock()).toHaveBeenCalledTimes(4);
     });
-    it('does not loop: a second 403 after the retry is surfaced as an error', async () => {
+    it('should not loop: a second 403 after the retry is surfaced as an error', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1']))
@@ -220,7 +216,7 @@ describe('FlexPLMConnect session reuse', () => {
             .rejects.toThrow('Error sending data to FlexPLM:status: 403');
         expect(fetchMock()).toHaveBeenCalledTimes(4);
     });
-    it('does not retry on non-auth errors such as 500 (event may already be processed)', async () => {
+    it('should not retry on non-auth errors such as 500 (event may already be processed)', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
@@ -229,7 +225,7 @@ describe('FlexPLMConnect session reuse', () => {
             .rejects.toThrow('Error sending data to FlexPLM:status: 500');
         expect(fetchMock()).toHaveBeenCalledTimes(2);
     });
-    it('retries the csrf GET without a cookie when the cached session is rejected there', async () => {
+    it('should retry the csrf GET without a cookie when the cached session is rejected there', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1'])) // event 1 GET
@@ -243,7 +239,7 @@ describe('FlexPLMConnect session reuse', () => {
         expect(callHeaders(3).Cookie).toBeUndefined();
         expect(callHeaders(4).Cookie).toBe('JSESSIONID=new.tomcat1');
     });
-    it('expires the cached session after ttlSeconds', async () => {
+    it('should expire the cached session after ttlSeconds', async () => {
         const u = uniqueUser();
         const realNow = Date.now();
         const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(realNow);
@@ -260,7 +256,7 @@ describe('FlexPLMConnect session reuse', () => {
         expect(callHeaders(3).Cookie).toBe('JSESSIONID=def.tomcat1');
         nowSpy.mockRestore();
     });
-    it('uses the last JSESSIONID when several Set-Cookie lines are returned', async () => {
+    it('should use the last JSESSIONID when several Set-Cookie lines are returned', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=first.tomcat1; Path=/', 'OTHER=x; Path=/', 'JSESSIONID=second.tomcat1; Path=/']))
@@ -268,7 +264,7 @@ describe('FlexPLMConnect session reuse', () => {
         await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).sendToFlexPLM(payload);
         expect(callHeaders(1).Cookie).toBe('JSESSIONID=second.tomcat1');
     });
-    it('falls back to headers.get("set-cookie") when getSetCookie is not available', async () => {
+    it('should fall back to headers.get("set-cookie") when getSetCookie is not available', async () => {
         const u = uniqueUser();
         const legacy = {
             status: 200,
@@ -280,7 +276,7 @@ describe('FlexPLMConnect session reuse', () => {
         await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).sendToFlexPLM(payload);
         expect(callHeaders(1).Cookie).toBe('JSESSIONID=legacy.tomcat1');
     });
-    it('honours a custom cookieName', async () => {
+    it('should honour a custom cookieName', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['MYSESSION=zzz; Path=/', 'JSESSIONID=ignored; Path=/']))
@@ -288,7 +284,7 @@ describe('FlexPLMConnect session reuse', () => {
         await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, cookieName: 'MYSESSION' })).sendToFlexPLM(payload);
         expect(callHeaders(1).Cookie).toBe('MYSESSION=zzz');
     });
-    it('accepts enabled as the string "true"', async () => {
+    it('should accept enabled as the string "true"', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
@@ -296,7 +292,39 @@ describe('FlexPLMConnect session reuse', () => {
         await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: 'true' })).sendToFlexPLM(payload);
         expect(callHeaders(1).Cookie).toBe('JSESSIONID=abc.tomcat1');
     });
-    it('keeps separate sessions per user', async () => {
+    it('should evict expired sessions of other users when a new session is stored', async () => {
+        const userA = uniqueUser();
+        const userB = uniqueUser();
+        const realNow = Date.now();
+        const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(realNow);
+        fetchMock()
+            .mockResolvedValueOnce(resp(200, ['JSESSIONID=a.tomcat1'])) // A GET
+            .mockResolvedValueOnce(resp(200, [], {})) // A POST
+            .mockResolvedValueOnce(resp(200, ['JSESSIONID=b.tomcat1'])) // B GET
+            .mockResolvedValueOnce(resp(200, [], {})) // B POST
+            .mockResolvedValueOnce(resp(200, ['JSESSIONID=a2.tomcat1'])) // A GET again
+            .mockResolvedValueOnce(resp(200, [], {}));
+        const cfg = (u) => sessionConfig(u, { enabled: true, ttlSeconds: 1 });
+        await new flexplm_connect_1.FlexPLMConnect(cfg(userA)).sendToFlexPLM(payload);
+        nowSpy.mockReturnValue(realNow + 2000); // A has expired
+        await new flexplm_connect_1.FlexPLMConnect(cfg(userB)).sendToFlexPLM(payload); // storing B sweeps A
+        nowSpy.mockReturnValue(realNow); // rewind: only a swept A has no entry left
+        await new flexplm_connect_1.FlexPLMConnect(cfg(userA)).sendToFlexPLM(payload);
+        expect(callHeaders(4).Cookie).toBeUndefined();
+        nowSpy.mockRestore();
+    });
+    it('should not hold more than the maximum number of cached sessions', async () => {
+        const first = uniqueUser();
+        fetchMock().mockImplementation(async () => resp(200, ['JSESSIONID=s.tomcat1']));
+        await new flexplm_connect_1.FlexPLMConnect(sessionConfig(first)).sendToFlexPLM(payload);
+        for (let i = 0; i < 100; i++) {
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(uniqueUser())).sendToFlexPLM(payload);
+        }
+        fetchMock().mockClear();
+        await new flexplm_connect_1.FlexPLMConnect(sessionConfig(first)).sendToFlexPLM(payload);
+        expect(callHeaders(0).Cookie).toBeUndefined(); // oldest entry was evicted
+    });
+    it('should keep separate sessions per user', async () => {
         const a = uniqueUser();
         const b = uniqueUser();
         fetchMock()
@@ -309,7 +337,7 @@ describe('FlexPLMConnect session reuse', () => {
         expect(callHeaders(2).Cookie).toBeUndefined(); // user b must not see user a's cookie
         expect(callHeaders(3).Cookie).toBe('JSESSIONID=bbb.tomcat1');
     });
-    it('never logs the cookie value', async () => {
+    it('should never log the cookie value', async () => {
         const isInfoOn = jest.spyOn(app_framework_1.Logger, 'isInfoOn').mockReturnValue(true);
         const info = jest.spyOn(console, 'info').mockImplementation();
         const u = uniqueUser();
@@ -326,10 +354,317 @@ describe('FlexPLMConnect session reuse', () => {
         isInfoOn.mockRestore();
         info.mockRestore();
     });
+    describe('static Cookie header', () => {
+        const withStatic = (user, staticHeaders, sessionReuse = { enabled: true }) => createConfig({ userName: () => user, flexplmConnect: { sessionReuse, staticHeaders } });
+        it('should keep other static cookies and replace only the managed one once a session is cached', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=new.tomcat1; Path=/']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(withStatic(u, { Cookie: 'lb=abc; JSESSIONID=stale; theme=dark' })).sendToFlexPLM(payload);
+            expect(callHeaders(0).Cookie).toBe('lb=abc; theme=dark'); // cold: stale managed cookie dropped
+            expect(callHeaders(1).Cookie).toBe('lb=abc; theme=dark; JSESSIONID=new.tomcat1');
+        });
+        it('should send a single Cookie header when the static header name is lowercase', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1; Path=/']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(withStatic(u, { cookie: 'lb=abc' })).sendToFlexPLM(payload);
+            const postHeaders = callHeaders(1);
+            expect(Object.keys(postHeaders).filter(k => k.toLowerCase() === 'cookie')).toEqual(['Cookie']);
+            expect(postHeaders.Cookie).toBe('lb=abc; JSESSIONID=abc.tomcat1');
+        });
+        it('should send the static Cookie unchanged when session reuse is disabled', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1; Path=/']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(withStatic(u, { Cookie: 'lb=abc; JSESSIONID=static' }, { enabled: false })).sendToFlexPLM(payload);
+            expect(callHeaders(0).Cookie).toBe('lb=abc; JSESSIONID=static');
+            expect(callHeaders(1).Cookie).toBe('lb=abc; JSESSIONID=static');
+        });
+        it('should not resend a rejected static JSESSIONID on the fresh retry', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1; Path=/']))
+                .mockResolvedValueOnce(resp(403, [], {})) // POST rejected
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=fresh.tomcat1; Path=/'])) // fresh GET
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(withStatic(u, { Cookie: 'lb=abc; JSESSIONID=static' })).sendToFlexPLM(payload);
+            expect(callHeaders(2).Cookie).toBe('lb=abc'); // fresh GET carries no JSESSIONID
+            expect(callHeaders(3).Cookie).toBe('lb=abc; JSESSIONID=fresh.tomcat1');
+        });
+        it('should mask a lowercase static cookie header in logs', async () => {
+            const isInfoOn = jest.spyOn(app_framework_1.Logger, 'isInfoOn').mockReturnValue(true);
+            const info = jest.spyOn(console, 'info').mockImplementation();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(withStatic(uniqueUser(), { cookie: 'lb=topsecret' }, { enabled: false })).sendToFlexPLM(payload);
+            const logged = info.mock.calls.map(c => String(c[0] ?? '')).join('\n');
+            expect(logged).not.toContain('topsecret');
+            isInfoOn.mockRestore();
+            info.mockRestore();
+        });
+    });
+    describe('option normalisation', () => {
+        const rejectedOnceThenOk = (u, opts) => {
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1']))
+                .mockResolvedValueOnce(resp(403, [], {}))
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=new.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            return new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, ...opts })).sendToFlexPLM(payload);
+        };
+        it.each([
+            ['a scalar number', 403],
+            ['a comma separated string', '401, 403'],
+            ['garbage (falls back to 401/403)', 'abc'],
+            ['an empty array (falls back to 401/403)', []],
+        ])('should not throw and still retry on 403 when retryStatuses is %s', async (_label, retryStatuses) => {
+            await rejectedOnceThenOk(uniqueUser(), { retryStatuses });
+            expect(fetchMock()).toHaveBeenCalledTimes(4);
+        });
+        it.each([['abc'], [0], [-5]])('should fall back to the 900s default when ttlSeconds is invalid (%p)', async (ttlSeconds) => {
+            const u = uniqueUser();
+            const realNow = Date.now();
+            const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(realNow);
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}))
+                .mockResolvedValueOnce(resp(200, []))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            const cfg = sessionConfig(u, { enabled: true, ttlSeconds });
+            await new flexplm_connect_1.FlexPLMConnect(cfg).sendToFlexPLM(payload);
+            nowSpy.mockReturnValue(realNow + 2000);
+            await new flexplm_connect_1.FlexPLMConnect(cfg).sendToFlexPLM(payload);
+            expect(callHeaders(2).Cookie).toBe('JSESSIONID=abc.tomcat1');
+            nowSpy.mockRestore();
+        });
+        it('should fall back to JSESSIONID when cookieName is blank', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, cookieName: '   ' })).sendToFlexPLM(payload);
+            expect(callHeaders(1).Cookie).toBe('JSESSIONID=abc.tomcat1');
+        });
+    });
+    describe('retryStatuses restricted to client-error statuses', () => {
+        const postFailsWith = async (status, retryStatuses) => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
+                .mockResolvedValueOnce(resp(status, [], {}));
+            await expect(new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, retryStatuses })).sendToFlexPLM({ id: '1' }))
+                .rejects.toThrow('Error sending data to FlexPLM:status: ' + status);
+            expect(fetchMock()).toHaveBeenCalledTimes(2); // no retry
+        };
+        it.each([[500], ['500'], [[200, 500]]])('should ignore non-4xx retryStatuses (%p) and not retry a 500', async (retryStatuses) => {
+            await postFailsWith(500, retryStatuses);
+        });
+        it('should keep 4xx entries and drop others from a mixed retryStatuses list', async () => {
+            await postFailsWith(500, [401, 500]);
+        });
+        it('should not resend a successful event when retryStatuses is configured as 200', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, retryStatuses: 200 })).sendToFlexPLM({ id: '1' });
+            expect(fetchMock()).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('session cache key includes session options', () => {
+        it('should not share a cached cookie between different cookieNames for the same user', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['AAA=a1; Path=/']))
+                .mockResolvedValueOnce(resp(200, [], {}))
+                .mockResolvedValueOnce(resp(200, ['BBB=b1; Path=/']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, cookieName: 'AAA' })).sendToFlexPLM({ id: '1' });
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, cookieName: 'BBB' })).sendToFlexPLM({ id: '1' });
+            expect(callHeaders(2).Cookie).toBeUndefined(); // BBB config must not pick up the AAA session
+            expect(callHeaders(3).Cookie).toBe('BBB=b1');
+        });
+        it('should not share a cached session between different ttlSeconds for the same user', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=short.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}))
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=long.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, ttlSeconds: 1 })).sendToFlexPLM({ id: '1' });
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, ttlSeconds: 900 })).sendToFlexPLM({ id: '1' });
+            expect(callHeaders(2).Cookie).toBeUndefined();
+            expect(callHeaders(3).Cookie).toBe('JSESSIONID=long.tomcat1');
+        });
+    });
+    describe('rejected response disposal', () => {
+        const withBody = (r) => Object.assign(r, { body: { cancel: jest.fn().mockResolvedValue(undefined) } });
+        it('should cancel the body of a POST rejected with 403 before retrying', async () => {
+            const u = uniqueUser();
+            const rejected = withBody(resp(403, [], {}));
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1']))
+                .mockResolvedValueOnce(rejected)
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=new.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).sendToFlexPLM({ id: '1' });
+            expect(rejected.body.cancel).toHaveBeenCalledTimes(1);
+        });
+        it('should cancel the body of a CSRF GET rejected with the cached cookie before retrying', async () => {
+            const u = uniqueUser();
+            const rejected = withBody(resp(401, []));
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}))
+                .mockResolvedValueOnce(rejected)
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=new.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).sendToFlexPLM({ id: '1' });
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).sendToFlexPLM({ id: '1' });
+            expect(rejected.body.cancel).toHaveBeenCalledTimes(1);
+        });
+        it('should cancel the body of a getRequest rejected with the cached cookie before retrying', async () => {
+            const u = uniqueUser();
+            const rejected = withBody(resp(401, []));
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}))
+                .mockResolvedValueOnce(rejected)
+                .mockResolvedValueOnce(resp(200, [], { items: [] }));
+            const connect = new flexplm_connect_1.FlexPLMConnect(sessionConfig(u));
+            await connect.sendToFlexPLM({ id: '1' });
+            await connect.getRequest();
+            expect(rejected.body.cancel).toHaveBeenCalledTimes(1);
+        });
+        it('should still retry when cancelling the body throws', async () => {
+            const u = uniqueUser();
+            const rejected = resp(403, [], {});
+            rejected.body = { cancel: jest.fn().mockRejectedValue(new Error('locked')) };
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1']))
+                .mockResolvedValueOnce(rejected)
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=new.tomcat1']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).sendToFlexPLM({ id: '1' });
+            expect(fetchMock()).toHaveBeenCalledTimes(4);
+        });
+    });
+    describe('cookie names containing regex metacharacters', () => {
+        it('should extract a cookie whose name contains "+"', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['SID+=abc; Path=/']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, cookieName: 'SID+' })).sendToFlexPLM(payload);
+            expect(callHeaders(1).Cookie).toBe('SID+=abc');
+        });
+        it('should treat "." literally and not match a look-alike cookie', async () => {
+            const u = uniqueUser();
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['AxB=wrong; Path=/']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u, { enabled: true, cookieName: 'A.B' })).sendToFlexPLM(payload);
+            expect(callHeaders(1).Cookie).toBeUndefined();
+        });
+    });
+    describe('concurrent session acquisition', () => {
+        const flush = () => new Promise(r => setImmediate(r));
+        const isColdGet = (call) => call[1].method === 'GET' && !call[1].headers.Cookie;
+        it('should not let a late response using an older cookie roll back a refreshed session', async () => {
+            const u = uniqueUser();
+            const cfg = () => sessionConfig(u);
+            // seed the cache with 'old'
+            fetchMock()
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=old']))
+                .mockResolvedValueOnce(resp(200, [], {}));
+            await new flexplm_connect_1.FlexPLMConnect(cfg()).sendToFlexPLM(payload);
+            let lateGetsSeen = 0;
+            let releaseLate;
+            const lateGate = new Promise(r => { releaseLate = r; });
+            fetchMock().mockReset();
+            fetchMock().mockImplementation(async (_url, opts) => {
+                const cookie = opts.headers.Cookie;
+                if (opts.method === 'GET' && cookie === 'JSESSIONID=old') {
+                    if (++lateGetsSeen === 1)
+                        return resp(403, []); // event A: old rejected
+                    await lateGate; // event B: slow 200, no Set-Cookie
+                    return resp(200, []);
+                }
+                if (opts.method === 'GET' && !cookie)
+                    return resp(200, ['JSESSIONID=new']); // A's fresh acquisition
+                if (opts.method === 'GET')
+                    return resp(200, []);
+                return resp(200, [], {});
+            });
+            const a = new flexplm_connect_1.FlexPLMConnect(cfg()).sendToFlexPLM(payload);
+            const b = new flexplm_connect_1.FlexPLMConnect(cfg()).sendToFlexPLM(payload);
+            await a;
+            releaseLate();
+            await b;
+            fetchMock().mockClear();
+            await new flexplm_connect_1.FlexPLMConnect(cfg()).getCSRF();
+            expect(callHeaders(0).Cookie).toBe('JSESSIONID=new'); // B must not have stored 'old' again
+        });
+        it('should share one session across concurrent events on a cold cache', async () => {
+            const u = uniqueUser();
+            let release;
+            const gate = new Promise(r => { release = r; });
+            fetchMock().mockImplementation(async (_url, opts) => {
+                if (opts.method === 'GET' && !opts.headers.Cookie) {
+                    await gate;
+                    return resp(200, ['JSESSIONID=abc.tomcat1']);
+                }
+                return resp(200, []);
+            });
+            const all = Promise.all([1, 2, 3].map(() => new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).getCSRF()));
+            await flush();
+            expect(fetchMock()).toHaveBeenCalledTimes(1); // the other two are waiting for the first acquisition
+            release();
+            const results = await all;
+            expect(fetchMock().mock.calls.filter(isColdGet)).toHaveLength(1);
+            results.forEach(r => expect(r.sessionCookie).toBe('abc.tomcat1'));
+        });
+        it('should not make a waiter inherit the failure of the first acquisition', async () => {
+            const u = uniqueUser();
+            let release;
+            const gate = new Promise(r => { release = r; });
+            fetchMock()
+                .mockImplementationOnce(async () => { await gate; return resp(500, []); })
+                .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']));
+            const first = new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).getCSRF();
+            const firstResult = first.catch(e => e);
+            const second = new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).getCSRF();
+            await flush();
+            release();
+            expect(await firstResult).toBeInstanceOf(Error);
+            expect((await second).sessionCookie).toBe('abc.tomcat1');
+        });
+        it('should create only one replacement session for parallel events rejected with 403', async () => {
+            const u = uniqueUser();
+            fetchMock().mockResolvedValueOnce(resp(200, ['JSESSIONID=old.tomcat1']));
+            await new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).getCSRF(); // prime the cache with the old session
+            fetchMock().mockReset();
+            fetchMock().mockImplementation(async (_url, opts) => {
+                const cookie = opts.headers.Cookie;
+                if (opts.method === 'POST')
+                    return cookie === 'JSESSIONID=new.tomcat1' ? resp(200, [], {}) : resp(403, [], {});
+                if (!cookie)
+                    return resp(200, ['JSESSIONID=new.tomcat1']);
+                return resp(200, []);
+            });
+            await Promise.all([1, 2, 3].map(() => new flexplm_connect_1.FlexPLMConnect(sessionConfig(u)).sendToFlexPLM(payload)));
+            expect(fetchMock().mock.calls.filter(isColdGet)).toHaveLength(1);
+        });
+    });
 });
 describe('FlexPLMConnect session reuse - feature disabled (default)', () => {
     const payload = { id: '123' };
-    it('sends no Cookie header and makes exactly one GET + one POST', async () => {
+    it('should send no Cookie header and make exactly one GET + one POST', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1'])) // Set-Cookie present but must be ignored
@@ -343,7 +678,7 @@ describe('FlexPLMConnect session reuse - feature disabled (default)', () => {
             expect(callHeaders(i).Cookie).toBeUndefined();
         }
     });
-    it('does not retry on 403 (behaves exactly as before)', async () => {
+    it('should not retry on 403 (behaves exactly as before)', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200))
@@ -352,7 +687,7 @@ describe('FlexPLMConnect session reuse - feature disabled (default)', () => {
             .rejects.toThrow('Error sending data to FlexPLM:status: 403');
         expect(fetchMock()).toHaveBeenCalledTimes(2);
     });
-    it('explicit enabled:false behaves the same as not configured', async () => {
+    it('should behave the same as not configured when enabled is false', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
@@ -361,8 +696,8 @@ describe('FlexPLMConnect session reuse - feature disabled (default)', () => {
         expect(callHeaders(1).Cookie).toBeUndefined();
     });
 });
-describe('FlexPLMConnect.getRequest session reuse (only if you applied step 2g)', () => {
-    it('sends the cached cookie on image/GET requests', async () => {
+describe('FlexPLMConnect.getRequest session reuse', () => {
+    it('should send the cached cookie on image/GET requests', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1'])) // csrf GET primes the cache
@@ -373,7 +708,7 @@ describe('FlexPLMConnect.getRequest session reuse (only if you applied step 2g)'
         await connect.getRequest();
         expect(callHeaders(2).Cookie).toBe('JSESSIONID=abc.tomcat1');
     });
-    it('retries once without the cookie when the cached session is rejected on getRequest', async () => {
+    it('should retry once without the cookie when the cached session is rejected on getRequest', async () => {
         const u = uniqueUser();
         fetchMock()
             .mockResolvedValueOnce(resp(200, ['JSESSIONID=abc.tomcat1']))
@@ -386,5 +721,20 @@ describe('FlexPLMConnect.getRequest session reuse (only if you applied step 2g)'
         expect(callHeaders(2).Cookie).toBe('JSESSIONID=abc.tomcat1');
         expect(callHeaders(3).Cookie).toBeUndefined();
     });
+    it('should not re-store the rejected cookie when the retry issues no Set-Cookie', async () => {
+        const u = uniqueUser();
+        fetchMock()
+            .mockResolvedValueOnce(resp(200, ['JSESSIONID=stale.tomcat1']))
+            .mockResolvedValueOnce(resp(200, [], {}))
+            .mockResolvedValueOnce(resp(401, [])) // getRequest with the cached cookie
+            .mockResolvedValueOnce(resp(200, [], { items: [] })) // retry succeeds, no Set-Cookie
+            .mockResolvedValueOnce(resp(200, [], { items: [] })); // next getRequest
+        const connect = new flexplm_connect_1.FlexPLMConnect(sessionConfig(u));
+        await connect.sendToFlexPLM({ id: '1' });
+        await connect.getRequest();
+        await connect.getRequest();
+        expect(callHeaders(3).Cookie).toBeUndefined();
+        expect(callHeaders(4).Cookie).toBeUndefined(); // stale cookie must not be sent again
+    });
 });
 // Added for Session reuse - ET-390 - Ends

package/lib/util/flexplm-session-manager.d.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { FCConfig } from '../interfaces/interfaces';
+export declare class SessionRejectedError extends Error {
+}
+/** Owns the FlexPLM session cookie cache: options, keying, expiry, in-flight acquisition sharing and Set-Cookie parsing. */
+export declare class FlexPLMSessionManager {
+    private config;
+    constructor(config: FCConfig);
+    get options(): {
+        enabled: boolean;
+        ttlMs: number;
+        cookieName: string;
+        retryStatuses: number[];
+    };
+    /**
+     * Waits until no cold session acquisition is running for this key.
+     * Callers must `await` this only when it returns a promise: awaiting even a resolved promise yields,
+     * and the check-then-register in runColdAcquisition has to stay synchronous to be race free.
+     */
+    waitForInFlightAcquisition(): Promise<void> | undefined;
+    /** Runs a cold acquisition and registers it so concurrent callers wait for it instead of opening their own session. */
+    runColdAcquisition<T>(acquire: () => Promise<T>): Promise<T>;
+    private getSessionKey;
+    getCachedSession(): string | undefined;
+    /**
+     * Compare-and-set: stores `cookie` only if the cache still holds the cookie this request was sent with
+     * (`sentCookie`, undefined for a cold acquisition = nothing cached). A late response must not roll back or
+     * resurrect a session that a concurrent event already replaced or cleared.
+     * @returns true if the cache was updated
+     */
+    storeSession(cookie: string, sentCookie: string | undefined): boolean;
+    clearSession(): void;
+    /** Returns the session cookie value Windchill issued on this response, if any (last one wins). */
+    extractSessionCookie(response: Response): string | undefined;
+    /**
+     * Builds the Cookie header value from the configured static Cookie header and the managed session cookie.
+     * With session reuse enabled only the managed cookie is replaced/removed; every other static cookie pair is kept.
+     * With session reuse disabled the static value is returned unchanged.
+     */
+    buildCookieHeader(staticCookie?: string, sessionCookie?: string): string | undefined;
+}

package/lib/util/flexplm-session-manager.js ADDED Viewed

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlexPLMSessionManager = exports.SessionRejectedError = void 0;
+const crypto_1 = require("crypto");
+// Module-level on purpose: a new FlexPLMConnect (and session manager) is constructed for every event.
+const sessionCache = new Map();
+// Upper bound so users/option combinations that are never requested again cannot accumulate cookies forever.
+const MAX_CACHED_SESSIONS = 100;
+const pruneSessionCache = () => {
+    const now = Date.now();
+    for (const [key, session] of sessionCache) {
+        if (session.expiresAt <= now)
+            sessionCache.delete(key);
+    }
+    // Still full: drop the oldest entries (Map keeps insertion order).
+    while (sessionCache.size >= MAX_CACHED_SESSIONS) {
+        sessionCache.delete(sessionCache.keys().next().value);
+    }
+};
+// In-flight cold session acquisitions per key, so concurrent events share one FlexPLM session instead of each creating their own.
+const inFlightAcquisitions = new Map();
+const SESSION_CACHE_DIGEST_KEY = (0, crypto_1.randomBytes)(32);
+const DEFAULT_SESSION_COOKIE_NAME = 'JSESSIONID';
+const DEFAULT_SESSION_TTL_SECONDS = 900;
+const DEFAULT_RETRY_STATUSES = [401, 403];
+const COOKIE_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+// Thrown internally when a cached cookie was rejected, so the caller can re-acquire under the lock.
+class SessionRejectedError extends Error {
+}
+exports.SessionRejectedError = SessionRejectedError;
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const parseRetryStatuses = (value) => {
+    let list = [];
+    if (Array.isArray(value))
+        list = value;
+    else if (typeof value === 'string')
+        list = value.split(',');
+    else if (value !== undefined && value !== null)
+        list = [value];
+    const statuses = list
+        .map(status => (typeof status === 'string' ? status.trim() : status))
+        .filter(status => status !== '' && status !== null && status !== undefined)
+        .map(Number)
+        // Only client-error statuses can mean "session rejected". 2xx/5xx would resend events the server already processed.
+        .filter(status => Number.isInteger(status) && status >= 400 && status <= 499);
+    return statuses.length ? statuses : DEFAULT_RETRY_STATUSES;
+};
+const parseTtlSeconds = (value) => {
+    const ttl = Number(value);
+    return Number.isFinite(ttl) && ttl > 0 ? ttl : DEFAULT_SESSION_TTL_SECONDS;
+};
+const parseCookieName = (value) => {
+    const name = typeof value === 'string' ? value.trim() : '';
+    return COOKIE_NAME_TOKEN.test(name) ? name : DEFAULT_SESSION_COOKIE_NAME;
+};
+/** Owns the FlexPLM session cookie cache: options, keying, expiry, in-flight acquisition sharing and Set-Cookie parsing. */
+class FlexPLMSessionManager {
+    constructor(config) {
+        this.config = config;
+    }
+    get options() {
+        const sessionReuseConfig = this.config?.flexplmConnect?.sessionReuse ?? {};
+        return {
+            enabled: sessionReuseConfig.enabled === true || String(sessionReuseConfig.enabled).toLowerCase() === 'true',
+            ttlMs: parseTtlSeconds(sessionReuseConfig.ttlSeconds) * 1000,
+            cookieName: parseCookieName(sessionReuseConfig.cookieName),
+            retryStatuses: parseRetryStatuses(sessionReuseConfig.retryStatuses),
+        };
+    }
+    /**
+     * Waits until no cold session acquisition is running for this key.
+     * Callers must `await` this only when it returns a promise: awaiting even a resolved promise yields,
+     * and the check-then-register in runColdAcquisition has to stay synchronous to be race free.
+     */
+    waitForInFlightAcquisition() {
+        const key = this.getSessionKey();
+        if (!inFlightAcquisitions.has(key))
+            return undefined;
+        return (async () => {
+            let pending = inFlightAcquisitions.get(key);
+            while (pending) {
+                await pending.catch(() => undefined);
+                pending = inFlightAcquisitions.get(key);
+            }
+        })();
+    }
+    /** Runs a cold acquisition and registers it so concurrent callers wait for it instead of opening their own session. */
+    async runColdAcquisition(acquire) {
+        const key = this.getSessionKey();
+        const acquisition = acquire();
+        inFlightAcquisitions.set(key, acquisition);
+        try {
+            return await acquisition;
+        }
+        finally {
+            if (inFlightAcquisitions.get(key) === acquisition)
+                inFlightAcquisitions.delete(key);
+        }
+    }
+    getSessionKey() {
+        // Options that change the cached value are part of the key; JSON avoids '|' collisions between fields.
+        const { cookieName, ttlMs } = this.options;
+        const staticHeaders = Object.entries(this.config.flexplmConnect?.staticHeaders ?? {})
+            .map(([name, value]) => [name.toLowerCase(), value])
+            .sort(([nameA, valueA], [nameB, valueB]) => {
+            if (nameA !== nameB)
+                return nameA < nameB ? -1 : 1;
+            return valueA < valueB ? -1 : valueA > valueB ? 1 : 0;
+        });
+        const authenticationAndRoutingDigest = (0, crypto_1.createHmac)('sha256', SESSION_CACHE_DIGEST_KEY)
+            .update(JSON.stringify([this.config.userName(), staticHeaders]))
+            .digest('hex');
+        return JSON.stringify([
+            this.config.apiHost, this.config.urlContext, this.config.plmEnviornment, cookieName, ttlMs, authenticationAndRoutingDigest,
+        ]);
+    }
+    getCachedSession() {
+        if (!this.options.enabled)
+            return undefined;
+        const key = this.getSessionKey();
+        const cachedSessValue = sessionCache.get(key);
+        if (!cachedSessValue)
+            return undefined;
+        if (cachedSessValue.expiresAt <= Date.now()) {
+            sessionCache.delete(key);
+            return undefined;
+        }
+        return cachedSessValue.cookie;
+    }
+    /**
+     * Compare-and-set: stores `cookie` only if the cache still holds the cookie this request was sent with
+     * (`sentCookie`, undefined for a cold acquisition = nothing cached). A late response must not roll back or
+     * resurrect a session that a concurrent event already replaced or cleared.
+     * @returns true if the cache was updated
+     */
+    storeSession(cookie, sentCookie) {
+        const key = this.getSessionKey();
+        if (sessionCache.get(key)?.cookie !== sentCookie)
+            return false;
+        // sliding expiry: Windchill's session timeout is also sliding
+        // delete first so a refreshed entry moves to the newest position (oldest-first eviction then acts as LRU)
+        sessionCache.delete(key);
+        pruneSessionCache();
+        sessionCache.set(key, { cookie, expiresAt: Date.now() + this.options.ttlMs });
+        return true;
+    }
+    clearSession() {
+        sessionCache.delete(this.getSessionKey());
+    }
+    /** Returns the session cookie value Windchill issued on this response, if any (last one wins). */
+    extractSessionCookie(response) {
+        const respHeader = response?.headers;
+        if (!respHeader)
+            return undefined;
+        let raw = [];
+        if (typeof respHeader.getSetCookie === 'function') {
+            raw = respHeader.getSetCookie();
+        }
+        else if (typeof respHeader.get === 'function' && respHeader.get('set-cookie')) {
+            raw = [respHeader.get('set-cookie')];
+        }
+        const name = this.options.cookieName;
+        const regexFilter = new RegExp('(?:^|[,\\s])' + escapeRegExp(name) + '=([^;,\\s]+)', 'g');
+        let jSession;
+        for (const line of raw) {
+            let cookieNameMatcher = regexFilter.exec(line);
+            while (cookieNameMatcher !== null) {
+                jSession = cookieNameMatcher[1];
+                cookieNameMatcher = regexFilter.exec(line);
+            }
+        }
+        return jSession;
+    }
+    /**
+     * Builds the Cookie header value from the configured static Cookie header and the managed session cookie.
+     * With session reuse enabled only the managed cookie is replaced/removed; every other static cookie pair is kept.
+     * With session reuse disabled the static value is returned unchanged.
+     */
+    buildCookieHeader(staticCookie, sessionCookie) {
+        if (!this.options.enabled)
+            return staticCookie || undefined;
+        const name = this.options.cookieName;
+        const pairs = (staticCookie ?? '')
+            .split(';')
+            .map(pair => pair.trim())
+            .filter(pair => pair && pair.split('=')[0].trim() !== name);
+        if (sessionCookie)
+            pairs.push(`${name}=${sessionCookie}`);
+        return pairs.length ? pairs.join('; ') : undefined;
+    }
+}
+exports.FlexPLMSessionManager = FlexPLMSessionManager;

package/lib/util/flexplm-session-manager.spec.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/lib/util/flexplm-session-manager.spec.js ADDED Viewed

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const flexplm_session_manager_1 = require("./flexplm-session-manager");
+let userCounter = 0;
+const newManager = (user = 'mgr-user-' + (++userCounter), staticHeaders) => {
+    const config = {
+        apiHost: 'https://flexplm.example.com',
+        urlContext: '/FlexPLM',
+        vibeEventEndpoint: '/api/events',
+        csrfEndpoint: '/csrf',
+        plmEnviornment: 'test',
+        userName: () => user,
+        password: () => 'pass',
+        itemPreDevelopmentLifecycleStages: [],
+        flexplmConnect: { staticHeaders, sessionReuse: { enabled: true } },
+    };
+    return new flexplm_session_manager_1.FlexPLMSessionManager(config);
+};
+describe('FlexPLMSessionManager.storeSession (compare-and-set)', () => {
+    it('should store a cold acquisition when nothing is cached', () => {
+        const m = newManager();
+        expect(m.storeSession('a', undefined)).toBe(true);
+        expect(m.getCachedSession()).toBe('a');
+    });
+    it('should not let a cold acquisition overwrite an entry that appeared meanwhile', () => {
+        const m = newManager();
+        m.storeSession('a', undefined);
+        expect(m.storeSession('b', undefined)).toBe(false);
+        expect(m.getCachedSession()).toBe('a');
+    });
+    it('should replace or refresh the entry while it still holds the cookie that was sent', () => {
+        const m = newManager();
+        m.storeSession('old', undefined);
+        expect(m.storeSession('new', 'old')).toBe(true);
+        expect(m.getCachedSession()).toBe('new');
+        expect(m.storeSession('new', 'new')).toBe(true); // sliding refresh with the same cookie
+    });
+    it('should ignore a late response that was sent with an older cookie', () => {
+        const m = newManager();
+        m.storeSession('old', undefined);
+        m.storeSession('new', 'old');
+        expect(m.storeSession('old', 'old')).toBe(false);
+        expect(m.getCachedSession()).toBe('new');
+    });
+    it('should not resurrect a session that was cleared meanwhile', () => {
+        const m = newManager();
+        m.storeSession('old', undefined);
+        m.clearSession();
+        expect(m.storeSession('old', 'old')).toBe(false);
+        expect(m.getCachedSession()).toBeUndefined();
+    });
+    it('should isolate cached sessions when static authorization headers differ', () => {
+        const firstManager = newManager('shared-user', { Authorization: 'Basic first', PLM_ENV: 'test' });
+        const secondManager = newManager('shared-user', { Authorization: 'Basic second', PLM_ENV: 'test' });
+        firstManager.storeSession('first-session', undefined);
+        expect(secondManager.getCachedSession()).toBeUndefined();
+    });
+    it('should isolate cached sessions when static routing headers differ', () => {
+        const firstManager = newManager('shared-user', { 'X-Route': 'route-a' });
+        const secondManager = newManager('shared-user', { 'X-Route': 'route-b' });
+        firstManager.storeSession('first-session', undefined);
+        expect(secondManager.getCachedSession()).toBeUndefined();
+    });
+    it('should reuse cached sessions for equivalent static headers regardless of header order or casing', () => {
+        const firstManager = newManager('shared-user', { 'Authorization': 'Basic same', 'X-Route': 'route-a' });
+        const secondManager = newManager('shared-user', { 'x-route': 'route-a', 'authorization': 'Basic same' });
+        firstManager.storeSession('shared-session', undefined);
+        expect(secondManager.getCachedSession()).toBe('shared-session');
+    });
+});

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/flexplm",
-  "version": "1.7.7-alpha.9292891",
+  "version": "1.7.7-alpha.99f62a7",
   "description": "Library used for integration with flexplm.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",