src/StoreSwapLogData.h

   1 /*
   2  * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_SRC_STORESWAPLOGDATA_H
  10 #define SQUID_SRC_STORESWAPLOGDATA_H
  11
  12 /**
  13  \defgroup FileFormatSwapStateAPI swap.state File Structure
  14  \ingroup FileSystems
  15  \section ImplementationNotes Implementation Notes
  16  \par
  17  *      When writing an object to disk, we must first write the meta data.
  18  *      Store::PackSwapMeta() serializes that meta data
  19  *      into a character buffer that we can write.
  20  *
  21  \note  MemObject has a MemObject::swap_hdr_sz.
  22  *      This value is the size of that character buffer; the size of the
  23  *      swap file meta data.  The StoreEntry has a member
  24  *      StoreEntry::swap_file_sz that represents the size of the disk file.
  25  *      Thus, the size of the object "content" is
  26  \code    StoreEntry->swap_file_sz  - MemObject->swap_hdr_sz;    \endcode
  27  \note The swap file content includes the HTTP reply headers and the HTTP reply body (if any).
  28  *
  29  \par
  30  *      When reading a swap file, Store::Unpack*SwapMeta*() functions iterate
  31  *      over stored swap meta data header fields and also extract
  32  *      the value for MemObject->swap_hdr_sz.
  33  */
  34
  35 #include "md5.h"
  36 #include "mem/forward.h"
  37 #include "store/forward.h"
  38
  39 /// maintains a 24-bit checksum over integer fields
  40 class SwapChecksum24
  41 {
  42 public:
  43     SwapChecksum24() { raw[0] = raw[1] = raw[2] = 0; }
  44
  45     bool operator ==(const SwapChecksum24 &o) const {
  46         return raw[0] == o.raw[0] && raw[1] == o.raw[1] && raw[2] == o.raw[2];
  47     }
  48
  49     bool operator !=(const SwapChecksum24 &o) const {
  50         return !(*this == o);
  51     }
  52
  53     /// compute and store checksum based on three 32bit integers
  54     void set(uint32_t f1, uint32_t f2, uint32_t f3);
  55
  56     /// compute and store checksum based on int32_t and uint64_t integers
  57     void set(int32_t f1, uint64_t f2);
  58
  59     // printing for debugging
  60     std::ostream &print(std::ostream &os) const;
  61
  62 private:
  63     uint8_t raw[3]; // designed to follow "op" members, in padding space
  64 };
  65
  66 inline std::ostream &
  67 operator <<(std::ostream &os, const SwapChecksum24 &sum)
  68 {
  69     return sum.print(os);
  70 }
  71
  72 /**
  73  \ingroup FielFormatSwapStateAPI
  74  *
  75  \par
  76  * Defines the structure of a binary swap.state file entry for UFS stores.
  77  * TODO: Move to fs/ufs
  78  *
  79  \note StoreSwapLogData entries are written in native machine byte order
  80  *     They are not necessarily portable across architectures.
  81  */
  82 class StoreSwapLogData
  83 {
  84     MEMPROXY_CLASS(StoreSwapLogData);
  85
  86 public:
  87     /// type to use for storing time-related members; must be signed
  88     typedef int64_t SwappedTime;
  89
  90     /// consistency self-check: whether the data appears to make sense
  91     bool sane() const;
  92
  93     /// call this before storing the log entry
  94     void finalize();
  95
  96     /**
  97      * Either SWAP_LOG_ADD when an object is added to the disk storage,
  98      * or SWAP_LOG_DEL when an object is deleted.
  99      */
 100     uint8_t op = 0;
 101
 102     /**
 103      * Fingerprint to weed out bogus/corrupted swap.state entries.
 104      */
 105     SwapChecksum24 checksum; // follows "op" because compiler will pad anyway
 106
 107     /**
 108      * The 32-bit file number which maps to a pathname.
 109      * Only the low 24-bits are relevant. The high 8-bits are
 110      * used as an index to an array of storage directories, and
 111      * are set at run time because the order of storage directories
 112      * may change over time.
 113      */
 114     sfileno swap_filen = 0;
 115
 116     /**
 117      * A Unix time value that represents the time when
 118      * the origin server generated this response. If the response
 119      * has a valid Date: header, this timestamp corresponds
 120      * to that time. Otherwise, it is set to the Squid process time
 121      * when the response is read (as soon as the end of headers are found).
 122      */
 123     SwappedTime timestamp = 0;
 124
 125     /**
 126      * The last time that a client requested this object.
 127      */
 128     SwappedTime lastref = 0;
 129
 130     /**
 131      * The value of the response's Expires: header, if any.
 132      * If the response does not have an Expires: header, this
 133      * is set to -1.
 134      * If the response has an invalid (unparsable)
 135      * Expires: header, it is also set to -1.  There are some cases
 136      * where Squid sets expires to -2. This happens for the
 137      * internal "netdb" object and for FTP URL responses.
 138      */
 139     SwappedTime expires = 0;
 140
 141     /**
 142      * The value of the response's Last-modified: header, if any.
 143      * This is set to -1 if there is no Last-modified: header,
 144      * or if it is unparsable.
 145      */
 146     SwappedTime lastmod = 0;
 147
 148     /**
 149      * This is the number of bytes that the object occupies on
 150      * disk. It includes the Squid "swap file header".
 151      */
 152     uint64_t swap_file_sz = 0;
 153
 154     /**
 155      * The number of times that this object has been accessed (referenced).
 156      * Since its a 16-bit quantity, it is susceptible to overflow
 157      * if a single object is accessed 65,536 times before being replaced.
 158      */
 159     uint16_t refcount;
 160
 161     /**
 162      * A copy of the StoreEntry flags field. Used as a sanity
 163      * check when rebuilding the cache at startup. Objects that
 164      * have the KEY_PRIVATE flag set are not added back to the cache.
 165      */
 166     uint16_t flags = 0;
 167
 168     /**
 169      * The 128-bit MD5 hash for this object.
 170      */
 171     unsigned char key[SQUID_MD5_DIGEST_LENGTH] = {};
 172 };
 173
 174 /// \ingroup FileFormatSwapStateAPI
 175 /// Swap log starts with this binary structure.
 176 class StoreSwapLogHeader
 177 {
 178 public:
 179     // sets default values for this Squid version; loaded values may differ
 180     StoreSwapLogHeader();
 181
 182     /// consistency self-check: whether the data appears to make sense
 183     bool sane() const;
 184
 185     /// number of bytes after the log header before the first log entry
 186     size_t gapSize() const;
 187
 188     uint8_t op;
 189     SwapChecksum24 checksum; // follows "op" because compiler will pad anyway
 190     int32_t version;
 191     int32_t record_size;
 192 };
 193
 194 #endif /* SQUID_SRC_STORESWAPLOGDATA_H */
 195