ti2 1.0.114 → 1.0.116

package/CLAUDE.md

@@ -28,6 +28,13 @@ Ti2 (Tourism Information Interchange) is an open-source integration framework fo
 
 4. **Code Confidence**: Do not make changes until 95% confident. Ask follow-up questions if uncertain.
 
+## Public Repo Privacy
+
+- `ti2` is open source. Before opening or updating public PRs, review summaries, inline comments, release notes, or commit messages, scrub internal TourConnect service names and private implementation details.
+- Do not mention internal services such as `pyfilematch`, `filematch`, `tcoutlook`, private frontend names, private trace URLs, private customer identifiers, or internal deployment architecture in public GitHub text.
+- Use generic wording such as `upstream caller`, `internal catalog caller`, `private frontend`, `caller-side timeout`, or `internal workflow` when context is needed.
+- After editing public GitHub text, search the PR body, issue comments, review comments, and review summaries for internal service names before handoff.
+
 ## Common Development Commands
 
 ```bash
@@ -156,4 +163,4 @@ export SSL_INSECURE_ALLOWED_DOMAINS="dev.example.com|test.example.com"
 - SSL configuration uses a per-request interceptor approach for better isolation
 - The configuration checks domains dynamically on each request
 
-**Warning**: Only use this in development/testing environments. Never skip SSL verification in production for security reasons.
+**Warning**: Only use this in development/testing environments. Never skip SSL verification in production for security reasons.

package/__tests__/cache.js

@@ -15,6 +15,30 @@ describe('cache', () => {
   });
 
 
+  describe('saveIfNotExists', () => {
+    it('should only save the first value for a key', async () => {
+      const key = 'lock:test';
+      testKeys.push(key);
+
+      const firstSaved = await cache.saveIfNotExists({
+        pluginName: testPluginName,
+        key,
+        value: { owner: 'first' },
+        ttl: 60,
+      });
+      const secondSaved = await cache.saveIfNotExists({
+        pluginName: testPluginName,
+        key,
+        value: { owner: 'second' },
+        ttl: 60,
+      });
+
+      expect(firstSaved).toBe(true);
+      expect(secondSaved).toBe(false);
+      expect(await cache.get({ pluginName: testPluginName, key })).toEqual({ owner: 'first' });
+    });
+  });
+
   describe('scan', () => {
     it('should return keys matching the pattern without plugin prefix', async () => {
       // Save some test keys

package/cache.js

@@ -5,6 +5,23 @@ const REDIS_URL = process.env.REDIS_URL || 'redis://redis:6379';
 const cache = new Redis(`${REDIS_URL}/2`);
 const defaultTTL = 60 * 60; // 1 hour
 
+const normalizeKey = ({
+  key: keyParam,
+  fn,
+  fnParams,
+  useFunctionFallback = false,
+}) => {
+  if (useFunctionFallback && !keyParam) {
+    return hash({ fn, fnParams });
+  }
+  if (typeof keyParam !== 'string') {
+    return hash(keyParam);
+  }
+  return keyParam;
+};
+
+const buildKey = ({ pluginName, ...args }) => `${pluginName}:${normalizeKey(args)}`;
+
 const save = async ({
   pluginName,
   key: keyParam,
@@ -12,12 +29,7 @@ const save = async ({
   skipTTL,
   ttl = defaultTTL,
 }) => {
-  const key = `${pluginName}:${(() => {
-    if (typeof keyParam !== 'string') {
-      return hash(keyParam);
-    }
-    return keyParam;
-  })()}`;
+  const key = buildKey({ pluginName, key: keyParam });
   // console.log('saving key', key);
   await cache.set(key, JSON.stringify(value));
   if (!skipTTL) {
@@ -25,16 +37,22 @@ const save = async ({
   }
 };
 
+const saveIfNotExists = async ({
+  pluginName,
+  key: keyParam,
+  value,
+  ttl = defaultTTL,
+}) => {
+  const key = buildKey({ pluginName, key: keyParam });
+  const result = await cache.set(key, JSON.stringify(value), 'EX', ttl, 'NX');
+  return result === 'OK';
+};
+
 const get = async ({
   pluginName,
   key: keyParam,
 }) => {
-  const key = `${pluginName}:${(() => {
-    if (typeof keyParam !== 'string') {
-      return hash(keyParam);
-    }
-    return keyParam;
-  })()}`;
+  const key = buildKey({ pluginName, key: keyParam });
   const storeVal = await cache.get(key);
   if (!storeVal) return storeVal;
   return JSON.parse(storeVal);
@@ -48,15 +66,7 @@ const getOrExec = async ({
   fnParams,
   forceRefresh,
 }) => {
-  const key = (() => {
-    if (!keyParam) {
-      return hash({ fn, fnParams });
-    }
-    if (typeof keyParam !== 'string') {
-      return hash(keyParam);
-    }
-    return keyParam;
-  })();
+  const key = normalizeKey({ key: keyParam, fn, fnParams, useFunctionFallback: true });
   let value;
   if (!forceRefresh) {
     value = await get({ pluginName, key });
@@ -78,15 +88,13 @@ const drop = async ({
   fn,
   fnParams,
 }) => {
-  const key = `${pluginName}:${(() => {
-    if (!keyParam) {
-      return hash({ fn, fnParams });
-    }
-    if (typeof keyParam !== 'string') {
-      return hash(keyParam);
-    }
-    return keyParam;
-  })()}`;
+  const key = buildKey({
+    pluginName,
+    key: keyParam,
+    fn,
+    fnParams,
+    useFunctionFallback: true,
+  });
   // console.log('dropping key', key);
   await cache.del(key);
 };
@@ -116,6 +124,7 @@ const scan = ({
 module.exports = {
   cache,
   save,
+  saveIfNotExists,
   getOrExec,
   drop,
   get,

package/controllers/__tests__/bookings-searchProducts.js

@@ -16,6 +16,7 @@ jest.mock('../../worker/queue', () => ({
 const { addJob, jobStatus: mockJobStatus } = require('../../worker/queue'); // Now addJob is the mock
 
 const testUtils = require('../../test/utils'); // Require the module itself
+const bookingsControllerFactory = require('../bookings');
 
 // Global setup for the entire test file
 let globalDoApiPost, globalPlugins, globalUtils, globalSqldb;
@@ -314,8 +315,8 @@ describe('user: bookings controller - searchProducts', () => {
 
     beforeEach(async () => {
       // Clear mocks
-      if (travelgatePlugin && travelgatePlugin.searchProducts && travelgatePlugin.searchProducts.mockClear) {
-        travelgatePlugin.searchProducts.mockClear();
+      if (travelgatePlugin && travelgatePlugin.searchProducts && travelgatePlugin.searchProducts.mockReset) {
+        travelgatePlugin.searchProducts.mockReset();
       }
       if (addJob && addJob.mockClear) {
         addJob.mockClear();
@@ -341,13 +342,18 @@ describe('user: bookings controller - searchProducts', () => {
           token: staleCacheTokenConfig,
       });
       // Clear mocks that might have been called during appSetup
-      if (travelgatePlugin.searchProducts.mockClear) travelgatePlugin.searchProducts.mockClear();
+      if (travelgatePlugin.searchProducts.mockReset) travelgatePlugin.searchProducts.mockReset();
       if (addJob.mockClear) addJob.mockClear();
     });
 
-    it('should return stale (non-empty) products when TTR expires and refresh yields empty products', async () => {
+    it('should return stale products and preserve the cache when refresh yields empty products', async () => {
       const initialProductsInCache = [{ productId: 'staleProd1', name: 'Stale Product One', optionId: 'optStale1' }];
       const productsFromPluginRefresh = []; // Simulate plugin returning empty on refresh
+      const cacheKeyForTest = hash({
+        userId: testUserId,
+        hint: staleCacheTestHint,
+        operationId: 'bookingsProductSearch',
+      });
 
       // 1. First call: Populate the cache with initialProductsInCache
       travelgatePlugin.searchProducts.mockResolvedValueOnce({ products: initialProductsInCache });
@@ -387,8 +393,195 @@ describe('user: bookings controller - searchProducts', () => {
       expect(travelgatePlugin.searchProducts).not.toHaveBeenCalled();
 
       // Note: This test verifies the immediate response serves stale data and a job is queued.
-      // It does not verify the cache state *after* the job (which would use the empty refresh)
-      // because $updateProductSearchCache currently caches empty results.
+      // Cache preservation for empty background refreshes is covered below.
+    });
+
+    it('should keep existing non-empty cache when background refresh returns empty products', async () => {
+      const initialProductsInCache = [{ productId: 'staleProd1', name: 'Stale Product One', optionId: 'optStale1' }];
+      const cacheKeyForTest = hash({
+        userId: testUserId,
+        hint: staleCacheTestHint,
+        operationId: 'bookingsProductSearch',
+      });
+      await cache.save({
+        pluginName: testAppName,
+        key: cacheKeyForTest,
+        value: { products: initialProductsInCache },
+        ttl: 60,
+      });
+      await cache.save({
+        pluginName: testAppName,
+        key: `${cacheKeyForTest}:lastUpdated`,
+        value: 1,
+        ttl: 60,
+      });
+      const emitSpy = jest.spyOn(travelgatePlugin.events, 'emit');
+
+      await bookingsControllerFactory(globalPlugins).$updateProductSearchCache({
+        appKey: testAppName,
+        userId: testUserId,
+        hint: staleCacheTestHint,
+        pluginResult: { products: [] },
+        requestId: 'empty-refresh-test',
+      });
+
+      const cached = await cache.get({ pluginName: testAppName, key: cacheKeyForTest });
+      const lastUpdated = await cache.get({ pluginName: testAppName, key: `${cacheKeyForTest}:lastUpdated` });
+      expect(cached.products).toEqual(initialProductsInCache);
+      expect(lastUpdated).toBeGreaterThan(1);
+      expect(emitSpy).toHaveBeenCalledWith(
+        'bookingsProductSearch:cache:emptyRefreshSkipped',
+        expect.objectContaining({
+          reason: 'emptyResultPreservedExistingCache',
+          cachePreserved: true,
+          existingProductCount: initialProductsInCache.length,
+        }),
+      );
+      emitSpy.mockRestore();
+    });
+
+    it('should not cache partial product refreshes as complete results', async () => {
+      const cacheKeyForTest = hash({
+        userId: testUserId,
+        hint: staleCacheTestHint,
+        operationId: 'bookingsProductSearch',
+      });
+      await cache.drop({ pluginName: testAppName, key: cacheKeyForTest });
+
+      await bookingsControllerFactory(globalPlugins).$updateProductSearchCache({
+        appKey: testAppName,
+        userId: testUserId,
+        hint: staleCacheTestHint,
+        pluginResult: {
+          catalogPartial: true,
+          products: [{ productId: 'partialProd1' }],
+        },
+        requestId: 'partial-refresh-test',
+      });
+
+      const cached = await cache.get({ pluginName: testAppName, key: cacheKeyForTest });
+      const lastUpdated = await cache.get({ pluginName: testAppName, key: `${cacheKeyForTest}:lastUpdated` });
+      expect(cached).toBeFalsy();
+      expect(lastUpdated).toBeTruthy();
+    });
+
+    it('should not update cache metadata when direct force refresh returns partial products', async () => {
+      const pluginResult = {
+        catalogPartial: true,
+        products: [{ productId: 'partialProd1' }],
+      };
+      const cacheKeyForTest = hash({
+        userId: testUserId,
+        hint: staleCacheTestHint,
+        operationId: 'bookingsProductSearch',
+      });
+      travelgatePlugin.searchProducts.mockResolvedValueOnce(pluginResult);
+
+      await doApiPost({
+        url: `/products/${testAppName}/${testUserId}/${staleCacheTestHint}/search`,
+        token: userToken,
+        payload: { forceRefresh: true },
+      });
+
+      const cached = await cache.get({ pluginName: testAppName, key: cacheKeyForTest });
+      const lastUpdated = await cache.get({ pluginName: testAppName, key: `${cacheKeyForTest}:lastUpdated` });
+      expect(travelgatePlugin.searchProducts).toHaveBeenCalledTimes(1);
+      expect(cached).toBeFalsy();
+      expect(lastUpdated).toBeFalsy();
+    });
+
+    it('should keep existing non-empty cache when background refresh returns partial products', async () => {
+      const initialProductsInCache = [{ productId: 'staleProd1', name: 'Stale Product One', optionId: 'optStale1' }];
+      const pluginResult = {
+        catalogPartial: true,
+        products: [{ productId: 'partialProd1' }],
+      };
+      const cacheKeyForTest = hash({
+        userId: testUserId,
+        hint: staleCacheTestHint,
+        operationId: 'bookingsProductSearch',
+      });
+      await cache.save({
+        pluginName: testAppName,
+        key: cacheKeyForTest,
+        value: { products: initialProductsInCache },
+        ttl: 60,
+      });
+      await cache.save({
+        pluginName: testAppName,
+        key: `${cacheKeyForTest}:lastUpdated`,
+        value: 1,
+        ttl: 60,
+      });
+      const emitSpy = jest.spyOn(travelgatePlugin.events, 'emit');
+
+      await bookingsControllerFactory(globalPlugins).$updateProductSearchCache({
+        appKey: testAppName,
+        userId: testUserId,
+        hint: staleCacheTestHint,
+        pluginResult,
+        requestId: 'partial-refresh-test',
+      });
+
+      const cached = await cache.get({ pluginName: testAppName, key: cacheKeyForTest });
+      const lastUpdated = await cache.get({ pluginName: testAppName, key: `${cacheKeyForTest}:lastUpdated` });
+      expect(cached.products).toEqual(initialProductsInCache);
+      expect(lastUpdated).toBeGreaterThan(1);
+      expect(emitSpy).toHaveBeenCalledWith(
+        'bookingsProductSearch:cache:partialRefreshSkipped',
+        expect.objectContaining({
+          reason: 'partialResultPreservedExistingCache',
+          cachePreserved: true,
+          existingProductCount: initialProductsInCache.length,
+          pluginResult,
+        }),
+      );
+      emitSpy.mockRestore();
+    });
+
+    it('should not cache empty products if non-empty cache appears before the empty save', async () => {
+      const cacheKeyForTest = hash({
+        userId: 'race-user',
+        hint: 'race-hint',
+        operationId: 'bookingsProductSearch',
+      });
+      const pluginResult = { products: [] };
+      const fakePlugin = {
+        name: 'racePlugin',
+        cache: {
+          get: jest.fn()
+            .mockResolvedValueOnce(null)
+            .mockResolvedValueOnce({ products: [{ productId: 'raceProd1' }] }),
+          save: jest.fn(async () => {}),
+        },
+        events: {
+          emit: jest.fn(),
+        },
+      };
+
+      await bookingsControllerFactory([fakePlugin]).$updateProductSearchCache({
+        appKey: fakePlugin.name,
+        userId: 'race-user',
+        hint: 'race-hint',
+        pluginResult,
+        requestId: 'race-refresh-test',
+      });
+
+      expect(fakePlugin.cache.save).toHaveBeenCalledWith(expect.objectContaining({
+        key: `${cacheKeyForTest}:lastUpdated`,
+      }));
+      expect(fakePlugin.cache.save).not.toHaveBeenCalledWith(expect.objectContaining({
+        key: cacheKeyForTest,
+        value: { products: [] },
+      }));
+      expect(fakePlugin.events.emit).toHaveBeenCalledWith(
+        'bookingsProductSearch:cache:emptyRefreshSkipped',
+        expect.objectContaining({
+          reason: 'emptyResultPreservedConcurrentCache',
+          cachePreserved: true,
+          existingProductCount: 1,
+        }),
+      );
     });
   });
 });
@@ -445,6 +638,24 @@ describe('Bookings Product Search Lock Mechanism (Job Queuing on Stale Cache)',
     await cache.drop({ pluginName: testAppName, key: `${cacheKey}:jobLock` }); // jobQueueLock
   });
 
+  const clearProductSearchCache = async () => {
+    const cacheKey = hash({
+      userId: testUserId,
+      hint: ttrTestHint,
+      operationId: 'bookingsProductSearch',
+    });
+    await cache.drop({ pluginName: testAppName, key: cacheKey });
+    await cache.drop({ pluginName: testAppName, key: `${cacheKey}:lastUpdated` });
+    await cache.drop({ pluginName: testAppName, key: `${cacheKey}:lock` });
+    await cache.drop({ pluginName: testAppName, key: `${cacheKey}:jobLock` });
+  };
+
+  const makeProductSearchRequest = () => doApiPost({
+    url: `/products/${testAppName}/${testUserId}/${ttrTestHint}/search`,
+    token: userToken,
+    payload: {},
+  });
+
   beforeEach(async () => {
     // Clear mocks before each test in this suite
     addJob.mockClear(); // Reset addJob mock calls
@@ -529,5 +740,102 @@ describe('Bookings Product Search Lock Mechanism (Job Queuing on Stale Cache)',
       );
     }
   });
-});
 
+  it('multiple concurrent requests with no cache should wait for one plugin fetch', async () => {
+    await clearProductSearchCache();
+
+    const coldProducts = [{
+      productId: 'cold-product',
+      productName: 'Cold Product',
+      options: [{
+        optionId: 'cold-option',
+        optionName: 'Cold Option',
+      }],
+    }];
+    lockTestPlugin.searchProducts.mockReset();
+    const releasePluginFetches = [];
+    const pluginFetchStarted = new Promise(resolve => {
+      lockTestPlugin.searchProducts.mockImplementation(() => {
+        resolve();
+        return new Promise(pluginResolve => {
+          releasePluginFetches.push(() => pluginResolve({ products: coldProducts }));
+        });
+      });
+    });
+
+    const requestPromises = [makeProductSearchRequest(), makeProductSearchRequest(), makeProductSearchRequest()];
+    await pluginFetchStarted;
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    releasePluginFetches.forEach(releasePluginFetch => releasePluginFetch());
+    const results = await Promise.all(requestPromises);
+
+    results.forEach(result => {
+      expect(result.products).toEqual(coldProducts);
+    });
+    expect(lockTestPlugin.searchProducts).toHaveBeenCalledTimes(1);
+    expect(addJob).not.toHaveBeenCalled();
+  });
+
+  it('multiple concurrent requests with no cache should share an empty plugin result', async () => {
+    await clearProductSearchCache();
+
+    lockTestPlugin.searchProducts.mockReset();
+    const releasePluginFetches = [];
+    const pluginFetchStarted = new Promise(resolve => {
+      lockTestPlugin.searchProducts.mockImplementation(() => {
+        resolve();
+        return new Promise(pluginResolve => {
+          releasePluginFetches.push(() => pluginResolve({ products: [] }));
+        });
+      });
+    });
+
+    const requestPromises = [makeProductSearchRequest(), makeProductSearchRequest(), makeProductSearchRequest()];
+    await pluginFetchStarted;
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    releasePluginFetches.forEach(releasePluginFetch => releasePluginFetch());
+    const results = await Promise.all(requestPromises);
+
+    results.forEach(result => {
+      expect(result.products).toEqual([]);
+    });
+    expect(lockTestPlugin.searchProducts).toHaveBeenCalledTimes(1);
+    expect(addJob).not.toHaveBeenCalled();
+  });
+
+  it('multiple concurrent requests with no cache should fail when the leader throws', async () => {
+    await clearProductSearchCache();
+
+    lockTestPlugin.searchProducts.mockReset();
+    let rejectPluginFetch;
+    const pluginFetchStarted = new Promise(resolve => {
+      lockTestPlugin.searchProducts.mockImplementation(() => {
+        resolve();
+        return new Promise((_, reject) => {
+          rejectPluginFetch = () => reject(new Error('boom'));
+        });
+      });
+    });
+
+    const requestPromises = [makeProductSearchRequest(), makeProductSearchRequest(), makeProductSearchRequest()]
+      .map(requestPromise => requestPromise
+        .then(result => ({ status: 'fulfilled', result }))
+        .catch(error => ({ status: 'rejected', error })));
+    await pluginFetchStarted;
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    rejectPluginFetch();
+    const results = await Promise.all(requestPromises);
+
+    results.forEach(result => {
+      expect(result.status).toBe('rejected');
+    });
+    expect(lockTestPlugin.searchProducts).toHaveBeenCalledTimes(1);
+    expect(addJob).not.toHaveBeenCalled();
+
+    const statuses = results.map(result => result.error.response.status).sort();
+    expect(statuses).toEqual([500, 503, 503]);
+  });
+});

package/controllers/__tests__/bookings.js

@@ -106,10 +106,10 @@ describe('user: bookings controller', () => {
         token: userToken,
         payload,
       });
-      expect(plugins[0].searchHotelBooking).toHaveBeenCalled();
+      expect(plugins[0].searchItineraries).toHaveBeenCalled();
       expect(Array.isArray(bookings)).toBeTruthy();
-      expect(plugins[0].searchHotelBooking.mock.calls[0][0].payload).toEqual(payload);
-      expect(plugins[0].searchHotelBooking.mock.calls[0][0].token).toEqual(token);
+      expect(plugins[0].searchItineraries.mock.calls[0][0].payload).toEqual(payload);
+      expect(plugins[0].searchItineraries.mock.calls[0][0].token).toEqual(token);
     });
 
   });

package/controllers/__tests__/user.js

@@ -222,6 +222,19 @@ describe('user', () => {
     expect(plugins[0].validateToken.mock.calls[0][0].payload).toEqual({
       tokenHint: apiKey.split('-')[0],
     });
+    expect(plugins[0].validateToken.mock.calls[0][0].userId).toBe(userId);
+    expect(plugins[0].validateToken.mock.calls[0][0].hint).toBe(apiKey.split('-')[0]);
+  });
+  it('testing the user token should not infer a hint when no hint is provided', async () => {
+    const { valid } = await doApiPost({
+      url: `/${appName}/${userId}/validate`,
+      token: userKey,
+      payload: {},
+    });
+    expect(plugins[0].validateToken).toHaveBeenCalled();
+    expect(valid).toBe(true);
+    expect(plugins[0].validateToken.mock.calls[0][0].userId).toBe(userId);
+    expect(plugins[0].validateToken.mock.calls[0][0].hint).toBeUndefined();
   });
   it('should be able to delete an app settings', async () => {
     const returnValue = await doApiDelete({

package/controllers/app.js

@@ -261,6 +261,8 @@ const validateAppToken = plugins => async (req, res, next) => {
       axios,
       token,
       payload: req.body,
+      userId,
+      hint,
       requestId: req.requestId,
     });
     return res.json({ valid });

package/controllers/bookings.js

@@ -28,6 +28,24 @@ const typeDefsAndQueries = {
   itineraryBookingQuery,
 };
 
+const getPositiveIntegerEnv = (name, defaultValue) => {
+  const value = Number(process.env[name]);
+  const integerValue = Math.floor(value);
+  return Number.isFinite(value) && integerValue > 0 ? integerValue : defaultValue;
+};
+
+const productSearchLockTtlSeconds = getPositiveIntegerEnv('PRODUCT_SEARCH_LOCK_TTL_SECONDS', 120);
+const productSearchLockWaitMs = getPositiveIntegerEnv('PRODUCT_SEARCH_LOCK_WAIT_MS', 25 * 1000);
+const productSearchLockPollMs = getPositiveIntegerEnv('PRODUCT_SEARCH_LOCK_POLL_MS', 250);
+const emptyProductSearchCacheTtlSeconds = 60;
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+const createProductSearchUnavailableError = () => {
+  const err = new Error('Product search cache refresh did not produce cached results');
+  err.status = 503;
+  return err;
+};
+
 const getAppAndToken = async ({ plugins, appKey, userId, hint }) => {
   const app = plugins.find(({ name }) => name === appKey);
   assert(app, 'could not find the app ' + appKey);
@@ -52,7 +70,8 @@ const bookingsSearch = plugins => async (req, res, next) => {
   try {
     const { app, token } = await getAppAndToken({ plugins, appKey, userId, hint });
     assert(app.searchItineraries || app.searchHotelBooking || app.searchBooking, `searchItineraries or searchHotelBooking or searchBooking is not available for ${appKey}`);
-    const search = (app.searchHotelBooking || app.searchBooking || app.searchItineraries).bind(app);
+    // Prefer the dedicated itinerary endpoint so date/filter payloads used by mining are preserved.
+    const search = (app.searchItineraries || app.searchHotelBooking || app.searchBooking).bind(app);
     const results = await search({
       axios,
       token,
@@ -122,6 +141,22 @@ const $searchProductList = (products, searchInput = '', optionId = '') => {
   return filteredProducts;
 };
 
+// Plugins may flag incomplete catalog responses with `catalogPartial` or `partial`;
+// both must suppress cache writes so a partial result does not replace a complete cache.
+const hasCacheableProductResults = pluginResults => Boolean(
+  pluginResults
+  && pluginResults.products
+  && pluginResults.products.length > 0
+  && !pluginResults.catalogPartial
+  && !pluginResults.partial
+);
+
+const hasNonEmptyProductCache = cacheContent => Boolean(
+  cacheContent
+  && cacheContent.products
+  && cacheContent.products.length > 0
+);
+
 const $bookingsProductSearch = plugins => async ({
   axios,
   appKey,
@@ -159,10 +194,44 @@ const $bookingsProductSearch = plugins => async ({
   const isStaleByTTR = lastUpdated && (Date.now() - lastUpdated > ttr * 1000);
   const doNotCallPluginForProducts = token.doNotCallPluginForProducts || R.path(['cacheSettings', 'bookingsProductSearch', 'doNotCall'], app);
   const hasPluginExecutionLock = await app.cache.get({ key: pluginExecutionLockKey });
+  assert(app.cache.saveIfNotExists, 'cache adapter must expose saveIfNotExists');
+
+  const getCachedProductSearchResults = async () => {
+    const cacheContent = await app.cache.get({ key: cacheKey });
+    if (cacheContent && cacheContent.products) return cacheContent;
+    return null;
+  };
+
+  const waitForProductSearchCache = async () => {
+    const timeoutAt = Date.now() + productSearchLockWaitMs;
+    while (Date.now() < timeoutAt) {
+      const cacheContent = await getCachedProductSearchResults();
+      if (cacheContent) return cacheContent;
+
+      const lockStillActive = await app.cache.get({ key: pluginExecutionLockKey });
+      if (!lockStillActive) return null;
+
+      await sleep(productSearchLockPollMs);
+    }
+
+    return getCachedProductSearchResults();
+  };
+
+  const acquirePluginExecutionLock = async () => app.cache.saveIfNotExists({
+    key: pluginExecutionLockKey,
+    value: true,
+    ttl: productSearchLockTtlSeconds,
+  });
 
   // Helper function to call the plugin, save cache, and return results
   const fetchFromPluginAndCache = async () => {
-    await app.cache.save({ key: pluginExecutionLockKey, value: true, ttl: 120 });
+    const lockAcquired = await acquirePluginExecutionLock();
+    if (!lockAcquired) {
+      const cacheContent = await waitForProductSearchCache();
+      if (cacheContent) return cacheContent;
+      throw createProductSearchUnavailableError();
+    }
+
     let pluginResults;
     try {
       pluginResults = await func({
@@ -175,20 +244,25 @@ const $bookingsProductSearch = plugins => async ({
         hint,
       });
 
-      // This function is responsible for caching if it fetched good results.
+      // This function is responsible for caching if it fetched usable results.
       // This applies to forceRefresh, initial load, or direct calls that result in a fetch.
       // The $updateProductSearchCache function handles caching for background jobs queued due to stale data.
-      if (pluginResults && pluginResults.products && pluginResults.products.length > 0) {
+      if (hasCacheableProductResults(pluginResults)) {
         const monthInSeconds = 30 * 24 * 60 * 60;
         await app.cache.save({ key: `${cacheKey}:lastUpdated`, value: Date.now(), ttl: monthInSeconds });
         await app.cache.save({ key: cacheKey, value: pluginResults, ttl: monthInSeconds });
         app.events.emit('bookingsProductSearch:cache:save', {
           cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
         });
+      } else if (pluginResults && (pluginResults.catalogPartial || pluginResults.partial)) {
+        app.events.emit('bookingsProductSearch:cache:partialRefreshSkipped', {
+          cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
+          reason: 'directPartialResultNotCached', pluginResult: pluginResults,
+        });
+      } else if (pluginResults && pluginResults.products && pluginResults.products.length === 0) {
+        // Short-lived empty cache gives concurrent waiters the same answer as the lock holder.
+        await app.cache.save({ key: cacheKey, value: pluginResults, ttl: emptyProductSearchCacheTtlSeconds });
       }
-      // If pluginResults are empty, cache is NOT updated here by fetchFromPluginAndCache.
-      // This maintains existing behavior for forceRefresh/initial load paths.
-      // $updateProductSearchCache has its own logic for handling empty results from background refresh.
     } finally {
       await app.cache.drop({ key: pluginExecutionLockKey });
     }
@@ -233,14 +307,16 @@ const $bookingsProductSearch = plugins => async ({
         return returnCachedResults();
       }
 
-      // Cache is stale - check if background job already queued
-      const hasJobQueueLock = await app.cache.get({ key: jobQueueLockKey });
-      if (hasJobQueueLock) {
+      // Cache is stale - queue at most one background refresh job and serve stale data.
+      const jobQueueLockAcquired = await app.cache.saveIfNotExists({
+        key: jobQueueLockKey,
+        value: true,
+        ttl: 60,
+      });
+      if (!jobQueueLockAcquired) {
         return returnCachedResults();
       }
 
-      // Queue background refresh job and serve stale data
-      await app.cache.save({ key: jobQueueLockKey, value: true, ttl: 60 });
       await addJob({
         type: 'plugin',
         pluginName: appKey,
@@ -551,26 +627,64 @@ const $updateProductSearchCache = plugins => async ({
 
   const cacheKey = hash({ userId, hint, operationId: 'bookingsProductSearch' });
   const monthInSeconds = 30 * 24 * 60 * 60;
+  const markRefreshAttempted = () => app.cache.save({
+    key: `${cacheKey}:lastUpdated`,
+    value: Date.now(),
+    ttl: monthInSeconds,
+  });
+  const emitCacheEvent = (eventName, extra = {}) => app.events.emit(eventName, {
+    cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
+    ...extra,
+  });
 
-  // Always update lastUpdated to prevent immediate re-trigger of background jobs
-  // even if the plugin returned empty results.
-  await app.cache.save({ key: `${cacheKey}:lastUpdated`, value: Date.now(), ttl: monthInSeconds });
-
-  if (pluginResult && pluginResult.products && pluginResult.products.length > 0) {
+  if (hasCacheableProductResults(pluginResult)) {
+    await markRefreshAttempted();
     await app.cache.save({ key: cacheKey, value: pluginResult, ttl: monthInSeconds });
-    app.events.emit('bookingsProductSearch:cache:save', {
-      cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
-    });
-    console.log(`[$updateProductSearchCache][requestId: ${requestId}] Saved products to cache for ${appKey}, user ${userId}, hint ${hint}.`);
+    emitCacheEvent('bookingsProductSearch:cache:save');
   } else {
-    // If plugin returned no products, update the cache to reflect this.
-    // This prevents serving stale data indefinitely if the source truly has no products anymore.
+    const isPartialRefresh = pluginResult && (pluginResult.catalogPartial || pluginResult.partial);
+    const existingCacheContent = await app.cache.get({ key: cacheKey });
+    if (hasNonEmptyProductCache(existingCacheContent)) {
+      await markRefreshAttempted();
+      const eventExtra = {
+        reason: isPartialRefresh ? 'partialResultPreservedExistingCache' : 'emptyResultPreservedExistingCache',
+        cachePreserved: true,
+        existingProductCount: existingCacheContent.products.length,
+      };
+      if (isPartialRefresh) eventExtra.pluginResult = pluginResult;
+      emitCacheEvent(
+        isPartialRefresh ? 'bookingsProductSearch:cache:partialRefreshSkipped' : 'bookingsProductSearch:cache:emptyRefreshSkipped',
+        eventExtra,
+      );
+      return;
+    }
+
+    if (isPartialRefresh) {
+      await markRefreshAttempted();
+      emitCacheEvent('bookingsProductSearch:cache:partialRefreshSkipped', {
+        reason: 'partialResultNotCached',
+        cachePreserved: false,
+        pluginResult,
+      });
+      return;
+    }
+
+    // Best-effort race guard: avoid overwriting a non-empty cache written after the first read.
+    const latestCacheContent = await app.cache.get({ key: cacheKey });
+    if (hasNonEmptyProductCache(latestCacheContent)) {
+      await markRefreshAttempted();
+      emitCacheEvent('bookingsProductSearch:cache:emptyRefreshSkipped', {
+        reason: 'emptyResultPreservedConcurrentCache',
+        cachePreserved: true,
+        existingProductCount: latestCacheContent.products.length,
+      });
+      return;
+    }
+
+    // Empty complete refreshes are authoritative only when there is no existing non-empty cache.
+    await markRefreshAttempted();
     await app.cache.save({ key: cacheKey, value: { products: [] }, ttl: monthInSeconds });
-    app.events.emit('bookingsProductSearch:cache:emptyRefresh', {
-      cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
-      pluginResult, // Log what the plugin returned
-    });
-    console.log(`[$updateProductSearchCache][requestId: ${requestId}] Plugin returned empty/no products. Cached empty for ${appKey}, user ${userId}, hint ${hint}.`);
+    emitCacheEvent('bookingsProductSearch:cache:emptyRefresh');
   }
 };
 

package/index.js

@@ -90,6 +90,7 @@ module.exports = async ({
         get: args => cache.get({ ...args, pluginName }),
         getOrExec: args => cache.getOrExec({ ...args, pluginName }),
         save: args => cache.save({ ...args, pluginName }),
+        saveIfNotExists: args => cache.saveIfNotExists({ ...args, pluginName }),
         scan: args => cache.scan({ ...args, pluginName }),
       },
       axios: pluginAxios,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ti2",
-  "version": "1.0.114",
+  "version": "1.0.116",
   "description": "Tourist Industry Exchange (TI2)",
   "main": "index.js",
   "scripts": {