xianyun_backends/kustomize/

mod.rs

//! Kustomize build operations.
//!
//! Ported from `internal/backends/kustomize/{interface,client}.go`. Go
//! builds *in process* against the `kustomize` Go library (`krusty`),
//! never shelling out to a `kustomize` binary -- there is no Rust
//! equivalent of `krusty` to link against. This port instead shells out
//! to the real `kustomize build` binary via [`xianyun_executor::exec::
//! CommandRunner`] (the same mechanism every other backend in this
//! crate uses), which gives generator (`secretGenerator`/
//! `configMapGenerator`) and `replacements` support -- and kustomize's
//! own remote-target resolution -- for free, rather than hand-rolling a
//! partial reimplementation of kustomize's YAML processing semantics.
//! See `PORT_NOTES.md` for the full design rationale.
//!
//! [`FileSystem`] (this crate's own invention, not a port of `sigs.k8s.
//! io/kustomize/kyaml/filesys.FileSystem`) still exists so unit tests can
//! stay hermetic: `Client::build` walks and reads the kustomize
//! directory through this trait, stages a copy on a real temporary
//! directory (the real `kustomize` binary can only read from disk), and
//! then invokes the real binary against that staging copy. A *remote*
//! target (`file://...//overlay?ref=...`, `https://...`, ...) bypasses
//! `FileSystem` and staging entirely: kustomize resolves those itself
//! (shallow git clone included), so the target string is passed straight
//! through to the binary.

pub mod remote;

use std::sync::Arc;

use thiserror::Error;
use xianyun_executor::exec::{CommandRunner, Options};

/// Ported from the subset of `sigs.k8s.io/kustomize/kyaml/filesys.
/// FileSystem` that `Client::build` needs: `WriteFile`/`ReadFile` (for
/// test fixtures to populate a hermetic directory tree) plus [`walk`],
/// which this port adds so `Client::build` can enumerate every file
/// under a directory to stage it onto real disk before invoking the
/// real `kustomize` binary. [`walk`] defaults to "unsupported" so
/// existing `FileSystem` implementors elsewhere in the workspace (which
/// predate this method) keep compiling without needing to implement it
/// themselves; an implementor that wants its fixtures to exercise real
/// generator/replacement builds through `Client::build` must override
/// it.
///
/// [`walk`]: FileSystem::walk
pub trait FileSystem: Send + Sync {
    fn write_file(&self, path: &str, content: &[u8]) -> std::io::Result<()>;
    fn read_file(&self, path: &str) -> std::io::Result<Vec<u8>>;

    /// Returns every file path under `dir`, recursively. The default
    /// implementation reports "unsupported": a `FileSystem` without a
    /// real `walk` cannot be staged onto disk, so any `Client::build`
    /// call against it fails with [`KustomizeError::BuildFailed`]
    /// rather than silently building an empty directory.
    fn walk(&self, dir: &str) -> std::io::Result<Vec<String>> {
        let _ = dir;
        Err(std::io::Error::other(
            "FileSystem::walk is not implemented for this filesystem",
        ))
    }
}

/// The real on-disk [`FileSystem`]: Go's zero-argument `NewClient`
/// defaults to `filesys.MakeFsOnDisk()`, and production callers of this
/// port's [`Client::new`] need the equivalent -- every `FileSystem`
/// implementor elsewhere in the workspace is test-only (an in-memory
/// map), since nothing needed a real-disk one until a production caller
/// (the `deployer::kustomize` manager) had an on-disk kustomization
/// directory, built by `builtin::materialize_builtin_overlay`, to build.
#[derive(Debug, Clone, Copy, Default)]
pub struct DiskFileSystem;

impl FileSystem for DiskFileSystem {
    fn write_file(&self, path: &str, content: &[u8]) -> std::io::Result<()> {
        std::fs::write(path, content)
    }

    fn read_file(&self, path: &str) -> std::io::Result<Vec<u8>> {
        std::fs::read(path)
    }

