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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
//! On-disk resume state for an interrupted download: a chunk bitfield.
//!
//! Progress is persisted next to the `.part` file as a compact bitset sidecar
//! so a dropped connection *or* a process restart continues instead of
//! restarting. The sidecar is bound to the blob's `id` + BLAKE3 `root` +
//! geometry, so a source regenerated between attempts can never splice
//! mismatched halves — on any mismatch the partial is discarded.
//!
//! Two crash-consistency rules (v1 violated both, H4/H5):
//!
//! 1. **Writes are atomic**: unique temp file → `sync_all` → `rename` → fsync
//! of the parent directory. A crash mid-save leaves the previous sidecar,
//! never a torn one.
//! 2. **Bits never claim un-synced data**: the client `sync_data`s the `.part`
//! *before* saving the sidecar (see the client's batching), so the failure
//! direction is always "data present, bit unset" — which merely re-fetches.
//!
//! The on-disk form is an 8-byte magic (`ZBLOBRS2`) + postcard body. Saves are
//! batched by the client (every N chunks / T seconds), not per chunk — v1's
//! per-chunk full-JSON rewrite generated ~2.4× the blob size in sidecar I/O.
use std::ops::Range;
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use crate::error::Result;
use crate::hash::Hash;
use crate::id::BlobId;
use crate::manifest::Manifest;
use crate::obs::zwarn;
use crate::paths::fsync_dir;
use crate::wire::WIRE_VERSION;
const MAGIC: &[u8; 8] = b"ZBLOBRS2";
/// Persistent record of which chunks of a blob are already on disk.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub(crate) struct ResumeState {
/// Sidecar schema version (first field; postcard is positional).
version: u16,
/// The blob id this partial belongs to.
id: BlobId,
/// The BLAKE3 bao root (resume binding — see module docs).
root: Hash,
/// Total blob length (must match the manifest to reuse the partial).
total_len: u64,
/// Transfer chunk size (ditto).
chunk_size: u32,
/// Presence bitfield: bit `i` (byte `i / 8`, LSB-first) = chunk `i` done.
bits: Vec<u8>,
}
impl ResumeState {
/// Path of the sidecar for a given `.part` file.
pub fn sidecar_path(part: &Path) -> PathBuf {
let mut p = part.as_os_str().to_os_string();
p.push(".meta");
PathBuf::from(p)
}
/// A fresh, all-missing state for `manifest` (validated by the caller).
pub fn fresh(manifest: &Manifest, chunk_count: u32) -> Self {
ResumeState {
version: WIRE_VERSION,
id: manifest.id.clone(),
root: manifest.root,
total_len: manifest.total_len,
chunk_size: manifest.chunk_size,
bits: vec![0u8; chunk_count.div_ceil(8) as usize],
}
}
/// Whether this saved state can be reused to resume `manifest` (same id,
/// root, geometry, and a well-formed bitfield).
pub fn matches(&self, manifest: &Manifest, chunk_count: u32) -> bool {
self.version == WIRE_VERSION
&& self.id == manifest.id
&& self.root == manifest.root
&& self.total_len == manifest.total_len
&& self.chunk_size == manifest.chunk_size
&& self.bits.len() == chunk_count.div_ceil(8) as usize
}
/// Number of chunks this state describes (derived from the recorded
/// geometry — bounds every bit access, including the byte-padding bits).
fn chunk_count(&self) -> u32 {
if self.chunk_size == 0 {
return 0;
}
self.total_len.div_ceil(self.chunk_size as u64) as u32
}
/// Whether chunk `i` is present.
pub fn is_set(&self, i: u32) -> bool {
i < self.chunk_count()
&& (i / 8) < self.bits.len() as u32
&& self.bits[(i / 8) as usize] & (1 << (i % 8)) != 0
}
/// Mark chunk `i` present; returns `true` if it was newly set.
pub fn mark(&mut self, i: u32) -> bool {
if i >= self.chunk_count() || (i / 8) >= self.bits.len() as u32 || self.is_set(i) {
return false;
}
self.bits[(i / 8) as usize] |= 1 << (i % 8);
true
}
/// Number of chunks present. The final byte's padding bits are masked so
/// a corrupt sidecar cannot inflate the count past real chunks (and make
/// `is_complete` rename a holey partial into place).
pub fn received(&self) -> u32 {
let count = self.chunk_count();
self.bits
.iter()
.enumerate()
.map(|(i, b)| {
let bit_base = i as u32 * 8;
let valid = count.saturating_sub(bit_base).min(8);
let mask = if valid >= 8 { 0xff } else { (1u8 << valid) - 1 };
(b & mask).count_ones()
})
.sum()
}
/// Whether all `chunk_count` chunks are present.
pub fn is_complete(&self, chunk_count: u32) -> bool {
self.received() >= chunk_count
}
/// Coalesced ranges of missing chunks in `[0, chunk_count)` — exactly the
/// holes a range-set query asks for.
pub fn missing_ranges(&self, chunk_count: u32) -> Vec<Range<u32>> {
let mut out: Vec<Range<u32>> = Vec::new();
let mut i = 0u32;
while i < chunk_count {
if self.is_set(i) {
i += 1;
continue;
}
let start = i;
while i < chunk_count && !self.is_set(i) {
i += 1;
}
out.push(start..i);
}
out
}
/// Load the sidecar for `part`, if it exists, has the magic, and parses.
///
/// `None` covers three different situations and the caller responds to all
/// three the same way — start over — which is correct: there is nothing to
/// resume from either way. What was wrong was doing it *silently*. An
/// absent sidecar is routine, but a present-and-unreadable one means a
/// completed transfer's worth of work is about to be repeated for a reason
/// nobody can see, so it says so.
pub async fn load(part: &Path) -> Option<ResumeState> {
let path = Self::sidecar_path(part);
let bytes = match tokio::fs::read(&path).await {
Ok(bytes) => bytes,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return None,
Err(e) => {
zwarn!(path = ?path, error = %e, "resume sidecar unreadable; restarting");
return None;
}
};
let Some(body) = bytes.strip_prefix(MAGIC.as_slice()) else {
zwarn!(path = ?path, "resume sidecar has a foreign magic; restarting");
return None;
};
match crate::wire::decode(body) {
Ok(state) => Some(state),
Err(e) => {
zwarn!(path = ?path, error = %e, "resume sidecar undecodable; restarting");
None
}
}
}
/// Persist the sidecar atomically: unique temp → `sync_all` → rename →
/// fsync the parent directory (rule 1 in the module docs).
pub async fn save_atomic(&self, part: &Path) -> Result<()> {
let dst = Self::sidecar_path(part);
let mut payload = Vec::with_capacity(8 + self.bits.len() + 64);
payload.extend_from_slice(MAGIC);
payload.extend_from_slice(&crate::wire::encode(self)?);
tokio::task::spawn_blocking(move || -> std::io::Result<()> {
use std::io::Write;
let dir = dst.parent().unwrap_or(Path::new("."));
let mut tmp = tempfile::NamedTempFile::new_in(dir)?;
tmp.write_all(&payload)?;
tmp.as_file().sync_all()?;
tmp.persist(&dst).map_err(|e| e.error)?;
fsync_dir(dir)
})
.await??;
Ok(())
}
/// Remove the sidecar (best-effort).
pub async fn remove(part: &Path) {
let _ = tokio::fs::remove_file(Self::sidecar_path(part)).await;
}
}
#[cfg(test)]
mod properties {
use super::*;
use crate::chunk::DEFAULT_CHUNK_SIZE;
use proptest::prelude::*;
fn manifest_for(chunk_count: u32) -> Manifest {
Manifest {
version: WIRE_VERSION,
id: BlobId::new("prop").unwrap(),
filename: None,
total_len: DEFAULT_CHUNK_SIZE as u64 * chunk_count as u64,
chunk_size: DEFAULT_CHUNK_SIZE,
root: Hash::of(b"prop"),
created_ms: 0,
ext: crate::wire::Ext::new(),
}
}
proptest! {
/// The bitfield's three views must never disagree: `is_set`,
/// `received`, `missing_ranges`, and `is_complete` are all consulted
/// independently by the download loop, and any drift between them
/// either re-fetches forever or renames a holey partial into place.
#[test]
fn bitfield_views_agree(
chunk_count in 1u32..300,
marks in prop::collection::vec(0u32..300, 0..300),
) {
let m = manifest_for(chunk_count);
let mut state = ResumeState::fresh(&m, chunk_count);
let mut expected: std::collections::BTreeSet<u32> = Default::default();
for i in marks {
let newly = state.mark(i);
if i < chunk_count {
prop_assert_eq!(newly, expected.insert(i), "mark({}) reported wrongly", i);
} else {
prop_assert!(!newly, "out-of-range mark({}) must be refused", i);
}
}
// received == |set|
prop_assert_eq!(state.received() as usize, expected.len());
// is_set agrees index by index
for i in 0..chunk_count {
prop_assert_eq!(state.is_set(i), expected.contains(&i));
}
// missing_ranges is exactly the complement, coalesced and sorted
let holes = state.missing_ranges(chunk_count);
let mut from_holes: std::collections::BTreeSet<u32> = Default::default();
let mut prev_end = 0u32;
for r in &holes {
prop_assert!(r.start < r.end && r.end <= chunk_count);
prop_assert!(r.start >= prev_end, "holes must be sorted and disjoint");
// Coalesced: a hole must not start exactly where the previous ended.
prop_assert!(r.start > prev_end || prev_end == 0, "holes not coalesced");
prev_end = r.end;
for i in r.clone() {
from_holes.insert(i);
}
}
let complement: std::collections::BTreeSet<u32> =
(0..chunk_count).filter(|i| !expected.contains(i)).collect();
prop_assert_eq!(from_holes, complement);
// is_complete ⟺ no holes ⟺ every index set
prop_assert_eq!(
state.is_complete(chunk_count),
holes.is_empty(),
"is_complete disagrees with missing_ranges"
);
prop_assert_eq!(
state.is_complete(chunk_count),
(0..chunk_count).all(|i| state.is_set(i)),
"is_complete disagrees with is_set"
);
}
/// A sidecar that survives save→load must describe the same progress.
/// (Persistence is the whole point; a lossy round trip silently
/// re-downloads or, worse, claims chunks it doesn't have.)
#[test]
fn sidecar_round_trips(
chunk_count in 1u32..200,
marks in prop::collection::vec(0u32..200, 0..100),
) {
let rt = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap();
rt.block_on(async {
let dir = tempfile::tempdir().unwrap();
let part = dir.path().join("x.part");
let m = manifest_for(chunk_count);
let mut state = ResumeState::fresh(&m, chunk_count);
for i in marks {
state.mark(i);
}
state.save_atomic(&part).await.unwrap();
let loaded = ResumeState::load(&part).await.expect("sidecar must load");
assert!(loaded.matches(&m, chunk_count));
assert_eq!(loaded.received(), state.received());
assert_eq!(loaded.missing_ranges(chunk_count), state.missing_ranges(chunk_count));
});
}
/// Arbitrary sidecar bytes must never panic and never be mistaken for
/// valid progress (the file is on disk where anything could corrupt
/// or forge it).
#[test]
fn arbitrary_sidecar_bytes_never_trusted(
bytes in prop::collection::vec(any::<u8>(), 0..300),
chunk_count in 1u32..100,
) {
let rt = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap();
rt.block_on(async {
let dir = tempfile::tempdir().unwrap();
let part = dir.path().join("y.part");
tokio::fs::write(ResumeState::sidecar_path(&part), &bytes).await.unwrap();
let m = manifest_for(chunk_count);
if let Some(state) = ResumeState::load(&part).await {
// Anything that loads must still be internally coherent and
// must not claim completion it cannot back with set bits.
if state.matches(&m, chunk_count) {
assert_eq!(
state.is_complete(chunk_count),
(0..chunk_count).all(|i| state.is_set(i)),
"a forged sidecar claimed completion it cannot back"
);
}
}
});
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::chunk::DEFAULT_CHUNK_SIZE;
fn manifest(chunks: u32) -> Manifest {
Manifest {
version: WIRE_VERSION,
id: BlobId::new("blob").unwrap(),
filename: None,
total_len: DEFAULT_CHUNK_SIZE as u64 * chunks as u64,
chunk_size: DEFAULT_CHUNK_SIZE,
root: Hash::of(b"data"),
created_ms: 0,
ext: crate::wire::Ext::new(),
}
}
#[test]
fn bitfield_marks_and_counts() {
let mut s = ResumeState::fresh(&manifest(10), 10);
assert_eq!(s.received(), 0);
assert!(s.mark(3));
assert!(!s.mark(3)); // duplicate → not newly set
assert!(s.mark(9));
assert!(!s.mark(10)); // out of capacity range
assert_eq!(s.received(), 2);
assert!(s.is_set(3) && s.is_set(9) && !s.is_set(0));
}
#[test]
fn missing_ranges_coalesce_holes() {
let mut s = ResumeState::fresh(&manifest(10), 10);
for i in [0u32, 1, 4, 7, 8] {
s.mark(i);
}
assert_eq!(s.missing_ranges(10), vec![2..4, 5..7, 9..10]);
for i in 0..10 {
s.mark(i);
}
assert!(s.missing_ranges(10).is_empty());
assert!(s.is_complete(10));
}
#[tokio::test]
async fn save_load_roundtrip_and_binding() {
let dir = tempfile::tempdir().unwrap();
let part = dir.path().join("x.part");
let m = manifest(20);
let mut s = ResumeState::fresh(&m, 20);
s.mark(5);
s.mark(6);
s.save_atomic(&part).await.unwrap();
let loaded = ResumeState::load(&part).await.unwrap();
assert!(loaded.matches(&m, 20));
assert_eq!(loaded.missing_ranges(20)[0], 0..5);
// A different root (regenerated source) must not match.
let other = Manifest {
root: Hash::of(b"other"),
..m
};
assert!(!loaded.matches(&other, 20));
}
#[tokio::test]
async fn torn_or_foreign_sidecar_ignored() {
let dir = tempfile::tempdir().unwrap();
let part = dir.path().join("y.part");
// Garbage without magic.
tokio::fs::write(ResumeState::sidecar_path(&part), b"not a sidecar")
.await
.unwrap();
assert!(ResumeState::load(&part).await.is_none());
// Magic but truncated body.
tokio::fs::write(ResumeState::sidecar_path(&part), &MAGIC[..])
.await
.unwrap();
assert!(ResumeState::load(&part).await.is_none());
}
}