src/Notes.h

   1 #ifndef SQUID_NOTES_H
   2 #define SQUID_NOTES_H
   3
   4 #include "acl/forward.h"
   5 #include "base/RefCount.h"
   6 #include "CbDataList.h"
   7 #include "format/Format.h"
   8 #include "MemPool.h"
   9 #include "SquidString.h"
  10 #include "typedefs.h"
  11
  12 #include <string>
  13 #include <vector>
  14
  15 class HttpRequest;
  16 class HttpReply;
  17 typedef RefCount<AccessLogEntry> AccessLogEntryPointer;
  18
  19 /**
  20  * Used to store a note configuration. The notes are custom key:value
  21  * pairs ICAP request headers or ECAP options used to pass
  22  * custom transaction-state related meta information to squid
  23  * internal subsystems or to adaptation services.
  24  */
  25 class Note: public RefCountable
  26 {
  27 public:
  28     typedef RefCount<Note> Pointer;
  29     /// Stores a value for the note.
  30     class Value: public RefCountable
  31     {
  32     public:
  33         typedef RefCount<Value> Pointer;
  34         String value; ///< Configured annotation value, possibly with %macros
  35         ACLList *aclList; ///< The access list used to determine if this value is valid for a request
  36         /// Compiled annotation value format
  37         Format::Format *valueFormat;
  38         explicit Value(const String &aVal) : value(aVal), aclList(NULL), valueFormat(NULL) {}
  39         ~Value();
  40     };
  41     typedef std::vector<Value::Pointer> Values;
  42
  43     explicit Note(const String &aKey): key(aKey) {}
  44
  45     /**
  46      * Adds a value to the note and returns a  pointer to the
  47      * related Value object.
  48      */
  49     Value::Pointer addValue(const String &value);
  50
  51     /**
  52      * Walks through the  possible values list of the note and selects
  53      * the first value which matches the given HttpRequest and HttpReply
  54      * or NULL if none matches.
  55      * If an AccessLogEntry given and Value::valueFormat is not null, the
  56      * formatted value returned.
  57      */
  58     const char *match(HttpRequest *request, HttpReply *reply, const AccessLogEntryPointer &al);
  59
  60     String key; ///< The note key
  61     Values values; ///< The possible values list for the note
  62 };
  63
  64 class ConfigParser;
  65 /**
  66  * Used to store a notes configuration list.
  67  */
  68 class Notes
  69 {
  70 public:
  71     typedef std::vector<Note::Pointer> NotesList;
  72     typedef NotesList::iterator iterator; ///< iterates over the notes list
  73     typedef NotesList::const_iterator const_iterator; ///< iterates over the notes list
  74
  75     Notes(const char *aDescr, const char **metasBlacklist, bool allowFormatted = false): descr(aDescr), blacklisted(metasBlacklist), formattedValues(allowFormatted) {}
  76     Notes(): descr(NULL), blacklisted(NULL) {}
  77     ~Notes() { notes.clear(); }
  78     /**
  79      * Parse a notes line and returns a pointer to the
  80      * parsed Note object.
  81      */
  82     Note::Pointer parse(ConfigParser &parser);
  83     /**
  84      * Dump the notes list to the given StoreEntry object.
  85      */
  86     void dump(StoreEntry *entry, const char *name);
  87     void clean(); /// clean the notes list
  88
  89     /// points to the first argument
  90     iterator begin() { return notes.begin(); }
  91     /// points to the end of list
  92     iterator end() { return notes.end(); }
  93     /// return true if the notes list is empty
  94     bool empty() { return notes.empty(); }
  95
  96     NotesList notes; ///< The Note::Pointer objects array list
  97     const char *descr; ///< A short description for notes list
  98     const char **blacklisted; ///< Null terminated list of blacklisted note keys
  99     bool formattedValues; ///< Whether the formatted values are supported
 100
 101 private:
 102     /**
 103      * Adds a note to the notes list and returns a pointer to the
 104      * related Note object. If the note key already exists in list,
 105      * returns a pointer to the existing object.
 106      */
 107     Note::Pointer add(const String &noteKey);
 108 };
 109
 110 /**
 111  * Used to store list of notes
 112  */
 113 class NotePairs: public RefCountable
 114 {
 115 public:
 116     typedef RefCount<NotePairs> Pointer;
 117
 118     /**
 119      * Used to store a note key/value pair.
 120      */
 121     class Entry
 122     {
 123     public:
 124         Entry(const char *aKey, const char *aValue): name(aKey), value(aValue) {}
 125         String name;
 126         String value;
 127         MEMPROXY_CLASS(Entry);
 128     };
 129
 130     NotePairs() {}
 131     ~NotePairs();
 132
 133     /**
 134      * Append the entries of the src NotePairs list to our list.
 135      */
 136     void append(const NotePairs *src);
 137
 138     /**
 139      * Append any new entries of the src NotePairs list to our list.
 140      * Entries which already exist in the destination set are ignored.
 141      */
 142     void appendNewOnly(const NotePairs *src);
 143
 144     /**
 145      * Returns a comma separated list of notes with key 'noteKey'.
 146      * Use findFirst instead when a unique kv-pair is needed.
 147      */
 148     const char *find(const char *noteKey, const char *sep = ",") const;
 149
 150     /**
 151      * Returns the first note value for this key or an empty string.
 152      */
 153     const char *findFirst(const char *noteKey) const;
 154
 155     /**
 156      * Adds a note key and value to the notes list.
 157      * If the key name already exists in list, add the given value to its set
 158      * of values.
 159      */
 160     void add(const char *key, const char *value);
 161
 162     /**
 163      * Adds a note key and values strList to the notes list.
 164      * If the key name already exists in list, add the new values to its set
 165      * of values.
 166      */
 167     void addStrList(const char *key, const char *values);
 168
 169     /**
 170      * Return true if the key/value pair is already stored
 171      */
 172     bool hasPair(const char *key, const char *value) const;
 173
 174     /**
 175      * Convert NotePairs list to a string consist of "Key: Value"
 176      * entries separated by sep string.
 177      */
 178     const char *toString(const char *sep = "\r\n") const;
 179
 180     /**
 181      * True if there are not entries in the list
 182      */
 183     bool empty() const {return entries.empty();}
 184
 185     std::vector<NotePairs::Entry *> entries;      ///< The key/value pair entries
 186
 187 private:
 188     NotePairs &operator = (NotePairs const &); // Not implemented
 189     NotePairs(NotePairs const &); // Not implemented
 190 };
 191
 192 MEMPROXY_CLASS_INLINE(NotePairs::Entry);
 193
 194 class AccessLogEntry;
 195 /**
 196  * Keep in sync HttpRequest and the corresponding AccessLogEntry objects
 197  */
 198 NotePairs &SyncNotes(AccessLogEntry &ale, HttpRequest &request);
 199
 200 #endif