armdb 0.15.1

sharded bitcask key-value storage optimized for NVMe
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
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
use std::collections::{HashMap, HashSet};

use crate::armour::db::Db;
use crate::error::{DbError, DbResult};

use super::expected::SkippedSource;
use super::registry::{BuiltRegistry, Decl, scan_target_actual};
use super::unique_repair;
use super::validate::hex;

pub use super::unique_repair::{NamespaceConflict, NamespaceRepairStats};

/// Options for [`repair`].
#[derive(Debug, Clone, Default)]
pub struct RepairOptions {
    /// Delete orphan index rows on targets marked [`super::SchemaRegistry::complete_index`].
    pub delete_orphans: bool,
}

/// Per-index repair counters.
#[derive(Debug, Clone, Default)]
pub struct IndexRepairStats {
    pub name: &'static str,
    pub puts: u64,
    pub rewrites: u64,
    pub deletes: u64,
    pub declined_orphans: u64,
}

/// Per-counter repair counters — one row per declared `(collection, field)`
/// counter target actually compared. A target declined because its source
/// had undecodable rows (see [`RepairReport::undecodable_sources`])
/// contributes no row here — nothing was compared for it.
#[derive(Debug, Clone, Default)]
pub struct CounterRepairStats {
    pub collection: &'static str,
    pub field: &'static str,
    pub fixed: u64,
}

/// A source collection whose scan skipped rows it could not read or decode,
/// or stopped at a read error.
#[derive(Debug, Clone)]
pub struct UndecodableSource {
    pub name: &'static str,
    /// Rows skipped. With [`stopped_at`](Self::stopped_at) set, a lower
    /// bound: the rows after the stop were never visited.
    pub rows: u64,
    /// The read error a segmented source's scan stopped at, if it did.
    pub stopped_at: Option<String>,
    /// Targets whose orphan deletion — or, for a counter source, whose
    /// rewrite — was suppressed because of it.
    pub protected_targets: Vec<&'static str>,
}

