blob: 884af2d14f1d9c2ff763120732167113e77325c0 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
#pragma once
#include <cstdint>
#include <optional>
#include <string>
#include <vector>
/**
* @file IStorageBackend.h
* @brief Abstract KV storage backend consumed by CursorManager.
*
* Storage is strictly content-addressed: every value is stored under its
* SHA256 hex digest. This mirrors the Sakura physical layer in which the
* key is always `Sha256.to_hex (Sha256.string serialized_bytes)` and the
* value is the raw serialized bytes.
*
* Relation membership (which tuple hashes belong to a given relation) is
* tracked via a separate index managed by LinkTuple / TupleHashes. This
* corresponds to Sakura's B+ tree of tuple hashes stored under each relation.
*/
namespace nt
{
/**
* @interface IStorageBackend
* @brief Contract between CursorManager and a physical (or mock) storage engine.
*
* Storage is strictly content-addressed: every value lives under its own
* SHA256 digest. Relation membership is tracked separately via
* LinkTuple / TupleHashes, mirroring Sakura's per-relation B+ tree.
*/
class IStorageBackend
{
public:
virtual ~IStorageBackend() = default;
/**
* @brief Stores a serialized value and returns its SHA256 hex hash.
*
* Idempotent: storing the same bytes twice does not create a duplicate.
* The hash is the only valid key for subsequent Get calls.
*/
virtual std::string Put(std::vector<uint8_t> value) = 0;
/**
* @brief Retrieves bytes by their SHA256 hex hash.
* @return The stored bytes, or std::nullopt when the hash is unknown.
*/
virtual std::optional<std::vector<uint8_t>> Get(const std::string& hash) = 0;
/**
* @brief Records that a tuple (by hash) belongs to a relation (by path).
*
* Idempotent. Corresponds to appending a tuple hash to a relation's
* B+ tree in Sakura's physical layer.
*/
virtual void LinkTuple(const std::vector<std::string>& relation_path,
const std::string& tuple_hash) = 0;
/**
* @brief Returns a page of tuple hashes for a relation.
*
* Pagination is tuple-level: @p offset and @p limit count whole tuples.
* Hashes are returned in insertion order.
*
* @param relation_path Logical relation path.
* @param offset Zero-based index of the first tuple to return.
* @param limit Maximum number of tuple hashes to return.
* @return Ordered list of SHA256 hex hashes. Empty when past the end.
*/
virtual std::vector<std::string> TupleHashes(
const std::vector<std::string>& relation_path,
std::size_t offset,
std::size_t limit) = 0;
};
}
|
