Skip to content

Commit 94f63ac

Browse files
alilleybrinkeralilleybrinker
committed
feat: More misc. fixups and docs improvements
Signed-off-by: Andrew Lilley Brinker <[email protected]>
1 parent 66c8622 commit 94f63ac

File tree

11 files changed

+197
-42
lines changed

11 files changed

+197
-42
lines changed

‎omnibor/src/artifact_id/identify.rs‎

Lines changed: 55 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
use crate::{
2+
artifact_id::identify::seal::IdentifySealed,
23
error::ArtifactIdError,
34
gitoid::internal::{gitoid_from_buffer, gitoid_from_reader},
45
hash_algorithm::HashAlgorithm,
@@ -17,15 +18,21 @@ use std::{
1718
sync::Arc,
1819
};
1920

21+
pub(crate) mod seal {
22+
pub trait IdentifySealed {}
23+
}
24+
2025
/// Types that can be identified with an `ArtifactId`.
21-
pub trait Identify<H>
26+
pub trait Identify<H>: IdentifySealed
2227
where
2328
H: HashAlgorithm,
2429
{
2530
/// Produce an [`ArtifactId`] with the given hash provider.
2631
fn identify(self) -> Result<ArtifactId<H>, ArtifactIdError>;
2732
}
2833

34+
impl IdentifySealed for &[u8] {}
35+
2936
impl<H> Identify<H> for &[u8]
3037
where
3138
H: HashAlgorithm,
@@ -37,6 +44,8 @@ where
3744
}
3845
}
3946

47+
impl<const N: usize> IdentifySealed for [u8; N] {}
48+
4049
impl<H, const N: usize> Identify<H> for [u8; N]
4150
where
4251
H: HashAlgorithm,
@@ -46,6 +55,8 @@ where
4655
}
4756
}
4857

58+
impl<const N: usize> IdentifySealed for &[u8; N] {}
59+
4960
impl<H, const N: usize> Identify<H> for &[u8; N]
5061
where
5162
H: HashAlgorithm,
@@ -55,6 +66,8 @@ where
5566
}
5667
}
5768

69+
impl IdentifySealed for &str {}
70+
5871
impl<H> Identify<H> for &str
5972
where
6073
H: HashAlgorithm,
@@ -64,6 +77,8 @@ where
6477
}
6578
}
6679

80+
impl IdentifySealed for &String {}
81+
6782
impl<H> Identify<H> for &String
6883
where
6984
H: HashAlgorithm,
@@ -73,6 +88,8 @@ where
7388
}
7489
}
7590

91+
impl IdentifySealed for &OsStr {}
92+
7693
impl<H> Identify<H> for &OsStr
7794
where
7895
H: HashAlgorithm,
@@ -82,6 +99,8 @@ where
8299
}
83100
}
84101

102+
impl IdentifySealed for &OsString {}
103+
85104
impl<H> Identify<H> for &OsString
86105
where
87106
H: HashAlgorithm,
@@ -91,6 +110,8 @@ where
91110
}
92111
}
93112

113+
impl IdentifySealed for &Path {}
114+
94115
impl<H> Identify<H> for &Path
95116
where
96117
H: HashAlgorithm,
@@ -105,6 +126,8 @@ where
105126
}
106127
}
107128

129+
impl IdentifySealed for &PathBuf {}
130+
108131
impl<H> Identify<H> for &PathBuf
109132
where
110133
H: HashAlgorithm,
@@ -114,6 +137,8 @@ where
114137
}
115138
}
116139

140+
impl IdentifySealed for File {}
141+
117142
impl<H> Identify<H> for File
118143
where
119144
H: HashAlgorithm,
@@ -123,6 +148,8 @@ where
123148
}
124149
}
125150

151+
impl IdentifySealed for &File {}
152+
126153
impl<H> Identify<H> for &File
127154
where
128155
H: HashAlgorithm,
@@ -133,16 +160,20 @@ where
133160
}
134161
}
135162

136-
impl<H> Identify<H> for Box<File>
163+
impl IdentifySealed for &mut File {}
164+
165+
impl<H> Identify<H> for &mut File
137166
where
138167
H: HashAlgorithm,
139168
{
140169
fn identify(self) -> Result<ArtifactId<H>, ArtifactIdError> {
141-
self.deref().identify()
170+
(&*self).identify()
142171
}
143172
}
144173

145-
impl<H> Identify<H> for Rc<File>
174+
impl IdentifySealed for Box<File> {}
175+
176+
impl<H> Identify<H> for Box<File>
146177
where
147178
H: HashAlgorithm,
148179
{
@@ -151,7 +182,9 @@ where
151182
}
152183
}
153184

154-
impl<H> Identify<H> for Arc<File>
185+
impl IdentifySealed for Rc<File> {}
186+
187+
impl<H> Identify<H> for Rc<File>
155188
where
156189
H: HashAlgorithm,
157190
{
@@ -160,18 +193,20 @@ where
160193
}
161194
}
162195