    fn walk(&self, dir: &str) -> std::io::Result<Vec<String>> {
        let mut files = Vec::new();
        let mut pending = vec![std::path::PathBuf::from(dir)];

        while let Some(current) = pending.pop() {
            for entry in std::fs::read_dir(&current)? {
                let entry = entry?;
                let path = entry.path();
                if entry.file_type()?.is_dir() {
                    pending.push(path);
                } else if let Some(path) = path.to_str() {
                    files.push(path.to_string());
                }
            }
        }

        Ok(files)
    }
}

/// Ported from the error `Client::Build` wraps: `kustomizer.Run` /
/// `resources.AsYaml` failures, and context cancellation.
#[derive(Debug, Error)]
pub enum KustomizeError {
    #[error("building kustomize directory {0:?}: {1}")]
    BuildFailed(String, String),

    #[error("serializing kustomize output for {0:?}: {1}")]
    SerializeFailed(String, String),

    #[error("building kustomize directory {0:?}: cancelled")]
    Cancelled(String),
}

/// Ported from the `Backend` interface in `interface.go`.
pub trait Backend {
    /// Renders a kustomize directory and returns the resulting YAML
    /// bytes.
    fn build(&self, dir: &str) -> Result<Vec<u8>, KustomizeError>;
}

/// Ported from `Client` in `client.go`.
///
/// Holds both a [`FileSystem`] (for staging a hermetic test directory
/// onto disk) and an [`xianyun_executor::exec::CommandRunner`] (to
/// invoke the real `kustomize` binary), matching the dependency-
/// injection convention every other backend in this crate already
/// follows (`docker::Client`, `git::Client`, `kubectl::Client`, ...).
pub struct Client {
    fsys: Arc<dyn FileSystem>,
    executor: Arc<dyn CommandRunner + Send + Sync>,
}

impl Client {
    /// Ported from `NewClient`. Go's zero-argument constructor defaults
    /// to the real on-disk filesystem; this port takes the filesystem
    /// and executor explicitly, matching `docker`/`git`/`kubectl::
    /// Client`'s constructor shape.
    pub fn new(fsys: Arc<dyn FileSystem>, executor: Arc<dyn CommandRunner + Send + Sync>) -> Self {
        Self::with_fs(fsys, executor)
    }

    /// Ported from `NewClientWithFS`. Panics if `fsys` construction
    /// yields a null pointer -- Go's `panic("filesystem cannot be nil")`
    /// has no direct Rust analogue since `Arc<dyn FileSystem>` cannot be
    /// null; callers wanting to exercise the "nil filesystem" case pass
    /// an `Option<Arc<dyn FileSystem>>` to [`Client::with_fs_option`]
    /// instead. See the ported `new_client_with_fs_nil_filesystem_panics`
    /// test.
    pub fn with_fs(
        fsys: Arc<dyn FileSystem>,
        executor: Arc<dyn CommandRunner + Send + Sync>,
    ) -> Self {
        Self { fsys, executor }
    }

    /// Ported from `NewClientWithFS`'s nil-check, for the one ported
    /// test that exercises it. Production code should call
    /// [`Client::with_fs`] directly with a non-optional `Arc`.
    #[must_use]
    pub fn with_fs_option(
        fsys: Option<Arc<dyn FileSystem>>,
        executor: Arc<dyn CommandRunner + Send + Sync>,
    ) -> Self {
        match fsys {
            Some(fsys) => Self { fsys, executor },
            None => panic!("filesystem cannot be nil"),
        }
    }

