Skip to main content

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}