sandogasa_cli/lib.rs
1// SPDX-License-Identifier: Apache-2.0 OR MIT
2
3//! Shared CLI utilities for sandogasa tools.
4
5pub mod date;
6
7use std::process::{Command, Stdio};
8
9use url::{Host, Url};
10
11/// Standard process-wide initialization for sandogasa tools.
12///
13/// Call this once as the first statement of `main()` in every
14/// binary. It is the single place for cross-cutting startup work:
15/// anything added to this function is automatically picked up by
16/// every tool that calls it, so prefer extending `init` over
17/// scattering setup across mains.
18///
19/// Today it registers the rustls crypto provider that reqwest's
20/// TLS support needs (see [`install_crypto_provider`]). Idempotent
21/// and cheap, so calling it from a tool that does no networking is
22/// harmless.
23pub fn init() {
24 install_crypto_provider();
25}
26
27/// Install the ring-based rustls [`CryptoProvider`] as the process
28/// default.
29///
30/// We build reqwest with the `rustls-no-provider` feature to keep
31/// `aws-lc-rs` — reqwest 0.13's default provider, which is not
32/// packaged in Fedora — out of the dependency tree. That leaves
33/// rustls with no compiled-in default provider, so one must be
34/// registered at runtime before the first HTTPS request or reqwest
35/// panics with "No provider set". `ring` is statically linked into
36/// the binary (a build-time dependency only); this just points
37/// rustls at it.
38///
39/// Idempotent: the underlying `install_default` only takes effect
40/// on the first call and reports an error on subsequent ones, which
41/// we ignore so repeated calls (e.g. across tests) are harmless.
42///
43/// [`CryptoProvider`]: rustls::crypto::CryptoProvider
44pub fn install_crypto_provider() {
45 let _ = rustls::crypto::ring::default_provider().install_default();
46}
47
48/// Environment variable that, when set to a non-empty value,
49/// disables [`ensure_secure_url`]'s plaintext-credential guard.
50/// Intended for local testing against `http://` mock servers or a
51/// trusted internal proxy — never for production credentials.
52pub const ALLOW_INSECURE_URL_ENV: &str = "SANDOGASA_ALLOW_INSECURE_URL";
53
54/// Refuse to hand credentials to a base URL that would transmit
55/// them in cleartext.
56///
57/// Returns `Ok(())` when the URL is `https`, when its host is a
58/// loopback address (`localhost`, `127.0.0.0/8`, `::1` — so mock
59/// servers and local development keep working), or when
60/// [`ALLOW_INSECURE_URL_ENV`] is set to a non-empty value.
61/// Otherwise returns an error naming the URL and the override, so
62/// an API token is never put on the wire over plain `http`.
63///
64/// Call this wherever a client is built with a token, before any
65/// request is made.
66pub fn ensure_secure_url(base_url: &str) -> Result<(), String> {
67 let allow_insecure = std::env::var_os(ALLOW_INSECURE_URL_ENV).is_some_and(|v| !v.is_empty());
68 check_secure_url(base_url, allow_insecure)
69}
70
71/// Pure core of [`ensure_secure_url`], with the env override passed
72/// in so it can be unit-tested without mutating process state.
73fn check_secure_url(base_url: &str, allow_insecure: bool) -> Result<(), String> {
74 let parsed = Url::parse(base_url).map_err(|e| format!("invalid URL '{base_url}': {e}"))?;
75 if parsed.scheme() == "https" || host_is_loopback(&parsed) {
76 return Ok(());
77 }
78 if allow_insecure {
79 return Ok(());
80 }
81 Err(format!(
82 "refusing to send credentials to '{base_url}' over plaintext \
83 {}: use an https URL, or set {ALLOW_INSECURE_URL_ENV}=1 to \
84 override (e.g. for local testing against a mock server).",
85 parsed.scheme()
86 ))
87}
88
89/// Whether a URL's host is a loopback address.
90fn host_is_loopback(u: &Url) -> bool {
91 match u.host() {
92 Some(Host::Domain(d)) => d == "localhost" || d.ends_with(".localhost"),
93 Some(Host::Ipv4(ip)) => ip.is_loopback(),
94 Some(Host::Ipv6(ip)) => ip.is_loopback(),
95 None => false,
96 }
97}
98
99/// Whether an executable named `name` is on `$PATH` (a lightweight
100/// check that does **not** run the tool).
101pub fn tool_exists(name: &str) -> bool {
102 std::env::var_os("PATH")
103 .map(|paths| std::env::split_paths(&paths).any(|dir| dir.join(name).is_file()))
104 .unwrap_or(false)
105}
106
107/// Whether `exe` is available, per its `probe`: `Some(arg)` runs
108/// `exe arg` and requires a zero exit (confirms it executes);
109/// `None` checks only `$PATH` existence.
110fn tool_available(exe: &str, probe: Option<&str>) -> bool {
111 match probe {
112 Some(arg) => Command::new(exe)
113 .arg(arg)
114 .stdout(Stdio::null())
115 .stderr(Stdio::null())
116 .status()
117 .is_ok_and(|s| s.success()),
118 None => tool_exists(exe),
119 }
120}
121
122/// Check that a batch of external tools is available, returning a
123/// single error that lists every missing one with its install hint.
124///
125/// Each entry is `(executable, install_hint, probe)`:
126/// - `probe = Some(arg)` *runs* `<executable> <arg>` (e.g.
127/// `Some("--version")`, or `Some("version")` for `koji`, or
128/// `Some("--help")` for `pbuilder-dist`) and requires a zero exit,
129/// confirming the tool actually executes.
130/// - `probe = None` checks only `$PATH` existence, for tools with no
131/// usable version/help flag.
132///
133/// All entries are checked, so the error names every missing tool
134/// rather than failing on the first.
135///
136/// # Example
137///
138/// ```no_run
139/// sandogasa_cli::require_tools(&[
140/// ("git", "sudo apt install git", Some("--version")),
141/// ("pbuilder-dist", "sudo apt install ubuntu-dev-tools", Some("--help")),
142/// ])
143/// .unwrap();
144/// ```
145pub fn require_tools(tools: &[(&str, &str, Option<&str>)]) -> Result<(), String> {
146 let missing: Vec<String> = tools
147 .iter()
148 .filter(|(exe, _, probe)| !tool_available(exe, *probe))
149 .map(|(exe, hint, _)| format!("{exe} (install: {hint})"))
150 .collect();
151 if missing.is_empty() {
152 Ok(())
153 } else {
154 Err(format!("missing required tool(s): {}", missing.join(", ")))
155 }
156}
157
158#[cfg(test)]
159mod tests {
160 use super::*;
161
162 #[test]
163 fn tool_exists_detects_present_and_absent() {
164 assert!(tool_exists("sh"));
165 assert!(!tool_exists("nonexistent_tool_xyz_123"));
166 }
167
168 #[test]
169 fn require_tools_path_and_probe_modes() {
170 // PATH mode (probe None): present is OK, absent is missing.
171 assert!(require_tools(&[("sh", "present", None)]).is_ok());
172 assert!(require_tools(&[("nonexistent_zzz", "install zzz", None)]).is_err());
173
174 // Probe mode: `true` runs and exits 0; a missing executable
175 // fails the probe. The error lists every missing tool with its
176 // hint, and skips the present one.
177 assert!(require_tools(&[("true", "ok", Some("--version"))]).is_ok());
178 let err = require_tools(&[
179 ("true", "ok", Some("--version")),
180 ("nonexistent_aaa_111", "install aaa", Some("--version")),
181 ("nonexistent_bbb_222", "install bbb", None),
182 ])
183 .unwrap_err();
184 assert!(err.contains("nonexistent_aaa_111"));
185 assert!(err.contains("install aaa"));
186 assert!(err.contains("nonexistent_bbb_222"));
187 assert!(err.contains("install bbb"));
188 assert!(!err.contains("true ("));
189 }
190
191 #[test]
192 fn secure_url_allows_https() {
193 assert!(check_secure_url("https://bugzilla.redhat.com", false).is_ok());
194 assert!(check_secure_url("https://gitlab.com/api/v4", false).is_ok());
195 }
196
197 #[test]
198 fn secure_url_allows_loopback_over_http() {
199 // Mock servers / local dev: loopback is fine over http.
200 assert!(check_secure_url("http://127.0.0.1:8080", false).is_ok());
201 assert!(check_secure_url("http://localhost:3000/api", false).is_ok());
202 assert!(check_secure_url("http://[::1]:9999", false).is_ok());
203 }
204
205 #[test]
206 fn secure_url_rejects_plaintext_remote() {
207 let err = check_secure_url("http://gitlab.example.com", false).unwrap_err();
208 assert!(err.contains("gitlab.example.com"));
209 assert!(err.contains(ALLOW_INSECURE_URL_ENV));
210 }
211
212 #[test]
213 fn secure_url_override_allows_plaintext_remote() {
214 // With the override "set", plaintext to a remote host is allowed.
215 assert!(check_secure_url("http://gitlab.example.com", true).is_ok());
216 }
217
218 #[test]
219 fn secure_url_rejects_invalid() {
220 assert!(check_secure_url("not a url", false).is_err());
221 }
222}