src/StoreSwapLogData.h

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