Skip to main content

koji_diff/
koji.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2
3//! Koji build system API client.
4
5use std::path::Path;
6use std::process::Command;
7
8use sandogasa_kojihub::{Client, Error, Value, retry};
9
10/// Default number of retry attempts for transient failures.
11const DEFAULT_RETRIES: u32 = 3;
12
13/// Task state constants from Koji (re-exported from the shared
14/// hub crate; local definitions (rather than re-exports) keep
15/// `koji::TASK_CLOSED` callers working AND visible to rustdoc /
16/// cargo-semver-checks, which don't inline foreign re-exports.
17pub const TASK_CLOSED: i64 = sandogasa_kojihub::hub::TASK_CLOSED;
18pub const TASK_FAILED: i64 = sandogasa_kojihub::hub::TASK_FAILED;
19
20/// Koji API client.
21pub struct KojiClient {
22    client: Client,
23    instance: String,
24}
25
26/// Information about a Koji build.
27#[derive(Debug)]
28pub struct BuildInfo {
29    pub id: i64,
30    pub task_id: i64,
31    pub name: String,
32    pub version: String,
33    pub release: String,
34    pub nvr: String,
35    pub state: i64,
36}
37
38/// Information about a Koji task.
39#[derive(Debug, Clone)]
40pub struct TaskInfo {
41    pub id: i64,
42    pub method: String,
43    pub arch: String,
44    pub state: i64,
45}
46
47impl TaskInfo {
48    pub fn state_name(&self) -> &'static str {
49        match self.state {
50            0 => "FREE",
51            1 => "OPEN",
52            2 => "CLOSED",
53            3 => "CANCELED",
54            4 => "ASSIGNED",
55            5 => "FAILED",
56            _ => "UNKNOWN",
57        }
58    }
59}
60
61impl KojiClient {
62    pub fn new(instance: &str) -> Self {
63        Self::with_hub_url(instance, &format!("https://{instance}/kojihub"))
64    }
65
66    /// A client for `instance` whose hub is at `hub_url`.
67    fn with_hub_url(instance: &str, hub_url: &str) -> Self {
68        Self {
69            client: Client::new(hub_url),
70            instance: instance.to_string(),
71        }
72    }
73
74    pub fn instance(&self) -> &str {
75        &self.instance
76    }
77
78    /// Fetch build information by build ID.
79    pub fn get_build(&self, build_id: i64) -> Result<BuildInfo, Error> {
80        let result = retry(DEFAULT_RETRIES, || {
81            self.client.call("getBuild", &[Value::Int(build_id)])
82        })?;
83        Ok(BuildInfo {
84            id: result
85                .get("id")
86                .and_then(|v| v.as_int())
87                .unwrap_or(build_id),
88            task_id: result
89                .get("task_id")
90                .and_then(|v| v.as_int())
91                .ok_or_else(|| Error::Parse("missing task_id in build info".into()))?,
92            name: result
93                .get("name")
94                .and_then(|v| v.as_str())
95                .unwrap_or("")
96                .to_string(),
97            version: result
98                .get("version")
99                .and_then(|v| v.as_str())
100                .unwrap_or("")
101                .to_string(),
102            release: result
103                .get("release")
104                .and_then(|v| v.as_str())
105                .unwrap_or("")
106                .to_string(),
107            nvr: result
108                .get("nvr")
109                .and_then(|v| v.as_str())
110                .unwrap_or("")
111                .to_string(),
112            state: result.get("state").and_then(|v| v.as_int()).unwrap_or(-1),
113        })
114    }
115
116    /// Fetch task information by task ID.
117    pub fn get_task_info(&self, task_id: i64) -> Result<TaskInfo, Error> {
118        let result = retry(DEFAULT_RETRIES, || {
119            self.client.call("getTaskInfo", &[Value::Int(task_id)])
120        })?;
121        Ok(TaskInfo {
122            id: result.get("id").and_then(|v| v.as_int()).unwrap_or(task_id),
123            method: result
124                .get("method")
125                .and_then(|v| v.as_str())
126                .unwrap_or("")
127                .to_string(),
128            arch: result
129                .get("arch")
130                .and_then(|v| v.as_str())
131                .unwrap_or("")
132                .to_string(),
133            state: result.get("state").and_then(|v| v.as_int()).unwrap_or(-1),
134        })
135    }
136
137    /// Fetch child tasks of a parent task.
138    pub fn get_task_children(&self, task_id: i64) -> Result<Vec<TaskInfo>, Error> {
139        let result = retry(DEFAULT_RETRIES, || {
140            self.client.call("getTaskChildren", &[Value::Int(task_id)])
141        })?;
142        let items = result
143            .as_array()
144            .ok_or_else(|| Error::Parse("expected array for task children".into()))?;
145        items
146            .iter()
147            .map(|v| {
148                Ok(TaskInfo {
149                    id: v
150                        .get("id")
151                        .and_then(|v| v.as_int())
152                        .ok_or_else(|| Error::Parse("missing id in child task".into()))?,
153                    method: v
154                        .get("method")
155                        .and_then(|v| v.as_str())
156                        .unwrap_or("")
157                        .to_string(),
158                    arch: v
159                        .get("arch")
160                        .and_then(|v| v.as_str())
161                        .unwrap_or("")
162                        .to_string(),
163                    state: v.get("state").and_then(|v| v.as_int()).unwrap_or(-1),
164                })
165            })
166            .collect()
167    }
168
169    /// Resolve a task ID to the buildArch task for the given architecture.
170    ///
171    /// If the task is already a buildArch task, returns it directly.
172    /// If it is a parent build task, finds the matching child.
173    pub fn resolve_build_arch_task(&self, task_id: i64, arch: &str) -> Result<TaskInfo, Error> {
174        let info = self.get_task_info(task_id)?;
175        if info.method == "buildArch" {
176            return Ok(info);
177        }
178
179        let children = self.get_task_children(task_id)?;
180        let arch_tasks: Vec<_> = children
181            .iter()
182            .filter(|t| t.method == "buildArch" && t.arch == arch)
183            .collect();
184
185        if arch_tasks.is_empty() {
186            let available: Vec<_> = children
187                .iter()
188                .filter(|t| t.method == "buildArch")
189                .map(|t| t.arch.as_str())
190                .collect();
191            return Err(Error::Parse(format!(
192                "no buildArch task for arch '{arch}' under task {task_id}; \
193                 available: {}",
194                if available.is_empty() {
195                    "(none)".to_string()
196                } else {
197                    available.join(", ")
198                }
199            )));
200        }
201
202        Ok(arch_tasks[0].clone())
203    }
204
205    /// Download a log file from a task using `koji download-logs`.
206    ///
207    /// Downloads into `dest_dir` and returns the content of `filename`.
208    pub fn download_log(
209        &self,
210        task_id: i64,
211        filename: &str,
212        dest_dir: &Path,
213    ) -> Result<String, Error> {
214        let profile = self.koji_profile();
215        retry(DEFAULT_RETRIES, || {
216            let mut cmd = Command::new("koji");
217            if let Some(p) = profile {
218                cmd.arg("-p").arg(p);
219            }
220            let output = cmd
221                .arg("download-logs")
222                .arg("--dir")
223                .arg(dest_dir)
224                .arg(task_id.to_string())
225                .output()
226                .map_err(|e| Error::Parse(format!("failed to run koji download-logs: {e}")))?;
227            if !output.status.success() {
228                let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
229                return Err(Error::Parse(format!(
230                    "koji download-logs {task_id} failed: {stderr}"
231                )));
232            }
233            Ok(())
234        })?;
235
236        read_downloaded_log(dest_dir, filename, task_id)
237    }
238
239    /// Download a log file from a build's persistent storage via HTTP.
240    ///
241    /// Build logs are stored at:
242    /// `https://{topurl}/packages/{name}/{version}/{release}/data/logs/{arch}/{filename}`
243    ///
244    /// These persist even after task logs are garbage collected.
245    pub fn download_build_log(
246        &self,
247        build: &BuildInfo,
248        arch: &str,
249        filename: &str,
250    ) -> Result<String, Error> {
251        let topurl = self.packages_url().ok_or_else(|| {
252            Error::Parse(format!(
253                "no known packages URL for instance {}",
254                self.instance
255            ))
256        })?;
257        fetch_text(&build_log_url(topurl, build, arch, filename))
258    }
259
260    /// Return the packages base URL for this instance, if known.
261    fn packages_url(&self) -> Option<&'static str> {
262        match self.instance.as_str() {
263            "koji.fedoraproject.org" => Some("https://kojipkgs.fedoraproject.org"),
264            "cbs.centos.org" => Some("https://cbs.centos.org/kojifiles"),
265            "kojihub.stream.centos.org" => Some("https://kojihub.stream.centos.org/kojifiles"),
266            _ => None,
267        }
268    }
269
270    /// Return the koji CLI profile for this instance, if any.
271    fn koji_profile(&self) -> Option<&'static str> {
272        match self.instance.as_str() {
273            "koji.fedoraproject.org" => None,
274            "cbs.centos.org" => Some("cbs"),
275            "kojihub.stream.centos.org" => Some("stream"),
276            _ => None,
277        }
278    }
279}
280
281/// Where a build's `filename` for `arch` is kept under `topurl`.
282fn build_log_url(topurl: &str, build: &BuildInfo, arch: &str, filename: &str) -> String {
283    format!(
284        "{topurl}/packages/{name}/{version}/{release}/data/logs/{arch}/{filename}",
285        name = build.name,
286        version = build.version,
287        release = build.release,
288    )
289}
290
291/// The body of `url`, retrying transient failures.
292fn fetch_text(url: &str) -> Result<String, Error> {
293    retry(DEFAULT_RETRIES, || {
294        let response = reqwest::blocking::get(url)
295            .map_err(|e| Error::Parse(format!("failed to fetch {url}: {e}")))?;
296        if !response.status().is_success() {
297            return Err(Error::Parse(format!("{url}: HTTP {}", response.status())));
298        }
299        response
300            .text()
301            .map_err(|e| Error::Parse(format!("failed to read {url}: {e}")))
302    })
303}
304
305/// Read `filename` from what `koji download-logs` left in `dest_dir`:
306/// at the top, or anywhere below, as its layout varies. When it is not
307/// there, the error lists what was downloaded.
308fn read_downloaded_log(dest_dir: &Path, filename: &str, task_id: i64) -> Result<String, Error> {
309    let path = dest_dir.join(filename);
310    if path.exists() {
311        return std::fs::read_to_string(&path).map_err(|e| {
312            Error::Parse(format!("failed to read {filename} for task {task_id}: {e}"))
313        });
314    }
315
316    if let Some(found) = find_file_recursive(dest_dir, filename) {
317        return std::fs::read_to_string(&found)
318            .map_err(|e| Error::Parse(format!("failed to read {}: {e}", found.display())));
319    }
320
321    // List what was actually downloaded for diagnostics.
322    let mut files = Vec::new();
323    collect_files(dest_dir, &mut files);
324    Err(Error::Parse(format!(
325        "{filename} not found for task {task_id}\n\
326         koji download-logs produced: {}",
327        if files.is_empty() {
328            "(no files)".to_string()
329        } else {
330            files
331                .iter()
332                .map(|p| p.strip_prefix(dest_dir).unwrap_or(p).display().to_string())
333                .collect::<Vec<_>>()
334                .join(", ")
335        }
336    )))
337}
338
339/// Recursively find a file by name under a directory.
340pub fn find_file_in(dir: &Path, name: &str) -> Option<std::path::PathBuf> {
341    find_file_recursive(dir, name)
342}
343
344fn find_file_recursive(dir: &Path, name: &str) -> Option<std::path::PathBuf> {
345    let entries = std::fs::read_dir(dir).ok()?;
346    for entry in entries.flatten() {
347        let path = entry.path();
348        if path.is_file() && path.file_name().and_then(|n| n.to_str()) == Some(name) {
349            return Some(path);
350        }
351        if path.is_dir()
352            && let Some(found) = find_file_recursive(&path, name)
353        {
354            return Some(found);
355        }
356    }
357    None
358}
359
360/// Collect all file paths under a directory.
361fn collect_files(dir: &Path, out: &mut Vec<std::path::PathBuf>) {
362    if let Ok(entries) = std::fs::read_dir(dir) {
363        for entry in entries.flatten() {
364            let path = entry.path();
365            if path.is_file() {
366                out.push(path);
367            } else if path.is_dir() {
368                collect_files(&path, out);
369            }
370        }
371    }
372}
373
374#[cfg(test)]
375mod tests {
376    use super::*;
377    use wiremock::matchers::{body_string_contains, method, path};
378    use wiremock::{Mock, MockServer, ResponseTemplate};
379
380    /// Start a mock server, each `(xml-rpc method, response)` answering
381    /// calls to that method; the runtime keeps it alive.
382    fn hub(answers: &[(&str, String)]) -> (tokio::runtime::Runtime, MockServer) {
383        let rt = tokio::runtime::Builder::new_current_thread()
384            .enable_all()
385            .build()
386            .unwrap();
387        let server = rt.block_on(MockServer::start());
388        for (name, body) in answers {
389            rt.block_on(
390                Mock::given(method("POST"))
391                    .and(body_string_contains(format!(
392                        "<methodName>{name}</methodName>"
393                    )))
394                    .respond_with(ResponseTemplate::new(200).set_body_string(body.clone()))
395                    .mount(&server),
396            );
397        }
398        (rt, server)
399    }
400
401    fn response(value: &str) -> String {
402        format!(
403            "<?xml version='1.0'?><methodResponse><params><param>{value}</param>\
404             </params></methodResponse>"
405        )
406    }
407
408    fn task(id: i64, method: &str, arch: &str, state: i64) -> String {
409        format!(
410            "<value><struct>\
411             <member><name>id</name><value><int>{id}</int></value></member>\
412             <member><name>method</name><value><string>{method}</string></value></member>\
413             <member><name>arch</name><value><string>{arch}</string></value></member>\
414             <member><name>state</name><value><int>{state}</int></value></member>\
415             </struct></value>"
416        )
417    }
418
419    fn children(tasks: &[String]) -> String {
420        response(&format!(
421            "<value><array><data>{}</data></array></value>",
422            tasks.concat()
423        ))
424    }
425
426    fn client(server: &MockServer) -> KojiClient {
427        KojiClient::with_hub_url("koji.example.org", &server.uri())
428    }
429
430    #[test]
431    fn a_build_is_read_from_getbuild() {
432        let build = response(
433            "<value><struct>\
434             <member><name>id</name><value><int>42</int></value></member>\
435             <member><name>task_id</name><value><int>7</int></value></member>\
436             <member><name>name</name><value><string>foo</string></value></member>\
437             <member><name>version</name><value><string>1.0</string></value></member>\
438             <member><name>release</name><value><string>1.fc45</string></value></member>\
439             <member><name>nvr</name><value><string>foo-1.0-1.fc45</string></value></member>\
440             <member><name>state</name><value><int>1</int></value></member>\
441             </struct></value>",
442        );
443        let (_rt, server) = hub(&[("getBuild", build)]);
444        let b = client(&server).get_build(42).unwrap();
445        assert_eq!((b.id, b.task_id, b.state), (42, 7, 1));
446        assert_eq!(b.nvr, "foo-1.0-1.fc45");
447        assert_eq!((b.name.as_str(), b.version.as_str()), ("foo", "1.0"));
448        assert_eq!(b.release, "1.fc45");
449    }
450
451    #[test]
452    fn a_build_without_a_task_is_an_error() {
453        // An imported build has no task to diff logs from.
454        let build = response(
455            "<value><struct>\
456             <member><name>nvr</name><value><string>foo-1-1</string></value></member>\
457             </struct></value>",
458        );
459        let (_rt, server) = hub(&[("getBuild", build)]);
460        let err = client(&server).get_build(42).unwrap_err();
461        assert!(err.to_string().contains("missing task_id"), "{err}");
462    }
463
464    #[test]
465    fn a_buildarch_task_resolves_to_itself() {
466        let (_rt, server) = hub(&[(
467            "getTaskInfo",
468            response(&task(9, "buildArch", "x86_64", TASK_CLOSED)),
469        )]);
470        let t = client(&server)
471            .resolve_build_arch_task(9, "aarch64")
472            .unwrap();
473        assert_eq!((t.id, t.arch.as_str()), (9, "x86_64"));
474        assert_eq!(t.state_name(), "CLOSED");
475    }
476
477    #[test]
478    fn a_build_task_resolves_to_its_child_for_the_arch() {
479        let (_rt, server) = hub(&[
480            ("getTaskInfo", response(&task(1, "build", "noarch", 2))),
481            (
482                "getTaskChildren",
483                children(&[
484                    task(2, "buildSRPMFromSCM", "noarch", 2),
485                    task(3, "buildArch", "x86_64", 2),
486                    task(4, "buildArch", "aarch64", TASK_FAILED),
487                ]),
488            ),
489        ]);
490        let t = client(&server)
491            .resolve_build_arch_task(1, "aarch64")
492            .unwrap();
493        assert_eq!(t.id, 4);
494        assert_eq!(t.state_name(), "FAILED");
495    }
496
497    #[test]
498    fn a_missing_arch_names_the_arches_there_are() {
499        let (_rt, server) = hub(&[
500            ("getTaskInfo", response(&task(1, "build", "noarch", 2))),
501            (
502                "getTaskChildren",
503                children(&[
504                    task(3, "buildArch", "x86_64", 2),
505                    task(4, "buildArch", "aarch64", 2),
506                ]),
507            ),
508        ]);
509        let err = client(&server)
510            .resolve_build_arch_task(1, "s390x")
511            .unwrap_err()
512            .to_string();
513        assert!(err.contains("no buildArch task for arch 's390x'"), "{err}");
514        assert!(err.contains("available: x86_64, aarch64"), "{err}");
515    }
516
517    #[test]
518    fn a_task_without_buildarch_children_says_none() {
519        let (_rt, server) = hub(&[
520            ("getTaskInfo", response(&task(1, "build", "noarch", 2))),
521            ("getTaskChildren", children(&[])),
522        ]);
523        let err = client(&server)
524            .resolve_build_arch_task(1, "x86_64")
525            .unwrap_err()
526            .to_string();
527        assert!(err.contains("available: (none)"), "{err}");
528    }
529
530    #[test]
531    fn a_child_task_without_an_id_is_an_error() {
532        let child = response(
533            "<value><array><data><value><struct>\
534             <member><name>method</name><value><string>buildArch</string></value></member>\
535             </struct></value></data></array></value>",
536        );
537        let (_rt, server) = hub(&[("getTaskChildren", child)]);
538        let err = client(&server).get_task_children(1).unwrap_err();
539        assert!(err.to_string().contains("missing id"), "{err}");
540        let (_rt, server) = hub(&[("getTaskChildren", response("<value><int>1</int></value>"))]);
541        let err = client(&server).get_task_children(1).unwrap_err();
542        assert!(err.to_string().contains("expected array"), "{err}");
543    }
544
545    #[test]
546    fn state_names_cover_every_koji_task_state() {
547        let names: Vec<&str> = (0..=6)
548            .map(|state| {
549                TaskInfo {
550                    id: 0,
551                    method: String::new(),
552                    arch: String::new(),
553                    state,
554                }
555                .state_name()
556            })
557            .collect();
558        assert_eq!(
559            names,
560            [
561                "FREE", "OPEN", "CLOSED", "CANCELED", "ASSIGNED", "FAILED", "UNKNOWN"
562            ]
563        );
564    }
565
566    #[test]
567    fn instances_map_to_their_packages_url_and_cli_profile() {
568        let fedora = KojiClient::new("koji.fedoraproject.org");
569        assert_eq!(fedora.instance(), "koji.fedoraproject.org");
570        assert_eq!(
571            fedora.packages_url(),
572            Some("https://kojipkgs.fedoraproject.org")
573        );
574        assert_eq!(fedora.koji_profile(), None);
575        let cbs = KojiClient::new("cbs.centos.org");
576        assert_eq!(cbs.packages_url(), Some("https://cbs.centos.org/kojifiles"));
577        assert_eq!(cbs.koji_profile(), Some("cbs"));
578        let stream = KojiClient::new("kojihub.stream.centos.org");
579        assert_eq!(stream.koji_profile(), Some("stream"));
580        let other = KojiClient::new("koji.example.org");
581        assert_eq!((other.packages_url(), other.koji_profile()), (None, None));
582    }
583
584    fn build() -> BuildInfo {
585        BuildInfo {
586            id: 1,
587            task_id: 2,
588            name: "foo".into(),
589            version: "1.0".into(),
590            release: "1.fc45".into(),
591            nvr: "foo-1.0-1.fc45".into(),
592            state: 1,
593        }
594    }
595
596    #[test]
597    fn a_build_log_is_fetched_from_the_packages_tree() {
598        assert_eq!(
599            build_log_url("https://pkgs.example", &build(), "x86_64", "build.log"),
600            "https://pkgs.example/packages/foo/1.0/1.fc45/data/logs/x86_64/build.log"
601        );
602        let rt = tokio::runtime::Builder::new_current_thread()
603            .enable_all()
604            .build()
605            .unwrap();
606        let server = rt.block_on(MockServer::start());
607        rt.block_on(
608            Mock::given(method("GET"))
609                .and(path("/packages/foo/1.0/1.fc45/data/logs/x86_64/build.log"))
610                .respond_with(ResponseTemplate::new(200).set_body_string("the log"))
611                .mount(&server),
612        );
613        let url = build_log_url(&server.uri(), &build(), "x86_64", "build.log");
614        assert_eq!(fetch_text(&url).unwrap(), "the log");
615        let missing = build_log_url(&server.uri(), &build(), "s390x", "build.log");
616        let err = fetch_text(&missing).unwrap_err().to_string();
617        assert!(err.contains("HTTP 404"), "{err}");
618    }
619
620    #[test]
621    fn a_build_log_needs_a_known_packages_url() {
622        let err = KojiClient::new("koji.example.org")
623            .download_build_log(&build(), "x86_64", "build.log")
624            .unwrap_err()
625            .to_string();
626        assert!(err.contains("no known packages URL"), "{err}");
627    }
628
629    #[test]
630    fn a_downloaded_log_is_found_wherever_koji_put_it() {
631        let dir = tempfile::tempdir().unwrap();
632        std::fs::write(dir.path().join("root.log"), "top").unwrap();
633        assert_eq!(
634            read_downloaded_log(dir.path(), "root.log", 1).unwrap(),
635            "top"
636        );
637        let nested = dir.path().join("kojilogs/x86_64-9");
638        std::fs::create_dir_all(&nested).unwrap();
639        std::fs::write(nested.join("build.log"), "nested").unwrap();
640        assert_eq!(
641            read_downloaded_log(dir.path(), "build.log", 9).unwrap(),
642            "nested"
643        );
644        assert_eq!(
645            find_file_in(dir.path(), "build.log"),
646            Some(nested.join("build.log"))
647        );
648        let err = read_downloaded_log(dir.path(), "state.log", 9)
649            .unwrap_err()
650            .to_string();
651        assert!(err.contains("state.log not found for task 9"), "{err}");
652        assert!(err.contains("root.log"), "{err}");
653        assert!(err.contains("build.log"), "{err}");
654        let empty = tempfile::tempdir().unwrap();
655        let err = read_downloaded_log(empty.path(), "build.log", 9)
656            .unwrap_err()
657            .to_string();
658        assert!(err.contains("(no files)"), "{err}");
659    }
660}