Notes.h

Go to the documentation of this file.

/*
 * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */
 
#ifndef SQUID_SRC_NOTES_H
#define SQUID_SRC_NOTES_H
 
#include "acl/forward.h"
#include "base/RefCount.h"
#include "format/Format.h"
#include "mem/forward.h"
#include "sbuf/forward.h"
#include "SquidString.h"
 
#include <iosfwd>
#include <optional>
#include <string>
#include <vector>
 
class HttpRequest;
class HttpReply;
class AccessLogEntry;
class NotePairs;
 
typedef RefCount<AccessLogEntry> AccessLogEntryPointer;
typedef RefCount<NotePairs> NotePairsPointer;
 
class Note: public RefCountable
{
public:
    typedef RefCount<Note> Pointer;
 
    class Value: public RefCountable
    {
    public:
        typedef RefCount<Value> Pointer;
        friend class Note;
 
        enum Method { mhReplace, mhAppend };
 
        Value(const char *aVal, const bool quoted, const char *descr, const Method method = mhReplace);
        ~Value() override;
        Value(const Value&) = delete;
        Value &operator=(const Value&) = delete;
 
        Method method() const { return theMethod; }
        const SBuf &value() const { return theValue; }
 
        ACLList *aclList; 
 
    private:
        const SBuf &format(const AccessLogEntryPointer &al);
 
        Format::Format *valueFormat; 
        SBuf theValue; 
        SBuf theFormattedValue;
        Method theMethod;
    };
    typedef std::vector<Value::Pointer> Values;
 
    Note(const char *aKey, const size_t keyLen): theKey(aKey, keyLen) {}
    explicit Note(const SBuf aKey): theKey(aKey) {}
    Note(const Note&) = delete;
    Note &operator=(const Note&) = delete;
 
    Value::Pointer addValue(const char *value, const bool quoted, const char *descr,
                            const Value::Method m = Value::mhAppend);
 
    bool match(HttpRequest *request, HttpReply *reply, const AccessLogEntryPointer &al, SBuf &matched);
    const SBuf &key() const { return theKey; }
    void updateNotePairs(NotePairsPointer pairs, const CharacterSet *delimiters, const AccessLogEntryPointer &al);
 
    void printAsNoteDirective(StoreEntry *, const char *directiveName) const;
 
    void printAsAnnotationAclParameters(std::ostream &) const;
 
private:
    SBuf theKey; 
    Values values; 
};
 
class ConfigParser;
 
class Notes : public RefCountable
{
public:
    typedef RefCount<Notes> Pointer;
    typedef std::vector<SBuf> Keys; 
    typedef std::vector<Note::Pointer> NotesList;
    typedef NotesList::iterator iterator; 
    typedef NotesList::const_iterator const_iterator; 
 
    explicit Notes(const char *aDescr, const Keys *extraReservedKeys = nullptr, bool allowFormatted = true);
    Notes() = default;
    ~Notes() override { notes.clear(); }
    Notes(const Notes&) = delete;
    Notes &operator=(const Notes&) = delete;
 
    Note::Pointer parse(ConfigParser &parser);
 
    void parseKvPair();
 
    void printAsNoteDirectives(StoreEntry *, const char *directiveName) const;
 
    void clean() { notes.clear(); }
 
    iterator begin() { return notes.begin(); }
    iterator end() { return notes.end(); }
    bool empty() const { return notes.empty(); }
 
    void printAsAnnotationAclParameters(std::ostream &) const;
 
    void updateNotePairs(NotePairsPointer pairs, const CharacterSet *delimiters,
                         const AccessLogEntryPointer &al);
private:
    void banReservedKey(const SBuf &key, const Keys &banned) const;
 
    void validateKey(const SBuf &key) const;
 
    Note::Pointer add(const SBuf &noteKey);
    Note::Pointer find(const SBuf &noteKey);
 
    NotesList notes; 
    const char *descr = nullptr; 
 
    Keys reservedKeys; 
    bool formattedValues = false; 
 
    static const Notes::Keys &ReservedKeys(); 
};
 
class NotePairs: public RefCountable
{
public:
    typedef RefCount<NotePairs> Pointer;
 
    class Entry : public RefCountable
    {
        MEMPROXY_CLASS(Entry);
    public:
        typedef RefCount<Entry> Pointer;
 
        Entry(const SBuf &aKey, const SBuf &aValue)
            : theName(aKey), theValue(aValue) {}
        Entry(const char *aKey, const char *aValue)
            : theName(aKey), theValue(aValue) {}
        Entry(const Entry &) = delete;
        Entry &operator=(const Entry &) = delete;
 
        const SBuf &name() const { return theName; }
        const SBuf &value() const { return theValue; }
 
    private:
        SBuf theName;
        SBuf theValue;
    };
    typedef std::vector<Entry::Pointer> Entries;      
    typedef std::vector<SBuf> Names;
 
    NotePairs() {}
    NotePairs &operator=(NotePairs const &) = delete;
    NotePairs(NotePairs const &) = delete;
 
    void append(const NotePairs *src);
 
    void replaceOrAddOrAppend(const NotePairs *src, const Names &appendables);
 
    void replaceOrAdd(const NotePairs *src);
 
    void appendNewOnly(const NotePairs *src);
 
    std::optional<SBuf> find(const char *noteKey, const char *sep = ",") const;
 
    const char *findFirst(const char *noteKey) const;
 
    void add(const SBuf &key, const SBuf &value);
    void add(const char *key, const char *value);
 
    void remove(const char *key);
    void remove(const SBuf &key);
 
    void addStrList(const SBuf &key, const SBuf &values, const CharacterSet &delimiters);
 
    bool hasPair(const SBuf &key, const SBuf &value) const;
 
    void print(std::ostream &os, const char *nameValueSeparator, const char *entryTerminator) const;
 
    bool empty() const {return entries.empty();}
 
    void clear() { entries.clear(); }
 
    const Entries &expandListEntries(const CharacterSet *delimiters) const;
 
private:
    Entries entries; 
};
 
#endif /* SQUID_SRC_NOTES_H */