Skip to main content

kevy_cli/
shadow.rs

1//! `shadow` — run the old query and the new one side by side and say
2//! where they disagree.
3//!
4//! Lesson 4 of the migration playbook, which is the one that decides
5//! whether anyone dares cut over: *serve reads from the old path while
6//! computing the new answer beside it, and compare the **order** too,
7//! not just the membership.* Score drift produces identical sets in
8//! different orders, and a paginated UI turns that into user-visible
9//! churn.
10//!
11//! It also carries lesson 2 without being asked to. A writer nobody
12//! remembered to update shows up here as rows the new path is missing —
13//! which is the same signal `TABLE.VERIFY` reports after the fact, seen
14//! before the cutover instead of after.
15
16use std::io;
17
18use kevy_resp_client::Reply;
19
20mod command;
21pub(crate) use command::run_on;
22
23/// One side's reading of a reply: the row keys in order, each with the
24/// sort value it was ordered by (empty when the shape does not carry
25/// one).
26type Rows = Vec<(Vec<u8>, Vec<u8>)>;
27
28/// How to read a reply into rows. Guessing is not free here — reading
29/// `ZRANGE … WITHSCORES` as a plain list silently treats every score as
30/// a row key and reports a divergence on every sample — so the two
31/// ambiguous shapes are told apart by the caller, not by a heuristic.
32///
33/// ```
34/// use kevy_cli::Reply;
35/// use kevy_cli::shadow::{Shape, compare, rows_of};
36/// let reply = Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"1".to_vec())]);
37/// // the same reply read two ways: two rows, or one row with its score
38/// assert_eq!(rows_of(&reply, Shape::Flat).len(), 2);
39/// assert_eq!(rows_of(&reply, Shape::Pairs), vec![(b"a".to_vec(), b"1".to_vec())]);
40/// ```
41#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
42#[non_exhaustive]
43pub enum Shape {
44    /// `[cursor, [key, sortval, key, sortval, …]]` — kevy's paged
45    /// index reply. Detected, not declared: a two-element array whose
46    /// second element is an array cannot be anything else here.
47    ///
48    /// ```
49    /// use kevy_cli::Reply;
50    /// use kevy_cli::shadow::{Shape, rows_of};
51    /// // IDX.QUERY: a cursor, then key / sort value pairs
52    /// let page = Reply::Array(vec![Reply::Bulk(b"0".to_vec()), Reply::Array(vec![Reply::Bulk(b"user:7".to_vec()), Reply::Bulk(b"42".to_vec())])]);
53    /// assert_eq!(rows_of(&page, Shape::Paged), vec![(b"user:7".to_vec(), b"42".to_vec())]);
54    /// ```
55    Paged,
56    /// `[a, b, c, …]` — every element is a row key.
57    ///
58    /// ```
59    /// use kevy_cli::Reply;
60    /// use kevy_cli::shadow::{Shape, rows_of};
61    /// // SMEMBERS, LRANGE, ZRANGE without scores: every element is a key
62    /// let rows = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
63    /// assert_eq!(rows, vec![(b"a".to_vec(), vec![]), (b"b".to_vec(), vec![])]);
64    /// ```
65    Flat,
66    /// `[member, score, member, score, …]` — `WITHSCORES` and friends.
67    ///
68    /// ```
69    /// use kevy_cli::Reply;
70    /// use kevy_cli::shadow::{Shape, rows_of};
71    /// // ZRANGE … WITHSCORES
72    /// let reply = Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"1.5".to_vec())]);
73    /// assert_eq!(rows_of(&reply, Shape::Pairs), vec![(b"a".to_vec(), b"1.5".to_vec())]);
74    /// ```
75    Pairs,
76}
77
78/// Read a reply into ordered rows under `shape`. `Paged` is recognised
79/// from the reply itself, so passing `Flat` for a kevy index reply
80/// still does the right thing rather than reporting nonsense.
81///
82/// ```
83/// use kevy_cli::Reply;
84/// use kevy_cli::shadow::{Shape, rows_of};
85/// let page = Reply::Array(vec![Reply::Bulk(b"0".to_vec()), Reply::Array(vec![Reply::Bulk(b"k".to_vec()), Reply::Bulk(b"9".to_vec())])]);
86/// // a paged reply is recognised even when the caller said Flat
87/// assert_eq!(rows_of(&page, Shape::Flat), rows_of(&page, Shape::Paged));
88/// assert!(rows_of(&Reply::Int(1), Shape::Flat).is_empty(), "not a list: no rows");
89/// ```
90pub fn rows_of(reply: &Reply, shape: Shape) -> Rows {
91    let Reply::Array(items) = reply else { return Vec::new() };
92    if let [Reply::Bulk(_), Reply::Array(inner)] = items.as_slice() {
93        return pairs(inner);
94    }
95    match shape {
96        Shape::Paged | Shape::Pairs => pairs(items),
97        Shape::Flat => items
98            .iter()
99            .filter_map(|r| match r {
100                Reply::Bulk(b) => Some((b.clone(), Vec::new())),
101                _ => None,
102            })
103            .collect(),
104    }
105}
106
107fn pairs(items: &[Reply]) -> Rows {
108    let bulks: Vec<&Vec<u8>> =
109        items.iter().filter_map(|r| if let Reply::Bulk(b) = r { Some(b) } else { None }).collect();
110    bulks
111        .chunks(2)
112        .map(|c| (c[0].clone(), c.get(1).map(|v| (*v).clone()).unwrap_or_default()))
113        .collect()
114}
115
116/// What one comparison found.
117///
118/// ```
119/// use kevy_cli::Reply;
120/// use kevy_cli::shadow::{Shape, compare, rows_of};
121/// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
122/// let new = rows_of(&Reply::Array(vec![Reply::Bulk(b"b".to_vec()), Reply::Bulk(b"a".to_vec())]), Shape::Flat);
123/// let d = compare(&old, &new).first.expect("same rows, different order");
124/// assert_eq!((d.at, d.old.map(|r| r.0), d.new.map(|r| r.0)), (0, Some(b"a".to_vec()), Some(b"b".to_vec())));
125/// ```
126#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
127#[non_exhaustive]
128pub struct Divergence {
129    /// Position of the first place the two orders differ.
130    ///
131    /// ```
132    /// use kevy_cli::Reply;
133    /// use kevy_cli::shadow::{Shape, compare, rows_of};
134    /// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
135    /// let new = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"c".to_vec())]), Shape::Flat);
136    /// assert_eq!(compare(&old, &new).first.map(|d| d.at), Some(1));
137    /// ```
138    pub at: usize,
139    /// The old side's row and the value it was ordered by.
140    ///
141    /// ```
142    /// use kevy_cli::Reply;
143    /// use kevy_cli::shadow::{Shape, compare, rows_of};
144    /// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"5".to_vec())]), Shape::Pairs);
145    /// let new = rows_of(&Reply::Array(vec![]), Shape::Pairs);
146    /// let d = compare(&old, &new).first.unwrap();
147    /// assert_eq!(d.old, Some((b"a".to_vec(), b"5".to_vec())), "the row and its sort value");
148    /// ```
149    pub old: Option<(Vec<u8>, Vec<u8>)>,
150    /// The new side's, at the same position.
151    ///
152    /// ```
153    /// use kevy_cli::Reply;
154    /// use kevy_cli::shadow::{Shape, compare, rows_of};
155    /// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec())]), Shape::Flat);
156    /// let new = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
157    /// let d = compare(&old, &new).first.unwrap();
158    /// assert_eq!(d.new, Some((b"b".to_vec(), vec![])));
159    /// assert_eq!(d.old, None, "the old side ended here");
160    /// ```
161    pub new: Option<(Vec<u8>, Vec<u8>)>,
162}
163
164/// Rows the new side lacks, rows it invents, and the first ordering
165/// difference. Membership and order are reported separately because
166/// they fail for different reasons: a missing row is a writer nobody
167/// updated, a reordering is score drift.
168///
169/// ```
170/// use kevy_cli::Reply;
171/// use kevy_cli::shadow::{Shape, compare, rows_of};
172/// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
173/// let new = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"c".to_vec())]), Shape::Flat);
174/// let c = compare(&old, &new);
175/// assert_eq!((c.missing, c.extra), (vec![b"b".to_vec()], vec![b"c".to_vec()]));
176/// ```
177#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
178#[non_exhaustive]
179pub struct Compared {
180    /// Rows the old path returns and the new one does not.
181    ///
182    /// ```
183    /// use kevy_cli::Reply;
184    /// use kevy_cli::shadow::{Shape, compare, rows_of};
185    /// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
186    /// let new = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec())]), Shape::Flat);
187    /// assert_eq!(compare(&old, &new).missing, [b"b".to_vec()]);
188    /// ```
189    pub missing: Vec<Vec<u8>>,
190    /// Rows the new path returns and the old one does not.
191    ///
192    /// ```
193    /// use kevy_cli::Reply;
194    /// use kevy_cli::shadow::{Shape, compare, rows_of};
195    /// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec())]), Shape::Flat);
196    /// let new = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
197    /// assert_eq!(compare(&old, &new).extra, [b"b".to_vec()]);
198    /// ```
199    pub extra: Vec<Vec<u8>>,
200    /// The first position where the two orders differ, if any.
201    ///
202    /// ```
203    /// use kevy_cli::Reply;
204    /// use kevy_cli::shadow::{Shape, compare, rows_of};
205    /// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
206    /// let new = rows_of(&Reply::Array(vec![Reply::Bulk(b"b".to_vec()), Reply::Bulk(b"a".to_vec())]), Shape::Flat);
207    /// let c = compare(&old, &new);
208    /// assert!(c.missing.is_empty() && c.extra.is_empty(), "same membership");
209    /// assert_eq!(c.first.map(|d| d.at), Some(0), "but not the same order");
210    /// ```
211    pub first: Option<Divergence>,
212}
213
214/// Compare two readings: what is missing, what is extra, and where the
215/// orders first part company.
216///
217/// ```
218/// use kevy_cli::Reply;
219/// use kevy_cli::shadow::{Shape, compare, rows_of};
220/// let old = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
221/// let new = rows_of(&Reply::Array(vec![Reply::Bulk(b"a".to_vec()), Reply::Bulk(b"b".to_vec())]), Shape::Flat);
222/// let c = compare(&old, &new);
223/// assert!(c.missing.is_empty() && c.extra.is_empty() && c.first.is_none());
224/// ```
225pub fn compare(old: &Rows, new: &Rows) -> Compared {
226    let old_set: std::collections::HashSet<&[u8]> = old.iter().map(|(k, _)| k.as_slice()).collect();
227    let new_set: std::collections::HashSet<&[u8]> = new.iter().map(|(k, _)| k.as_slice()).collect();
228    let missing = old
229        .iter()
230        .filter(|(k, _)| !new_set.contains(k.as_slice()))
231        .map(|(k, _)| k.clone())
232        .collect();
233    let extra = new
234        .iter()
235        .filter(|(k, _)| !old_set.contains(k.as_slice()))
236        .map(|(k, _)| k.clone())
237        .collect();
238    let mut first = None;
239    for i in 0..old.len().max(new.len()) {
240        if old.get(i).map(|(k, _)| k) != new.get(i).map(|(k, _)| k) {
241            first = Some(Divergence { at: i, old: old.get(i).cloned(), new: new.get(i).cloned() });
242            break;
243        }
244    }
245    Compared { missing, extra, first }
246}
247
248/// Outcome of a shadow run — the paste-able conclusion.
249///
250/// ```
251/// use kevy_cli::shadow::{Shape, print_report, run};
252/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
253/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
254/// # client.request_borrowed(&[b"ZADD", b"feed", b"1", b"a", b"2", b"b", b"3", b"c"])?;
255/// # client.request_borrowed(&[b"RPUSH", b"feed:new", b"a", b"c"])?;
256/// # let argv = |s: &str| s.split(' ').map(|w| w.as_bytes().to_vec()).collect::<Vec<_>>();
257/// let r = run(&mut client, &argv("ZRANGE feed 0 -1"), &argv("LRANGE feed:new 0 -1"),
258///     Shape::Flat, Shape::Flat, 3)?;
259/// print_report(&r);
260/// assert!(r.diverged > 0);
261/// # Ok::<(), Box<dyn std::error::Error>>(())
262/// ```
263#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
264#[non_exhaustive]
265pub struct ShadowReport {
266    /// How many times both sides were asked.
267    ///
268    /// ```
269    /// use kevy_cli::shadow::{Shape, run};
270    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
271    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
272    /// # client.request_borrowed(&[b"ZADD", b"feed", b"1", b"a", b"2", b"b", b"3", b"c"])?;
273    /// # client.request_borrowed(&[b"RPUSH", b"feed:new", b"a", b"c"])?;
274    /// # let argv = |s: &str| s.split(' ').map(|w| w.as_bytes().to_vec()).collect::<Vec<_>>();
275    /// let r = run(&mut client, &argv("ZRANGE feed 0 -1"), &argv("LRANGE feed:new 0 -1"),
276    ///     Shape::Flat, Shape::Flat, 3)?;
277    /// assert_eq!(r.samples, 3);
278    /// # Ok::<(), Box<dyn std::error::Error>>(())
279    /// ```
280    pub samples: u64,
281    /// How many of those disagreed in membership or order.
282    ///
283    /// ```
284    /// use kevy_cli::shadow::{Shape, run};
285    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
286    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
287    /// # client.request_borrowed(&[b"ZADD", b"feed", b"1", b"a", b"2", b"b", b"3", b"c"])?;
288    /// # client.request_borrowed(&[b"RPUSH", b"feed:new", b"a", b"c"])?;
289    /// # let argv = |s: &str| s.split(' ').map(|w| w.as_bytes().to_vec()).collect::<Vec<_>>();
290    /// let same = argv("ZRANGE feed 0 -1");
291    /// let r = run(&mut client, &same, &same, Shape::Flat, Shape::Flat, 2)?;
292    /// assert_eq!(r.diverged, 0, "a path agrees with itself");
293    /// # Ok::<(), Box<dyn std::error::Error>>(())
294    /// ```
295    pub diverged: u64,
296    /// The first sample that disagreed, and how.
297    ///
298    /// ```
299    /// use kevy_cli::shadow::{Shape, run};
300    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
301    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
302    /// # client.request_borrowed(&[b"ZADD", b"feed", b"1", b"a", b"2", b"b", b"3", b"c"])?;
303    /// # client.request_borrowed(&[b"RPUSH", b"feed:new", b"a", b"c"])?;
304    /// # let argv = |s: &str| s.split(' ').map(|w| w.as_bytes().to_vec()).collect::<Vec<_>>();
305    /// let r = run(&mut client, &argv("ZRANGE feed 0 -1"), &argv("LRANGE feed:new 0 -1"),
306    ///     Shape::Flat, Shape::Flat, 3)?;
307    /// let (sample, c) = r.first.expect("diverged");
308    /// assert_eq!((sample, c.missing), (0, vec![b"b".to_vec()]));
309    /// # Ok::<(), Box<dyn std::error::Error>>(())
310    /// ```
311    pub first: Option<(u64, Compared)>,
312}
313
314/// Run both commands `samples` times and compare each pair.
315///
316/// Both sides are issued on the same connection, back to back, so the
317/// window between them is as small as this can make it. A row written
318/// between the two reads shows up as a divergence, which is why a
319/// single disagreement is a lead rather than a verdict — the report
320/// carries the count so a rate can be read off it.
321///
322/// ```
323/// use kevy_cli::shadow::{Shape, run};
324/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
325/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
326/// # client.request_borrowed(&[b"ZADD", b"feed", b"1", b"a", b"2", b"b", b"3", b"c"])?;
327/// # client.request_borrowed(&[b"RPUSH", b"feed:new", b"a", b"c"])?;
328/// # let argv = |s: &str| s.split(' ').map(|w| w.as_bytes().to_vec()).collect::<Vec<_>>();
329/// // the new path, once its writer is fixed
330/// client.request_borrowed(&[b"RPUSH", b"feed:fixed", b"a", b"b", b"c"])?;
331/// let r = run(&mut client, &argv("ZRANGE feed 0 -1"), &argv("LRANGE feed:fixed 0 -1"),
332///     Shape::Flat, Shape::Flat, 5)?;
333/// assert_eq!((r.samples, r.diverged), (5, 0));
334/// # Ok::<(), Box<dyn std::error::Error>>(())
335/// ```
336pub fn run(
337    client: &mut dyn crate::link::Link,
338    old_cmd: &[Vec<u8>],
339    new_cmd: &[Vec<u8>],
340    old_shape: Shape,
341    new_shape: Shape,
342    samples: u64,
343) -> io::Result<ShadowReport> {
344    let mut report = ShadowReport { samples: 0, diverged: 0, first: None };
345    for i in 0..samples {
346        let old_ref: Vec<&[u8]> = old_cmd.iter().map(|a| a.as_slice()).collect();
347        let new_ref: Vec<&[u8]> = new_cmd.iter().map(|a| a.as_slice()).collect();
348        let old = rows_of(&client.request_borrowed(&old_ref)?, old_shape);
349        let new = rows_of(&client.request_borrowed(&new_ref)?, new_shape);
350        report.samples += 1;
351        let c = compare(&old, &new);
352        if !c.missing.is_empty() || !c.extra.is_empty() || c.first.is_some() {
353            report.diverged += 1;
354            if report.first.is_none() {
355                report.first = Some((i, c));
356            }
357        }
358    }
359    Ok(report)
360}
361
362/// Print the report the way lesson 4 asks for: the first divergence
363/// with **both** sort keys, because that one line names the drifting
364/// writer.
365///
366/// ```
367/// use kevy_cli::shadow::{Shape, print_report, run};
368/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
369/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
370/// # client.request_borrowed(&[b"ZADD", b"feed", b"1", b"a", b"2", b"b", b"3", b"c"])?;
371/// # client.request_borrowed(&[b"RPUSH", b"feed:new", b"a", b"c"])?;
372/// # let argv = |s: &str| s.split(' ').map(|w| w.as_bytes().to_vec()).collect::<Vec<_>>();
373/// let r = run(&mut client, &argv("ZRANGE feed 0 -1"), &argv("LRANGE feed:new 0 -1"),
374///     Shape::Flat, Shape::Flat, 3)?;
375/// // "shadow: 3 samples, 3 diverged (first at sample 0)", then
376/// // "MISSING from the new path (1): b" and the order difference
377/// print_report(&r);
378/// # Ok::<(), Box<dyn std::error::Error>>(())
379/// ```
380pub fn print_report(r: &ShadowReport) {
381    let show = |b: &[u8]| String::from_utf8_lossy(b).into_owned();
382    match &r.first {
383        None => println!(
384            "shadow: {} samples, 0 divergences — the new path answers what the old one does",
385            r.samples
386        ),
387        Some((n, c)) => {
388            println!(
389                "shadow: {} samples, {} diverged (first at sample {})",
390                r.samples, r.diverged, n
391            );
392            if !c.missing.is_empty() {
393                println!(
394                    "  MISSING from the new path ({}): {}",
395                    c.missing.len(),
396                    c.missing.iter().take(5).map(|k| show(k)).collect::<Vec<_>>().join(", ")
397                );
398                println!("    a row the old path has and the new one does not is usually a writer");
399                println!(
400                    "    that was never updated — the same class TABLE.VERIFY's `missing` finds"
401                );
402            }
403            if !c.extra.is_empty() {
404                println!(
405                    "  EXTRA in the new path ({}): {}",
406                    c.extra.len(),
407                    c.extra.iter().take(5).map(|k| show(k)).collect::<Vec<_>>().join(", ")
408                );
409            }
410            if let Some(d) = &c.first {
411                let side = |x: &Option<(Vec<u8>, Vec<u8>)>| match x {
412                    Some((k, v)) if v.is_empty() => show(k),
413                    Some((k, v)) => format!("{} (sort {})", show(k), show(v)),
414                    None => "<past the end>".to_string(),
415                };
416                println!("  ORDER differs at position {}:", d.at);
417                println!("    old: {}", side(&d.old));
418                println!("    new: {}", side(&d.new));
419                println!("    identical sets in different orders is score drift, and a paged UI");
420                println!("    shows it to users as churn — compare the two sort values above");
421            }
422        }
423    }
424}
425
426#[cfg(test)]
427mod tests {
428    use super::*;
429
430    fn bulk(s: &str) -> Reply {
431        Reply::Bulk(s.as_bytes().to_vec())
432    }
433
434    /// kevy's paged reply is recognised from its shape, so a caller who
435    /// never thought about shapes still gets rows rather than nonsense.
436    #[test]
437    fn a_paged_reply_is_read_without_being_declared() {
438        let reply = Reply::Array(vec![
439            bulk("0"),
440            Reply::Array(vec![bulk("u:1"), bulk("10"), bulk("u:2"), bulk("20")]),
441        ]);
442        let rows = rows_of(&reply, Shape::Flat); // deliberately the "wrong" shape
443        assert_eq!(rows.len(), 2);
444        assert_eq!(rows[0], (b"u:1".to_vec(), b"10".to_vec()));
445    }
446
447    /// The ambiguity that cannot be detected: member/score pairs look
448    /// exactly like a plain list. Reading WITHSCORES as flat would make
449    /// every score a row key and report a divergence on every sample.
450    #[test]
451    fn pairs_and_flat_are_told_apart_by_the_caller() {
452        let reply = Reply::Array(vec![bulk("u:1"), bulk("10"), bulk("u:2"), bulk("20")]);
453        assert_eq!(rows_of(&reply, Shape::Flat).len(), 4, "flat: four rows");
454        assert_eq!(rows_of(&reply, Shape::Pairs).len(), 2, "pairs: two rows with scores");
455    }
456
457    /// Lesson 2's consequence: a row the old path has and the new one
458    /// does not is a writer nobody updated.
459    #[test]
460    fn a_row_only_the_old_path_has_is_reported_missing() {
461        let old = vec![(b"u:1".to_vec(), vec![]), (b"u:2".to_vec(), vec![])];
462        let new = vec![(b"u:1".to_vec(), vec![])];
463        let c = compare(&old, &new);
464        assert_eq!(c.missing, vec![b"u:2".to_vec()]);
465        assert!(c.extra.is_empty());
466    }
467
468    /// Lesson 4's whole point: identical membership, different order.
469    /// Set comparison alone calls this a match.
470    #[test]
471    fn identical_sets_in_different_orders_still_diverge() {
472        let old = vec![(b"u:2".to_vec(), b"5".to_vec()), (b"u:1".to_vec(), b"10".to_vec())];
473        let new = vec![(b"u:1".to_vec(), b"10".to_vec()), (b"u:2".to_vec(), b"20".to_vec())];
474        let c = compare(&old, &new);
475        assert!(c.missing.is_empty() && c.extra.is_empty(), "same membership");
476        let d = c.first.expect("order must still diverge");
477        assert_eq!(d.at, 0);
478        // Both sort keys travel with it — that pair is what names the
479        // drifting writer.
480        assert_eq!(d.old.unwrap().1, b"5".to_vec());
481        assert_eq!(d.new.unwrap().1, b"10".to_vec());
482    }
483
484    #[test]
485    fn agreement_reports_nothing() {
486        let rows = vec![(b"u:1".to_vec(), b"10".to_vec())];
487        let c = compare(&rows, &rows);
488        assert!(c.missing.is_empty() && c.extra.is_empty() && c.first.is_none());
489    }
490}