    /// A cancellation-aware variant of [`Backend::build`]. Go's
    /// `Client.Build` takes a `context.Context` and can abandon a build
    /// genuinely in flight (a blocked `FileSystem.ReadFile` call) as
    /// soon as the context is cancelled, without waiting for that call
    /// to return -- `TestClient_Build_cancellationUnblocksCaller` proves
    /// exactly this. `Backend::build`'s plain synchronous signature has
    /// no way to express that.
    ///
    /// Rather than make `Backend::build` `async` (a cross-crate
    /// breaking change `PORT_NOTES.md` already deferred) or add a new
    /// dependency for a cancellation-token type, this runs the real
    /// build on a background thread and polls a channel for its result
    /// while checking `cancelled` -- a plain `AtomicBool` is enough of
    /// a "cancellation token" here, and both are already in `std`. If
    /// `cancelled` flips to `true` before the background thread
    /// finishes, this returns [`KustomizeError::Cancelled`] immediately
    /// and *does not* wait for (or kill) the background thread, mirroring
    /// Go's abandoned-goroutine behaviour: the blocked `FileSystem` call
    /// keeps running until it unblocks on its own, but nothing is left
    /// waiting on it.
    pub fn build_cancellable(
        &self,
        dir: &str,
        cancelled: &std::sync::atomic::AtomicBool,
    ) -> Result<Vec<u8>, KustomizeError> {
        let worker = Self {
            fsys: Arc::clone(&self.fsys),
            executor: Arc::clone(&self.executor),
        };
        let dir_owned = dir.to_string();
        let (tx, rx) = std::sync::mpsc::channel();

        std::thread::spawn(move || {
            let _ = tx.send(worker.build(&dir_owned));
        });

        loop {
            match rx.recv_timeout(std::time::Duration::from_millis(5)) {
                Ok(result) => return result,
                Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
                    return Err(KustomizeError::Cancelled(dir.to_string()));
                }
                Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
                    if cancelled.load(std::sync::atomic::Ordering::SeqCst) {
                        return Err(KustomizeError::Cancelled(dir.to_string()));
                    }
                }
            }
        }
    }
}

/// A real, uniquely-named directory under the OS temp directory,
/// removed when dropped. Used to stage a [`FileSystem`]'s contents onto
/// disk so the real `kustomize` binary (which only reads from disk) can
/// build them.
///
/// Not built on the `tempfile` crate: `tempfile` is already a
/// `[dev-dependencies]` entry for this crate's tests (see `git::state`'s
/// integration tests), but promoting it to a runtime dependency here
/// would change this crate's resolved dependency graph in the root
/// `Cargo.lock` -- out of scope for this change. A process-id-plus-
/// counter-plus-timestamp suffix is enough entropy for a same-host temp
/// directory name.
struct StagingDir {
    path: std::path::PathBuf,
}

impl StagingDir {
    fn create() -> std::io::Result<Self> {
        use std::sync::atomic::{AtomicU64, Ordering};

        static COUNTER: AtomicU64 = AtomicU64::new(0);

        let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
        let nanos = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map_or(0, |d| d.as_nanos());
        let path = std::env::temp_dir().join(format!(
            "xianyun-kustomize-{}-{unique}-{nanos}",
            std::process::id(),
        ));

        std::fs::create_dir_all(&path)?;

        Ok(Self { path })
    }
}

impl Drop for StagingDir {
    fn drop(&mut self) {
        let _ = std::fs::remove_dir_all(&self.path);
    }
}

/// Stages every file [`FileSystem::walk`] finds under `dir` onto
/// `staging`, preserving each file's path relative to `dir`. The result
/// is a real on-disk mirror of whatever `dir` names in `fsys` -- the
/// real `kustomize` binary can then build `staging` directly.
fn stage_directory(
    fsys: &dyn FileSystem,
    dir: &str,
    staging: &std::path::Path,
) -> std::io::Result<()> {
    let dir_with_slash = format!("{}/", dir.trim_end_matches('/'));

    for file_path in fsys.walk(dir)? {
        let relative = file_path
            .strip_prefix(&dir_with_slash)
            .unwrap_or(&file_path)
            .trim_start_matches('/');

        let dest = staging.join(relative);
        if let Some(parent) = dest.parent() {
            std::fs::create_dir_all(parent)?;
        }

        let content = fsys.read_file(&file_path)?;
        std::fs::write(&dest, content)?;
    }

    Ok(())
}

