LCOV - code coverage report
Current view: top level - OdbDesignLib/App - DesignCache.cpp (source / functions) Coverage Total Hit
Test: OdbDesign Test Coverage Lines: 74.2 % 671 498
Test Date: 2026-11-21 03:51:50 Functions: 88.2 % 76 67
Legend: Lines: hit not hit

            Line data    Source code
       1              : #include "DesignCache.h"
       2              : #include "ArchiveExtractor.h"
       3              : #include "Logger.h"
       4              : #include <exception>
       5              : #include <filesystem>
       6              : #include <stdexcept>
       7              : #include <thread>
       8              : #include <vector>
       9              : #include "../FileModel/Design/FileArchive.h"
      10              : #include <memory>
      11              : #include "../ProductModel/Design.h"
      12              : #include <iosfwd>
      13              : #include <string>
      14              : #include <type_traits>
      15              : #include <StringVector.h>
      16              : #include <shared_mutex>
      17              : 
      18              : using namespace Utils;
      19              : using namespace std::filesystem;
      20              : 
      21              : namespace Odb::Lib::App
      22              : {
      23          125 :     DesignCache::DesignCache(std::string directory) :
      24          125 :         m_directory(std::move(directory))
      25              :     {
      26          125 :                 ensureDirectoryExists();
      27          125 :     }
      28              : 
      29          125 :     DesignCache::~DesignCache()
      30              :     {
      31          125 :         Clear();
      32              : 
      33              :         // Detached background loads hold `this`; drain them before member
      34              :         // teardown. A queued load first acquires its semaphore slot (running
      35              :         // loads release theirs), so the wait is bounded by the outstanding
      36              :         // parse time.
      37          125 :         std::unique_lock<std::mutex> lock(m_backgroundMutex);
      38          125 :         m_backgroundDoneCv.wait(lock, [this]()
      39              :         {
      40          148 :             return m_outstandingBackgroundLoads == 0;
      41              :         });
      42          125 :     }
      43              : 
      44          102 :     std::shared_ptr<ProductModel::Design> DesignCache::GetDesign(const std::string& designName)
      45              :     {
      46              :         return GetOrLoadSingleFlight<ProductModel::Design>(
      47              :             designName,
      48          102 :             m_designsByName,
      49          102 :             m_designsInFlight,
      50           70 :             [this, &designName]() { return LoadDesign(designName); },
      51          102 :             true);
      52              :     }
      53              : 
      54           86 :     std::shared_ptr<FileModel::Design::FileArchive> DesignCache::GetFileArchive(const std::string& designName)
      55              :     {
      56           86 :         return GetFileArchiveInternal(designName, true);
      57              :     }
      58              : 
      59          144 :     std::shared_ptr<FileModel::Design::FileArchive> DesignCache::GetFileArchiveInternal(const std::string& designName, bool updateState)
      60              :     {
      61          144 :         std::stringstream ss;
      62          144 :         ss << "Retrieving design \"" << designName << "\" from cache... ";
      63          288 :         logdebug(ss.str());
      64              : 
      65              :         return GetOrLoadSingleFlight<FileModel::Design::FileArchive>(
      66              :             designName,
      67          144 :             m_fileArchivesByName,
      68          144 :             m_fileArchivesInFlight,
      69          106 :             [this, &designName]() { return LoadFileArchive(designName); },
      70          275 :             updateState);
      71          144 :     }
      72              : 
      73            4 :     void DesignCache::AddFileArchive(const std::string& designName, std::shared_ptr<FileModel::Design::FileArchive> fileArchive, bool save, std::uint64_t injectedBytes)
      74              :     {
      75              :         {
      76            4 :             std::unique_lock<std::shared_mutex> writeLock(m_cacheMutex);
      77            4 :             m_fileArchivesByName[designName] = fileArchive;
      78              :             // Re-upload invalidation (M1.4): any previously cached Design was
      79              :             // built from the OLD archive contents, so it — and every serialized
      80              :             // response payload derived from it — must go. Dropping the Design
      81              :             // (not just the payloads) is what makes invalidation airtight: a
      82              :             // later GetDesign rebuilds from the new archive, and re-populated
      83              :             // payloads describe the new contents.
      84            4 :             m_designsByName.erase(designName);
      85            4 :         }
      86              : 
      87              :         // Drop serialized response payloads for the design (generation bump)
      88              :         // before the state/LRU bookkeeping.
      89            4 :         InvalidateResponsePayloads(designName);
      90              : 
      91              :         // Charge the injected archive to the byte budget (never its own eviction
      92              :         // victim) and reflect the externally-completed load in the state machine.
      93              :         // injectedBytes stands in for the archive size while nothing on disk
      94              :         // backs the name (save=false); without it the charge is only the flat
      95              :         // DESIGN_BYTES_OVERHEAD.
      96            4 :         InsertLruAndEvict(designName, injectedBytes);
      97            4 :         TransitionLoadState(designName, LoadState::Loaded);
      98              : 
      99            4 :         if (save)
     100              :         {
     101              :             // SaveFileArchive calls GetFileArchive internally, which takes the locks.
     102              :             // We must release before calling to avoid deadlock. (No locks held here.)
     103            0 :             SaveFileArchive(designName);
     104              :             // The estimate above ran before the file landed, so a fresh name was
     105              :             // still charged injectedBytes-only; now that the archive exists on
     106              :             // disk, re-estimate (real file size) and adjust the charge.
     107            0 :             ResyncLruEstimate(designName);
     108              :         }
     109            4 :     }
     110              : 
     111            4 :     void DesignCache::InvalidateDesign(const std::string& designName)
     112              :     {
     113              :         {
     114            4 :             std::unique_lock<std::shared_mutex> writeLock(m_cacheMutex);
     115              :             // Same contract as AddFileArchive's re-upload invalidation: a cached
     116              :             // Design (and the payloads derived from it) was built from the old
     117              :             // archive contents and must not survive the replacement.
     118            4 :             m_fileArchivesByName.erase(designName);
     119            4 :             m_designsByName.erase(designName);
     120            4 :         }
     121              : 
     122              :         // Drop serialized response payloads (generation bump), uncharging their
     123              :         // LRU bytes when an entry exists.
     124            4 :         InvalidateResponsePayloads(designName);
     125              : 
     126              :         // Mirror eviction's state handling: observers see Loaded -> Unloaded and
     127              :         // the next load announces a fresh Loading -> Loaded cycle.
     128            4 :         TransitionLoadState(designName, LoadState::Unloaded);
     129              : 
     130            8 :         loginfo("Invalidated cached design \"" + designName + "\" (archive replaced)");
     131            4 :     }
     132              : 
     133            0 :     bool DesignCache::SaveFileArchive(const std::string& designName)
     134              :     {
     135            0 :         auto fileArchive = GetFileArchive(designName);
     136            0 :         if (fileArchive != nullptr)
     137              :         {
     138            0 :             std::string directory;
     139              :             {
     140            0 :                 std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     141            0 :                 directory = m_directory;
     142            0 :             }
     143            0 :             return fileArchive->SaveFileModel(directory);
     144            0 :         }
     145            0 :         return false;
     146            0 :     }
     147              : 
     148       550519 :     std::vector<std::string> DesignCache::getLoadedDesignNames(const std::string& filter) const
     149              :     {
     150       550519 :         std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     151       550519 :         std::vector<std::string> loadedDesigns;
     152       550522 :         for (const auto& kv : m_designsByName)
     153              :         {
     154            3 :             loadedDesigns.push_back(kv.first);
     155              :         }
     156      1101038 :         return loadedDesigns;
     157       550519 :     }
     158              : 
     159       543644 :     std::vector<std::string> DesignCache::getLoadedFileArchiveNames(const std::string& filter) const
     160              :     {
     161       543644 :         std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     162       543644 :         std::vector<std::string> loadedFileArchives;
     163       543645 :         for (const auto& kv : m_fileArchivesByName)
     164              :                 {
     165            1 :                         loadedFileArchives.push_back(kv.first);
     166              :                 }
     167      1087288 :         return loadedFileArchives;
     168       543644 :     }
     169              : 
     170          250 :     std::vector<std::string> DesignCache::getUnloadedDesignNames(const std::string& filter) const
     171              :     {
     172          250 :         std::string directory;
     173              :         {
     174          250 :             std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     175          250 :             directory = m_directory;
     176          250 :         }
     177              : 
     178          250 :         std::vector<std::string> unloadedNames;
     179              : 
     180              :         //try
     181              :         {
     182          250 :             path dir(directory);
     183          250 :             for (const auto& entry : directory_iterator(dir))
     184              :             {
     185            0 :                 if (entry.is_regular_file())
     186              :                 {
     187            0 :                     unloadedNames.push_back(entry.path().stem().string());
     188              :                 }
     189          250 :             }
     190          250 :         }
     191              :         //catch (std::filesystem::filesystem_error& fe)
     192              :         //{
     193              :         //    logexception(fe);
     194              :         //    // re-throw it so we get a HTTP 500 response to the client
     195              :         //    throw fe;
     196              :         //}
     197              : 
     198          500 :         return unloadedNames;
     199          250 :     }
     200              : 
     201            0 :     int DesignCache::loadAllFileArchives(bool stopOnError)
     202              :     {
     203            0 :         int loaded = 0;
     204              : 
     205            0 :         std::string directory;
     206              :         {
     207            0 :             std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     208            0 :             directory = m_directory;
     209            0 :         }
     210              : 
     211            0 :         for (const auto& entry : directory_iterator(directory))
     212              :         {
     213            0 :             if (entry.is_regular_file())
     214              :             {
     215            0 :                 if (ArchiveExtractor::IsArchiveTypeSupported(entry.path().filename()))
     216              :                 {
     217              :                     try
     218              :                     {
     219            0 :                         auto pFileArchive = GetFileArchive(entry.path().stem().string());
     220            0 :                         if (pFileArchive != nullptr)
     221              :                         {
     222            0 :                             loaded++;
     223              :                         }
     224            0 :                     }
     225            0 :                     catch (std::exception& e)
     226              :                     {
     227              :                         // continue if we encounter an error loading one
     228            0 :                         logexception(e);
     229            0 :                         if (stopOnError) throw e;
     230            0 :                     }
     231              :                 }
     232              :             }
     233            0 :        }
     234              : 
     235            0 :         return loaded;
     236            0 :     }
     237              : 
     238            0 :     int DesignCache::loadAllDesigns(bool stopOnError)
     239              :     {
     240            0 :         int loaded = 0;
     241              : 
     242            0 :         std::string directory;
     243              :         {
     244            0 :             std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     245            0 :             directory = m_directory;
     246            0 :         }
     247              : 
     248            0 :         for (const auto& entry : directory_iterator(directory))
     249              :         {
     250            0 :             if (entry.is_regular_file())
     251              :             {
     252            0 :                 if (ArchiveExtractor::IsArchiveTypeSupported(entry.path().filename()))
     253              :                 {
     254              :                     try
     255              :                     {
     256            0 :                         auto pDesign = GetDesign(entry.path().stem().string());
     257            0 :                         if (pDesign != nullptr)
     258              :                         {
     259            0 :                             loaded++;
     260              :                         }
     261            0 :                     }
     262            0 :                     catch (std::exception& e)
     263              :                     {
     264            0 :                         logexception(e);
     265            0 :                         if (stopOnError)
     266              :                         {
     267            0 :                             throw;
     268              :                         }
     269            0 :                     }
     270              :                 }
     271              :             }
     272            0 :         }
     273              : 
     274            0 :         return loaded;
     275            0 :     }
     276              : 
     277            0 :     int DesignCache::loadFileArchives(const StringVector& names)
     278              :     {
     279            0 :         int loaded = 0;
     280              : 
     281            0 :         for (const auto& name : names)
     282              :         {
     283              :             try
     284              :             {
     285            0 :                 auto pFileArchive = GetFileArchive(name);
     286            0 :                 if (pFileArchive != nullptr)
     287              :                 {
     288            0 :                     loaded++;
     289              :                 }
     290            0 :             }
     291            0 :             catch (std::exception& e)
     292              :             {
     293              :                 // continue on error
     294            0 :                 logexception(e);
     295            0 :             }
     296              :         }
     297              : 
     298            0 :         return loaded;
     299              :     }
     300              : 
     301            0 :     int DesignCache::loadDesigns(const StringVector& names)
     302              :     {
     303            0 :         int loaded = 0;
     304              : 
     305            0 :         for (const auto& name : names)
     306              :         {
     307              :             try
     308              :             {
     309            0 :                 auto pDesign = GetDesign(name);
     310            0 :                 if (pDesign != nullptr)
     311              :                 {
     312            0 :                     loaded++;
     313              :                 }
     314            0 :             }
     315            0 :             catch (std::exception& e)
     316              :             {
     317              :                 // continue on error
     318            0 :                 logexception(e);
     319            0 :             }
     320              :         }
     321              : 
     322            0 :         return loaded;
     323              :     }
     324              : 
     325          250 :     void DesignCache::setDirectory(const std::string& directory)
     326              :     {
     327          250 :         std::unique_lock<std::shared_mutex> writeLock(m_cacheMutex);
     328          250 :         m_directory = directory;
     329          250 :     }
     330              : 
     331       799561 :     std::string DesignCache::getDirectory() const
     332              :     {
     333       799561 :         std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     334      1599122 :         return m_directory;
     335       799561 :     }
     336              : 
     337          498 :     void DesignCache::Clear()
     338              :     {
     339          498 :         std::vector<std::string> knownDesigns;
     340              :         {
     341          498 :             std::unique_lock<std::shared_mutex> writeLock(m_cacheMutex);
     342              :             // Collect before wiping: every design this cache held gets its
     343              :             // generation tombstone bumped below, so a post-Clear reload can
     344              :             // never land on a generation a GetDesignStream spool was published
     345              :             // at before the Clear (the disk-load path itself does not bump).
     346          498 :             knownDesigns.reserve(m_fileArchivesByName.size() + m_designsByName.size());
     347          572 :             for (const auto& kv : m_fileArchivesByName)
     348              :             {
     349           74 :                 knownDesigns.push_back(kv.first);
     350              :             }
     351          542 :             for (const auto& kv : m_designsByName)
     352              :             {
     353           44 :                 knownDesigns.push_back(kv.first);
     354              :             }
     355          498 :             m_fileArchivesByName.clear();
     356          498 :             m_designsByName.clear();
     357          498 :         }
     358              :         {
     359          498 :             std::lock_guard<std::mutex> lruLock(m_lruMutex);
     360          498 :             m_lruEntries.clear();
     361          498 :             m_cachedBytes = 0;
     362          498 :         }
     363              :         {
     364              :             // Drop all serialized response payloads. A pre-serialization commit
     365              :             // in flight during this Clear() is discarded by its epoch check.
     366          498 :             m_responseStore.Clear();
     367              :             // ...and advance every held design's generation so pre-Clear
     368              :             // GetDesignStream spools (keyed by generation) go stale.
     369          498 :             m_responseStore.BumpGenerations(knownDesigns);
     370              :         }
     371              :         {
     372              :             // Wipe the state map and bump the cache generation under the state
     373              :             // lock. Loads that registered before this Clear() see the epoch change
     374              :             // on completion and abandon their bookkeeping — no cache insert, no
     375              :             // LRU charge, no stale state transition — instead of re-populating
     376              :             // the just-wiped cache with a phantom entry. Their in-flight futures
     377              :             // are left to their owning threads (which erase their own entries);
     378              :             // parsed values are still delivered to the direct callers holding
     379              :             // those futures.
     380          498 :             std::lock_guard<std::mutex> stateLock(m_loadStateMutex);
     381          498 :             m_loadStatesByName.clear();
     382          498 :             ++m_epoch;
     383          498 :         }
     384          498 :     }
     385              : 
     386        60230 :     DesignCache::LoadState DesignCache::GetLoadState(const std::string& designName) const
     387              :     {
     388        60230 :         std::lock_guard<std::mutex> stateLock(m_loadStateMutex);
     389        60230 :         auto stateIt = m_loadStatesByName.find(designName);
     390        60230 :         if (stateIt != m_loadStatesByName.end())
     391              :         {
     392        10335 :             return stateIt->second;
     393              :         }
     394        49895 :         return LoadState::Unloaded;
     395        60230 :     }
     396              : 
     397           23 :     void DesignCache::AddLoadObserver(LoadEventCallback callback)
     398              :     {
     399           23 :         std::lock_guard<std::mutex> stateLock(m_loadStateMutex);
     400           23 :         m_loadObservers.push_back(std::move(callback));
     401           23 :     }
     402              : 
     403              :     // Epoch snapshot comparison for Clear()-during-load detection; see m_epoch.
     404          172 :     bool DesignCache::WasClearedSince(std::uint64_t epoch) const
     405              :     {
     406          172 :         std::lock_guard<std::mutex> stateLock(m_loadStateMutex);
     407          172 :         return m_epoch != epoch;
     408          172 :     }
     409              : 
     410           12 :     void DesignCache::setCacheMaxBytes(std::uint64_t maxBytes)
     411              :     {
     412           12 :         std::vector<std::string> evicted;
     413              :         {
     414           12 :             std::lock_guard<std::mutex> lruLock(m_lruMutex);
     415           12 :             m_maxBytes = maxBytes;
     416              :             // No protected name: shrinking the budget evicts immediately
     417           12 :             evicted = EvictOverBudgetLocked("");
     418           12 :         }
     419           12 :         EvictCacheEntries(evicted);
     420           12 :     }
     421              : 
     422           15 :     std::uint64_t DesignCache::getCacheMaxBytes() const
     423              :     {
     424           15 :         std::lock_guard<std::mutex> lruLock(m_lruMutex);
     425           15 :         return m_maxBytes;
     426           15 :     }
     427              : 
     428            3 :     void DesignCache::setMaxBackgroundLoads(std::size_t maxLoads)
     429              :     {
     430              :         {
     431            3 :             std::lock_guard<std::mutex> lock(m_backgroundMutex);
     432            3 :             m_maxBackgroundLoads = maxLoads;
     433            3 :         }
     434              :         // A raised cap frees waiting loads immediately
     435            3 :         m_backgroundSlotCv.notify_all();
     436            3 :     }
     437              : 
     438            2 :     std::size_t DesignCache::getMaxBackgroundLoads() const
     439              :     {
     440            2 :         std::lock_guard<std::mutex> lock(m_backgroundMutex);
     441            2 :         return m_maxBackgroundLoads;
     442            2 :     }
     443              : 
     444            4 :     bool DesignCache::ContainsDesign(const std::string& designName) const
     445              :     {
     446            4 :         return !FindArchivePath(designName).empty();
     447              :     }
     448              : 
     449           15 :     bool DesignCache::LoadDesignAsync(const std::string& designName)
     450              :     {
     451              :         {
     452           15 :             std::lock_guard<std::mutex> lock(m_loadStateMutex);
     453              :             // A kick we issued earlier (queued or parsing) or a synchronous
     454              :             // single-flight load in progress means already-loading; registering
     455              :             // the pending marker here closes the window before the background
     456              :             // thread announces Loading.
     457           28 :             if (m_pendingAsyncLoads.find(designName) != m_pendingAsyncLoads.end() ||
     458           28 :                 m_designsInFlight.find(designName) != m_designsInFlight.end() ||
     459           28 :                 m_fileArchivesInFlight.find(designName) != m_fileArchivesInFlight.end())
     460              :             {
     461            2 :                 return false;
     462              :             }
     463           13 :             m_pendingAsyncLoads.insert(designName);
     464           15 :         }
     465              : 
     466              :         {
     467           13 :             std::lock_guard<std::mutex> lock(m_backgroundMutex);
     468           13 :             ++m_outstandingBackgroundLoads;
     469           13 :         }
     470              : 
     471              :         try
     472              :         {
     473              :             // Detached by design (fire-and-forget): ~DesignCache drains
     474              :             // m_outstandingBackgroundLoads so the thread never outlives members.
     475           13 :             std::thread(&DesignCache::BackgroundLoad, this, designName).detach();
     476              :         }
     477            0 :         catch (...)
     478              :         {
     479              :             {
     480            0 :                 std::lock_guard<std::mutex> lock(m_backgroundMutex);
     481            0 :                 --m_outstandingBackgroundLoads;
     482            0 :             }
     483              :             // ~DesignCache's drain waits on the CV until the count reaches
     484              :             // zero; a decrement without this notify is a missed wakeup that
     485              :             // hangs shutdown forever when this was the last outstanding load
     486              :             // (mirrors the normal BackgroundLoad exit).
     487            0 :             m_backgroundDoneCv.notify_all();
     488              :             {
     489            0 :                 std::lock_guard<std::mutex> lock(m_loadStateMutex);
     490            0 :                 m_pendingAsyncLoads.erase(designName);
     491            0 :             }
     492            0 :             throw;
     493            0 :         }
     494           13 :         return true;
     495              :     }
     496              : 
     497           13 :     void DesignCache::BackgroundLoad(const std::string& designName)
     498              :     {
     499           13 :         AcquireBackgroundSlot();
     500              :         try
     501              :         {
     502              :             // The single-flight path registers the Loading/Loaded/Failed
     503              :             // transitions and observers exactly as a synchronous load; a failed
     504              :             // parse records Failed and drops the in-flight entry (retryable).
     505           13 :             auto pDesign = GetDesign(designName);
     506           11 :             if (pDesign == nullptr)
     507              :             {
     508            3 :                 logwarn("Background load: no archive found for design \"" + designName + "\"");
     509              :             }
     510              :             else
     511              :             {
     512           30 :                 loginfo("Background load of design \"" + designName + "\" completed");
     513              :             }
     514           11 :         }
     515            2 :         catch (const std::exception& e)
     516              :         {
     517            4 :             logexception_msg(e, "Background load of design \"" + designName + "\" failed (retryable)");
     518            2 :         }
     519            0 :         catch (...)
     520              :         {
     521            0 :             logerror("Background load of design \"" + designName + "\" failed with an unknown exception (retryable)");
     522            0 :         }
     523           13 :         ReleaseBackgroundSlot();
     524              : 
     525              :         {
     526           13 :             std::lock_guard<std::mutex> lock(m_loadStateMutex);
     527           13 :             m_pendingAsyncLoads.erase(designName);
     528           13 :         }
     529              :         {
     530           13 :             std::lock_guard<std::mutex> lock(m_backgroundMutex);
     531           13 :             --m_outstandingBackgroundLoads;
     532           13 :         }
     533           13 :         m_backgroundDoneCv.notify_all();
     534           13 :     }
     535              : 
     536           66 :     void DesignCache::AcquireBackgroundSlot()
     537              :     {
     538           66 :         std::unique_lock<std::mutex> lock(m_backgroundMutex);
     539           66 :         m_backgroundSlotCv.wait(lock, [this]()
     540              :         {
     541           69 :             return m_maxBackgroundLoads == 0 || m_activeBackgroundLoads < m_maxBackgroundLoads;
     542              :         });
     543           66 :         ++m_activeBackgroundLoads;
     544           66 :     }
     545              : 
     546           66 :     void DesignCache::ReleaseBackgroundSlot()
     547              :     {
     548              :         {
     549           66 :             std::lock_guard<std::mutex> lock(m_backgroundMutex);
     550           66 :             --m_activeBackgroundLoads;
     551           66 :         }
     552           66 :         m_backgroundSlotCv.notify_one();
     553           66 :     }
     554              : 
     555          125 :     void DesignCache::ensureDirectoryExists() const
     556              :     {
     557          125 :         if (!std::filesystem::exists(m_directory))
     558              :         {
     559              :             // create directory
     560              :             try
     561              :             {
     562            0 :                 std::filesystem::create_directories(m_directory);
     563              :             }
     564            0 :             catch (const std::exception& e)
     565              :             {
     566            0 :                 std::string msg = "Failed to create design cache directory: " + m_directory;
     567            0 :                 logexception_msg(e, msg);
     568            0 :                 throw e;
     569            0 :                         }
     570              :         }
     571          125 :     }
     572              : 
     573          317 :     std::filesystem::path DesignCache::FindArchivePath(const std::string& designName) const
     574              :     {
     575          317 :         std::string directory;
     576              :         {
     577          317 :             std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     578          317 :             directory = m_directory;
     579          317 :         }
     580              : 
     581          317 :         std::error_code ec;
     582          317 :         const auto options = directory_options::skip_permission_denied;
     583          317 :         directory_iterator dirIt(directory, options, ec);
     584          317 :         if (ec)
     585              :         {
     586            0 :             return {};
     587              :         }
     588              : 
     589         1065 :         for (const auto& entry : dirIt)
     590              :         {
     591          662 :             if (entry.is_regular_file() && entry.path().stem() == designName)
     592              :             {
     593          288 :                 return entry.path();
     594              :             }
     595          605 :         }
     596              : 
     597           29 :         return {};
     598          317 :     }
     599              : 
     600           70 :     std::shared_ptr<ProductModel::Design> DesignCache::LoadDesign(const std::string& designName)
     601              :     {
     602              :         // NOTE: This is a lock-free I/O helper. It does NOT modify the cache maps.
     603              :         // Cache insertion is handled by GetOrLoadSingleFlight().
     604           70 :         if (FindArchivePath(designName).empty())
     605              :         {
     606           12 :             return nullptr;
     607              :         }
     608              : 
     609              :         // GetFileArchive is thread-safe, manages its own locking.
     610              :         // updateState=false: the archive is a sub-step of this design load
     611              :         // and must not flip the design's load state mid-load.
     612           58 :         auto pFileModel = GetFileArchiveInternal(designName, false);
     613           55 :         if (pFileModel == nullptr)
     614              :         {
     615            0 :             return nullptr;
     616              :         }
     617              : 
     618           55 :         auto pDesign = std::make_shared<ProductModel::Design>();
     619           55 :         if (pDesign->Build(pFileModel))
     620              :         {
     621           55 :             return pDesign;
     622              :         }
     623              : 
     624            0 :         return nullptr;
     625           55 :     }
     626              : 
     627          106 :     std::shared_ptr<FileModel::Design::FileArchive> DesignCache::LoadFileArchive(const std::string& designName)
     628              :     {
     629              :         // NOTE: This is a lock-free I/O helper. It does NOT modify the cache maps.
     630              :         // Cache insertion is handled by GetOrLoadSingleFlight().
     631          106 :         const auto archivePath = FindArchivePath(designName);
     632          106 :         if (archivePath.empty())
     633              :         {
     634           26 :             logwarn("Failed to find file for design \"" + designName + "\"");
     635              : 
     636           26 :             logdebug("Listing all files in directory: " + getDirectory());
     637           13 :             const auto options = directory_options::skip_permission_denied;
     638           13 :             std::error_code ec;
     639           37 :             for (const auto& entry : directory_iterator(getDirectory(), options, ec))
     640              :             {
     641           24 :                 if (entry.is_regular_file())
     642              :                 {
     643           72 :                     logdebug("Found file: " + entry.path().filename().string() + " (stem: " + entry.path().stem().string() + ")");
     644              :                 }
     645           13 :             }
     646              : 
     647           13 :             return nullptr;
     648              :         }
     649              : 
     650          186 :         loginfo("file found: [" + archivePath.string() + "], attempting to parse...");
     651              : 
     652           93 :         auto pFileArchive = std::make_shared<FileModel::Design::FileArchive>(archivePath.string());
     653           93 :         if (pFileArchive->ParseFileModel())
     654              :         {
     655           81 :             return pFileArchive;
     656              :         }
     657              : 
     658              :         // A matching file was found but failed to extract or parse. Treat this
     659              :         // as a corrupt/unloadable design (error) rather than a missing one, so
     660              :         // callers surface INTERNAL/500 instead of a misleading NOT_FOUND/404.
     661              :         // (ParseFileModel already throws on parse failure; this covers the
     662              :         // extraction / missing-root-dir paths that return false.)
     663              :         // The file path is intentionally omitted here to avoid leaking server
     664              :         // filesystem details to API clients (it is logged above for diagnostics).
     665              :         throw std::runtime_error(
     666            5 :             "Failed to load design \"" + designName + "\": could not extract or parse archive");
     667          118 :     }
     668              : 
     669           69 :     void DesignCache::TouchLru(const std::string& designName)
     670              :     {
     671           69 :         std::lock_guard<std::mutex> lruLock(m_lruMutex);
     672           69 :         auto findIt = m_lruEntries.find(designName);
     673           69 :         if (findIt != m_lruEntries.end())
     674              :         {
     675           68 :             findIt->second.lastServed = std::chrono::steady_clock::now();
     676              :         }
     677              :         // No entry: the name raced with eviction, was never charged, or belonged
     678              :         // to a load abandoned across Clear(). Touch is a no-op for absent names —
     679              :         // it never inserts — so a joiner of an abandoned load cannot phantom-charge
     680              :         // the byte budget for an uncached name.
     681           69 :     }
     682              : 
     683          137 :     void DesignCache::InsertLruAndEvict(const std::string& designName, std::uint64_t injectedBytes)
     684              :     {
     685          137 :         const auto now = std::chrono::steady_clock::now();
     686          137 :         const auto bytes = EstimateDesignBytes(designName, injectedBytes);
     687              : 
     688          137 :         std::vector<std::string> evicted;
     689              :         {
     690          137 :             std::lock_guard<std::mutex> lruLock(m_lruMutex);
     691          137 :             auto findIt = m_lruEntries.find(designName);
     692          137 :             if (findIt != m_lruEntries.end())
     693              :             {
     694           57 :                 findIt->second.lastServed = now;
     695              :                 // Re-injection over an existing entry (e.g. POST /filemodels
     696              :                 // overwriting a save=false design): refresh the charge to the
     697              :                 // new estimate instead of silently keeping the previous
     698              :                 // injection's bytes. The payload term is excluded —
     699              :                 // serialized payload bytes are charged separately via
     700              :                 // LruEntry::serializedBytes, and counting them here too would
     701              :                 // over-subtract at eviction. (m_lruMutex -> store mutex is a
     702              :                 // permitted nesting; see the lock-order note above.)
     703           57 :                 const auto base = bytes - m_responseStore.StoredBytes(designName);
     704           57 :                 const auto delta = static_cast<std::int64_t>(base) - static_cast<std::int64_t>(findIt->second.estimatedBytes);
     705           57 :                 findIt->second.estimatedBytes = base;
     706           57 :                 m_cachedBytes = static_cast<std::uint64_t>(static_cast<std::int64_t>(m_cachedBytes) + delta);
     707              :             }
     708              :             else
     709              :             {
     710           80 :                 m_lruEntries.emplace(designName, LruEntry{bytes, 0, now});
     711           80 :                 m_cachedBytes += bytes;
     712              :             }
     713          137 :             evicted = EvictOverBudgetLocked(designName);
     714          137 :         }
     715          137 :         EvictCacheEntries(evicted);
     716          137 :     }
     717              : 
     718              :     // Requires m_lruMutex held. May acquire m_loadStateMutex (the one permitted
     719              :     // nesting) to skip in-flight (Loading) designs. Returns evicted names; cache-map
     720              :     // and state cleanup happens in EvictCacheEntries after m_lruMutex is released.
     721          172 :     std::vector<std::string> DesignCache::EvictOverBudgetLocked(const std::string& protectedName)
     722              :     {
     723          172 :         std::vector<std::string> evicted;
     724              : 
     725          172 :         if (m_maxBytes == 0)
     726              :         {
     727              :             // Budget of 0 disables eviction
     728            6 :             return evicted;
     729              :         }
     730              : 
     731          172 :         while (m_cachedBytes > m_maxBytes)
     732              :         {
     733           14 :             auto victimIt = m_lruEntries.end();
     734           14 :             auto oldest = std::chrono::steady_clock::time_point::max();
     735              : 
     736           30 :             for (auto it = m_lruEntries.begin(); it != m_lruEntries.end(); ++it)
     737              :             {
     738           16 :                 if (it->first == protectedName) continue;       // never evict the entry being served
     739            6 :                 if (it->second.lastServed >= oldest) continue;  // least-recently-served first
     740              :                 {
     741            6 :                     std::lock_guard<std::mutex> stateLock(m_loadStateMutex);
     742            6 :                     auto stateIt = m_loadStatesByName.find(it->first);
     743            6 :                     if (stateIt != m_loadStatesByName.end() && stateIt->second == LoadState::Loading)
     744              :                     {
     745            0 :                         continue;  // never evict an in-flight design
     746              :                     }
     747            6 :                 }
     748            6 :                 oldest = it->second.lastServed;
     749            6 :                 victimIt = it;
     750              :             }
     751              : 
     752           14 :             if (victimIt == m_lruEntries.end())
     753              :             {
     754              :                 // Nothing evictable (only the protected/in-flight entries remain);
     755              :                 // over-budget is tolerated rather than dropping protected work.
     756            8 :                 break;
     757              :             }
     758              : 
     759              :             // Uncharge the victim's FULL contribution: the archive/Design
     760              :             // estimate plus the serialized response payloads committed on top
     761              :             // of it (CommitResponsePayloads charges both to m_cachedBytes).
     762              :             // Stranding the payload half would permanently inflate the byte
     763              :             // count every time a warm design is evicted.
     764            6 :             m_cachedBytes -= victimIt->second.estimatedBytes + victimIt->second.serializedBytes;
     765            6 :             const auto evictedName = victimIt->first;
     766            6 :             m_lruEntries.erase(victimIt);
     767            6 :             evicted.push_back(evictedName);
     768            6 :         }
     769              : 
     770          166 :         return evicted;
     771            0 :     }
     772              : 
     773          172 :     void DesignCache::EvictCacheEntries(const std::vector<std::string>& names)
     774              :     {
     775          178 :         for (const auto& name : names)
     776              :         {
     777              :             // Drop the serialized response payloads (generation bump keeps a
     778              :             // commit that raced the eviction from re-publishing them). Their
     779              :             // bytes were uncharged together with the estimate in
     780              :             // EvictOverBudgetLocked — the entry (estimate + serialized charge)
     781              :             // was removed as a whole there.
     782            6 :             m_responseStore.Invalidate(name);
     783              : 
     784              :             {
     785            6 :                 std::unique_lock<std::shared_mutex> writeLock(m_cacheMutex);
     786            6 :                 m_designsByName.erase(name);
     787            6 :                 m_fileArchivesByName.erase(name);
     788            6 :             }
     789              : 
     790           12 :             loginfo("Evicted design \"" + name + "\" from cache (over byte budget)");
     791              : 
     792            6 :             TransitionLoadState(name, LoadState::Unloaded);
     793              :         }
     794          172 :     }
     795              : 
     796          137 :     std::uint64_t DesignCache::EstimateDesignBytes(const std::string& designName, std::uint64_t injectedBytes) const
     797              :     {
     798              :         // Estimate: archive file size on disk + a small constant + the bytes
     799              :         // currently held for the design's cached serialized response payloads
     800              :         // (M1.4). The payload term is zero for a fresh entry — payload bytes
     801              :         // are charged incrementally at commit time (CommitResponsePayloads) —
     802              :         // but a re-insert while payloads exist stays honest. injectedBytes
     803              :         // covers in-memory-only archives (AddFileArchive with save=false):
     804              :         // nothing on disk backs the name, so the request-body size stands in
     805              :         // for the archive footprint.
     806          137 :         const auto archivePath = FindArchivePath(designName);
     807          137 :         if (archivePath.empty())
     808              :         {
     809            3 :             return DESIGN_BYTES_OVERHEAD + m_responseStore.StoredBytes(designName) + injectedBytes;
     810              :         }
     811              : 
     812          134 :         std::error_code ec;
     813          134 :         const auto size = std::filesystem::file_size(archivePath, ec);
     814          134 :         if (ec)
     815              :         {
     816            0 :             return DESIGN_BYTES_OVERHEAD + m_responseStore.StoredBytes(designName) + injectedBytes;
     817              :         }
     818          134 :         return static_cast<std::uint64_t>(size) + DESIGN_BYTES_OVERHEAD + m_responseStore.StoredBytes(designName);
     819          137 :     }
     820              : 
     821            0 :     void DesignCache::ResyncLruEstimate(const std::string& designName)
     822              :     {
     823              :         // Estimate outside m_lruMutex (directory scan + store lookup), the
     824              :         // same pattern InsertLruAndEvict uses, then apply the delta under it.
     825            0 :         const auto bytes = EstimateDesignBytes(designName);
     826            0 :         std::lock_guard<std::mutex> lruLock(m_lruMutex);
     827            0 :         auto findIt = m_lruEntries.find(designName);
     828            0 :         if (findIt == m_lruEntries.end())
     829              :         {
     830            0 :             return;
     831              :         }
     832              :         // Exclude the payload term: serialized payload bytes are charged via
     833              :         // LruEntry::serializedBytes, and including them in estimatedBytes too
     834              :         // would double-count at eviction. (Safe today either way — the only
     835              :         // caller runs right after an invalidation emptied the store — but the
     836              :         // exclusion keeps the invariant local instead of call-site-dependent.)
     837            0 :         const auto base = bytes - m_responseStore.StoredBytes(designName);
     838              :         // Signed delta: the file may be smaller than the injected estimate
     839              :         // the entry was charged with at insert time.
     840            0 :         const auto delta = static_cast<std::int64_t>(base) - static_cast<std::int64_t>(findIt->second.estimatedBytes);
     841            0 :         findIt->second.estimatedBytes = base;
     842            0 :         m_cachedBytes = static_cast<std::uint64_t>(static_cast<std::int64_t>(m_cachedBytes) + delta);
     843            0 :     }
     844              : 
     845           45 :     std::uint64_t DesignCache::GetResponseGeneration(const std::string& designName) const
     846              :     {
     847           45 :         return m_responseStore.CurrentGeneration(designName);
     848              :     }
     849              : 
     850            8 :     std::uint64_t DesignCache::cachedBytes() const
     851              :     {
     852            8 :         std::lock_guard<std::mutex> lruLock(m_lruMutex);
     853            8 :         return m_cachedBytes;
     854            8 :     }
     855              : 
     856          225 :     void DesignCache::TransitionLoadState(const std::string& designName, LoadState to)
     857              :     {
     858          225 :         LoadObserverList observers;
     859          225 :         auto from = LoadState::Unloaded;
     860              :         {
     861          225 :             std::lock_guard<std::mutex> stateLock(m_loadStateMutex);
     862          225 :             auto stateIt = m_loadStatesByName.find(designName);
     863          225 :             from = (stateIt != m_loadStatesByName.end()) ? stateIt->second : LoadState::Unloaded;
     864          225 :             if (from == to)
     865              :             {
     866              :                 // Not a transition (e.g. an archive load under an already-Loading
     867              :                 // design, or a duplicate completion) — no observer event.
     868            3 :                 return;
     869              :             }
     870          222 :             m_loadStatesByName[designName] = to;
     871          222 :             observers = m_loadObservers;
     872          225 :         }
     873          222 :         NotifyLoadObservers(designName, from, to, observers);
     874          225 :     }
     875              : 
     876              :     // Removes the design's state entry and reports the revert to Unloaded. If no
     877              :     // entry exists (nothing was recorded, or Clear() already wiped it) this is a
     878              :     // no-op: the name is already at the implicit Unloaded, so no event is due.
     879           25 :     void DesignCache::EraseLoadState(const std::string& designName)
     880              :     {
     881           25 :         LoadObserverList observers;
     882           25 :         auto from = LoadState::Unloaded;
     883              :         {
     884           25 :             std::lock_guard<std::mutex> stateLock(m_loadStateMutex);
     885           25 :             auto stateIt = m_loadStatesByName.find(designName);
     886           25 :             if (stateIt == m_loadStatesByName.end())
     887              :             {
     888            0 :                 return;
     889              :             }
     890           25 :             from = stateIt->second;
     891           25 :             m_loadStatesByName.erase(stateIt);
     892           25 :             observers = m_loadObservers;
     893           25 :         }
     894           25 :         if (from != LoadState::Unloaded)
     895              :         {
     896           25 :             NotifyLoadObservers(designName, from, LoadState::Unloaded, observers);
     897              :         }
     898           25 :     }
     899              : 
     900              :     // Observers run with no locks held (they may re-enter the cache) and must be
     901              :     // cheap/non-blocking; a throwing observer is logged and skipped.
     902          247 :     void DesignCache::NotifyLoadObservers(const std::string& designName, LoadState from, LoadState to, const LoadObserverList& observers)
     903              :     {
     904          313 :         for (const auto& observer : observers)
     905              :         {
     906              :             try
     907              :             {
     908           66 :                 observer(designName, from, to);
     909              :             }
     910            0 :             catch (const std::exception& e)
     911              :             {
     912            0 :                 logwarn(std::string("Design load observer threw: ") + e.what());
     913            0 :             }
     914            0 :             catch (...)
     915              :             {
     916            0 :                 logwarn("Design load observer threw an unknown exception");
     917            0 :             }
     918              :         }
     919          247 :     }
     920              : 
     921              :     // ---- serialized-response cache (M1.4) ----
     922              : 
     923           20 :     bool DesignCache::ResponseStore::TryGetDesignBytes(const std::string& designName, std::string& outBytes) const
     924              :     {
     925           20 :         std::lock_guard<std::mutex> lock(m_mutex);
     926           20 :         auto findIt = m_entriesByName.find(designName);
     927           20 :         if (findIt == m_entriesByName.end() || findIt->second.payload.designPbBytes.empty())
     928              :         {
     929           15 :             return false;
     930              :         }
     931            5 :         outBytes = findIt->second.payload.designPbBytes;
     932            5 :         return true;
     933           20 :     }
     934              : 
     935            5 :     bool DesignCache::ResponseStore::TryGetJsonPayload(const std::string& designName, JsonPayloadKind kind, std::string& outJson) const
     936              :     {
     937            5 :         std::lock_guard<std::mutex> lock(m_mutex);
     938            5 :         auto findIt = m_entriesByName.find(designName);
     939            5 :         if (findIt == m_entriesByName.end())
     940              :         {
     941            3 :             return false;
     942              :         }
     943              :         const auto& json = (kind == JsonPayloadKind::Design)
     944            1 :             ? findIt->second.payload.designJson
     945            3 :             : findIt->second.payload.fileModelJson;
     946            2 :         if (json.empty())
     947              :         {
     948            2 :             return false;
     949              :         }
     950            0 :         outJson = json;
     951            0 :         return true;
     952            5 :     }
     953              : 
     954        45952 :     bool DesignCache::ResponseStore::HasEntry(const std::string& designName) const
     955              :     {
     956        45952 :         std::lock_guard<std::mutex> lock(m_mutex);
     957        91904 :         return m_entriesByName.find(designName) != m_entriesByName.end();
     958        45952 :     }
     959              : 
     960          198 :     std::uint64_t DesignCache::ResponseStore::StoredBytes(const std::string& designName) const
     961              :     {
     962          198 :         std::lock_guard<std::mutex> lock(m_mutex);
     963          198 :         auto findIt = m_entriesByName.find(designName);
     964          396 :         return findIt != m_entriesByName.end() ? findIt->second.payload.totalBytes() : 0;
     965          198 :     }
     966              : 
     967            3 :     std::uint64_t DesignCache::ResponseStore::TotalStoredBytes() const
     968              :     {
     969            3 :         std::lock_guard<std::mutex> lock(m_mutex);
     970            3 :         std::uint64_t total = 0;
     971            4 :         for (const auto& kv : m_entriesByName)
     972              :         {
     973            1 :             total += kv.second.payload.totalBytes();
     974              :         }
     975            3 :         return total;
     976            3 :     }
     977              : 
     978          432 :     std::uint64_t DesignCache::ResponseStore::CurrentGeneration(const std::string& designName) const
     979              :     {
     980          432 :         std::lock_guard<std::mutex> lock(m_mutex);
     981          432 :         auto findIt = m_generationsByName.find(designName);
     982          864 :         return findIt != m_generationsByName.end() ? findIt->second : 0;
     983          432 :     }
     984              : 
     985           23 :     DesignCache::ResponseStore::StoreResult DesignCache::ResponseStore::TryStore(
     986              :         const std::string& designName, std::uint64_t generation, ResponsePayload&& payload)
     987              :     {
     988           23 :         std::lock_guard<std::mutex> lock(m_mutex);
     989              : 
     990              :         // Validate against the generation tombstone: any invalidation since the
     991              :         // committer captured its generation bumps past it and loses the race.
     992           23 :         auto genIt = m_generationsByName.find(designName);
     993           23 :         const auto currentGeneration = genIt != m_generationsByName.end() ? genIt->second : 0;
     994           23 :         if (generation != currentGeneration)
     995              :         {
     996            0 :             StoreResult lost;
     997            0 :             lost.stored = false;
     998            0 :             return lost;
     999              :         }
    1000              : 
    1001           23 :         auto findIt = m_entriesByName.find(designName);
    1002           23 :         if (findIt != m_entriesByName.end())
    1003              :         {
    1004              :             // Already stored for this generation (a racing background/lazy
    1005              :             // committer won): report success without re-storing so the
    1006              :             // serialization counter stays exact — one per design per generation.
    1007            0 :             StoreResult result;
    1008            0 :             result.stored = true;
    1009            0 :             result.storedBytes = findIt->second.payload.totalBytes();
    1010            0 :             return result;
    1011              :         }
    1012              : 
    1013           23 :         auto& entry = m_entriesByName[designName];
    1014           23 :         entry.payload = std::move(payload);
    1015           23 :         ++m_designSerializations;
    1016              : 
    1017           23 :         StoreResult result;
    1018           23 :         result.stored = true;
    1019           23 :         result.storedBytes = entry.payload.totalBytes();
    1020           23 :         return result;
    1021           23 :     }
    1022              : 
    1023           14 :     std::uint64_t DesignCache::ResponseStore::Invalidate(const std::string& designName)
    1024              :     {
    1025           14 :         std::lock_guard<std::mutex> lock(m_mutex);
    1026           14 :         std::uint64_t dropped = 0;
    1027           14 :         auto findIt = m_entriesByName.find(designName);
    1028           14 :         if (findIt != m_entriesByName.end())
    1029              :         {
    1030            5 :             dropped = findIt->second.payload.totalBytes();
    1031            5 :             m_entriesByName.erase(findIt);
    1032              :         }
    1033              :         // Bump the tombstone even when no entry existed: a commit that captured
    1034              :         // the pre-invalidation generation must lose its TryStore.
    1035           14 :         ++m_generationsByName[designName];
    1036           14 :         return dropped;
    1037           14 :     }
    1038              : 
    1039          498 :     void DesignCache::ResponseStore::BumpGenerations(const std::vector<std::string>& designNames)
    1040              :     {
    1041          498 :         std::lock_guard<std::mutex> lock(m_mutex);
    1042          616 :         for (const auto& name : designNames)
    1043              :         {
    1044              :             // Creates the tombstone when absent (a loaded-but-never-invalidated
    1045              :             // design sits at generation 0 with no entry here).
    1046          118 :             ++m_generationsByName[name];
    1047              :         }
    1048          498 :     }
    1049              : 
    1050          498 :     void DesignCache::ResponseStore::Clear()
    1051              :     {
    1052          498 :         std::lock_guard<std::mutex> lock(m_mutex);
    1053          498 :         m_entriesByName.clear();
    1054              :         // Generation tombstones are intentionally PRESERVED (and the cache's
    1055              :         // Clear() additionally bumps one for every design it held, via
    1056              :         // BumpGenerations). The disk-load path does NOT bump generations —
    1057              :         // only re-upload (AddFileArchive), InvalidateDesign and eviction do —
    1058              :         // so erasing the tombstones (or leaving them un-bumped) would let a
    1059              :         // post-Clear reload land on the same generation a GetDesignStream
    1060              :         // spool was published at before the Clear, warm-serving content the
    1061              :         // system had invalidated.
    1062              :         // Counter intentionally NOT reset: it counts work performed, not work
    1063              :         // currently cached (tests read it as "how many serializations happened").
    1064          498 :     }
    1065              : 
    1066            4 :     std::uint64_t DesignCache::ResponseStore::designSerializations() const
    1067              :     {
    1068            4 :         std::lock_guard<std::mutex> lock(m_mutex);
    1069            4 :         return m_designSerializations;
    1070            4 :     }
    1071              : 
    1072              :     // ---- DesignCache-level response-cache API ----
    1073              : 
    1074           20 :     bool DesignCache::TryGetDesignBytes(const std::string& designName, std::string& outBytes) const
    1075              :     {
    1076           20 :         return m_responseStore.TryGetDesignBytes(designName, outBytes);
    1077              :     }
    1078              : 
    1079            5 :     bool DesignCache::TryGetJsonPayload(const std::string& designName, JsonPayloadKind kind, std::string& outJson) const
    1080              :     {
    1081            5 :         return m_responseStore.TryGetJsonPayload(designName, kind, outJson);
    1082              :     }
    1083              : 
    1084        45952 :     bool DesignCache::HasCachedResponse(const std::string& designName) const
    1085              :     {
    1086        45952 :         return m_responseStore.HasEntry(designName);
    1087              :     }
    1088              : 
    1089            4 :     std::uint64_t DesignCache::designSerializationCount() const
    1090              :     {
    1091            4 :         return m_responseStore.designSerializations();
    1092              :     }
    1093              : 
    1094            3 :     std::uint64_t DesignCache::cachedResponseBytes() const
    1095              :     {
    1096            3 :         return m_responseStore.TotalStoredBytes();
    1097              :     }
    1098              : 
    1099           16 :     void DesignCache::setMonolithicWireBudget(std::uint64_t maxBytes)
    1100              :     {
    1101           16 :         std::lock_guard<std::mutex> lruLock(m_lruMutex);
    1102           16 :         m_monolithicWireBudget = maxBytes;
    1103           16 :     }
    1104              : 
    1105           27 :     std::uint64_t DesignCache::getMonolithicWireBudget() const
    1106              :     {
    1107           27 :         std::lock_guard<std::mutex> lruLock(m_lruMutex);
    1108           27 :         return m_monolithicWireBudget;
    1109           27 :     }
    1110              : 
    1111            0 :     std::uint64_t DesignCache::CurrentEpoch() const
    1112              :     {
    1113            0 :         std::lock_guard<std::mutex> stateLock(m_loadStateMutex);
    1114            0 :         return m_epoch;
    1115            0 :     }
    1116              : 
    1117           53 :     DesignCache::ResponsePayload DesignCache::BuildResponsePayload(const ProductModel::Design& design)
    1118              :     {
    1119           53 :         ResponsePayload payload;
    1120              : 
    1121              :         // M6 monolithic serve budget: a design whose estimated serialized
    1122              :         // size exceeds the budget must not have its protobuf tree built here
    1123              :         // (the full-tree build + serialized copy is the 10 GiB-pod OOM, and
    1124              :         // this worker runs unprompted at load completion). It stays
    1125              :         // un-cached; the chunked GetDesignStream RPC serves it, spooling to
    1126              :         // disk instead of RAM. Budget 0 = disabled (pre-M6 behavior).
    1127              :         {
    1128           53 :             std::lock_guard<std::mutex> lruLock(m_lruMutex);
    1129          106 :             if (m_monolithicWireBudget != 0 &&
    1130           53 :                 design.EstimateWireSizeBytes(/*includeNormalizedLists=*/false) > m_monolithicWireBudget)
    1131              :             {
    1132           28 :                 loginfo("Skipping monolithic response pre-serialization (over serve budget); design is served via GetDesignStream");
    1133            7 :                 return payload;
    1134              :             }
    1135           53 :         }
    1136              : 
    1137              :         // One protobuf tree build serves both the wire bytes and the JSON.
    1138              :         // These bytes back the gRPC GetDesign fast path, which serves the
    1139              :         // DEFAULT (pruned) flavor — serialize that flavor here explicitly.
    1140              :         // (include_normalized_lists requests are served cold from the live
    1141              :         // design; REST/JSON consumers call the full-flavor no-arg
    1142              :         // to_protobuf() on the cached Design object themselves.)
    1143           46 :         auto pMessage = design.to_protobuf(/*includeNormalizedLists=*/false);
    1144           46 :         if (pMessage != nullptr)
    1145              :         {
    1146           46 :             if (!pMessage->SerializeToString(&payload.designPbBytes))
    1147              :             {
    1148            0 :                 payload.designPbBytes.clear();
    1149              :             }
    1150              : 
    1151              :         }
    1152              : 
    1153              :         // JSON payloads (designJson/fileModelJson) are deliberately NOT built
    1154              :         // here: their REST consumers arrive with the controller-wiring
    1155              :         // follow-up, and eagerly building two full-JSON strings per design
    1156              :         // alongside the protobuf tree was a major memory-thrash contributor
    1157              :         // on large designs. TryGetJsonPayload returns false until that
    1158              :         // follow-up adds (lazy) JSON population.
    1159           46 :         return payload;
    1160           46 :     }
    1161              : 
    1162           53 :     void DesignCache::CommitResponsePayloads(const std::string& designName,
    1163              :         std::uint64_t epochAtStart,
    1164              :         const std::shared_ptr<ProductModel::Design>& pDesign,
    1165              :         ResponsePayload&& payload,
    1166              :         std::uint64_t generation)
    1167              :     {
    1168           53 :         if (pDesign == nullptr || payload.totalBytes() == 0)
    1169              :         {
    1170           30 :             return;
    1171              :         }
    1172              : 
    1173              :         // Design-object identity: the payloads are valid only for the Design
    1174              :         // object they were built from. Eviction, Clear(), and AddFileArchive
    1175              :         // remove or replace the cached Design; a mismatch (shared_ptr identity,
    1176              :         // so no address-reuse ABA) aborts the commit.
    1177              :         {
    1178           46 :             std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
    1179           46 :             auto findIt = m_designsByName.find(designName);
    1180           46 :             if (findIt == m_designsByName.end() || findIt->second != pDesign)
    1181              :             {
    1182           22 :                 return;
    1183              :             }
    1184           46 :         }
    1185              : 
    1186           24 :         std::vector<std::string> evicted;
    1187              :         {
    1188           24 :             std::lock_guard<std::mutex> lruLock(m_lruMutex);
    1189           24 :             auto entryIt = m_lruEntries.find(designName);
    1190           24 :             if (entryIt == m_lruEntries.end())
    1191              :             {
    1192            0 :                 return; // evicted while serializing
    1193              :             }
    1194           24 :             if (WasClearedSince(epochAtStart))
    1195              :             {
    1196            0 :                 return; // Clear() ran since the load/serialization started
    1197              :             }
    1198              : 
    1199              :             // Budget re-check at COMMIT time: BuildResponsePayload checked at
    1200              :             // serialization START; a worker that began under a higher (or
    1201              :             // disabled) budget must not publish over-budget bytes after the
    1202              :             // budget was lowered.
    1203              :             //
    1204              :             // Note the two gates compare different sizes: the start gate uses
    1205              :             // the EstimateWireSizeBytes estimate, this gate the actual payload.
    1206              :             // For a design in the estimate < budget < actual band, the tree is
    1207              :             // built and serialized but never committed, so every fetch repeats
    1208              :             // that work (transiently re-creating the memory spike the budget
    1209              :             // exists to prevent). Accepted tradeoff: this gate exists to stop
    1210              :             // budgets lowered mid-flight from being violated; estimate-miss
    1211              :             // designs simply never get a monolithic in-RAM response and are
    1212              :             // served by GetDesignStream + spool instead.
    1213           24 :             if (m_monolithicWireBudget != 0 && payload.totalBytes() > m_monolithicWireBudget)
    1214              :             {
    1215            1 :                 return; // over the (now lower) monolithic serve budget
    1216              :             }
    1217              : 
    1218           23 :             const auto storeResult = m_responseStore.TryStore(designName, generation, std::move(payload));
    1219           23 :             if (storeResult.stored)
    1220              :             {
    1221              :                 // Resync the entry's serialized charge with the store. An
    1222              :                 // invalidation racing between TryStore and StoredBytes shows up
    1223              :                 // here as a smaller/zero reading, which is exactly the right
    1224              :                 // charge for the store's current contents.
    1225           23 :                 const auto delta = storeResult.storedBytes - entryIt->second.serializedBytes;
    1226           23 :                 entryIt->second.serializedBytes = storeResult.storedBytes;
    1227           23 :                 m_cachedBytes += delta;
    1228              :             }
    1229              : 
    1230           23 :             evicted = EvictOverBudgetLocked(designName);
    1231           24 :         }
    1232           23 :         EvictCacheEntries(evicted);
    1233           24 :     }
    1234              : 
    1235           53 :     void DesignCache::ScheduleResponsePreSerialization(const std::string& designName,
    1236              :         std::shared_ptr<ProductModel::Design> pDesign,
    1237              :         std::uint64_t epochAtStart)
    1238              :     {
    1239           53 :         const auto generation = m_responseStore.CurrentGeneration(designName);
    1240              : 
    1241              :         // Counted + drained exactly like background loads so detached threads
    1242              :         // never outlive the cache members they touch (~DesignCache waits on
    1243              :         // m_outstandingBackgroundLoads).
    1244              :         {
    1245           53 :             std::lock_guard<std::mutex> lock(m_backgroundMutex);
    1246           53 :             ++m_outstandingBackgroundLoads;
    1247           53 :         }
    1248              : 
    1249              :         try
    1250              :         {
    1251          106 :             std::thread(&DesignCache::PreSerializeWorker, this, designName, std::move(pDesign),
    1252           53 :                 epochAtStart, generation).detach();
    1253              :         }
    1254            0 :         catch (const std::exception& e)
    1255              :         {
    1256              :             {
    1257            0 :                 std::lock_guard<std::mutex> lock(m_backgroundMutex);
    1258            0 :                 --m_outstandingBackgroundLoads;
    1259            0 :             }
    1260              :             // Missed-wakeup guard, identical to LoadDesignAsync's catch: the
    1261              :             // destructor drains on the CV.
    1262            0 :             m_backgroundDoneCv.notify_all();
    1263              :             // A failed pre-serialization schedule must not fail the load that
    1264              :             // just succeeded; the first fetch repopulates lazily.
    1265            0 :             logwarn("Failed to schedule response pre-serialization for design \"" + designName + "\": " + e.what());
    1266            0 :         }
    1267           53 :     }
    1268              : 
    1269           53 :     void DesignCache::PreSerializeWorker(std::string designName,
    1270              :         std::shared_ptr<ProductModel::Design> pDesign,
    1271              :         std::uint64_t epochAtStart,
    1272              :         std::uint64_t generation)
    1273              :     {
    1274              :         // Shares the background-load semaphore: serialization competes with
    1275              :         // parses for --max-background-loads slots, bounding memory spikes.
    1276           53 :         AcquireBackgroundSlot();
    1277              :         try
    1278              :         {
    1279           53 :             auto payload = BuildResponsePayload(*pDesign);
    1280           53 :             CommitResponsePayloads(designName, epochAtStart, pDesign, std::move(payload), generation);
    1281          106 :             logdebug("Response pre-serialization for design \"" + designName + "\" committed");
    1282           53 :         }
    1283            0 :         catch (const std::exception& e)
    1284              :         {
    1285            0 :             logwarn("Response pre-serialization for design \"" + designName + "\" failed: " + e.what());
    1286            0 :         }
    1287            0 :         catch (...)
    1288              :         {
    1289            0 :             logwarn("Response pre-serialization for design \"" + designName + "\" failed with an unknown exception");
    1290            0 :         }
    1291           53 :         ReleaseBackgroundSlot();
    1292              : 
    1293              :         {
    1294           53 :             std::lock_guard<std::mutex> lock(m_backgroundMutex);
    1295           53 :             --m_outstandingBackgroundLoads;
    1296           53 :         }
    1297           53 :         m_backgroundDoneCv.notify_all();
    1298           53 :     }
    1299              : 
    1300            8 :     void DesignCache::InvalidateResponsePayloads(const std::string& designName)
    1301              :     {
    1302            8 :         m_responseStore.Invalidate(designName);
    1303            8 :         AdjustLruSerializedBytes(designName);
    1304            8 :     }
    1305              : 
    1306            8 :     void DesignCache::AdjustLruSerializedBytes(const std::string& designName)
    1307              :     {
    1308            8 :         std::lock_guard<std::mutex> lruLock(m_lruMutex);
    1309            8 :         auto entryIt = m_lruEntries.find(designName);
    1310            8 :         if (entryIt == m_lruEntries.end())
    1311              :         {
    1312            4 :             return;
    1313              :         }
    1314            4 :         const auto stored = m_responseStore.StoredBytes(designName);
    1315            4 :         if (stored != entryIt->second.serializedBytes)
    1316              :         {
    1317            2 :             m_cachedBytes -= entryIt->second.serializedBytes - stored;
    1318            2 :             entryIt->second.serializedBytes = stored;
    1319              :         }
    1320            8 :     }
    1321              : 
    1322            0 :     void DesignCache::LogFailedStateRecordError(const std::string& designName)
    1323              :     {
    1324              :         // Lives out-of-line because the calling template is in the header,
    1325              :         // which does not include Logger.h.
    1326            0 :         logerror("Failed to record Failed load-state for design \"" + designName + "\" during load-failure cleanup");
    1327            0 :     }
    1328              : 
    1329            0 :     void DesignCache::SerializeResponsePayloads(const std::string& designName)
    1330              :     {
    1331            0 :         std::shared_ptr<ProductModel::Design> pDesign;
    1332              :         {
    1333            0 :             std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
    1334            0 :             auto findIt = m_designsByName.find(designName);
    1335            0 :             if (findIt == m_designsByName.end())
    1336              :             {
    1337            0 :                 return;
    1338              :             }
    1339            0 :             pDesign = findIt->second;
    1340            0 :         }
    1341              : 
    1342            0 :         const auto generation = m_responseStore.CurrentGeneration(designName);
    1343            0 :         const auto epoch = CurrentEpoch();
    1344              : 
    1345              :         try
    1346              :         {
    1347            0 :             auto payload = BuildResponsePayload(*pDesign);
    1348            0 :             CommitResponsePayloads(designName, epoch, pDesign, std::move(payload), generation);
    1349            0 :         }
    1350            0 :         catch (const std::exception& e)
    1351              :         {
    1352            0 :             logwarn("Lazy response serialization for design \"" + designName + "\" failed: " + e.what());
    1353            0 :         }
    1354            0 :         catch (...)
    1355              :         {
    1356            0 :             logwarn("Lazy response serialization for design \"" + designName + "\" failed with an unknown exception");
    1357            0 :         }
    1358            0 :     }
    1359              : }
        

Generated by: LCOV version 2.0-1