dbwrapper.h

Go to the documentation of this file.

// Copyright (c) 2012-present The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
#ifndef BITCOIN_DBWRAPPER_H
#define BITCOIN_DBWRAPPER_H
 
#include <attributes.h>
#include <serialize.h>
#include <span.h>
#include <streams.h>
#include <util/byte_units.h>
#include <util/check.h>
#include <util/expected.h>
#include <util/fs.h>
#include <util/not_null.h>
#include <util/obfuscation.h>
 
#include <cstddef>
#include <cstdint>
#include <exception>
#include <memory>
#include <optional>
#include <span>
#include <stdexcept>
#include <string>
 
namespace leveldb {
class Env;
} // namespace leveldb
 
inline constexpr size_t DBWRAPPER_PREALLOC_KEY_SIZE = 64;
inline constexpr size_t DBWRAPPER_PREALLOC_VALUE_SIZE = 1024;
inline constexpr size_t DBWRAPPER_MAX_FILE_SIZE{32_MiB};
 
struct DBOptions {
    bool force_compact = false;
};
 
struct DBParams {
    fs::path path;
    uint64_t cache_bytes;
    bool memory_only = false;
    bool wipe_data = false;
    bool obfuscate = false;
    bool bloom_filter = true;
    DBOptions options{};
    leveldb::Env* testing_env = nullptr;
    size_t max_file_size = DBWRAPPER_MAX_FILE_SIZE;
};
 
class dbwrapper_error : public std::runtime_error
{
public:
    explicit dbwrapper_error(const std::string& msg) : std::runtime_error(msg) {}
};
 
class CDBWrapper;
 
namespace dbwrapper_private {
 
const Obfuscation& GetObfuscation(const CDBWrapper&);
}; // namespace dbwrapper_private
 
bool DestroyDB(const std::string& path_str);
 
class CDBBatch
{
    friend class CDBWrapper;
 
private:
    const CDBWrapper &parent;
 
    struct WriteBatchImpl;
    const std::unique_ptr<WriteBatchImpl> m_impl_batch;
 
    DataStream m_key_scratch{};
    DataStream m_value_scratch{};
 
    void WriteImpl(std::span<const std::byte> key, DataStream& value);
    void EraseImpl(std::span<const std::byte> key);
 
public:
    explicit CDBBatch(const CDBWrapper& _parent);
    ~CDBBatch();
    void Clear();
 
    template <typename K, typename V>
    void Write(const K& key, const V& value)
    {
        ScopedDataStreamUsage scoped_key{m_key_scratch}, scoped_value{m_value_scratch};
        m_key_scratch << key;
        m_value_scratch << value;
        WriteImpl(m_key_scratch, m_value_scratch);
    }
 
    template <typename K>
    void Erase(const K& key)
    {
        ScopedDataStreamUsage scoped_key{m_key_scratch};
        m_key_scratch << key;
        EraseImpl(m_key_scratch);
    }
 
    size_t ApproximateSize() const;
};
 
class CDBIterator
{
public:
    struct IteratorImpl;
 
private:
    const CDBWrapper &parent;
    const std::unique_ptr<IteratorImpl> m_impl_iter;
    DataStream m_scratch{};
 
    void SeekImpl(std::span<const std::byte> key);
    std::span<const std::byte> GetKeyImpl() const;
    std::span<const std::byte> GetValueImpl() const;
 
public:
 
    CDBIterator(const CDBWrapper& _parent, std::unique_ptr<IteratorImpl> _piter);
    ~CDBIterator();
 
    bool Valid() const;
 
    void SeekToFirst();
 
    template<typename K> void Seek(const K& key) {
        ScopedDataStreamUsage scoped_scratch{m_scratch};
        m_scratch << key;
        SeekImpl(m_scratch);
    }
 
    void Next();
 
    template<typename K> bool GetKey(K& key) {
        try {
            SpanReader ssKey{GetKeyImpl()};
            ssKey >> key;
        } catch (const std::exception&) {
            return false;
        }
        return true;
    }
 
    template<typename V> bool GetValue(V& value) {
        try {
            ScopedDataStreamUsage scoped_scratch{m_scratch};
            m_scratch.write(GetValueImpl());
            dbwrapper_private::GetObfuscation(parent)(m_scratch);
            m_scratch >> value;
        } catch (const std::exception&) {
            return false;
        }
        return true;
    }
};
 
struct LevelDBContext;
 