impl Backend for Client {
    fn build(&self, dir: &str) -> Result<Vec<u8>, KustomizeError> {
        // Error messages carry the directory for context; a remote
        // target may embed git credentials, so they are stripped before
        // the path reaches any error -- ported from `client.go`'s
        // `redacted := RedactCredentials(dir)`.
        let redacted = remote::redact_credentials(dir);

        // A remote target (`file://...//overlay?ref=...`, `https://...`,
        // ...) is resolved by kustomize itself (shallow git clone
        // included): pass it straight through rather than routing it
        // through `FileSystem`/staging, which only understands local
        // paths.
        if remote::is_remote_target(dir) {
            return self.run_kustomize_build(dir, &redacted);
        }

        let staging = StagingDir::create().map_err(|err| {
            KustomizeError::BuildFailed(redacted.clone(), format!("staging build directory: {err}"))
        })?;

        stage_directory(self.fsys.as_ref(), dir, &staging.path).map_err(|err| {
            KustomizeError::BuildFailed(redacted.clone(), format!("reading kustomization: {err}"))
        })?;

        self.run_kustomize_build(&staging.path.to_string_lossy(), &redacted)
    }
}

impl Client {
    /// Invokes the real `kustomize build <target>` binary and returns
    /// its trimmed stdout, or a [`KustomizeError::BuildFailed`] carrying
    /// kustomize's own stderr diagnostics (not just an exit code) when
    /// the build fails.
    fn run_kustomize_build(&self, target: &str, redacted: &str) -> Result<Vec<u8>, KustomizeError> {
        let result = self.executor.run(
            "kustomize",
            &["build".to_string(), target.to_string()],
            Some(Options {
                disable_streaming: true,
                ..Default::default()
            }),
        );

        if let Some(error) = result.error {
            let stderr = result.stderr.join("\n");
            let detail = if stderr.is_empty() {
                error.to_string()
            } else {
                stderr
            };

            return Err(KustomizeError::BuildFailed(redacted.to_string(), detail));
        }

        let manifests = result.stdout.join("\n");

        Ok(manifests.trim().as_bytes().to_vec())
    }
}

#[cfg(test)]
pub(crate) mod fixtures {
    //! Ported from `fixtures_test.go`. `namePrefixKustomization` and
    //! `settings_config_map` form a minimal kustomization whose render
    //! proves a transformation ran: the emitted ConfigMap carries the
    //! `dev-` prefix only if kustomize actually built it. Shared by
    //! `client_test.go` and `remote_integration_test.go`'s Rust ports.

    pub(crate) const NAME_PREFIX_KUSTOMIZATION: &str =
        "\nnamePrefix: dev-\nresources:\n  - configmap.yaml\n";

    pub(crate) const SETTINGS_CONFIG_MAP: &str =
        "\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: settings\ndata:\n  key: value\n";

    /// Ported from `assertDevPrefixedConfigMap`. Go's version parses the
    /// rendered manifest as YAML and asserts on the decoded `kind`/
    /// `metadata.name` fields; no YAML crate is a dependency of this
    /// crate, so this checks the same facts as substrings of the
    /// rendered text instead.
    pub(crate) fn assert_dev_prefixed_config_map(manifests: &[u8], msg: &str) {
        let text = String::from_utf8(manifests.to_vec()).expect("manifests must be UTF-8");
        assert!(text.contains("kind: ConfigMap"), "{msg}");
        assert!(text.contains("name: dev-settings"), "{msg}");
    }
}

#[cfg(test)]
mod tests {
    use super::fixtures::{
        NAME_PREFIX_KUSTOMIZATION, SETTINGS_CONFIG_MAP, assert_dev_prefixed_config_map,
    };
    use super::*;
    use std::collections::HashMap;
    use std::sync::Mutex;

