app/lib/operator/sync-report.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/lib/operator/sync-tools.server.ts.

Source

1// `converged` is DERIVED from counts read back after the writes, never asserted by the caller: `ship`
2// fails on it, and a loop over a wrongly built corpus still reports a healthy `uploaded`.
3
4/**
5 * Any failed key makes `converged` false, even when the counts happen to agree.
6 *
7 * @param {{
8 *   uploaded: number,
9 *   removed: number,
10 *   cacheDropped: number,
11 *   expected: number,
12 *   present: number,
13 *   failed?: Array<{ key: string, error: string }>,
14 * }} counts
15 * @returns {{
16 *   uploaded: number,
17 *   removed: number,
18 *   cacheDropped: number,
19 *   expected: number,
20 *   present: number,
21 *   drift: number,
22 *   converged: boolean,
23 *   failed: Array<{ key: string, error: string }>,
24 *   unreadable: boolean,
25 * }}
26 */
27export function askSyncReport(counts) {
28  const agreement = convergence(counts.expected, counts.present);
29  // An absent list means the caller had nothing to report; anything else that is not an array is an
30  // unreadable failure list, and a report that cannot say what failed has not converged.
31  const failedReadable = counts.failed === undefined || Array.isArray(counts.failed);
32  const failed = Array.isArray(counts.failed) ? counts.failed : [];
33  return {
34    uploaded: whole(counts.uploaded),
35    removed: whole(counts.removed),
36    cacheDropped: whole(counts.cacheDropped),
37    ...agreement,
38    converged: agreement.converged && failedReadable && failed.length === 0,
39    failed,
40    unreadable: !failedReadable,
41  };
42}
43
44/**
45 * ABSOLUTE drift: an index holding more than its source is stale too, and a negative number would read
46 * as healthy to a caller testing `drift > 0`.
47 *
48 *
49 * @param {unknown} expectedRaw @param {unknown} presentRaw
50 * @returns {{ expected: number, present: number, drift: number, converged: boolean }}
51 */
52function convergence(expectedRaw, presentRaw) {
53  const expected = whole(expectedRaw);
54  const present = whole(presentRaw);
55  const drift = Math.abs(expected - present);
56  return {
57    expected,
58    present,
59    drift,
60    converged: unreadable(expectedRaw, presentRaw) ? false : drift === 0,
61  };
62}
63
64/**
65 * Media drifts by KEY: dropping one file while inventing one row leaves the totals equal, so drift is
66 * `missing` plus `extra`, not a count difference.
67 *
68 *
69 * @param {{
70 *   indexed: number,
71 *   removed: number,
72 *   failures: string[],
73 *   expected: number,
74 *   present: number,
75 *   missing: string[],
76 *   extra: string[],
77 * }} counts
78 */
79export function mediaSyncReport(counts) {
80  const totals = convergence(counts.expected, counts.present);
81  const missing = list(counts.missing);
82  const extra = list(counts.extra);
83  const drift = missing.length + extra.length;
84  const failures = list(counts.failures);
85  // Fails closed: a list that is not an array of strings cannot say what is missing or what failed, so
86  // the report does not converge on it.
87  const readable = [counts.missing, counts.extra, counts.failures].every(stringList);
88
89  return {
90    indexed: whole(counts.indexed),
91    removed: whole(counts.removed),
92    expected: totals.expected,
93    present: totals.present,
94    drift,
95    missing,
96    extra,
97    failures,
98    // A failed derivation leaves no row and no source change, so the key sets can agree while wrong.
99    converged: totals.converged && readable && drift === 0 && failures.length === 0,
100    unreadable: !readable,
101  };
102}
103
104/** @param {unknown} v @returns {string[]} */
105function list(v) {
106  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
107}
108
109/** @param {unknown} v @returns {boolean} */
110function stringList(v) {
111  return Array.isArray(v) && v.every((x) => typeof x === "string");
112}
113
114/**
115 * @param {ReturnType<typeof mediaSyncReport>} report
116 * @returns {string}
117 */
118export function mediaSyncSummary(report) {
119  if (report.converged) {
120    return (
121      `Media index converged: ${report.expected} expected, ${report.present} present, ` +
122      `${report.indexed} indexed, ${report.removed} removed.`
123    );
124  }
125  const why = [
126    report.missing.length ? `${report.missing.length} missing` : "",
127    report.extra.length ? `${report.extra.length} extra` : "",
128    report.failures.length ? `${report.failures.length} failed to derive` : "",
129    report.unreadable ? "an unreadable missing, extra or failure list" : "",
130  ].filter(Boolean);
131  return (
132    `MEDIA INDEX STILL DRIFTED: ${report.expected} expected, ${report.present} present` +
133    (why.length ? ` (${why.join(", ")})` : "") +
134    `, after indexing ${report.indexed} and removing ${report.removed}.`
135  );
136}
137
138/**
139 * An unreadable count is not a passing count.
140 *
141 * @param {unknown} a @param {unknown} b
142 */
143function unreadable(a, b) {
144  return !Number.isInteger(a) || !Number.isInteger(b);
145}
146
147/** @param {unknown} n @returns {number} */
148function whole(n) {
149  return Number.isInteger(n) ? Number(n) : 0;
150}
151
152/**
153 * @param {ReturnType<typeof askSyncReport>} report
154 * @returns {string}
155 */
156export function askSyncSummary(report) {
157  if (report.failed?.length) {
158    return (
159      `ASK UPLOAD FAILED for ${report.failed.length} key(s) after retries: ` +
160      `${report.failed.map((f) => `${f.key} (${f.error})`).join(", ")}. ` +
161      `${report.expected} expected, ${report.present} present.`
162    );
163  }
164  if (report.unreadable) {
165    return (
166      `ASK SYNC REPORT UNREADABLE: the failure list was not a list, so what failed is unknown. ` +
167      `${report.expected} expected, ${report.present} present.`
168    );
169  }
170  return report.converged
171    ? `Ask index converged: ${report.expected} expected, ${report.present} present, ` +
172        `${report.uploaded} uploaded, ${report.removed} removed.`
173    : `ASK INDEX STILL SHORT: ${report.expected} expected, ${report.present} present, ` +
174        `drift ${report.drift}, after uploading ${report.uploaded} and removing ${report.removed}.`;
175}