src/Notes.h

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