    #[test]
    fn disk_file_system_writes_reads_and_walks_real_directories() {
        let dir = tempfile::tempdir().unwrap();
        let fsys = DiskFileSystem;

        let file_path = dir.path().join("resources").join("configmap.yaml");
        std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
        fsys.write_file(file_path.to_str().unwrap(), SETTINGS_CONFIG_MAP.as_bytes())
            .unwrap();

        let read_back = fsys.read_file(file_path.to_str().unwrap()).unwrap();
        assert_eq!(read_back, SETTINGS_CONFIG_MAP.as_bytes());

        let walked = fsys.walk(dir.path().to_str().unwrap()).unwrap();
        assert_eq!(walked, vec![file_path.to_str().unwrap().to_string()]);
    }

    /// A minimal in-memory [`FileSystem`], standing in for
    /// `filesys.MakeFsInMemory()`.
    #[derive(Default)]
    struct InMemoryFs {
        files: Mutex<HashMap<String, Vec<u8>>>,
    }

    impl InMemoryFs {
        fn new() -> Self {
            Self::default()
        }
    }

    impl FileSystem for InMemoryFs {
        fn write_file(&self, path: &str, content: &[u8]) -> std::io::Result<()> {
            self.files
                .lock()
                .unwrap()
                .insert(path.to_string(), content.to_vec());
            Ok(())
        }

