src/Notes.h

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