io-m2dir 0.2.0

M2dir client library for Rust
Documentation 
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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

//! Entry-level m2dir coroutines and their shared types.
//!
//! An entry is a single message file inside an m2dir, named
//! `<date>,<checksum>.<nonce>` per the specification. This module holds
//! the [`M2dirEntry`] handle and its companions, shared by the store,
//! get, list and delete coroutines below.

pub mod delete;
pub mod get;
pub mod list;
pub mod store;

use alloc::{string::String, vec::Vec};

use thiserror::Error;

use crate::{flag::M2dirFlags, path::M2dirPath};

/// Errors that can occur while parsing or validating an entry
/// filename.
#[derive(Clone, Debug, Error)]
pub enum M2dirEntryParseError {
    /// The given path is not a regular file.
    #[error("path {0} is not a regular file")]
    NotFile(M2dirPath),
    /// The path has no final filename component.
    #[error("path {0} is missing a filename")]
    MissingFilename(M2dirPath),
    /// The filename does not match the m2dir specification.
    #[error("entry {path} does not match filename spec: {reason}")]
    InvalidFilename {
        path: M2dirPath,
        reason: &'static str,
    },
    /// The checksum embedded in the filename does not match the file
    /// contents.
    #[error("invalid checksum for {path}: expected {expected:?}, got {got:?}")]
    InvalidChecksum {
        path: M2dirPath,
        expected: String,
        got: String,
    },
}

/// A single entry inside an [`M2dir`](crate::m2dir::M2dir).
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct M2dirEntry {
    id: String,
    path: M2dirPath,
}

impl M2dirEntry {
    /// Builds an [`M2dirEntry`] from a path and its unique id without
    /// checking the on-disk checksum. Used by coroutines that have
    /// just delivered the entry and trust their own checksum.
    pub fn from_parts(id: impl Into<String>, path: impl Into<M2dirPath>) -> Self {
        Self {
            id: id.into(),
            path: path.into(),
        }
    }

    /// Returns the path to the entry file.
    pub fn path(&self) -> &M2dirPath {
        &self.path
    }

    /// Returns the unique identifier of the entry (the
    /// `<checksum>.<nonce>` portion of the filename).
    pub fn id(&self) -> &str {
        &self.id
    }

    /// Returns the checksum portion of the id (the chunk before the
    /// last `.`).
    pub fn checksum(&self) -> &str {
        self.id.rsplit_once('.').map(|(c, _)| c).unwrap_or(&self.id)
    }
}

/// An [`M2dirEntry`] paired with its file contents and flags metadata.
///
/// Produced by the bulk reads on
/// [`M2dirClient`](crate::client::M2dirClient), which fetch an entry's
/// bytes and its `.flags` sidecar in one pass.
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct M2dirFullEntry {
    entry: M2dirEntry,
    contents: Vec<u8>,
    flags: M2dirFlags,
}

impl M2dirFullEntry {
    /// Builds a full entry from its resolved handle, file contents and
    /// flags set.
    pub fn from_parts(entry: M2dirEntry, contents: Vec<u8>, flags: M2dirFlags) -> Self {
        Self {
            entry,
            contents,
            flags,
        }
    }

    /// Returns the underlying entry handle (id and on-disk path).
    pub fn entry(&self) -> &M2dirEntry {
        &self.entry
    }

    /// Returns the raw bytes read from the entry file.
    pub fn contents(&self) -> &[u8] {
        &self.contents
    }

    /// Returns the flags read from the entry's `.flags` sidecar.
    pub fn flags(&self) -> &M2dirFlags {
        &self.flags
    }
}