        fn read_file(&self, path: &str) -> std::io::Result<Vec<u8>> {
            self.files
                .lock()
                .unwrap()
                .get(path)
                .cloned()
                .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, path.to_string()))
        }

        fn walk(&self, dir: &str) -> std::io::Result<Vec<String>> {
            let prefix = format!("{}/", dir.trim_end_matches('/'));
            Ok(self
                .files
                .lock()
                .unwrap()
                .keys()
                .filter(|path| path.starts_with(&prefix))
                .cloned()
                .collect())
        }
    }

    /// A real (not mocked) [`CommandRunner`], since these tests exercise
    /// generator/replacement support that can only be validated against
    /// the actual `kustomize` binary's own YAML processing -- a
    /// `MockCommandRunner` would need to assert on a randomly-generated
    /// staging directory path it has no way to predict.
    fn real_executor() -> Arc<dyn CommandRunner + Send + Sync> {
        Arc::new(xianyun_executor::exec::Client::new())
    }

    fn client_with(fsys: Arc<dyn FileSystem>) -> Client {
        Client::with_fs(fsys, real_executor())
    }

    // --- Ported from client_test.go: TestClient_Build ---

    #[test]
    fn client_build() {
        let fsys = Arc::new(InMemoryFs::new());
        fsys.write_file(
            "/app/kustomization.yaml",
            NAME_PREFIX_KUSTOMIZATION.as_bytes(),
        )
        .unwrap();
        fsys.write_file("/app/configmap.yaml", SETTINGS_CONFIG_MAP.as_bytes())
            .unwrap();

        let client = client_with(fsys);

        let got = client.build("/app").unwrap();

        assert_dev_prefixed_config_map(&got, "the namePrefix transformation must be applied");
    }

    // --- New: secretGenerator/configMapGenerator/replacements support.
    // These were unreachable under the hand-rolled line-oriented
    // `Kustomization`/`Manifest` readers this `Client::build` used to
    // have (see git history) -- they only understood `namePrefix:` and
    // a flat `resources:` list. Shelling out to the real `kustomize`
    // binary handles them with no extra code in this crate at all. ---

    #[test]
    fn client_build_renders_secret_generator() {
        let fsys = Arc::new(InMemoryFs::new());
        fsys.write_file(
            "/app/kustomization.yaml",
            b"\
generatorOptions:
  disableNameSuffixHash: true
secretGenerator:
  - name: app-credentials
    literals:
      - username=admin
      - password=s3cr3t
",
        )
        .unwrap();

        let client = client_with(fsys);

        let got = client.build("/app").unwrap();
        let text = String::from_utf8(got).unwrap();

        assert!(text.contains("kind: Secret"), "got: {text}");
        assert!(text.contains("name: app-credentials"), "got: {text}");
        // Secret data is base64-encoded by kustomize; "admin" -> "YWRtaW4=".
        assert!(text.contains("username: YWRtaW4="), "got: {text}");
    }

    #[test]
    fn client_build_renders_config_map_generator() {
        let fsys = Arc::new(InMemoryFs::new());
        fsys.write_file(
            "/app/kustomization.yaml",
            b"\
generatorOptions:
  disableNameSuffixHash: true
configMapGenerator:
  - name: app-settings
    literals:
      - log_level=debug
",
        )
        .unwrap();

        let client = client_with(fsys);

        let got = client.build("/app").unwrap();
        let text = String::from_utf8(got).unwrap();

        assert!(text.contains("kind: ConfigMap"), "got: {text}");
        assert!(text.contains("name: app-settings"), "got: {text}");
        assert!(text.contains("log_level: debug"), "got: {text}");
    }

    #[test]
    fn client_build_renders_replacements() {
        let fsys = Arc::new(InMemoryFs::new());
        fsys.write_file(
            "/app/kustomization.yaml",
            b"\
resources:
  - configmap.yaml
  - deployment.yaml
replacements:
  - source:
      kind: ConfigMap
      name: settings
      fieldPath: data.image-tag
    targets:
      - select:
          kind: Deployment
          name: app
        fieldPaths:
          - spec.template.spec.containers.0.image
",
        )
        .unwrap();
        fsys.write_file(
            "/app/configmap.yaml",
            b"\
apiVersion: v1
kind: ConfigMap
metadata:
  name: settings
data:
  image-tag: v1.2.3
",
        )
        .unwrap();
        fsys.write_file(
            "/app/deployment.yaml",
            b"\
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  template:
    spec:
      containers:
        - name: app
          image: PLACEHOLDER
",
        )
        .unwrap();

        let client = client_with(fsys);

        let got = client.build("/app").unwrap();
        let text = String::from_utf8(got).unwrap();

        assert!(
            text.contains("image: v1.2.3"),
            "the replacement must substitute the ConfigMap's image tag into the Deployment: {text}"
        );
    }

    // --- Ported from client_test.go: TestClient_Build_errors ---

    struct BuildErrorCase {
        name: &'static str,
        dir: &'static str,
        files: &'static [(&'static str, &'static str)],
    }

    #[test]
    fn client_build_errors() {
        let cases = [
            BuildErrorCase {
                name: "missing kustomization",
                dir: "/does/not/exist",
                files: &[],
            },
            BuildErrorCase {
                name: "kustomization references missing resource",
                dir: "/app",
                files: &[("/app/kustomization.yaml", "resources:\n  - missing.yaml\n")],
            },
        ];

        for case in cases {
            let fsys = Arc::new(InMemoryFs::new());
            for (name, content) in case.files {
                fsys.write_file(name, content.as_bytes()).unwrap();
            }

            let client = client_with(fsys);

            let err = client.build(case.dir).unwrap_err();
            assert!(err.to_string().contains(case.dir), "{}", case.name);
        }
    }

    // --- Ported from client_test.go: TestClient_Build_appliesLegacyResourceOrder ---

    #[test]
    fn client_build_applies_legacy_resource_order() {
        let fsys = Arc::new(InMemoryFs::new());
        fsys.write_file(
            "/app/kustomization.yaml",
            b"\nresources:\n  - configmap.yaml\n  - namespace.yaml\n",
        )
        .unwrap();
        fsys.write_file(
            "/app/configmap.yaml",
            b"\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: settings\n  namespace: demo\n",
        )
        .unwrap();
        fsys.write_file(
            "/app/namespace.yaml",
            b"\napiVersion: v1\nkind: Namespace\nmetadata:\n  name: demo\n",
        )
        .unwrap();

        let client = client_with(fsys);

        let got = client.build("/app").unwrap();
        let text = String::from_utf8(got).unwrap();
        let first_doc = text.split("\n---\n").next().unwrap();

        assert!(
            first_doc.contains("kind: Namespace"),
            "the Namespace must be emitted before the resources it contains"
        );
    }

    // --- Ported from client_test.go: TestClient_Build_cancellationUnblocksCaller ---
    //
    // Go's `blockingFS` wraps a filesystem so `ReadFile` blocks on a
    // channel until released, letting the test synchronize on the build
    // being genuinely in flight before cancelling a `context.Context`.
    // Ported against `Client::build_cancellable`'s `&AtomicBool` token
    // (see its doc comment) instead of a `context.Context`; the same
    // "block until released, prove cancellation returns promptly without
    // waiting for the blocked call" shape survives the port.

    /// Ported from `blockingFS`: wraps a [`FileSystem`] so `read_file`
    /// signals `started_tx` on its first call (via `start_once`, the
    /// equivalent of Go's `sync.Once`), then blocks until a value is
    /// received on `release_rx`.
    struct BlockingFileSystem {
        inner: Arc<dyn FileSystem>,
        start_once: std::sync::Once,
        started_tx: Mutex<Option<std::sync::mpsc::Sender<()>>>,
        release_rx: Mutex<std::sync::mpsc::Receiver<()>>,
    }

    impl FileSystem for BlockingFileSystem {
        fn write_file(&self, path: &str, content: &[u8]) -> std::io::Result<()> {
            self.inner.write_file(path, content)
        }

        fn read_file(&self, path: &str) -> std::io::Result<Vec<u8>> {
            self.start_once.call_once(|| {
                if let Some(tx) = self.started_tx.lock().unwrap().take() {
                    let _ = tx.send(());
                }
            });

            // Blocks until the test releases it, same as Go's
            // `<-b.release`.
            let _ = self.release_rx.lock().unwrap().recv();

            self.inner.read_file(path)
        }

        // Enumeration itself doesn't block -- only `read_file` does, so
        // the "build genuinely in flight" signal still fires on the
        // first content read, same as before this `walk` passthrough
        // was added.
        fn walk(&self, dir: &str) -> std::io::Result<Vec<String>> {
            self.inner.walk(dir)
        }
    }

    #[test]
    fn client_build_cancellation_unblocks_caller() {
        let fsys = Arc::new(InMemoryFs::new());
        fsys.write_file("/app/kustomization.yaml", b"resources: []\n")
            .unwrap();

        let (started_tx, started_rx) = std::sync::mpsc::channel();
        let (release_tx, release_rx) = std::sync::mpsc::channel();

        let blocking_fs = Arc::new(BlockingFileSystem {
            inner: fsys,
            start_once: std::sync::Once::new(),
            started_tx: Mutex::new(Some(started_tx)),
            release_rx: Mutex::new(release_rx),
        });

        let client = client_with(blocking_fs);
        let cancelled = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));

        let (err_tx, err_rx) = std::sync::mpsc::channel();
        let cancelled_for_thread = std::sync::Arc::clone(&cancelled);
        std::thread::spawn(move || {
            let result = client.build_cancellable("/app", &cancelled_for_thread);
            let _ = err_tx.send(result);
        });

        started_rx
            .recv_timeout(std::time::Duration::from_secs(5))
            .expect("build never started reading the filesystem");

        cancelled.store(true, std::sync::atomic::Ordering::SeqCst);

        let result = err_rx
            .recv_timeout(std::time::Duration::from_secs(5))
            .expect("Build did not return after cancellation");

        let err = result.expect_err("a cancelled build must return an error");
        assert!(matches!(err, KustomizeError::Cancelled(ref dir) if dir == "/app"));
        assert!(err.to_string().contains("/app"));

        // Unblock the abandoned background thread so it doesn't leak
        // past the test.
        let _ = release_tx.send(());
    }

    // --- Ported from client_test.go: TestNewClientWithFS_nilFilesystemPanics ---

    #[test]
    #[should_panic(expected = "filesystem cannot be nil")]
    fn new_client_with_fs_nil_filesystem_panics() {
        let _ = Client::with_fs_option(None, real_executor());
    }
}