Skip to main content

release_kit/commands/
versions.rs

1//! `rk versions`: the pinned-tool registry, and its freshness check.
2//!
3//! Plain `rk versions` prints the registry exactly as authored, offline.
4//! `--check` is the canon-side freshness answer and, beside `rk self-depend
5//! sync`, one of the two verbs that fetch: it consults each pin's check
6//! URL and reports per pin, where
7//! an unreachable or unparsable source is a reported result at exit 0,
8//! not an error — and it never edits `versions.toml`, because a pin
9//! update is a reviewed change in this repository. The fetch goes through
10//! `crate::http`, the one owner of the requests rk sends, whose test seam
11//! lets a test serve the network locally.
12
13use serde::Serialize;
14
15use crate::cli::versions::VersionsArgs;
16use crate::error::RkError;
17use crate::output::Output;
18use crate::{embedded, registry};
19
20/// One pin's check result.
21#[derive(Debug, Serialize)]
22struct PinResult {
23    /// The tool's registry name.
24    tool: String,
25    /// The pinned version.
26    pinned: String,
27    /// `current`, `update-available`, `source-unreachable`,
28    /// `source-unparsable`, or — for a pin whose freshness lives in its
29    /// ref alone — `no-version-source`.
30    result: &'static str,
31    /// The version the source serves, where one was read.
32    #[serde(skip_serializing_if = "Option::is_none")]
33    available: Option<String>,
34    /// The immutable execution commit, where the pin is an action.
35    #[serde(skip_serializing_if = "Option::is_none")]
36    commit: Option<String>,
37    /// How the discovery ref moves, from the registry.
38    #[serde(skip_serializing_if = "Option::is_none")]
39    ref_class: Option<String>,
40    /// `ref-unmoved`, `ref-moved`, `ref-unreachable`, or
41    /// `ref-unparsable`, for a pin carrying an action and a commit.
42    #[serde(skip_serializing_if = "Option::is_none")]
43    ref_result: Option<&'static str>,
44    /// The commit the discovery ref names today, where it was read.
45    #[serde(skip_serializing_if = "Option::is_none")]
46    ref_commit: Option<String>,
47}
48
49/// The machine form of a check report.
50#[derive(Debug, Serialize)]
51struct Report {
52    /// The shape version of this document.
53    schema: &'static str,
54    /// One result per pin, in registry order.
55    pins: Vec<PinResult>,
56}
57
58/// Print the registry, or check each pin upstream under `--check`.
59///
60/// # Errors
61///
62/// Returns [`RkError::Other`] only when the report cannot serialize; an
63/// unreachable or unparsable source is a reported result, not a failure.
64pub fn run(args: &VersionsArgs) -> Result<(), RkError> {
65    if !args.check {
66        Output::human().result_raw(embedded::VERSIONS);
67        return Ok(());
68    }
69    let out = Output::new(args.json);
70    let mut results = Vec::new();
71    for pin in registry::pins() {
72        let mut result = pin.check.as_deref().map_or_else(
73            || PinResult {
74                tool: pin.name.clone(),
75                pinned: pin.version.clone(),
76                // A pin can live without a version source only where its
77                // freshness signal is the discovery ref itself.
78                result: if pin.action.is_some() && pin.commit.is_some() {
79                    "no-version-source"
80                } else {
81                    "source-unreachable"
82                },
83                available: None,
84                commit: None,
85                ref_class: None,
86                ref_result: None,
87                ref_commit: None,
88            },
89            |url| check_one(&pin.name, &pin.version, url),
90        );
91        if let (Some(action), Some(commit)) = (&pin.action, &pin.commit) {
92            let (ref_result, ref_commit) = resolve_ref(action, commit);
93            result.commit = Some(commit.clone());
94            result.ref_class.clone_from(&pin.ref_class);
95            result.ref_result = Some(ref_result);
96            result.ref_commit = ref_commit;
97        }
98        out.result_line(match (&result.result, &result.available) {
99            (&"update-available", Some(available)) => format!(
100                "update-available {} {} pinned, {available} at the source",
101                result.tool, result.pinned
102            ),
103            _ => format!("{} {} {}", result.result, result.tool, result.pinned),
104        });
105        if let Some(ref_result) = result.ref_result {
106            let reference = pin
107                .action
108                .as_deref()
109                .and_then(|action| action.split_once('@'))
110                .map_or_else(String::new, |(_, reference)| reference.to_owned());
111            out.result_line(match (ref_result, &result.ref_commit) {
112                // Movement of a discovery ref is normal and by design: it
113                // is an update signal the pinned commit already contains,
114                // never something the tool can call an attack.
115                ("ref-moved", Some(now)) => format!(
116                    "ref-moved {}: {reference} now names {now}; an update to review, not an incident",
117                    result.tool
118                ),
119                ("ref-unmoved", _) => format!(
120                    "ref-unmoved {}: {reference} still names the pinned commit",
121                    result.tool
122                ),
123                _ => format!("{ref_result} {}: {reference}", result.tool),
124            });
125        }
126        results.push(result);
127    }
128    out.next(&[
129        "a pin update is a reviewed change to versions.toml, with its checked date".to_owned(),
130    ]);
131    out.emit(&Report {
132        schema: "rk.versions-check/2",
133        pins: results,
134    })
135}
136
137/// Resolve an action's discovery ref to the commit it names today and
138/// compare it against the pinned execution commit.
139fn resolve_ref(action: &str, pinned_commit: &str) -> (&'static str, Option<String>) {
140    let Some((path, reference)) = action.split_once('@') else {
141        return ("ref-unparsable", None);
142    };
143    // An action may live below its repository's root — `owner/repo/init` is
144    // one entry point of `owner/repo` — and a ref belongs to the repository,
145    // so only the first two segments address it.
146    let mut segments = path.split('/');
147    let (Some(owner), Some(repo)) = (segments.next(), segments.next()) else {
148        return ("ref-unparsable", None);
149    };
150    // The ref is one path segment, so a `/` inside it is encoded rather than
151    // passed through. This endpoint happens to accept the raw form too, but
152    // the documented contract is the encoded one and a maintained-branch ref
153    // like `release/v1` is exactly the case that relies on it.
154    let encoded: String = reference
155        .bytes()
156        .map(|byte| {
157            if byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-' | b'_' | b'~') {
158                char::from(byte).to_string()
159            } else {
160                format!("%{byte:02X}")
161            }
162        })
163        .collect();
164    let url = format!("https://api.github.com/repos/{owner}/{repo}/commits/{encoded}");
165    let Some(body) = fetch(&url) else {
166        return ("ref-unreachable", None);
167    };
168    let Some(sha) = serde_json::from_slice::<serde_json::Value>(&body)
169        .ok()
170        .and_then(|value| {
171            value
172                .get("sha")
173                .and_then(serde_json::Value::as_str)
174                .map(str::to_owned)
175        })
176    else {
177        return ("ref-unparsable", None);
178    };
179    if sha == pinned_commit {
180        ("ref-unmoved", Some(sha))
181    } else {
182        ("ref-moved", Some(sha))
183    }
184}
185
186/// The page bound for a paged answer: at 100 entries a page, ten pages is
187/// a thousand tags, past any forge project this registry pins, and Docker
188/// Hub refuses an anonymous read past its tenth page. A source deeper than
189/// that reads as unreachable rather than as a version this check silently
190/// guessed.
191const MAX_PAGES: u32 = 10;
192
193/// One GET, following redirects within ten seconds, or `None` where the
194/// fetch got no answer or a status other than a success.
195fn fetch(url: &str) -> Option<Vec<u8>> {
196    crate::http::send(
197        &crate::http::Request::get(url, std::time::Duration::from_secs(10)).following(),
198    )
199    .ok()
200    .filter(crate::http::Response::ok)
201    .map(|response| response.body)
202}
203
204/// The same URL at a later page, in the query form every paged source here
205/// takes.
206fn paged(url: &str, page: u32) -> String {
207    let joiner = if url.contains('?') { '&' } else { '?' };
208    format!("{url}{joiner}page={page}")
209}
210
211/// Fetch one check URL and classify the answer.
212///
213/// An object answer — a crates.io crate, a forge's latest release — is one
214/// GET. An array answer is a page of a list, and the endpoint documents no
215/// ordering, so reading one page would compute the greatest of an arbitrary
216/// subset and could report a stale pin as current. Every page is therefore
217/// read, to the bound above, and the greatest version across all of them
218/// wins.
219///
220/// Reaching the bound with a page still full is not an answer: the list
221/// continues past what was read, so the greatest version is unknown. That
222/// reads as `source-unreachable`, the same as a failed fetch, rather than
223/// as the greatest of the pages that happened to fit. A Docker Hub tag
224/// list is an object that links its next page, and it is read the same
225/// way: every page to the same bound, the greatest numbered tag across
226/// them, and a failed page or a bound reached with a next page still
227/// named reads as `source-unreachable`.
228fn check_one(tool: &str, pinned: &str, url: &str) -> PinResult {
229    check_with(tool, pinned, url, fetch)
230}
231
232/// [`check_one`] over any fetch, so a test can answer each URL itself.
233fn check_with(
234    tool: &str,
235    pinned: &str,
236    url: &str,
237    fetch: impl Fn(&str) -> Option<Vec<u8>>,
238) -> PinResult {
239    let result = |result, available| PinResult {
240        tool: tool.to_owned(),
241        pinned: pinned.to_owned(),
242        result,
243        available,
244        commit: None,
245        ref_class: None,
246        ref_result: None,
247        ref_commit: None,
248    };
249    let Some(body) = fetch(url) else {
250        return result("source-unreachable", None);
251    };
252    let mut best = latest_version(&body);
253    if is_page(&body) && !is_empty_page(&body) {
254        let mut ended = false;
255        for page in 2..=MAX_PAGES {
256            let Some(body) = fetch(&paged(url, page)) else {
257                return result("source-unreachable", None);
258            };
259            // Every page of a list is a list. A later page that answers
260            // some other shape is a source this reader does not
261            // understand, and feeding it to the object parser would mint
262            // a version out of an answer that names no tag.
263            if !is_page(&body) {
264                return result("source-unparsable", None);
265            }
266            if is_empty_page(&body) {
267                ended = true;
268                break;
269            }
270            best = greater(best, latest_version(&body));
271        }
272        if !ended {
273            return result("source-unreachable", None);
274        }
275    } else {
276        // A Docker Hub tag list names its next page in `next`, and its
277        // order does not establish the greatest version, so every page is
278        // read, to the bound.
279        let mut next = next_page(&body);
280        let mut pages = 1;
281        while let Some(link) = next {
282            if pages == MAX_PAGES {
283                return result("source-unreachable", None);
284            }
285            let Some(body) = fetch(&link) else {
286                return result("source-unreachable", None);
287            };
288            if !is_tag_list(&body) {
289                return result("source-unparsable", None);
290            }
291            best = greater(best, latest_version(&body));
292            next = next_page(&body);
293            pages += 1;
294        }
295    }
296    let Some(available) = best else {
297        return result("source-unparsable", None);
298    };
299    if is_current(pinned, &available) {
300        result("current", Some(available))
301    } else {
302        result("update-available", Some(available))
303    }
304}
305
306/// Whether the answer is one page of a list rather than a single object.
307fn is_page(body: &[u8]) -> bool {
308    serde_json::from_slice::<serde_json::Value>(body).is_ok_and(|value| value.is_array())
309}
310
311/// Whether the answer is a page of a Docker Hub tag list.
312fn is_tag_list(body: &[u8]) -> bool {
313    serde_json::from_slice::<serde_json::Value>(body).is_ok_and(|value| {
314        value
315            .get("results")
316            .is_some_and(serde_json::Value::is_array)
317    })
318}
319
320/// The link a Docker Hub tag list page gives to the page after it, or
321/// `None` on its last page and on every other answer.
322fn next_page(body: &[u8]) -> Option<String> {
323    let value: serde_json::Value = serde_json::from_slice(body).ok()?;
324    value.get("results")?.as_array()?;
325    value
326        .get("next")?
327        .as_str()
328        .filter(|link| !link.is_empty())
329        .map(str::to_owned)
330}
331
332/// Whether the answer is a page past the end of the list.
333fn is_empty_page(body: &[u8]) -> bool {
334    serde_json::from_slice::<serde_json::Value>(body)
335        .is_ok_and(|value| value.as_array().is_some_and(Vec::is_empty))
336}
337
338/// The greater of two versions, comparing numerically component by
339/// component, with an absent version losing to any present one.
340fn greater(left: Option<String>, right: Option<String>) -> Option<String> {
341    match (left, right) {
342        (Some(left), Some(right)) => {
343            if numeric_parts(&right) > numeric_parts(&left) {
344                Some(right)
345            } else {
346                Some(left)
347            }
348        }
349        (some, None) | (None, some) => some,
350    }
351}
352
353/// The latest version a source's JSON names, across the four answer
354/// shapes: `max_stable_version` from a crates.io answer, `tag_name` from a
355/// forge's releases answer, the greatest `name` from a forge's tags
356/// answer, which is an array, and the greatest numbered `name` in the
357/// `results` of a Docker Hub tag list.
358///
359/// The tags shape exists for a project that publishes tags and cuts no
360/// releases, so no releases answer names its latest version. The greatest
361/// is taken rather than the first, because the endpoint promises no
362/// ordering. A Docker Hub tag counts only where it opens with its version,
363/// read up to the variant suffix, so `13.7-slim` reads as `13.7` and a
364/// dated suite tag never passes for a version.
365fn latest_version(body: &[u8]) -> Option<String> {
366    let value: serde_json::Value = serde_json::from_slice(body).ok()?;
367    if let Some(tags) = value.as_array() {
368        return tags
369            .iter()
370            .filter_map(|tag| tag.get("name").and_then(serde_json::Value::as_str))
371            .filter_map(number_from)
372            .max_by(|left, right| numeric_parts(left).cmp(&numeric_parts(right)));
373    }
374    if let Some(results) = value.get("results").and_then(serde_json::Value::as_array) {
375        return results
376            .iter()
377            .filter_map(|tag| tag.get("name").and_then(serde_json::Value::as_str))
378            .filter(|name| name.starts_with(|c: char| c.is_ascii_digit()))
379            .map(|name| {
380                name.split(|c: char| !(c.is_ascii_digit() || c == '.'))
381                    .next()
382                    .unwrap_or_default()
383                    .trim_end_matches('.')
384                    .to_owned()
385            })
386            .max_by(|left, right| numeric_parts(left).cmp(&numeric_parts(right)));
387    }
388    let raw = value
389        .get("crate")
390        .and_then(|krate| krate.get("max_stable_version"))
391        .or_else(|| value.get("tag_name"))
392        .and_then(serde_json::Value::as_str)?;
393    number_from(raw)
394}
395
396/// A ref name from its first digit on: a tag may prefix the number —
397/// `v2.13.1`, or a name before it.
398fn number_from(raw: &str) -> Option<String> {
399    let start = raw.find(|c: char| c.is_ascii_digit())?;
400    Some(raw[start..].to_owned())
401}
402
403/// A version's numeric components, so that 2.10 orders above 2.9 rather
404/// than below it; the first component that is not a number ends the list,
405/// which keeps a suffixed variant below its plain sibling.
406fn numeric_parts(version: &str) -> Vec<u64> {
407    version
408        .split('.')
409        .map_while(|part| part.parse::<u64>().ok())
410        .collect()
411}
412
413/// Whether the pin already matches the source: exactly, or — for a pin
414/// naming only a major, as the action pins do — by major version.
415fn is_current(pinned: &str, available: &str) -> bool {
416    if pinned == available {
417        return true;
418    }
419    !pinned.contains('.') && available.split('.').next() == Some(pinned)
420}
421
422#[cfg(test)]
423mod tests {
424    use super::{PinResult, Report, check_with, is_current, latest_version};
425
426    /// One page of a Docker Hub tag list naming `tags`, with `next` as its
427    /// link to the page after it.
428    fn tag_page(next: Option<&str>, tags: &[&str]) -> Vec<u8> {
429        serde_json::json!({
430            "next": next,
431            "results": tags.iter().map(|name| serde_json::json!({"name": name})).collect::<Vec<_>>(),
432        })
433        .to_string()
434        .into_bytes()
435    }
436
437    const HUB: &str =
438        "https://hub.docker.com/v2/namespaces/library/repositories/debian/tags?page_size=100";
439
440    /// A newer numbered tag on a later page of a Docker Hub tag list wins,
441    /// because the list's order does not establish the greatest version.
442    #[test]
443    fn a_docker_hub_tag_list_reads_a_newer_tag_on_a_later_page() {
444        let checked = check_with("debian-image", "13.7", HUB, |url| match url {
445            HUB => Some(tag_page(
446                Some("https://hub.example/p2"),
447                &["13.7-slim", "13-slim"],
448            )),
449            "https://hub.example/p2" => Some(tag_page(None, &["13.8-slim", "12.15-slim"])),
450            _ => None,
451        });
452        assert_eq!(checked.result, "update-available");
453        assert_eq!(checked.available.as_deref(), Some("13.8"));
454    }
455
456    /// A later page that fails leaves the greatest version unknown, so the
457    /// pin reads as not observed, never as current.
458    #[test]
459    fn a_docker_hub_tag_list_with_a_failed_page_is_not_observed() {
460        let checked = check_with("debian-image", "13.7", HUB, |url| {
461            (url == HUB).then(|| tag_page(Some("https://hub.example/p2"), &["13.7-slim"]))
462        });
463        assert_eq!(checked.result, "source-unreachable");
464        assert_eq!(checked.available, None);
465    }
466
467    /// A list that still names a next page at the bound is read only in
468    /// part, so the pin reads as not observed, never as current.
469    #[test]
470    fn a_docker_hub_tag_list_past_the_bound_is_not_observed() {
471        let checked = check_with("debian-image", "13.7", HUB, |url| {
472            let page: u32 = url
473                .strip_prefix("https://hub.example/p")
474                .map_or(1, |page| page.parse().expect("a page number"));
475            Some(tag_page(
476                Some(&format!("https://hub.example/p{}", page + 1)),
477                &["13.7-slim"],
478            ))
479        });
480        assert_eq!(checked.result, "source-unreachable");
481        assert_eq!(checked.available, None);
482    }
483
484    #[test]
485    fn a_source_version_is_read_from_both_answer_shapes() {
486        assert_eq!(
487            latest_version(br#"{"crate":{"max_stable_version":"0.3.170"}}"#),
488            Some("0.3.170".to_owned())
489        );
490        assert_eq!(
491            latest_version(br#"{"tag_name":"v2.13.1"}"#),
492            Some("2.13.1".to_owned())
493        );
494        assert_eq!(
495            latest_version(br#"{"tag_name":"release-plz-v0.3.160"}"#),
496            Some("0.3.160".to_owned())
497        );
498        assert_eq!(latest_version(b"not json"), None);
499        assert_eq!(latest_version(br#"{"unrelated":true}"#), None);
500    }
501
502    /// The tags shape, for a project that publishes tags and cuts no
503    /// releases. The greatest wins, not the first, because the endpoint
504    /// promises no ordering; and 2.10 is above 2.9, not below it.
505    #[test]
506    fn a_tags_answer_reads_the_greatest_name() {
507        assert_eq!(
508            latest_version(br#"[{"name":"2.35.0"},{"name":"2.35.2"},{"name":"2.34.8"}]"#),
509            Some("2.35.2".to_owned())
510        );
511        assert_eq!(
512            latest_version(br#"[{"name":"2.9.0"},{"name":"2.10.0"}]"#),
513            Some("2.10.0".to_owned())
514        );
515        assert_eq!(
516            latest_version(br#"[{"name":"v1.2.3"}]"#),
517            Some("1.2.3".to_owned())
518        );
519        assert_eq!(latest_version(b"[]"), None);
520        assert_eq!(latest_version(br#"[{"sha":"abc"}]"#), None);
521    }
522
523    /// Docker Hub's tag list, for an image that cuts no forge release. Only
524    /// a tag that opens with its version counts, read up to the variant
525    /// suffix, so a dated or suite-named tag never passes for a version.
526    #[test]
527    fn a_docker_hub_tag_list_reads_the_greatest_numbered_tag() {
528        assert_eq!(
529            latest_version(
530                br#"{"count":5,"next":null,"results":[{"name":"trixie-20261104-slim"},{"name":"13.7-slim"},{"name":"13-slim"},{"name":"12.15-slim"},{"name":"stable-slim"}]}"#
531            ),
532            Some("13.7".to_owned())
533        );
534        assert_eq!(
535            latest_version(br#"{"results":[{"name":"13.10-slim"},{"name":"13.9-slim"}]}"#),
536            Some("13.10".to_owned())
537        );
538        assert_eq!(
539            latest_version(br#"{"results":[{"name":"stable-slim"}]}"#),
540            None
541        );
542    }
543
544    #[test]
545    fn a_major_only_pin_is_current_within_its_major() {
546        assert!(is_current("0.3.160", "0.3.160"));
547        assert!(!is_current("0.3.160", "0.3.170"));
548        assert!(is_current("4", "4.3.1"));
549        assert!(!is_current("4", "5.0.0"));
550    }
551
552    /// The complete `rk.versions-check/2` shape, held by snapshot.
553    #[test]
554    fn the_versions_check_schema_snapshot_holds() {
555        let report = Report {
556            schema: "rk.versions-check/2",
557            pins: vec![PinResult {
558                tool: "release-plz".into(),
559                pinned: "0.3.160".into(),
560                result: "update-available",
561                available: Some("0.3.170".into()),
562                commit: Some("2eb1d8bcb770b4c48ccfaad919734b38b51958c9".into()),
563                ref_class: Some("moving-minor-tag".into()),
564                ref_result: Some("ref-unmoved"),
565                ref_commit: Some("2eb1d8bcb770b4c48ccfaad919734b38b51958c9".into()),
566            }],
567        };
568        assert_eq!(
569            serde_json::to_string(&report).expect("a report serializes"),
570            r#"{"schema":"rk.versions-check/2","pins":[{"tool":"release-plz","pinned":"0.3.160","result":"update-available","available":"0.3.170","commit":"2eb1d8bcb770b4c48ccfaad919734b38b51958c9","ref_class":"moving-minor-tag","ref_result":"ref-unmoved","ref_commit":"2eb1d8bcb770b4c48ccfaad919734b38b51958c9"}]}"#
571        );
572    }
573}