/// Aggregate result of [`repair`].
#[derive(Debug, Clone, Default)]
pub struct RepairReport {
    /// Segmented targets skipped before any index repair writes.
    pub unchecked_targets: Vec<(&'static str, super::UncheckedReason)>,
    pub per_index: Vec<IndexRepairStats>,
    pub per_counter: Vec<CounterRepairStats>,
    /// Per-namespace unique-claim repair counters (T10 Task 10) — the
    /// namespace twin of `per_index`/`per_counter`. See
    /// `schema::unique_repair`'s module doc for what drives each field and
    /// why a namespace is repaired by its own pass rather than the generic
    /// carrier reconcile.
    pub per_namespace: Vec<NamespaceRepairStats>,
    /// Sources that could not be scanned in full. Their index rows — and, for
    /// a counter source, every declared counter target it feeds, and for a
    /// unique-claim source, every namespace it feeds — are missing from the
    /// expected set, so orphan deletion / counter rewriting / namespace
    /// orphan deletion is held back for everything they feed — see
    /// [`repair`].
    pub undecodable_sources: Vec<UndecodableSource>,
}

/// Apply the same scan as `validate` and fix index drift: put missing rows,
/// rewrite mismatches, optionally delete orphans on complete targets. Also
/// fixes counter drift (`Decl::Counter` targets): resolves each declared
/// counter to its expected absolute value via
/// [`super::expected::build_counters`] — the same shared pass `validate`
/// reads — and applies the difference through
/// [`crate::counter::ErasedCounterTarget::apply_delta`].
///
/// Aborts with [`DbError::IndexKeyCollision`] if two source owners project the
/// same `(target, key)` — collisions are unrepairable and must not leave an
/// arbitrary scan-order winner on disk.
///
/// # Undecodable source rows
///
/// A source scan skips rows whose value cannot be read or decoded (Var, LSM
/// and segmented families; see `Finding::UndecodableRows`), and a segmented
/// scan stops at a read error (`Finding::ScanAborted`). The outcome is that
/// of the very pass that built the expected set, so a transient error counts
/// too. Those rows contribute
/// nothing to the expected set, so their live index entries would look like
/// orphans, and their counter contributions are simply missing — a rewrite
/// from either would create drift, not fix it. Deleting an orphan under this
/// condition would destroy the only remaining record of a row whose
/// value is already unreadable, so **orphan deletion is suppressed** for every
/// index target fed by such a source, and **counter rewriting is suppressed**
/// for every counter target it feeds, regardless of
/// [`RepairOptions::delete_orphans`] and `complete_index`. Missing rows are
/// still put and mismatches still rewritten — only the destructive half is held
/// back. The affected sources are listed in
/// [`RepairReport::undecodable_sources`].
///
/// # Unique namespaces (T10)
///
/// Pass 5 repairs every declared unique namespace — see
/// `schema::unique_repair`'s module doc for the full rule (missing claims
/// written, conflicts refused and reported with the key and both owners,
/// orphans deleted only under `complete_namespace` + `delete_orphans`,
/// reservations and corrupt rows never touched). It runs *after* the index
/// and counter passes above, so a namespace scan failure (an I/O-level
/// error from `ClaimTarget::scan_rows`, propagated via `?`) aborts `repair`
/// with whatever the earlier passes already wrote already landed on disk —
/// the same partial-failure shape `expected::build_counters(reg)?` already
/// has relative to the index passes before it, not a new one this pass
/// introduces.
pub fn repair(db: &Db, reg: &BuiltRegistry, opts: RepairOptions) -> DbResult<RepairReport> {
    use super::expected::{self, BuildIssue};

    // Pass 1: the expected set — shared with `validate`, so the two cannot
    // disagree about what an index should hold. Any issue aborts here, before
    // anything below has written a byte.
    let mut budget = super::seg_budget::SegBudget::new(reg);
    let (mut expected, skipped) = expected::build(reg, &mut budget, &mut |issue| match issue {
        #[cfg(feature = "segmented")]
        BuildIssue::NotOwned {
            index, source_key, ..
        } => Err(DbError::IndexKeyNotOwned {
            target: index,
            source_key: hex(&source_key),
        }),
        BuildIssue::Collision { index, key, owners } => Err(DbError::IndexKeyCollision {
            index,
            key: hex(&key),
            owners: owners.to_vec(),
        }),
        BuildIssue::Projection { error, .. } => Err(error),
    })?;

    // Targets whose expected set is known to be short, so an "orphan" there may
    // be a live row of a source record that can no longer be read.
    let protected: HashSet<&'static str> = skipped
        .iter()
        .flat_map(|s| s.targets.iter().copied())
        .collect();
    let mut undecodable_sources: Vec<UndecodableSource> = Vec::new();
    for s in skipped {
        merge_skipped(&mut undecodable_sources, s);
    }
    // Target scans: a row the scan could not read is absent from `actual`,
    // so it can be put again but never deleted as an orphan.
    let mut target_scans = super::validate::ScanLog::default();

    let mut actual_by_target: HashMap<&'static str, HashMap<Vec<u8>, Vec<u8>>> = HashMap::new();
    let mut stats_by_name: HashMap<&'static str, IndexRepairStats> = HashMap::new();
    super::registry::preflight_targets(
        reg,
        &mut expected,
        &mut actual_by_target,
        &mut target_scans,
        &mut budget,
    );
    let all_targets = expected::declared_targets(reg);

    // Pass 2: put what is missing, rewrite what differs. Keyed by target, not by
    // declaration — the expected set already unions every source, and `actual`
    // is a pre-mutation snapshot, so walking a shared target once per
    // declaration would re-put each row and double-count the report.
    for target_name in &all_targets {
        if budget.is_unchecked(target_name) {
            continue;
        }
        let Some(rows) = expected.rows(target_name) else {
            continue;
        };
        let Some(t) = expected::target_decl(reg, target_name) else {
            continue;
        };
        let actual = scan_target_actual(
            reg,
            &mut actual_by_target,
            t.name,
            &t.value_to_bytes,
            &mut target_scans,
            &mut budget,
        );
        for (key, (value, _owner)) in rows {
            let action = match actual.get(key) {
                None => Some(true),
                Some(actual_bytes) => match (t.value_eq)(value, actual_bytes) {
                    Ok(false) => Some(false),
                    Ok(true) => None,
                    Err(e) => return Err(e),
                },
            };
            if let Some(missing) = action {
                {
                    let _cap = budget
                        .is_segmented(t.name)
                        .then(|| crate::index_maintenance::IndexMaintenance::enter(t.name));
                    t.index.put_bytes(key, value)?;
                }
                let stats = stats_by_name
                    .entry(t.name)
                    .or_insert_with(|| IndexRepairStats {
                        name: t.name,
                        ..Default::default()
                    });
                if missing {
                    stats.puts += 1;
                } else {
                    stats.rewrites += 1;
                }
            }
        }
    }

    // Pass 3: orphans — index rows no source claims.
    for target_name in all_targets {
        if budget.is_unchecked(target_name) {
            continue;
        }
        let Some(tdecl) = expected::target_decl(reg, target_name) else {
            continue;
        };
        let actual = scan_target_actual(
            reg,
            &mut actual_by_target,
            target_name,
            &tdecl.value_to_bytes,
            &mut target_scans,
            &mut budget,
        );
        let complete =
            reg.complete_indices.contains(target_name) && !protected.contains(target_name);
        let orphans: Vec<Vec<u8>> = actual
            .keys()
            .filter(|kb| !expected.contains(target_name, kb))
            .cloned()
            .collect();
        for kb in orphans {
            let stats = stats_by_name
                .entry(target_name)
                .or_insert_with(|| IndexRepairStats {
                    name: target_name,
                    ..Default::default()
                });
            if complete && opts.delete_orphans {
                {
                    let _cap = budget
                        .is_segmented(tdecl.name)
                        .then(|| crate::index_maintenance::IndexMaintenance::enter(tdecl.name));
                    tdecl.index.delete_bytes(&kb)?;
                }
                stats.deletes += 1;
            } else {
                stats.declined_orphans += 1;
            }
        }
    }

    let mut per_index: Vec<_> = stats_by_name.into_values().collect();
    per_index.sort_by_key(|s| s.name);

    // Pass 4: counters — shares `expected::build_counters` with `validate`,
    // exactly as the index passes above share `expected::build`.
    //
    // A source whose scan skipped rows contributes an undercount, so its
    // declared targets are declined here — merged into the same
    // `undecodable_sources` list the index passes populate above, since a
    // source could in principle feed both an index and a counter — rather
    // than rewritten from a short sum. Rewriting from a short scan would
    // *create* drift, not fix it.
    let (counter_expected, counter_skipped) = expected::build_counters(reg)?;
    let counter_skipped_sources: HashSet<&'static str> =
        counter_skipped.iter().map(|s| s.name).collect();
    for s in counter_skipped {
        merge_skipped(&mut undecodable_sources, s);
    }
    let mut per_counter: Vec<CounterRepairStats> = Vec::new();
    for d in &reg.reg.decls {
        let Decl::Counter {
            source, targets, ..
        } = d
        else {
            continue;
        };
        // An unregistered source must never be read as "expected zero" — it
        // has no `CollectionEntry`, so `build_counters` silently skipped this
        // whole declaration and `counter_expected` holds nothing for its
        // targets. Skip repairing them entirely rather than "fixing" every
        // stored row down to zero; `validate`'s structural check is what
        // reports this (see `run_decls`).
        if reg.reg.entries.iter().all(|e| e.name != *source) {
            continue;
        }
        // The pass that summed this source did not visit every row: its
        // targets were already listed as protected above.
        if counter_skipped_sources.contains(source) {
            continue;
        }
        for t in targets.all() {
            let drift = expected::counter_drift(t, &counter_expected)?;
            let mut fixed = 0u64;
            for d in drift {
                let delta = i128::from(d.want) - i128::from(d.stored);
                // Mirror the open-time recount's leniency (`counter::recount`)
                // — and what `docs/schema-metadata.md` already documents for
                // `validate`/`repair`: a **dangling contribution** (a live
                // source row whose target row is gone) degrades to a `warn!`
                // and is skipped. Propagating it here would abort the whole
                // repair part-way through, after earlier deltas already
                // landed, over a row `validate` reports anyway.
                // `AmbiguousCounterTarget` has no safe target to skip to and
                // still propagates.
                // `Ok(false)` — the resolved decision was `Upsert::Keep`, so
                // nothing was written. Counting it would report a repair that
                // did not happen, on a mismatch that is still there at the
                // next run.
                match t.apply_delta(&d.key, delta) {
                    Ok(true) => fixed += 1,
                    Ok(false) => {}
                    Err(DbError::CounterTargetMissing { targets, key }) => {
                        tracing::warn!(
                            collection = t.collection_name(),
                            field = t.field(),
                            targets = %targets,
                            key = %key,
                            "repair: dangling contribution — target row missing, skipping (see schema::validate)"
                        );
                    }
                    Err(e) => return Err(e),
                }
            }
            per_counter.push(CounterRepairStats {
                collection: t.collection_name(),
                field: t.field(),
                fixed,
            });
        }
    }
    per_counter.sort_by(|a, b| (a.collection, a.field).cmp(&(b.collection, b.field)));

    // Pass 5: unique namespaces — shares `expected::build_unique` with
    // `validate`, exactly as passes 1-4 share `expected::build`/
    // `build_counters`. A namespace is repaired by ITS OWN pass, never the
    // generic `reconcile_carrier_projections` above — see
    // `schema::unique_repair`'s module doc.
    let (per_namespace, unique_skipped, repaired_sources) =
        unique_repair::repair_namespaces(reg, &opts)?;
    for s in unique_skipped {
        merge_skipped(&mut undecodable_sources, s);
    }

    // A marker is conservative evidence rather than a report derived from
    // current rows: even an apparently clean namespace must complete the
    // registered union scan before it can be retired. `repair_namespaces`
    // only returns sources whose every declared namespace participated and
    // whose scan/write path was free of decode failures and conflicts.
    // Reaching here also proves the pass did not return an I/O or persistence
    // error, so no partial namespace pass can clear an obligation.
    let dirty_sources: Vec<&str> = repaired_sources
        .into_iter()
        .filter(|source| db.unique_dirty(source))
        .collect();
    if !dirty_sources.is_empty() {
        db.clear_unique_dirty(&dirty_sources)?;
    }

    let mut unchecked_targets: Vec<_> = budget
        .unchecked()
        .iter()
        .map(|(name, reason)| (*name, reason.clone()))
        .collect();
    unchecked_targets.sort_by_key(|(name, _)| *name);
    Ok(RepairReport {
        unchecked_targets,
        per_index,
        per_counter,
        per_namespace,
        undecodable_sources,
    })
}

/// Fold one pass's skipped source into the report: a source can feed an
/// index, a counter and a namespace, each built by its own pass.
fn merge_skipped(sources: &mut Vec<UndecodableSource>, s: SkippedSource) {
    match sources.iter_mut().find(|u| u.name == s.name) {
        Some(existing) => {
            existing.rows = existing.rows.max(s.outcome.skipped);
            if existing.stopped_at.is_none() {
                existing.stopped_at = s.outcome.stopped_at;
            }
            for name in s.targets {
                if !existing.protected_targets.contains(&name) {
                    existing.protected_targets.push(name);
                }
            }
        }
        None => sources.push(UndecodableSource {
            name: s.name,
            rows: s.outcome.skipped,
            stopped_at: s.outcome.stopped_at,
            protected_targets: s.targets,
        }),
    }
}