foundationdb/directory/
mod.rs

1// Copyright 2018 foundationdb-rs developers, https://github.com/Clikengo/foundationdb-rs/graphs/contributors
2// Copyright 2013-2018 Apple, Inc and the FoundationDB project authors.
3//
4// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
5// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
6// http://opensource.org/licenses/MIT>, at your option. This file may not be
7// copied, modified, or distributed except according to those terms.
8
9//! Directory provides a tool for managing related subspaces.
10//!
11//! The FoundationDB API provides directories as a tool for managing related Subspaces.
12//! For general guidance on directory usage, see the discussion in the [Developer Guide](https://apple.github.io/foundationdb/developer-guide.html#directories).
13//!
14//! Directories are identified by hierarchical paths analogous to the paths in a Unix-like file system.
15//! A path is represented as a slice of strings. Each directory has an associated subspace used to
16//! store its content. The directory layer maps each path to a short prefix used for the
17//! corresponding subspace. In effect, directories provide a level of indirection for access to subspaces.
18//! Directory operations are transactional.
19//!
20//! It is a direct backport of the [Flow implementation](https://github.com/apple/foundationdb/tree/master/bindings/flow).
21//!
22//! Examples:
23//!
24//! ```rust
25//! use futures::prelude::*;
26//! use foundationdb::directory::Directory;
27//!
28//! async fn async_main() -> foundationdb::FdbResult<()> {
29//!     let db = foundationdb::Database::default()?;
30//!
31//!     // creates a transaction
32//!     let trx = db.create_trx()?;
33//!
34//!     // creates a directory
35//!     let directory = foundationdb::directory::DirectoryLayer::default();
36//!
37//!     let path = vec![String::from("my-awesome-app"), String::from("my-awesome-user")];
38//!
39//!     // use the directory to create a subspace to use
40//!     let content_subspace = directory.create_or_open(
41//!         // the transaction used to read/write the directory.
42//!         &trx,
43//!         // the path used, which can view as a UNIX path like `/app/my-app`.
44//!         &path,
45//!         // do not use any custom prefix or layer
46//!         None, None,
47//!     ).await;
48//!     assert_eq!(true, content_subspace.is_ok());
49//!
50//!     // Don't forget to commit your transaction to persist the subspace
51//!     trx.commit().await?;
52//!
53//!     Ok(())
54//! }
55//!
56//! foundationdb::boot().expect("failed to initialize FoundationDB");
57//! futures::executor::block_on(async_main()).expect("failed to run");
58//! ```
59
60mod directory_layer;
61mod directory_partition;
62mod directory_subspace;
63mod error;
64mod node;
65
66use crate::Transaction;
67use crate::tuple::{PackResult, Subspace, TuplePack, TupleUnpack};
68use async_trait::async_trait;
69use core::cmp;
70pub use directory_layer::DirectoryLayer;
71pub use directory_partition::DirectoryPartition;
72pub use directory_subspace::DirectorySubspace;
73pub use error::DirectoryError;
74use std::cmp::Ordering;
75
76/// `Directory` represents a subspace of keys in a FoundationDB database, identified by a hierarchical path.
77///
78/// # Warning: Hanging on Network/DNS failures
79///
80/// Directory operations are transactional and rely on the [`Transaction`] passed to them.
81/// By default, the FoundationDB C API will retry indefinitely if it cannot reach the cluster
82/// or if DNS resolution fails. This can cause directory operations to hang forever.
83/// To prevent this, you should set [`crate::options::DatabaseOption::TransactionTimeout`] or
84/// [`crate::options::DatabaseOption::TransactionRetryLimit`] on the [`crate::Database`] object, or
85/// [`crate::options::TransactionOption::Timeout`] or [`crate::options::TransactionOption::RetryLimit`] on the transaction
86/// itself.
87#[async_trait]
88pub trait Directory {
89    /// Creates or opens the subdirectory of this Directory located at path (creating parent directories, if necessary).
90    ///
91    /// # Warning
92    ///
93    /// Creating several paths with the same prefix **concurrently** within the same transaction
94    /// is unsafe and may race. Serial calls (fully awaiting each `create_or_open` before issuing
95    /// the next) within the same transaction are safe. Alternatively, use separate transactions.
96    /// See [this link](https://github.com/apple/foundationdb/issues/895#issuecomment-436704180) for context.
97    async fn create_or_open(
98        &self,
99        txn: &Transaction,
100        path: &[String],
101        prefix: Option<&[u8]>,
102        layer: Option<&[u8]>,
103    ) -> Result<DirectoryOutput, DirectoryError>;
104
105    /// Creates a subdirectory of this Directory located at path (creating parent directories if necessary).
106    ///
107    /// # Warning
108    ///
109    /// Creating several paths with the same prefix **concurrently** within the same transaction
110    /// is unsafe and may race. Serial calls (fully awaiting each `create` before issuing the
111    /// next) within the same transaction are safe. Alternatively, use separate transactions.
112    /// See [this link](https://github.com/apple/foundationdb/issues/895#issuecomment-436704180) for context.
113    async fn create(
114        &self,
115        txn: &Transaction,
116        path: &[String],
117        prefix: Option<&[u8]>,
118        layer: Option<&[u8]>,
119    ) -> Result<DirectoryOutput, DirectoryError>;
120
121    /// Opens the subdirectory of this Directory located at path.
122    async fn open(
123        &self,
124        txn: &Transaction,
125        path: &[String],
126        layer: Option<&[u8]>,
127    ) -> Result<DirectoryOutput, DirectoryError>;
128
129    /// Checks if the subdirectory of this Directory located at path exists.
130    async fn exists(&self, trx: &Transaction, path: &[String]) -> Result<bool, DirectoryError>;
131
132    /// Moves this Directory to the specified newAbsolutePath.
133    async fn move_directory(
134        &self,
135        trx: &Transaction,
136        new_path: &[String],
137    ) -> Result<DirectoryOutput, DirectoryError>;
138
139    /// Moves the subdirectory of this Directory located at oldpath to newpath.
140    async fn move_to(
141        &self,
142        trx: &Transaction,
143        old_path: &[String],
144        new_path: &[String],
145    ) -> Result<DirectoryOutput, DirectoryError>;
146
147    /// Removes the subdirectory of this Directory located at path and all of its subdirectories, as well as all of their contents.
148    async fn remove(&self, trx: &Transaction, path: &[String]) -> Result<bool, DirectoryError>;
149
150    /// Removes the subdirectory of this Directory located at path (if the path exists) and all of its subdirectories, as well as all of their contents.
151    async fn remove_if_exists(
152        &self,
153        trx: &Transaction,
154        path: &[String],
155    ) -> Result<bool, DirectoryError>;
156
157    /// List the subdirectories of this directory at a given subpath.
158    async fn list(&self, trx: &Transaction, path: &[String])
159    -> Result<Vec<String>, DirectoryError>;
160}
161
162pub(crate) fn compare_slice<T: Ord>(a: &[T], b: &[T]) -> cmp::Ordering {
163    for (ai, bi) in a.iter().zip(b.iter()) {
164        match ai.cmp(bi) {
165            Ordering::Equal => continue,
166            ord => return ord,
167        }
168    }
169
170    // if every single element was equal, compare length
171    a.len().cmp(&b.len())
172}
173
174/// DirectoryOutput represents the different output of a Directory.
175#[derive(Clone, Debug)]
176pub enum DirectoryOutput {
177    /// Under classic usage, you will obtain an `DirectorySubspace`
178    DirectorySubspace(DirectorySubspace),
179    /// You can open an `DirectoryPartition` by using the "partition" layer
180    DirectoryPartition(DirectoryPartition),
181}
182
183impl DirectoryOutput {
184    pub fn subspace<T: TuplePack>(&self, t: &T) -> Result<Subspace, DirectoryError> {
185        match self {
186            DirectoryOutput::DirectorySubspace(d) => Ok(d.subspace(t)),
187            DirectoryOutput::DirectoryPartition(_) => {
188                Err(DirectoryError::CannotOpenDirectoryPartition)
189            }
190        }
191    }
192
193    pub fn bytes(&self) -> Result<&[u8], DirectoryError> {
194        match self {
195            DirectoryOutput::DirectorySubspace(d) => Ok(d.bytes()),
196            DirectoryOutput::DirectoryPartition(_) => {
197                Err(DirectoryError::CannotOpenDirectoryPartition)
198            }
199        }
200    }
201
202    pub fn pack<T: TuplePack>(&self, t: &T) -> Result<Vec<u8>, DirectoryError> {
203        match self {
204            DirectoryOutput::DirectorySubspace(d) => Ok(d.pack(t)),
205            DirectoryOutput::DirectoryPartition(_) => {
206                Err(DirectoryError::CannotPackDirectoryPartition)
207            }
208        }
209    }
210
211    pub fn unpack<'de, T: TupleUnpack<'de>>(
212        &self,
213        key: &'de [u8],
214    ) -> Result<PackResult<T>, DirectoryError> {
215        match self {
216            DirectoryOutput::DirectorySubspace(d) => Ok(d.unpack(key)),
217            DirectoryOutput::DirectoryPartition(_) => {
218                Err(DirectoryError::CannotPackDirectoryPartition)
219            }
220        }
221    }
222
223    pub fn range(&self) -> Result<(Vec<u8>, Vec<u8>), DirectoryError> {
224        match self {
225            DirectoryOutput::DirectorySubspace(d) => Ok(d.range()),
226            DirectoryOutput::DirectoryPartition(_) => {
227                Err(DirectoryError::CannotRangeDirectoryPartition)
228            }
229        }
230    }
231
232    pub fn get_path(&self) -> &[String] {
233        match self {
234            DirectoryOutput::DirectorySubspace(d) => d.get_path(),
235            DirectoryOutput::DirectoryPartition(d) => d.get_path(),
236        }
237    }
238
239    pub fn get_layer(&self) -> &[u8] {
240        match self {
241            DirectoryOutput::DirectorySubspace(d) => d.get_layer(),
242            DirectoryOutput::DirectoryPartition(d) => d.get_layer(),
243        }
244    }
245}
246
247#[async_trait]
248impl Directory for DirectoryOutput {
249    async fn create_or_open(
250        &self,
251        txn: &Transaction,
252        path: &[String],
253        prefix: Option<&[u8]>,
254        layer: Option<&[u8]>,
255    ) -> Result<DirectoryOutput, DirectoryError> {
256        match self {
257            DirectoryOutput::DirectorySubspace(d) => {
258                d.create_or_open(txn, path, prefix, layer).await
259            }
260            DirectoryOutput::DirectoryPartition(d) => {
261                d.create_or_open(txn, path, prefix, layer).await
262            }
263        }
264    }
265
266    async fn create(
267        &self,
268        txn: &Transaction,
269        path: &[String],
270        prefix: Option<&[u8]>,
271        layer: Option<&[u8]>,
272    ) -> Result<DirectoryOutput, DirectoryError> {
273        match self {
274            DirectoryOutput::DirectorySubspace(d) => d.create(txn, path, prefix, layer).await,
275            DirectoryOutput::DirectoryPartition(d) => d.create(txn, path, prefix, layer).await,
276        }
277    }
278
279    async fn open(
280        &self,
281        txn: &Transaction,
282        path: &[String],
283        layer: Option<&[u8]>,
284    ) -> Result<DirectoryOutput, DirectoryError> {
285        match self {
286            DirectoryOutput::DirectorySubspace(d) => d.open(txn, path, layer).await,
287            DirectoryOutput::DirectoryPartition(d) => d.open(txn, path, layer).await,
288        }
289    }
290
291    async fn exists(&self, trx: &Transaction, path: &[String]) -> Result<bool, DirectoryError> {
292        match self {
293            DirectoryOutput::DirectorySubspace(d) => d.exists(trx, path).await,
294            DirectoryOutput::DirectoryPartition(d) => d.exists(trx, path).await,
295        }
296    }
297
298    async fn move_directory(
299        &self,
300        trx: &Transaction,
301        new_path: &[String],
302    ) -> Result<DirectoryOutput, DirectoryError> {
303        match self {
304            DirectoryOutput::DirectorySubspace(d) => d.move_directory(trx, new_path).await,
305            DirectoryOutput::DirectoryPartition(d) => d.move_directory(trx, new_path).await,
306        }
307    }
308
309    async fn move_to(
310        &self,
311        trx: &Transaction,
312        old_path: &[String],
313        new_path: &[String],
314    ) -> Result<DirectoryOutput, DirectoryError> {
315        match self {
316            DirectoryOutput::DirectorySubspace(d) => d.move_to(trx, old_path, new_path).await,
317            DirectoryOutput::DirectoryPartition(d) => d.move_to(trx, old_path, new_path).await,
318        }
319    }
320
321    async fn remove(&self, trx: &Transaction, path: &[String]) -> Result<bool, DirectoryError> {
322        match self {
323            DirectoryOutput::DirectorySubspace(d) => d.remove(trx, path).await,
324            DirectoryOutput::DirectoryPartition(d) => d.remove(trx, path).await,
325        }
326    }
327
328    async fn remove_if_exists(
329        &self,
330        trx: &Transaction,
331        path: &[String],
332    ) -> Result<bool, DirectoryError> {
333        match self {
334            DirectoryOutput::DirectorySubspace(d) => d.remove_if_exists(trx, path).await,
335            DirectoryOutput::DirectoryPartition(d) => d.remove_if_exists(trx, path).await,
336        }
337    }
338
339    async fn list(
340        &self,
341        trx: &Transaction,
342        path: &[String],
343    ) -> Result<Vec<String>, DirectoryError> {
344        match self {
345            DirectoryOutput::DirectorySubspace(d) => d.list(trx, path).await,
346            DirectoryOutput::DirectoryPartition(d) => d.list(trx, path).await,
347        }
348    }
349}
350
351// Strinc returns the first key that would sort outside the range prefixed by prefix.
352pub(crate) fn strinc(key: Vec<u8>) -> Vec<u8> {
353    let mut key = key;
354
355    for i in (0..key.len()).rev() {
356        if key[i] != 0xff {
357            key[i] += 1;
358            break;
359        } else {
360            // stripping key from trailing 0xFF bytes
361            key.remove(i);
362        }
363    }
364    key
365}
366
367#[cfg(test)]
368mod tests {
369    use super::*;
370
371    // https://github.com/apple/foundationdb/blob/e34df983ee8c0db333babf36fb620318d026553d/bindings/c/test/unit/unit_tests.cpp#L95
372    #[test]
373    fn test_strinc() {
374        assert_eq!(strinc(Vec::from("a".as_bytes())), Vec::from("b".as_bytes()));
375        assert_eq!(strinc(Vec::from("y".as_bytes())), Vec::from("z".as_bytes()));
376        assert_eq!(
377            strinc(Vec::from("!".as_bytes())),
378            Vec::from("\"".as_bytes())
379        );
380        assert_eq!(strinc(Vec::from("*".as_bytes())), Vec::from("+".as_bytes()));
381        assert_eq!(
382            strinc(Vec::from("fdb".as_bytes())),
383            Vec::from("fdc".as_bytes())
384        );
385        assert_eq!(
386            strinc(Vec::from("foundation database 6".as_bytes())),
387            Vec::from("foundation database 7".as_bytes())
388        );
389
390        assert_eq!(strinc(vec![61u8, 62u8, 255u8]), vec![61u8, 63u8]);
391        assert_eq!(strinc(vec![253u8, 255u8]), vec![254u8]);
392        assert_eq!(strinc(vec![253u8, 255u8, 255u8]), vec![254u8]);
393        assert_eq!(strinc(vec![255u8, 255u8, 255u8]), Vec::<u8>::new());
394    }
395}