store_api/logstore.rs
1// Copyright 2023 Greptime Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! LogStore APIs.
16
17pub mod entry;
18pub mod provider;
19
20use std::collections::HashMap;
21use std::pin::Pin;
22
23use common_error::ext::ErrorExt;
24use entry::Entry;
25use futures::Stream;
26
27pub type SendableEntryStream<'a, I, E> = Pin<Box<dyn Stream<Item = Result<Vec<I>, E>> + Send + 'a>>;
28
29pub use crate::logstore::entry::Id as EntryId;
30use crate::logstore::provider::Provider;
31use crate::storage::RegionId;
32
33/// `LogStore` serves as a Write-Ahead-Log for storage engine.
34#[async_trait::async_trait]
35pub trait LogStore: Send + Sync + 'static + std::fmt::Debug {
36 type Error: ErrorExt + Send + Sync + 'static;
37
38 /// Returns regions whose retained WAL is under storage pressure and may be
39 /// released by flushing. This is an advisory snapshot, not permission to
40 /// flush or delete entries. The caller checks the current region state and
41 /// uses [`Self::obsolete`] only after persisting its data.
42 ///
43 /// Implementations inspect local metadata without I/O. Backends without
44 /// pressure-driven flushing return no candidates.
45 fn flush_candidates(&self) -> Vec<RegionId> {
46 Vec::new()
47 }
48
49 /// Stops components of the logstore.
50 async fn stop(&self) -> Result<(), Self::Error>;
51
52 /// Appends a batch of entries and returns a response containing a map where the key is a region id
53 /// while the value is the id of the last successfully written entry of the region.
54 async fn append_batch(&self, entries: Vec<Entry>) -> Result<AppendBatchResponse, Self::Error>;
55
56 /// Creates a new `EntryStream` to asynchronously generates `Entry` with ids
57 /// starting from `id`.
58 async fn read(
59 &self,
60 provider: &Provider,
61 id: EntryId,
62 ) -> Result<SendableEntryStream<'static, Entry, Self::Error>, Self::Error>;
63
64 /// Creates a new `Namespace` from the given ref.
65 async fn create_namespace(&self, ns: &Provider) -> Result<(), Self::Error>;
66
67 /// Deletes an existing `Namespace` specified by the given ref.
68 async fn delete_namespace(&self, ns: &Provider) -> Result<(), Self::Error>;
69
70 /// Lists all existing namespaces.
71 async fn list_namespaces(&self) -> Result<Vec<Provider>, Self::Error>;
72
73 /// Marks all entries with ids `<=entry_id` of the given `namespace` as obsolete,
74 /// so that the log store can safely delete those entries. This method does not guarantee
75 /// that the obsolete entries are deleted immediately.
76 async fn obsolete(
77 &self,
78 provider: &Provider,
79 region_id: RegionId,
80 entry_id: EntryId,
81 ) -> Result<(), Self::Error>;
82
83 /// Marks all entries of a region as obsolete and removes its dedicated namespace when
84 /// supported by the backend.
85 async fn obsolete_all(
86 &self,
87 provider: &Provider,
88 region_id: RegionId,
89 ) -> Result<(), Self::Error>;
90
91 /// Makes an entry instance of the associated Entry type
92 fn entry(
93 &self,
94 data: Vec<u8>,
95 entry_id: EntryId,
96 region_id: RegionId,
97 provider: &Provider,
98 ) -> Result<Entry, Self::Error>;
99
100 /// Returns the latest entry id in the log store.
101 fn latest_entry_id(&self, provider: &Provider) -> Result<EntryId, Self::Error>;
102
103 /// Waits until every entry of the provider's region with an id at or below
104 /// `entry_id` has the persistence this log store guarantees for an
105 /// acknowledged append, so that a caller can persist `entry_id` as a
106 /// replay watermark.
107 ///
108 /// The default returns at once and keeps each log store's own
109 /// acknowledgement guarantee, whatever it is: Raft Engine with
110 /// `sync_write = false`, for example, acknowledges an append before its
111 /// periodic sync. A log store that acknowledges an append before its
112 /// entries have that persistence overrides this method.
113 async fn wait_durable(
114 &self,
115 _provider: &Provider,
116 _entry_id: EntryId,
117 ) -> Result<(), Self::Error> {
118 Ok(())
119 }
120
121 /// Releases every entry of a region the caller dropped, after `obsolete`
122 /// marked them obsolete, so that the log store keeps none of them even
123 /// across a restart, which never opens the region again to mark its
124 /// entries obsolete.
125 ///
126 /// The default does nothing and keeps each log store's existing handling
127 /// of a dropped region. A log store that keeps obsolete marks only in
128 /// memory overrides this method and returns once the release is durable.
129 async fn release_region(
130 &self,
131 _provider: &Provider,
132 _region_id: RegionId,
133 ) -> Result<(), Self::Error> {
134 Ok(())
135 }
136
137 /// Queues a persistent release of a region's entries through `entry_id`.
138 ///
139 /// The caller must ensure these entries are no longer needed for recovery.
140 /// Success means the store accepted the release, not that it is durable.
141 /// A stopped store may ignore the hint successfully, retaining extra history.
142 /// Implementations may batch records and retry failed writes; a crash before
143 /// persistence may retain extra history. Later entries remain readable.
144 /// The default does nothing, preserving other stores' reclamation policies.
145 async fn release_entries(
146 &self,
147 _provider: &Provider,
148 _region_id: RegionId,
149 _entry_id: EntryId,
150 ) -> Result<(), Self::Error> {
151 Ok(())
152 }
153
154 /// Checks, before an existing region is replayed from its persisted
155 /// state, that the log store holds the region's WAL history through
156 /// `entry_id`, the largest replay watermark the region persisted, so that
157 /// an open against a WAL that lost that history fails instead of
158 /// silently replaying nothing.
159 ///
160 /// The default accepts, which keeps the behaviour of every log store that
161 /// does not override it.
162 async fn check_region_history(
163 &self,
164 _provider: &Provider,
165 _entry_id: EntryId,
166 ) -> Result<(), Self::Error> {
167 Ok(())
168 }
169
170 /// Records that the WAL history of the provider's region starts in this
171 /// log store, as it does for a region created on it, so that
172 /// [`check_region_history`](Self::check_region_history) accepts a later
173 /// open of the region by the same log store.
174 ///
175 /// The default does nothing.
176 fn start_region_history(&self, _provider: &Provider) -> Result<(), Self::Error> {
177 Ok(())
178 }
179
180 /// Streams the entries of `region_id` in `(after, upper]` from the WAL of node `node_id`,
181 /// which shares this log store's storage, without writing to that WAL.
182 ///
183 /// The default returns `None`: the log store cannot read the WAL of another node.
184 async fn read_node(
185 &self,
186 _node_id: u64,
187 _region_id: RegionId,
188 _after: EntryId,
189 _upper: WalReadUpperBound,
190 ) -> Result<Option<SendableEntryStream<'static, Entry, Self::Error>>, Self::Error> {
191 Ok(None)
192 }
193}
194
195/// Upper bound of a WAL range read through [`LogStore::read_node`]. A reported final entry
196/// must be present, whereas a LIST boundary need not contain entries of the region.
197#[derive(Debug, Clone, Copy, PartialEq, Eq)]
198pub enum WalReadUpperBound {
199 /// The durable last entry reported by the source on downgrade.
200 LastEntry(EntryId),
201 /// A conservative bound obtained by listing the source prefix.
202 Listed(EntryId),
203}
204
205impl WalReadUpperBound {
206 /// Returns the bound.
207 pub fn entry_id(self) -> EntryId {
208 match self {
209 Self::LastEntry(id) | Self::Listed(id) => id,
210 }
211 }
212}
213
214/// The response of an `append` operation.
215#[derive(Debug, Default)]
216pub struct AppendResponse {
217 /// The id of the entry appended to the log store.
218 pub last_entry_id: EntryId,
219}
220
221/// The response of an `append_batch` operation.
222#[derive(Debug, Default)]
223pub struct AppendBatchResponse {
224 /// Key: region id (as u64). Value: the id of the last successfully written entry of the region.
225 pub last_entry_ids: HashMap<RegionId, EntryId>,
226}