LCOV - code coverage report
Current view: top level - OdbDesignServer/Services - StreamSpoolCache.h (source / functions) Coverage Total Hit
Test: OdbDesign Test Coverage Lines: 100.0 % 5 5
Test Date: 2026-11-19 04:56:22 Functions: 100.0 % 5 5
Legend: Lines: hit not hit

            Line data    Source code
       1              : #pragma once
       2              : 
       3              : // StreamSpoolCache — disk-backed spool of a design's GetDesignStream chunk
       4              : // sequence (M6.3, getdesign-streaming-oom-plan.md).
       5              : //
       6              : // The monolithic in-RAM response cache (DesignCache M1.4) is unusable for
       7              : // over-budget designs: its payload IS the multi-GB serialized Design. For
       8              : // those designs the first GetDesignStream fill tees every chunk to a spool
       9              : // file while writing it to the wire; subsequent (warm) requests re-emit the
      10              : // chunks by reading the file record-by-record — never materializing more
      11              : // than one chunk of heap. The RAM cost of a warm hit is page cache, which
      12              : // the kernel reclaims under pressure, instead of anonymous heap.
      13              : //
      14              : // Spool file format: length-delimited protobuf records — each record is the
      15              : // standard varint-encoded byte length of the serialized Odb::Grpc::DesignChunk
      16              : // followed by those bytes, in chunk emission order, so a spool replays the
      17              : // exact chunk sequence (and therefore the exact monolithic Design bytes after
      18              : // reassembly).
      19              : //
      20              : // Identity/invalidation: an entry is valid for (design name, response-cache
      21              : // generation). DesignCache bumps the generation on AddFileArchive (re-upload),
      22              : // InvalidateDesign, and LRU eviction, so a stale spool is detected on the next
      23              : // open and the next fill re-spools the fresh contents. The cache owns a
      24              : // private spool directory (per service instance, under the system temp dir by
      25              : // default, removed in the destructor) so parallel server/test instances never
      26              : // touch each other's files; a total-bytes cap LRU-evicts spool files beyond it.
      27              : 
      28              : #include <cstdint>
      29              : #include <filesystem>
      30              : #include <fstream>
      31              : #include <map>
      32              : #include <mutex>
      33              : #include <string>
      34              : 
      35              : #include <google/protobuf/message.h>
      36              : 
      37              : namespace OdbDesignServer
      38              : {
      39              :     namespace Services
      40              :     {
      41              :         class StreamSpoolCache
      42              :         {
      43              :         public:
      44              :             // Default total-bytes cap for the private-directory constructor.
      45              :             static constexpr std::uint64_t kDefaultMaxTotalBytes = 4ull * 1024ull * 1024ull * 1024ull;
      46              : 
      47              :             // Creates a cache with a private spool directory under the system
      48              :             // temp directory (keeps parallel instances isolated; the directory
      49              :             // is removed in the destructor). maxTotalBytes defaults to
      50              :             // kDefaultMaxTotalBytes.
      51              :             explicit StreamSpoolCache(std::uint64_t maxTotalBytes = kDefaultMaxTotalBytes);
      52              : 
      53              :             // Creates a cache rooted at an explicit directory. The directory is
      54              :             // created if missing; its spool files are NOT removed wholesale by
      55              :             // the destructor (only files this cache itself published).
      56              :             StreamSpoolCache(const std::filesystem::path& directory, std::uint64_t maxTotalBytes);
      57              :             ~StreamSpoolCache();
      58              : 
      59              :             StreamSpoolCache(const StreamSpoolCache&) = delete;
      60              :             StreamSpoolCache& operator=(const StreamSpoolCache&) = delete;
      61              : 
      62              :             // Sequential record reader over an open spool file. Never holds
      63              :             // more than one record's bytes in heap.
      64              :             class Reader
      65              :             {
      66              :             public:
      67              :                 // Reads the next length-delimited record into `record`.
      68              :                 // Returns false at end-of-spool or on a read/parse failure;
      69              :                 // Failed() distinguishes the two. A failure poisons the reader.
      70              :                 bool Next(google::protobuf::Message& record);
      71            9 :                 bool Failed() const { return m_failed; }
      72              :                 // True when the reader reached a clean EOF SHORT of the record
      73              :                 // count the entry was committed with — the file was truncated
      74              :                 // at a record boundary (or emptied), which framing alone
      75              :                 // cannot distinguish from a legitimate end-of-spool.
      76            4 :                 bool Truncated() const { return !m_failed && m_recordsRead < m_expectedRecords; }
      77            5 :                 std::uint64_t RecordsRead() const { return m_recordsRead; }
      78            3 :                 std::uint64_t ExpectedRecords() const { return m_expectedRecords; }
      79              : 
      80              :             private:
      81              :                 friend class StreamSpoolCache;
      82              :                 std::ifstream m_stream;
      83              :                 std::uint64_t m_recordsRead = 0;
      84              :                 std::uint64_t m_expectedRecords = 0;
      85              :                 bool m_failed = false;
      86              :             };
      87              : 
      88              :             // Append-only record writer over a spool file. Commit() publishes
      89              :             // the file for warm serving; Abort() deletes it. An uncommitted
      90              :             // writer aborts in its destructor.
      91              :             class Writer
      92              :             {
      93              :             public:
      94           15 :                 Writer() = default;
      95              :                 ~Writer();
      96              :                 Writer(Writer&& other) noexcept;
      97              :                 Writer& operator=(Writer&& other) noexcept;
      98              : 
      99              :                 // Appends one length-delimited record. Returns false on I/O or
     100              :                 // serialization failure (the writer is poisoned afterwards).
     101              :                 bool Append(const google::protobuf::Message& record);
     102              : 
     103              :                 // Flushes, closes, and publishes the spool entry. Returns
     104              :                 // false when the flush/close failed (e.g. ENOSPC surfaced only
     105              :                 // at flush time) — the incomplete file is deleted instead of
     106              :                 // published; the already-delivered cold response stands.
     107              :                 bool Commit();
     108              :                 // Closes and deletes the spool file without publishing.
     109              :                 void Abort();
     110              : 
     111              :                 std::uint64_t BytesWritten() const { return m_bytesWritten; }
     112              :                 std::uint64_t RecordsWritten() const { return m_recordsWritten; }
     113              :                 bool OpenForWrite() const { return m_openForWrite; }
     114              : 
     115              :             private:
     116              :                 friend class StreamSpoolCache;
     117              :                 void Close(bool commit);
     118              : 
     119              :                 std::ofstream m_stream;
     120              :                 std::filesystem::path m_path;
     121              :                 StreamSpoolCache* m_pCache = nullptr;
     122              :                 std::string m_designName;
     123              :                 std::uint64_t m_generation = 0;
     124              :                 std::uint64_t m_bytesWritten = 0;
     125              :                 std::uint64_t m_recordsWritten = 0;
     126              :                 bool m_openForWrite = false;
     127              :                 bool m_committed = false;
     128              :                 bool m_publishSucceeded = false;
     129              :             };
     130              : 
     131              :             // True (and fills `readerOut`) when a spool valid for (name,
     132              :             // generation) exists and opens. A stale entry is dropped (its file
     133              :             // deleted). False when no valid spool exists: cold fill required.
     134              :             bool TryOpenReader(const std::string& designName, std::uint64_t generation, Reader& readerOut);
     135              : 
     136              :             // Opens a fresh spool file for (name, generation). Returns false
     137              :             // when the spool directory is unusable (caller serves the stream
     138              :             // without spooling).
     139              :             bool BeginWrite(const std::string& designName, std::uint64_t generation, Writer& writerOut);
     140              : 
     141              :             // Drops the design's spool entry (and file), if any.
     142              :             void Drop(const std::string& designName);
     143              : 
     144              :             // Path-guarded Drop for call sites that observed an entry outside
     145              :             // m_mutex (e.g. after a lock-free is_regular_file probe on a
     146              :             // captured path): removes the entry only if it still refers to the
     147              :             // observed spool file. Paths are unique per fill (generation + pid
     148              :             // + fillId), so neither a different-generation re-publish nor a
     149              :             // same-generation last-committer-wins fill is ever dropped instead
     150              :             // of the stale entry.
     151              :             void DropStaleEntry(const std::string& designName, const std::filesystem::path& expectedPath);
     152              : 
     153              :             // Counters (observability/tests).
     154              :             std::uint64_t WarmOpens() const;
     155              :             std::uint64_t TotalSpoolBytes() const;
     156              :             std::size_t EntryCount() const;
     157              : 
     158              :         private:
     159              :             struct Entry
     160              :             {
     161              :                 std::filesystem::path path;
     162              :                 std::uint64_t generation = 0;
     163              :                 std::uint64_t bytes = 0;
     164              :                 std::uint64_t records = 0;
     165              :                 std::uint64_t lastUsed = 0;
     166              :             };
     167              : 
     168              :             void InitializeDirectory(const std::filesystem::path& directory, bool ownsDirectory, std::uint64_t maxTotalBytes);
     169              :             std::filesystem::path MakeSpoolPath(const std::string& designName, std::uint64_t generation, std::uint64_t fillId) const;
     170              :             // Returns false when the entry was refused (individually over
     171              :             // spool_max_bytes — file deleted, nothing published).
     172              :             bool PublishEntry(const std::string& designName, const Entry& entry);
     173              :             void EvictOverBudgetLocked(const std::string& protectedName);
     174              : 
     175              :             mutable std::mutex m_mutex;
     176              :             std::filesystem::path m_directory;
     177              :             bool m_ownsDirectory = false;
     178              :             std::uint64_t m_maxTotalBytes = 0;
     179              :             std::uint64_t m_totalBytes = 0;
     180              :             std::uint64_t m_warmOpens = 0;
     181              :             std::uint64_t m_useCounter = 0;
     182              :             std::map<std::string, Entry> m_entriesByName;
     183              :             bool m_usable = false;
     184              :         };
     185              :     }
     186              : }
        

Generated by: LCOV version 2.0-1