163-
impl<H, R> Identify<H> for BufReader<R>
196+
impl IdentifySealed for Arc<File> {}
197+
198+
impl<H> Identify<H> for Arc<File>
164199
where
165200
H: HashAlgorithm,
166-
R: Read + Seek,
167201
{
168202
fn identify(self) -> Result<ArtifactId<H>, ArtifactIdError> {
169-
let mut digester = get_hash_provider().digester();
170-
gitoid_from_reader::<H, Blob, _>(&mut *digester, self).map(ArtifactId::from_gitoid)
203+
self.deref().identify()
171204
}
172205
}
173206

174-
impl<H, R> Identify<H> for &mut R
207+
impl<R> IdentifySealed for BufReader<R> where R: Read + Seek {}
208+
209+
impl<H, R> Identify<H> for BufReader<R>
175210
where
176211
H: HashAlgorithm,
177212
R: Read + Seek,
@@ -182,6 +217,8 @@ where
182217
}
183218
}
184219

220+
impl<T> IdentifySealed for Cursor<T> where T: AsRef<[u8]> {}
221+
185222
impl<H, T> Identify<H> for Cursor<T>
186223
where
187224
H: HashAlgorithm,
@@ -193,6 +230,8 @@ where
193230
}
194231
}
195232

233+
impl<H> IdentifySealed for InputManifest<H> where H: HashAlgorithm {}
234+
196235
impl<H> Identify<H> for InputManifest<H>
197236
where
198237
H: HashAlgorithm,
@@ -202,6 +241,8 @@ where
202241
}
203242
}
204243

244+
impl<H> IdentifySealed for &InputManifest<H> where H: HashAlgorithm {}
245+
205246
impl<H> Identify<H> for &InputManifest<H>
206247
where
207248
H: HashAlgorithm,
@@ -211,6 +252,8 @@ where
211252
}
212253
}
213254

255+
impl<H> IdentifySealed for ArtifactId<H> where H: HashAlgorithm {}
256+
214257
impl<H> Identify<H> for ArtifactId<H>
215258
where
216259
H: HashAlgorithm,
@@ -220,6 +263,8 @@ where
220263
}
221264
}
222265

266+
impl<H> IdentifySealed for &ArtifactId<H> where H: HashAlgorithm {}
267+
223268
impl<H> Identify<H> for &ArtifactId<H>
224269
where
225270
H: HashAlgorithm,

‎omnibor/src/artifact_id/identify_async.rs‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
use crate::{
2-
error::ArtifactIdError, gitoid::internal::gitoid_from_async_reader,
3-
hash_algorithm::HashAlgorithm, hash_provider::registry::get_hash_provider, object_type::Blob,
2+
artifact_id::identify::seal::IdentifySealed, error::ArtifactIdError,
3+
gitoid::internal::gitoid_from_async_reader, hash_algorithm::HashAlgorithm,
4+
hash_provider::registry::get_hash_provider, object_type::Blob,
45
util::clone_as_boxstr::CloneAsBoxstr, ArtifactId,
56
};
67
use std::{
@@ -14,7 +15,7 @@ use tokio::{
1415
};
1516

1617
/// Types that can be identified with an `ArtifactId` asynchronously.
17-
pub trait IdentifyAsync<H>
18+
pub trait IdentifyAsync<H>: IdentifySealed
1819
where
1920
H: HashAlgorithm,
2021
{
@@ -87,6 +88,8 @@ where
8788
}
8889
}
8990

91+
impl IdentifySealed for &mut File {}
92+
9093
impl<H> IdentifyAsync<H> for &mut File
9194
where
9295
H: HashAlgorithm,
@@ -98,6 +101,8 @@ where
98101
}
99102
}
100103

104+
impl IdentifySealed for File {}
105+
101106
impl<H> IdentifyAsync<H> for File
102107
where
103108
H: HashAlgorithm,
@@ -107,6 +112,8 @@ where
107112
}
108113
}
109114

115+
impl<R> IdentifySealed for BufReader<R> where R: AsyncRead + AsyncSeek + Unpin {}
116+
110117
impl<H, R> IdentifyAsync<H> for BufReader<R>
111118
where
112119
H: HashAlgorithm,

‎omnibor/src/embed.rs‎

