bneradt commented on code in PR #13603:
URL: https://github.com/apache/trafficserver/pull/13603#discussion_r4050734427
##########
doc/developer-guide/cache-architecture/architecture.en.rst:
##########
@@ -483,6 +483,47 @@ default). Objects which are in use when the write cursor
is near use the same
underlying evacuation mechanism but are handled automatically and not via the
explicit ``pinned`` bit in :cpp:class:`Dir`.
+Object Versioning
+-----------------
+
+Every ``Doc`` records the cache format version that wrote it, in its
``v_major``
+and ``v_minor`` fields, taken from ``CACHE_DB_MAJOR_VERSION`` and
+``CACHE_DB_MINOR_VERSION`` in ``iocore/cache/CacheDefs.h``.
+
+Bumping the minor version does not clear the cache. Stripe validation looks
only
+at the major version, and the current reader still reads every object written
at
+an older minor version. What the bump buys is protection in the other
direction:
+a reader rejects any object newer than itself and refetches it, rather than
+misreading a shape it does not understand.
+
+Reading an older object sometimes needs work that reading a current one does
+not. Compare against **the fixed version at which that part of the format
+changed**, never against ``CACHE_DB_VERSION``. The latter silently changes
+meaning at the next bump, and sends every object the previous release wrote
down
+the wrong path. ``CACHE_DB_FRAG_OFFSET_TABLE_VERSION`` is such a fixed point.
+
+Well-Known Strings
+------------------
+
+A marshalled header stores indexes into the well-known string table
+(``proxy/hdrs/HdrToken.cc``) beside the strings those indexes stand for: the
+index of every MIME field name, of the request method, and of the request URL
+scheme, plus the presence bits and slot accelerators derived from them. Change
+the table and every stored index denotes a different string.
+
+The strings are in the object too, so the indexes are only a cache over them.
+``HTTPInfo::unmarshal()`` rebuilds all of it through
+``HTTPHdrImpl::recompute_wks_indices()`` before anything reads the header,
+unconditionally rather than on a version test, since an object written by a
+same-version build with a different table needs the same treatment as an older
+one. The ``CacheAltMagic`` check keeps this to once per marshalled buffer, on a
+read that already paid for disk I/O or a RAM-cache decompression.
+
+The table is therefore free to change without invalidating anyone's cache. The
Review Comment:
Qualified in 98f47635ca. The documentation now explicitly limits this to WKS
index/cardinality changes and explains that persisted m_cooked_stuff is not
reconstructed; recognized Cache-Control directives and cooked masks require a
separate compatibility decision. The documentation build passes.
##########
include/iocore/cache/CacheDefs.h:
##########
@@ -37,13 +37,35 @@ enum class CacheInitState : int {
#define CACHE_ALT_INDEX_DEFAULT -1
#define CACHE_ALT_REMOVED -2
+// Bumping the minor version does not clear anyone's cache: stripe validation
looks only at the
+// major version, and this build still reads every object written at an older
minor version. What
+// it does mean is that an ATS older than this treats the objects this build
writes as corrupt and
+// refetches them, so bump it whenever an object gains a shape an older ATS
would misread.
+//
+// 24.2 marshalled the fragment offset table in full; see
CACHE_DB_FRAG_OFFSET_TABLE_VERSION below.
+// 24.3 stopped trusting the well-known string indexes stored in an object and
started rebuilding
+// them from the header strings stored alongside them, in
HTTPHdrImpl::recompute_wks_indices().
+// That is what frees the well-known string table in proxy/hdrs/HdrToken.cc to
change: any ATS at
+// 24.3 or newer reads objects written against any table, and anything older
refuses them outright
+// rather than resolving their indexes against the wrong table.
static const uint8_t CACHE_DB_MAJOR_VERSION = 24;
-static const uint8_t CACHE_DB_MINOR_VERSION = 2;
+static const uint8_t CACHE_DB_MINOR_VERSION = 3;
Review Comment:
Fixed in 98f47635ca. The tool now shares the server version constants,
accepts supported 24.3 metadata, selects the fragment-table layout by object
version, and consumes WKS identity trailers. A new CTest covers supported and
future stripe versions. I also exercised the offline decoder against the WKS
AuTest cache: four 24.3 metadata records and five cached alternates decoded
successfully.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
