1 /*
2  * Copyright (C) 1996-2021 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:
StoreMeta()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;
~StoreMeta()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 
146