Lines changed: 46 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,49 @@
11
//! Control whether an `InputManifest`'s `ArtifactId` is stored in the target artifact.
2+
//!
3+
//! "Embedding" is one of the core operations in OmniBOR. When an Input Manifest
4+
//! is created, its Artifact ID can be embedded in the "target artifact" (the
5+
//! artifact whose build inputs the Input Manifest is describing). If embedding
6+
//! is done, then the Artifact ID of the target artifact will now depend on
7+
//! the Input Manifest, meaning that any change in the Input Manifest's contents
8+
//! caused by a change in build dependencies will cause a change in the
9+
//! Artifact ID of the target artifact.
10+
//!
11+
//! This is how OmniBOR produces a Merkle-tree-like structure for tracking
12+
//! fine-grained build dependencies (individual files, including intermediate
13+
//! files, used to build things like binaries).
14+
//!
15+
//! __Embedding is not required, but it is highly recommended.__ An Input
16+
//! Manifest without an associated target is considered "detached," and is
17+
//! generally not going to be very useful unless it's augmented with knowledge
18+
//! of the target artifact.
19+
//!
20+
//! # Embedding Options
21+
//!
22+
//! This module contains three key structs:
23+
//!
24+
//! - `NoEmbed`: Do not perform embedding.
25+
//! - `AutoEmbed`: Automatically infer the filetype of the target artifact and
26+
//! attempt to embed in it.
27+
//! - `CustomEmbed`: The user provides a function for doing embedding.
28+
//!
29+
//! `AutoEmbed` is only available if the `infer-filetypes` feature is turned on.
30+
//!
31+
//! If `CustomEmbed` is selected, the function takes the path to the target
32+
//! artifact, plus a [`CustomEmbedProvider`], which provides methods for getting
33+
//! the embedding data as bytes or a UTF-8 string.
34+
//!
35+
//! [__See the main documentation on embedding for more information.__][idx]
36+
//!
37+
//! [idx]: crate#embedding
238
339
#[cfg(feature = "infer-filetypes")]
440
pub(crate) mod auto_embed;
5-
pub(crate) mod embed_provider;
41+
pub(crate) mod custom_embed_provider;
642

743
use crate::{error::InputManifestError, hash_algorithm::HashAlgorithm, util::sealed::Sealed};
844
use std::{marker::PhantomData, path::Path};
945

10-
pub use crate::embed::embed_provider::EmbedProvider;
46+
pub use crate::embed::custom_embed_provider::CustomEmbedProvider;
1147

1248
#[cfg(feature = "infer-filetypes")]
1349
use crate::embed::auto_embed::embed_manifest_in_target;
@@ -24,7 +60,7 @@ where
2460
fn try_embed(
2561
&self,
2662
target_path: &Path,
27-
embed_provider: EmbedProvider<H>,
63+
embed_provider: CustomEmbedProvider<H>,
2864
) -> Option<Result<(), InputManifestError>>;
2965

3066
/// Indicates if the embedder will attempt to embed.
@@ -44,7 +80,7 @@ impl<H: HashAlgorithm> Embed<H> for NoEmbed {
4480
fn try_embed(
4581
&self,
4682
_target_path: &Path,
47-
_embed_provider: EmbedProvider<H>,
83+
_embed_provider: CustomEmbedProvider<H>,
4884
) -> Option<Result<(), InputManifestError>> {
4985
None
5086
}
@@ -67,7 +103,7 @@ impl<H: HashAlgorithm> Embed<H> for AutoEmbed {
67103
fn try_embed(
68104
&self,
69105
target_path: &Path,
70-
embed_provider: EmbedProvider<H>,
106+
embed_provider: CustomEmbedProvider<H>,
71107
) -> Option<Result<(), InputManifestError>> {
72108
Some(embed_manifest_in_target(target_path, embed_provider))
73109
}
@@ -77,7 +113,7 @@ impl<H: HashAlgorithm> Embed<H> for AutoEmbed {
77113
pub struct CustomEmbed<H, F>
78114
where
79115
H: HashAlgorithm,
80-
F: Fn(&Path, EmbedProvider<H>) -> Result<(), InputManifestError>,
116+
F: Fn(&Path, CustomEmbedProvider<H>) -> Result<(), InputManifestError>,
81117
{
82118
op: F,
83119
_phantom: PhantomData<H>,
@@ -86,7 +122,7 @@ where
86122
impl<H, F> CustomEmbed<H, F>
87123
where
88124
H: HashAlgorithm,
89-
F: Fn(&Path, EmbedProvider<H>) -> Result<(), InputManifestError>,
125+
F: Fn(&Path, CustomEmbedProvider<H>) -> Result<(), InputManifestError>,
90126
{
91127
/// Construct a new custom embedder.
92128
pub fn new(op: F) -> Self {
@@ -100,19 +136,19 @@ where
100136
impl<H, F> Sealed for CustomEmbed<H, F>
101137
where
102138
H: HashAlgorithm,
103-
F: Fn(&Path, EmbedProvider<H>) -> Result<(), InputManifestError>,
139+
F: Fn(&Path, CustomEmbedProvider<H>) -> Result<(), InputManifestError>,
104140
{
105141
}
106142

107143
impl<H, F> Embed<H> for CustomEmbed<H, F>
108144
where
109145
H: HashAlgorithm,
110-
F: Fn(&Path, EmbedProvider<H>) -> Result<(), InputManifestError>,
146+
F: Fn(&Path, CustomEmbedProvider<H>) -> Result<(), InputManifestError>,
111147
{
112148
fn try_embed(
113149
&self,
114150
target_path: &Path,
115-
embed_provider: EmbedProvider<H>,
151+
embed_provider: CustomEmbedProvider<H>,
116152
) -> Option<Result<(), InputManifestError>> {
117153
Some((self.op)(target_path, embed_provider))
118154
}

0 commit comments

Comments
 (0)