Various API improvements and instrumentation

Author: Limeth

src/cbor.rs

@@ -71,14 +71,6 @@ impl Equivalent<HashableCborValue> for HashableCborValueRef<'_> {
     }
 }
 
-#[derive(Debug, Error)]
-pub enum DateTimeParseError {
-    #[error("Invalid CBOR type")]
-    InvalidCborType,
-    #[error("Invalid format: {0}")]
-    Format(#[from] chrono::ParseError),
-}
-
 #[derive(Clone, Debug, PartialEq, Default)]
 pub struct Map(IndexMap<HashableCborValue, Value>);
 
@@ -103,38 +95,16 @@ impl Map {
         self.0.shift_remove(&HashableCborValueRef(key))
     }
 
-    pub fn get_date_time(
-        &self,
-        key: impl Into<Value>,
-    ) -> std::result::Result<Option<DateTime<FixedOffset>>, DateTimeParseError> {
-        let Some(value) = self.get(key) else {
-            return Ok(None);
-        };
-        let string = match value {
-            Value::Tag(tag, deref!(Value::Text(string)))
-                if *tag == iana::CborTag::DateTime as u64 =>
-            {
-                string
-            }
-            Value::Text(string) => string,
-            _ => return Err(DateTimeParseError::InvalidCborType),
-        };
-        let date_time = DateTime::parse_from_rfc3339(string)?;
-
-        Ok(Some(date_time))
+    pub fn get_date_time(&self, key: impl Into<Value>) -> Option<DateTime<FixedOffset>> {
+        self.get(key)?.as_datetime()
     }
 
     pub fn insert_date_time<Tz: TimeZone>(
         &mut self,
         key: impl Into<Value>,
         date_time: DateTime<Tz>,
     ) -> Option<Value> {
-        let string = date_time.to_rfc3339();
-        let value = Value::Tag(
-            iana::CborTag::DateTime as u64,
-            Box::new(Value::Text(string)),
-        );
-        self.insert(key, value)
+        self.insert(key, Value::new_datetime(&date_time))
     }
 
     pub fn iter(&self) -> impl Iterator<Item = (&HashableCborValue, &Value)> {
@@ -258,7 +228,7 @@ where
 //     }
 // }
 
-pub(crate) mod iana {
+pub mod iana {
     #[repr(u64)]
     pub enum CborTag {
         DateTime = 0,
@@ -327,9 +297,16 @@ pub(crate) mod iana {
 //     }
 // }
 
-pub trait ValueExt {
+pub trait ValueExt
+where
+    Self: Sized,
+{
     fn canonicalize(&mut self);
     fn is_canonical(&self) -> bool;
+    fn new_datetime(datetime: &DateTime<impl TimeZone>) -> Self;
+    fn is_datetime(&self) -> bool;
+    fn as_datetime(&self) -> Option<DateTime<FixedOffset>>;
+    fn into_datetime(self) -> ::std::result::Result<DateTime<FixedOffset>, Self>;
 }
 
 impl ValueExt for Value {
@@ -385,6 +362,35 @@ impl ValueExt for Value {
             _ => panic!("Unsupported CBOR type."),
         }
     }
+
+    fn new_datetime(datetime: &DateTime<impl TimeZone>) -> Self {
+        Value::Tag(
+            iana::CborTag::DateTime as u64,
+            Box::new(Value::Text(datetime.to_rfc3339())),
+        )
+    }
+
+    fn is_datetime(&self) -> bool {
+        self.as_datetime().is_some()
+    }
+
+    fn as_datetime(&self) -> Option<DateTime<FixedOffset>> {
+        let string = match self {
+            Value::Tag(tag, deref!(Value::Text(string)))
+                if *tag == iana::CborTag::DateTime as u64 =>
+            {
+                string
+            }
+            _ => return None,
+        };
+        let date_time = DateTime::parse_from_rfc3339(string).ok()?;
+
+        Some(date_time)
+    }
+
+    fn into_datetime(self) -> ::std::result::Result<DateTime<FixedOffset>, Self> {
+        self.as_datetime().ok_or(self)
+    }
 }
 
 pub struct AsCanonicalValue<T>(pub PhantomData<T>);

src/lib.rs

@@ -1,5 +1,4 @@
 #![feature(array_windows)]
-#![feature(async_closure)]
 #![feature(deref_patterns)]
 #![feature(fn_traits)]
 #![feature(try_blocks)]

src/record/mod.rs

@@ -1,4 +1,4 @@
-use crate::cbor::{self, DateTimeParseError, TAG_RRR_RECORD};
+use crate::cbor::{self, TAG_RRR_RECORD};
 use crate::crypto::encryption::EncryptionAlgorithm;
 use crate::crypto::signature::SigningKey;
 use crate::error::{Error, IoResultExt, Result};
@@ -8,6 +8,7 @@ use crate::utils::serde::{BytesOrAscii, BytesOrHexString, Secret};
 use async_fd_lock::LockWrite;
 use chrono::{DateTime, FixedOffset, TimeZone};
 use coset::cbor::tag;
+use coset::cbor::value::Integer;
 use derive_more::{Deref, DerefMut};
 use futures::{pin_mut, Stream, StreamExt};
 use itertools::Itertools;
@@ -21,6 +22,7 @@ use segment::{
     RecordVersion, Segment, SegmentEncryption, SegmentMetadata,
 };
 use serde::{Deserialize, Serialize};
+use std::fmt::Display;
 use std::iter;
 use std::ops::{Deref, DerefMut};
 use std::{borrow::Cow, fmt::Debug, io::Cursor};
@@ -54,28 +56,78 @@ impl DerefMut for SuccessionNonce {
     }
 }
 
+#[repr(u64)]
+pub enum RecordMetadataId {
+    CreatedAt = 1,
+}
+
+impl Display for RecordMetadataId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::CreatedAt => write!(f, "Created At"),
+        }
+    }
+}
+
+impl TryFrom<&Integer> for RecordMetadataId {
+    type Error = ();
+
+    fn try_from(value: &Integer) -> std::result::Result<Self, ()> {
+        // Consider using the `num_enum` crate if this becomes cumbersome.
+        let value: u64 = value.clone().try_into().map_err(|_| ())?;
+        Ok(match value {
+            _ if value == Self::CreatedAt as u64 => Self::CreatedAt,
+            _ => return Err(()),
+        })
+    }
+}
+
+impl TryFrom<&cbor::Value> for RecordMetadataId {
+    type Error = ();
+
+    fn try_from(value: &cbor::Value) -> std::result::Result<Self, ()> {
+        let integer = value.as_integer().ok_or(())?;
+
+        Self::try_from(&integer)
+    }
+}
+
+pub enum RecordMetadataKey<'a> {
+    Id(RecordMetadataId),
+    Custom(cbor::HashableCborValueRef<'a>),
+}
+
 /// A CBOR map of metadata.
 #[derive(Clone, Debug, Default, Deref, DerefMut, PartialEq, Serialize, Deserialize)]
 pub struct RecordMetadata(pub cbor::Map);
 
 impl RecordMetadata {
-    pub const KEY_CREATED_AT: u64 = 1;
-
-    pub fn get_created_at(
-        &self,
-    ) -> std::result::Result<Option<DateTime<FixedOffset>>, DateTimeParseError> {
-        self.get_date_time(Self::KEY_CREATED_AT)
+    pub fn get_created_at(&self) -> Option<DateTime<FixedOffset>> {
+        self.get_date_time(RecordMetadataId::CreatedAt as u64)
     }
 
     pub fn insert_created_at<Tz: TimeZone>(
         &mut self,
         date_time: DateTime<Tz>,
     ) -> Option<cbor::Value> {
-        self.insert_date_time(Self::KEY_CREATED_AT, date_time)
+        self.insert_date_time(RecordMetadataId::CreatedAt as u64, date_time)
     }
 
     pub fn shift_remove_created_at(&mut self) -> Option<cbor::Value> {
-        self.shift_remove(Self::KEY_CREATED_AT)
+        self.shift_remove(RecordMetadataId::CreatedAt as u64)
+    }
+
+    pub fn iter_with_semantic_keys<'a>(
+        &'a self,
+    ) -> impl Iterator<Item = (RecordMetadataKey<'a>, &'a cbor::Value)> {
+        self.iter()
+            .map(|(key, value)| match RecordMetadataId::try_from(&key.0) {
+                Ok(id) => (RecordMetadataKey::Id(id), value),
+                Err(()) => (
+                    RecordMetadataKey::Custom(cbor::HashableCborValueRef(&key.0)),
+                    value,
+                ),
+            })
     }
 }
 
@@ -343,6 +395,7 @@ impl Record {
         }
     }
 
+    /// Returns the available record versions, sorted from least to most recent.
     #[instrument(level = Level::TRACE, ret, err)]
     pub async fn list_versions<L>(
         registry: &Registry<L>,

src/registry.rs

@@ -35,7 +35,7 @@ use tokio::{
     io::{AsyncRead, AsyncWrite},
 };
 use tokio_util::io::SyncIoBridge;
-use tracing::warn;
+use tracing::{info, instrument, warn};
 
 pub const BYTES_HASH_PEPPER_RECOMMENDED: usize = 32;
 
@@ -578,6 +578,7 @@ impl<L: FileLock> PartialEq for Registry<L> {
 }
 
 impl Registry<ReadLock> {
+    #[instrument]
     pub async fn open(directory_path: PathBuf) -> Result<Self> {
         let open_options = {
             let mut open_options = File::options();
@@ -595,6 +596,7 @@ impl Registry<ReadLock> {
         })
     }
 
+    #[instrument]
     pub async fn lock_write(self) -> Result<Registry<WriteLock>> {
         let open_options = {
             let mut open_options = File::options();
@@ -616,6 +618,7 @@ impl Registry<ReadLock> {
 }
 
 impl Registry<WriteLock> {
+    #[instrument]
     pub async fn create(
         directory_path: PathBuf,
         config: RegistryConfig,
@@ -683,6 +686,7 @@ impl Registry<WriteLock> {
             .await
     }
 
+    #[instrument]
     pub async fn lock_read(self) -> Result<Registry<ReadLock>> {
         let open_options = {
             let mut open_options = File::options();