src/StoreMeta.h

   1 /*
   2  * Copyright (C) 1996-2017 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_TYPELENGTHVALUE_H
  10 #define SQUID_TYPELENGTHVALUE_H
  11
  12 class StoreEntry;
  13
  14 // WTF?
  15 typedef class StoreMeta tlv;
  16
  17 /**
  18  \ingroup SwapStoreAPI
  19  \todo AYJ: for critical lists like this we should use A=64,B=65 etc to enforce and reserve values.
  20  \note NOTE!  We must preserve the order of this list!
  21  *
  22  \section StoreSwapMeta Store "swap meta" Description
  23  \par
  24  * "swap meta" refers to a section of meta data stored at the beginning
  25  * of an object that is stored on disk.  This meta data includes information
  26  * such as the object's cache key (MD5), URL, and part of the StoreEntry
  27  * structure.
  28  *
  29  \par
  30  * The meta data is stored using a TYPE-LENGTH-VALUE format.  That is,
  31  * each chunk of meta information consists of a TYPE identifier, a
  32  * LENGTH field, and then the VALUE (which is LENGTH octets long).
  33  */
  34 enum {
  35     /**
  36      * Just a placeholder for the zeroth value. It is never used on disk.
  37      */
  38     STORE_META_VOID,
  39
  40     /**
  41      \deprecated
  42      * This represents the case when we use the URL as the cache
  43      * key, as Squid-1.1 does.  Currently we don't support using
  44      * a URL as a cache key, so this is not used.
  45      */
  46     STORE_META_KEY_URL,
  47
  48     /**
  49      \deprecated
  50      * For a brief time we considered supporting SHA (secure
  51      * hash algorithm) as a cache key.  Nobody liked it, and
  52      * this type is not currently used.
  53      */
  54     STORE_META_KEY_SHA,
  55
  56     /**
  57      * This represents the MD5 cache key that Squid currently uses.
  58      * When Squid opens a disk file for reading, it can check that
  59      * this MD5 matches the MD5 of the user's request.  If not, then
  60      * something went wrong and this is probably the wrong object.
  61      */
  62     STORE_META_KEY_MD5,
  63
  64     /**
  65      * The object's URL.  This also may be matched against a user's
  66      *  request for cache hits to make sure we got the right object.
  67      */
  68     STORE_META_URL,
  69
  70     /**
  71      * This is the "standard metadata" for an object.
  72      * Really its just this middle chunk of the StoreEntry structure:
  73      \code
  74         time_t timestamp;
  75         time_t lastref;
  76         time_t expires;
  77         time_t lastmod;
  78         uint64_t swap_file_sz;
  79         uint16_t refcount;
  80         uint16_t flags;
  81      \endcode
  82      */
  83     STORE_META_STD,
  84
  85     /**
  86      * Reserved for future hit-metering (RFC 2227) stuff
  87      */
  88     STORE_META_HITMETERING,
  89
  90     /// \todo DOCS: document.
  91     STORE_META_VALID,
  92
  93     /**
  94      * Stores Vary request headers
  95      */
  96     STORE_META_VARY_HEADERS,
  97
  98     /**
  99      * Updated version of STORE_META_STD, with support for  >2GB objects.
 100      * As STORE_META_STD except that the swap_file_sz is a 64-bit integer instead of 32-bit.
 101      */
 102     STORE_META_STD_LFS,
 103
 104     STORE_META_OBJSIZE,
 105
 106     STORE_META_STOREURL,    /* the store url, if different to the normal URL */
 107     STORE_META_VARY_ID,     /* Unique ID linking variants */
 108     STORE_META_END
 109 };
 110
 111 /// \ingroup SwapStoreAPI
 112 class StoreMeta
 113 {
 114 protected:
 115     StoreMeta() : length(-1), value(nullptr), next(nullptr) { }
 116     StoreMeta(const StoreMeta &);
 117     StoreMeta& operator=(const StoreMeta &);
 118
 119 public:
 120     static bool validType(char);
 121     static int const MaximumTLVLength;
 122     static int const MinimumTLVLength;
 123     static StoreMeta *Factory(char type, size_t len, void const *value);
 124     static StoreMeta **Add(StoreMeta **tail, StoreMeta *aNode);
 125     static void FreeList(StoreMeta **head);
 126
 127     virtual char getType() const = 0;
 128     virtual bool validLength(int) const;
 129     virtual bool checkConsistency(StoreEntry *) const;
 130     virtual ~StoreMeta() {}
 131
 132     int length;
 133     void *value;
 134     tlv *next;
 135 };
 136
 137 /// \ingroup SwapStoreAPI
 138 char *storeSwapMetaPack(tlv * tlv_list, int *length);
 139 /// \ingroup SwapStoreAPI
 140 tlv *storeSwapMetaBuild(StoreEntry * e);
 141 /// \ingroup SwapStoreAPI
 142 void storeSwapTLVFree(tlv * n);
 143
 144 #endif /* SQUID_TYPELENGTHVALUE_H */
 145