1// Copyright (c) 2012-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_DBWRAPPER_H
6#define BITCOIN_DBWRAPPER_H
7
8#include <attributes.h>
9#include <serialize.h>
10#include <span.h>
11#include <streams.h>
12#include <util/byte_units.h>
13#include <util/check.h>
14#include <util/expected.h>
15#include <util/fs.h>
16#include <util/obfuscation.h>
17
18#include <cstddef>
19#include <cstdint>
20#include <exception>
21#include <memory>
22#include <optional>
23#include <span>
24#include <stdexcept>
25#include <string>
26
27namespace leveldb {
28class Env;
29} // namespace leveldb
30
31inline constexpr size_t DBWRAPPER_PREALLOC_KEY_SIZE = 64;
32inline constexpr size_t DBWRAPPER_PREALLOC_VALUE_SIZE = 1024;
33inline constexpr size_t DBWRAPPER_MAX_FILE_SIZE{32_MiB};
34
35//! User-controlled performance and debug options.
36struct DBOptions {
37    //! Compact database on startup.
38    bool force_compact = false;
39};
40
41//! Application-specific storage settings.
42struct DBParams {
43    //! Location in the filesystem where leveldb data will be stored.
44    fs::path path;
45    //! Configures various leveldb cache settings.
46    uint64_t cache_bytes;
47    //! If true, use leveldb's memory environment.
48    bool memory_only = false;
49    //! If true, remove all existing data.
50    bool wipe_data = false;
51    //! If true, store data obfuscated via simple XOR. If false, XOR with a
52    //! zero'd byte array.
53    bool obfuscate = false;
54    //! If true, build a LevelDB bloom filter to accelerate point lookups.
55    bool bloom_filter = true;
56    //! Passed-through options.
57    DBOptions options{};
58    //! If non-null, use this as the leveldb::Env instead of the default.
59    //! Caller retains ownership.
60    leveldb::Env* testing_env = nullptr;
61    //! Maximum LevelDB SST file size. Larger values reduce the frequency
62    //! of compactions but increase their duration.
63    size_t max_file_size = DBWRAPPER_MAX_FILE_SIZE;
64};
65
66class dbwrapper_error : public std::runtime_error
67{
68public:
69    explicit dbwrapper_error(const std::string& msg) : std::runtime_error(msg) {}
70};
71
72class CDBWrapper;
73
74/** These should be considered an implementation detail of the specific database.
75 */
76namespace dbwrapper_private {
77
78/** Work around circular dependency, as well as for testing in dbwrapper_tests.
79 * Database obfuscation should be considered an implementation detail of the
80 * specific database.
81 */
82const Obfuscation& GetObfuscation(const CDBWrapper&);
83}; // namespace dbwrapper_private
84
85bool DestroyDB(const std::string& path_str);
86
87/** Batch of changes queued to be written to a CDBWrapper */
88class CDBBatch
89{
90    friend class CDBWrapper;
91
92private:
93    const CDBWrapper &parent;
94
95    struct WriteBatchImpl;
96    const std::unique_ptr<WriteBatchImpl> m_impl_batch;
97
98    DataStream m_key_scratch{};
99    DataStream m_value_scratch{};
100
101    void WriteImpl(std::span<const std::byte> key, DataStream& value);
102    void EraseImpl(std::span<const std::byte> key);
103
104public:
105    /**
106     * @param[in] _parent   CDBWrapper that this batch is to be submitted to
107     */
108    explicit CDBBatch(const CDBWrapper& _parent);
109    ~CDBBatch();
110    void Clear();
111
112    template <typename K, typename V>
113    void Write(const K& key, const V& value)
114    {
115        ScopedDataStreamUsage scoped_key{m_key_scratch}, scoped_value{m_value_scratch};
116        m_key_scratch << key;
117        m_value_scratch << value;
118        WriteImpl(m_key_scratch, m_value_scratch);
119    }
120
121    template <typename K>
122    void Erase(const K& key)
123    {
124        ScopedDataStreamUsage scoped_key{m_key_scratch};
125        m_key_scratch << key;
126        EraseImpl(m_key_scratch);
127    }
128
129    size_t ApproximateSize() const;
130};
131
132class CDBIterator
133{
134public:
135    struct IteratorImpl;
136
137private:
138    const CDBWrapper &parent;
139    const std::unique_ptr<IteratorImpl> m_impl_iter;
140    DataStream m_scratch{};
141
142    void SeekImpl(std::span<const std::byte> key);
143    std::span<const std::byte> GetKeyImpl() const;
144    std::span<const std::byte> GetValueImpl() const;
145
146public:
147
148    /**
149     * @param[in] _parent          Parent CDBWrapper instance.
150     * @param[in] _piter           The original leveldb iterator.
151     */
152    CDBIterator(const CDBWrapper& _parent, std::unique_ptr<IteratorImpl> _piter);
153    ~CDBIterator();
154
155    bool Valid() const;
156
157    void SeekToFirst();
158
159    template<typename K> void Seek(const K& key) {
160        ScopedDataStreamUsage scoped_scratch{m_scratch};
161        m_scratch << key;
162        SeekImpl(m_scratch);
163    }
164
165    void Next();
166
167    template<typename K> bool GetKey(K& key) {
168        try {
169            SpanReader ssKey{GetKeyImpl()};
170            ssKey >> key;
171        } catch (const std::exception&) {
172            return false;
173        }
174        return true;
175    }
176
177    template<typename V> bool GetValue(V& value) {
178        try {
179            ScopedDataStreamUsage scoped_scratch{m_scratch};
180            m_scratch.write(GetValueImpl());
181            dbwrapper_private::GetObfuscation(parent)(m_scratch);
182            m_scratch >> value;
183        } catch (const std::exception&) {
184            return false;
185        }
186        return true;
187    }
188};
189
190struct LevelDBContext;
191
192class CDBWrapper
193{
194    friend const Obfuscation& dbwrapper_private::GetObfuscation(const CDBWrapper&);
195private:
196    //! holds all leveldb-specific fields of this class
197    std::unique_ptr<LevelDBContext> m_db_context;
198
199    //! the name of this database
200    std::string m_name;
201
202    //! optional XOR-obfuscation of the database
203    Obfuscation m_obfuscation;
204
205    //! obfuscation key storage key, null-prefixed to avoid collisions
206    inline static const std::string OBFUSCATION_KEY{"\000obfuscate_key", 14}; // explicit size to avoid truncation at leading \0
207
208    std::optional<std::string> ReadImpl(std::span<const std::byte> key) const;
209    bool ExistsImpl(std::span<const std::byte> key) const;
210    size_t EstimateSizeImpl(std::span<const std::byte> key1, std::span<const std::byte> key2) const;
211    auto& DBContext() const LIFETIMEBOUND { return *Assert(m_db_context); }
212
213public:
214    CDBWrapper(const DBParams& params);
215    ~CDBWrapper();
216
217    CDBWrapper(const CDBWrapper&) = delete;
218    CDBWrapper& operator=(const CDBWrapper&) = delete;
219
220    struct ReadFailure {
221        enum class Code {
222            DeserializationError,   //!< Key exists but value could not be deserialized.
223            DatabaseError,          //!< Unexpected internal DB error.
224        };
225
226        Code status;
227        std::string err_msg;
228    };
229
230    using ReadStatus = util::Expected<bool, ReadFailure>;
231
232    /**
233     * Read and deserialize a value from the database, with explicit error discrimination.
234     *
235     * Unlike Read(), this method distinguishes between a missing key, a deserialization
236     * failure (DeserializationError), and an internal DB error (DatabaseError),
237     * enabling callers to treat data corruption differently from an absent entry.
238     *
239     * @note Callers are expected to provide well-formed keys; key serialization
240     *       is the only operation that may throw.
241     *
242     * @param[in]  key    The key to look up.
243     * @param[out] value  Populated with the deserialized value when the returned
244     *                    Expected holds true; indeterminate otherwise.
245     * @return On success, true if the key was found (value populated) or false if
246     *         the key was absent. On failure, a ReadFailure describing the error.
247     */
248    template <typename K, typename V>
249    [[nodiscard]] ReadStatus TryRead(const K& key, V& value) const
250    {