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 : }
|