class CDBWrapper
{
    friend const Obfuscation& dbwrapper_private::GetObfuscation(const CDBWrapper&);
private:
    util::NotNullUniquePtr<LevelDBContext> m_db_context;
 
    std::string m_name;
 
    Obfuscation m_obfuscation;
 
    inline static const std::string OBFUSCATION_KEY{"\000obfuscate_key", 14}; // explicit size to avoid truncation at leading \0
 
    std::optional<std::string> ReadImpl(std::span<const std::byte> key) const;
    bool ExistsImpl(std::span<const std::byte> key) const;
    size_t EstimateSizeImpl(std::span<const std::byte> key1, std::span<const std::byte> key2) const;
    auto& DBContext() const LIFETIMEBOUND { return *m_db_context; }
 
public:
    CDBWrapper(const DBParams& params);
    ~CDBWrapper();
 
    CDBWrapper(const CDBWrapper&) = delete;
    CDBWrapper& operator=(const CDBWrapper&) = delete;
 
    struct ReadFailure {
        enum class Code {
            DeserializationError,   
            DatabaseError,          
        };
 
        Code status;
        std::string err_msg;
    };
 
    using ReadStatus = util::Expected<bool, ReadFailure>;
 
    template <typename K, typename V>
    [[nodiscard]] ReadStatus TryRead(const K& key, V& value) const
    {
        DataStream ssKey{};
        ssKey.reserve(DBWRAPPER_PREALLOC_KEY_SIZE);
        // Key serialization is the only operation that may throw.
        // Callers are expected to provide well-formed keys.
        ssKey << key;
 
        std::optional<std::string> strValue;
        try {
            strValue = ReadImpl(ssKey);
            if (!strValue) {
                return false; // not found
            }
        } catch (const std::exception& e) {
            return util::Unexpected(ReadFailure{ReadFailure::Code::DatabaseError, e.what()});
        }
 
        try {
            std::span ssValue{MakeWritableByteSpan(*strValue)};
            m_obfuscation(ssValue);
            SpanReader{ssValue} >> value;
        } catch (const std::exception& e) {
            return util::Unexpected(ReadFailure{ReadFailure::Code::DeserializationError, e.what()});
        }
 
        return true;
    }
 
    template <typename K, typename V>
    bool Read(const K& key, V& value) const
    {
        const ReadStatus res = TryRead(key,value);
        if (res.has_value()) return res.value();
        switch (const auto& [err_code, err_msg] = res.error(); err_code) {
            case ReadFailure::Code::DeserializationError: return false;
            case ReadFailure::Code::DatabaseError: throw dbwrapper_error(err_msg);
        } // no default case, so the compiler can warn about missing cases
        std::abort(); // unreachable
    }
 
    template <typename K, typename V>
    void Write(const K& key, const V& value, bool fSync = false)
    {
        CDBBatch batch(*this);
        batch.Write(key, value);
        WriteBatch(batch, fSync);
    }
 
    template <typename K>
    bool Exists(const K& key) const
    {
        DataStream ssKey{};
        ssKey.reserve(DBWRAPPER_PREALLOC_KEY_SIZE);
        ssKey << key;
        return ExistsImpl(ssKey);
    }
 
    template <typename K>
    void Erase(const K& key, bool fSync = false)
    {
        CDBBatch batch(*this);
        batch.Erase(key);
        WriteBatch(batch, fSync);
    }
 
    void WriteBatch(CDBBatch& batch, bool fSync = false);
 
    void CompactFull();
 
    std::optional<std::string> GetProperty(const std::string& property) const;
 
    // Get an estimate of LevelDB memory usage (in bytes).
    size_t DynamicMemoryUsage() const;
 
    CDBIterator* NewIterator();
 
    bool IsEmpty();
 
    static bool HasKeyStartingWith(const fs::path& path, uint8_t prefix);
 
    template<typename K>
    size_t EstimateSize(const K& key_begin, const K& key_end) const
    {
        DataStream ssKey1{}, ssKey2{};
        ssKey1.reserve(DBWRAPPER_PREALLOC_KEY_SIZE);
        ssKey2.reserve(DBWRAPPER_PREALLOC_KEY_SIZE);
        ssKey1 << key_begin;
        ssKey2 << key_end;
        return EstimateSizeImpl(ssKey1, ssKey2);
    }
};
 
#endif // BITCOIN_DBWRAPPER_H