Skip to main content

gadk_cli/
stage.rs

1// Copyright 2026 Chris Olson
2// Portions derived from ADK-Go (https://github.com/google/adk-go), Copyright 2026 Google LLC.
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8//     http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16//! The build context a deploy ships: the two-stage Dockerfile's text, the staged source
17//! tree (copy and archive) and the temp-dir helper (a `<prefix>YYYYMMDD_HHMMSS__*`
18//! directory).
19
20use std::ffi::OsStr;
21use std::fs::{self, DirBuilder, File};
22use std::hash::{BuildHasher, RandomState};
23use std::io::{self, Write};
24use std::os::unix::fs::DirBuilderExt;
25use std::path::{Path, PathBuf};
26
27use chrono::{DateTime, Local, Utc};
28use flate2::Compression;
29use flate2::write::GzEncoder;
30use tar::{Builder, Header, HeaderMode};
31
32/// The runtime image (glibc, Debian 12 like the `rust:*-bookworm` builder).
33pub const RUNTIME_IMAGE: &str = "gcr.io/distroless/cc-debian12";
34/// The builder's `cargo build --target-dir`.
35pub const TARGET_DIR: &str = "/gadk-target";
36
37/// The builder stage of the generated Dockerfile.
38#[derive(Debug, Clone, Default, PartialEq, Eq)]
39pub struct BuilderStage {
40    /// `rust:<ver>-bookworm` or `rust:bookworm` ([`crate::target::builder_image`]).
41    pub image: String,
42    /// The workspace root relative to the staged root (`""` for Cloud Run): `WORKDIR /app/<workdir>`.
43    pub workdir: String,
44    /// `cargo build -p <package>`.
45    pub package: String,
46    /// `cargo build --bin <bin>`; the runtime stage's `/app/<bin>`.
47    pub bin: String,
48}
49
50/// The whole Dockerfile, starting with a leading newline: the builder stage, the
51/// distroless runtime stage, `EXPOSE <server_port>`, a comment and
52/// `CMD ["/app/<bin>", "web", "-host", "0.0.0.0", "-port", "<server_port>"` + `cmd_tail` + `]`
53/// (`cmd_tail` is a segment list, each starting `, `).
54// The build happens remotely in a `rust:<ver>-bookworm` stage
55// (`cargo build --release --locked --target-dir /gadk-target -p <pkg> --bin <bin>`, the
56// whole staged root copied to `/app/`) and the image runs on `distroless/cc-debian12`. The
57// runtime stage's `EXPOSE`, comment and `CMD` match ADK's generated Dockerfile.
58pub fn dockerfile(builder: &BuilderStage, server_port: i64, cmd_tail: &str) -> String {
59    let BuilderStage {
60        image,
61        workdir,
62        package,
63        bin,
64    } = builder;
65    format!(
66        "
67FROM {image} AS builder
68WORKDIR /app/{workdir}
69COPY . /app/
70RUN cargo build --release --locked --target-dir {TARGET_DIR} -p {package} --bin {bin}
71
72FROM {RUNTIME_IMAGE}
73
74COPY --from=builder {TARGET_DIR}/release/{bin}  /app/{bin}
75EXPOSE {server_port}
76# Command to run the executable when the container starts
77CMD [\"/app/{bin}\", \"web\", \"-host\", \"0.0.0.0\", \"-port\", \"{server_port}\"{cmd_tail}]"
78    )
79}
80
81/// What a [`SourceTree`] entry is.
82#[derive(Debug, Clone, Copy, PartialEq, Eq)]
83pub enum EntryKind {
84    Dir,
85    File,
86    Symlink,
87}
88
89/// One staged path, relative to the tree's root.
90#[derive(Debug, Clone, PartialEq, Eq)]
91pub struct Entry {
92    pub path: PathBuf,
93    pub kind: EntryKind,
94}
95
96/// The files of a source root in sorted path order, without `.git`, `target` (at any depth)
97/// and the excluded paths.
98#[derive(Debug, Clone, Default, PartialEq, Eq)]
99pub struct SourceTree {
100    pub root: PathBuf,
101    pub entries: Vec<Entry>,
102}
103
104/// Names never staged, at any depth: VCS data (`.git`) and Cargo build output.
105// `.git` and `target` are excluded at any depth. Cloud Run sources are staged too: no
106// prebuilt binary is uploaded.
107const EXCLUDED_NAMES: [&str; 2] = [".git", "target"];
108
109impl SourceTree {
110    /// Walks `root`, skipping `.git` and `target` at any depth and every absolute path in
111    /// `exclude` (the temp dir when nested; the root `Dockerfile` for an archive). Entries are
112    /// sorted by path (component-wise); symbolic links are recorded as links and not followed
113    /// (as `tar` and `gcloud`'s upload do); other special files are skipped.
114    pub fn walk(root: &Path, exclude: &[PathBuf]) -> io::Result<SourceTree> {
115        let mut entries = Vec::new();
116        walk_dir(root, Path::new(""), exclude, &mut entries)?;
117        Ok(SourceTree {
118            root: root.to_path_buf(),
119            entries,
120        })
121    }
122
123    /// Copies the entries under `dir`: directories created, files copied with their
124    /// permissions, symbolic links recreated with the same target.
125    pub fn copy_into(&self, dir: &Path) -> io::Result<()> {
126        for entry in &self.entries {
127            let src = self.root.join(&entry.path);
128            let dst = dir.join(&entry.path);
129            match entry.kind {
130                EntryKind::Dir => fs::create_dir_all(&dst)?,
131                EntryKind::File => {
132                    fs::copy(&src, &dst)?;
133                }
134                EntryKind::Symlink => std::os::unix::fs::symlink(fs::read_link(&src)?, &dst)?,
135            }
136        }
137        Ok(())
138    }
139
140    /// Writes a gzip tar of the entries in order at `path`, then each `extra` `(name, bytes)`
141    /// file at the archive root (the generated `Dockerfile` last).
142    // The archive is written in-process: sorted entries without a `./` prefix, deterministic
143    // headers (fixed mtime, uid/gid 0, mode 0644/0755), the extra files appended last.
144    pub fn write_tar_gz(&self, path: &Path, extra: &[(&str, &[u8])]) -> io::Result<()> {
145        let mut tar = Builder::new(GzEncoder::new(File::create(path)?, Compression::default()));
146        tar.mode(HeaderMode::Deterministic);
147        tar.follow_symlinks(false);
148        for entry in &self.entries {
149            tar.append_path_with_name(self.root.join(&entry.path), &entry.path)?;
150        }
151        for (name, data) in extra {
152            let mut header = Header::new_gnu();
153            header.set_size(data.len() as u64);
154            header.set_mode(0o644);
155            header.set_mtime(tar::DETERMINISTIC_TIMESTAMP);
156            header.set_cksum();
157            tar.append_data(&mut header, name, *data)?;
158        }
159        let mut file = tar.into_inner()?.finish()?;
160        file.flush()
161    }
162}
163
164/// Appends the sorted entries of `root/rel` (recursively) to `out`.
165fn walk_dir(root: &Path, rel: &Path, exclude: &[PathBuf], out: &mut Vec<Entry>) -> io::Result<()> {
166    let mut children: Vec<(PathBuf, fs::FileType)> = fs::read_dir(root.join(rel))?
167        .map(|e| e.and_then(|e| Ok((rel.join(e.file_name()), e.file_type()?))))
168        .collect::<io::Result<_>>()?;
169    children.sort_by(|a, b| a.0.cmp(&b.0));
170    for (path, file_type) in children {
171        let name = path.file_name().unwrap_or(OsStr::new(""));
172        if EXCLUDED_NAMES.iter().any(|n| name == *n) || exclude.contains(&root.join(&path)) {
173            continue;
174        }
175        if file_type.is_symlink() {
176            out.push(Entry {
177                path,
178                kind: EntryKind::Symlink,
179            });
180        } else if file_type.is_dir() {
181            out.push(Entry {
182                path: path.clone(),
183                kind: EntryKind::Dir,
184            });
185            walk_dir(root, &path, exclude, out)?;
186        } else if file_type.is_file() {
187            out.push(Entry {
188                path,
189                kind: EntryKind::File,
190            });
191        }
192    }
193    Ok(())
194}
195
196/// A new directory under `base` named `<prefix>YYYYMMDD_HHMMSS__<random>` with
197/// `now` in local time (`chrono::Local`); returns the created directory (mode 0700, a
198/// random decimal suffix, retried on a name clash up to 10000 attempts).
199pub fn make_temp(base: &Path, prefix: &str, now: DateTime<Utc>) -> io::Result<PathBuf> {
200    let stamp = now.with_timezone(&Local).format("%Y%m%d_%H%M%S__");
201    let random = RandomState::new();
202    let mut builder = DirBuilder::new();
203    builder.mode(0o700);
204    for attempt in 0u64..10_000 {
205        // The decimal form of a random uint32.
206        let suffix = random.hash_one(attempt) as u32;
207        let dir = base.join(format!("{prefix}{stamp}{suffix}"));
208        match builder.create(&dir) {
209            Ok(()) => return Ok(dir),
210            Err(e) if e.kind() == io::ErrorKind::AlreadyExists => continue,
211            Err(e) => return Err(e),
212        }
213    }
214    Err(io::Error::new(
215        io::ErrorKind::AlreadyExists,
216        format!(
217            "mkdirtemp {}: file exists",
218            base.join(format!("{prefix}{stamp}*")).display()
219        ),
220    ))
221}
222
223#[cfg(test)]
224mod tests {
225    use std::fs;
226    use std::io::Read;
227    use std::os::unix::fs::{PermissionsExt, symlink};
228    use std::path::{Path, PathBuf};
229
230    use chrono::{DateTime, Local, Utc};
231    use flate2::read::GzDecoder;
232    use pretty_assertions::assert_eq;
233
234    use super::*;
235    use crate::testutil::default_now;
236
237    #[test]
238    fn dockerfile_golden_cloud_run_shape() {
239        let builder = BuilderStage {
240            image: "rust:1.99.1-bookworm".into(),
241            workdir: String::new(),
242            package: "my-agent".into(),
243            bin: "agent".into(),
244        };
245        let tail = r#", "api", "-webui_address", "127.0.0.1:8081", "a2a", "--a2a_agent_url", "http://127.0.0.1:8081", "webui", "--api_server_address", "http://127.0.0.1:8081/api""#;
246
247        let got = dockerfile(&builder, 8080, tail);
248
249        assert_eq!(
250            got,
251            r#"
252FROM rust:1.99.1-bookworm AS builder
253WORKDIR /app/
254COPY . /app/
255RUN cargo build --release --locked --target-dir /gadk-target -p my-agent --bin agent
256
257FROM gcr.io/distroless/cc-debian12
258
259COPY --from=builder /gadk-target/release/agent  /app/agent
260EXPOSE 8080
261# Command to run the executable when the container starts
262CMD ["/app/agent", "web", "-host", "0.0.0.0", "-port", "8080", "api", "-webui_address", "127.0.0.1:8081", "a2a", "--a2a_agent_url", "http://127.0.0.1:8081", "webui", "--api_server_address", "http://127.0.0.1:8081/api"]"#
263        );
264    }
265
266    #[test]
267    fn dockerfile_golden_agent_engine_shape() {
268        let builder = BuilderStage {
269            image: "rust:bookworm".into(),
270            workdir: "ws".into(),
271            package: "agent".into(),
272            bin: "agent".into(),
273        };
274
275        let got = dockerfile(&builder, 9090, r#", "agentengine""#);
276
277        assert_eq!(
278            got,
279            r#"
280FROM rust:bookworm AS builder
281WORKDIR /app/ws
282COPY . /app/
283RUN cargo build --release --locked --target-dir /gadk-target -p agent --bin agent
284
285FROM gcr.io/distroless/cc-debian12
286
287COPY --from=builder /gadk-target/release/agent  /app/agent
288EXPOSE 9090
289# Command to run the executable when the container starts
290CMD ["/app/agent", "web", "-host", "0.0.0.0", "-port", "9090", "agentengine"]"#
291        );
292    }
293
294    #[test]
295    fn dockerfile_without_tail_closes_the_cmd_array() {
296        let got = dockerfile(&BuilderStage::default(), 8080, "");
297
298        assert!(
299            got.ends_with(r#"CMD ["/app/", "web", "-host", "0.0.0.0", "-port", "8080"]"#),
300            "{got}"
301        );
302    }
303
304    /// A source root:
305    /// ```text
306    /// Cargo.lock, Cargo.toml, Dockerfile, README -> Cargo.toml (symlink), a.txt,
307    /// a/b.rs, .git/HEAD, target/debug/x, crates/c/{Cargo.toml, Dockerfile, .git (file),
308    /// target/y, src/main.rs (0755)}, tmp/cloudrun_x/staged, empty/
309    /// ```
310    fn source_root() -> tempfile::TempDir {
311        let dir = tempfile::tempdir().unwrap();
312        let r = dir.path();
313        for d in [
314            ".git",
315            "target/debug",
316            "a",
317            "crates/c/src",
318            "crates/c/target",
319            "tmp/cloudrun_x",
320            "empty",
321        ] {
322            fs::create_dir_all(r.join(d)).unwrap();
323        }
324        for (f, body) in [
325            ("Cargo.toml", "[workspace]\n"),
326            ("Cargo.lock", "version = 4\n"),
327            ("Dockerfile", "FROM user\n"),
328            ("a.txt", "a\n"),
329            ("a/b.rs", "b\n"),
330            (".git/HEAD", "ref\n"),
331            ("target/debug/x", "x\n"),
332            ("crates/c/Cargo.toml", "[package]\n"),
333            ("crates/c/Dockerfile", "FROM nested\n"),
334            ("crates/c/.git", "gitdir: x\n"),
335            ("crates/c/target/y", "y\n"),
336            ("crates/c/src/main.rs", "fn main() {}\n"),
337            ("tmp/cloudrun_x/staged", "s\n"),
338        ] {
339            fs::write(r.join(f), body).unwrap();
340        }
341        fs::set_permissions(
342            r.join("crates/c/src/main.rs"),
343            fs::Permissions::from_mode(0o755),
344        )
345        .unwrap();
346        symlink("Cargo.toml", r.join("README")).unwrap();
347        dir
348    }
349
350    fn entry(path: &str, kind: EntryKind) -> Entry {
351        Entry {
352            path: PathBuf::from(path),
353            kind,
354        }
355    }
356
357    #[test]
358    fn walk_sorts_and_excludes() {
359        let dir = source_root();
360        let r = dir.path();
361
362        let tree = SourceTree::walk(r, &[r.join("tmp/cloudrun_x"), r.join("Dockerfile")]).unwrap();
363
364        assert_eq!(tree.root, r);
365        assert_eq!(
366            tree.entries,
367            vec![
368                entry("Cargo.lock", EntryKind::File),
369                entry("Cargo.toml", EntryKind::File),
370                entry("README", EntryKind::Symlink),
371                entry("a", EntryKind::Dir),
372                entry("a/b.rs", EntryKind::File),
373                entry("a.txt", EntryKind::File),
374                entry("crates", EntryKind::Dir),
375                entry("crates/c", EntryKind::Dir),
376                entry("crates/c/Cargo.toml", EntryKind::File),
377                entry("crates/c/Dockerfile", EntryKind::File),
378                entry("crates/c/src", EntryKind::Dir),
379                entry("crates/c/src/main.rs", EntryKind::File),
380                entry("empty", EntryKind::Dir),
381                entry("tmp", EntryKind::Dir),
382            ]
383        );
384    }
385
386    #[test]
387    fn walk_without_excludes_keeps_the_root_dockerfile() {
388        let dir = source_root();
389        let r = dir.path();
390
391        let tree = SourceTree::walk(r, &[]).unwrap();
392        let paths: Vec<&Path> = tree.entries.iter().map(|e| e.path.as_path()).collect();
393
394        assert!(paths.contains(&Path::new("Dockerfile")));
395        assert!(paths.contains(&Path::new("tmp/cloudrun_x/staged")));
396        assert!(
397            !paths
398                .iter()
399                .any(|p| p.starts_with(".git") || p.starts_with("target"))
400        );
401    }
402
403    #[test]
404    fn walk_of_a_missing_root_is_an_error() {
405        let dir = tempfile::tempdir().unwrap();
406
407        assert!(SourceTree::walk(&dir.path().join("missing"), &[]).is_err());
408    }
409
410    #[test]
411    fn copy_into_reproduces_the_tree() {
412        let dir = source_root();
413        let r = dir.path();
414        let out = tempfile::tempdir().unwrap();
415        let tree = SourceTree::walk(r, &[r.join("tmp/cloudrun_x")]).unwrap();
416
417        tree.copy_into(out.path()).unwrap();
418
419        let copied = SourceTree::walk(out.path(), &[]).unwrap();
420        assert_eq!(copied.entries, tree.entries);
421        assert_eq!(
422            fs::read_to_string(out.path().join("crates/c/src/main.rs")).unwrap(),
423            "fn main() {}\n"
424        );
425        assert_eq!(
426            fs::metadata(out.path().join("crates/c/src/main.rs"))
427                .unwrap()
428                .permissions()
429                .mode()
430                & 0o777,
431            0o755
432        );
433        assert_eq!(
434            fs::read_link(out.path().join("README")).unwrap(),
435            PathBuf::from("Cargo.toml")
436        );
437        assert_eq!(
438            fs::read_to_string(out.path().join("Dockerfile")).unwrap(),
439            "FROM user\n"
440        );
441        assert!(out.path().join("empty").is_dir());
442    }
443
444    /// `(name, entry type, mode, mtime, contents)` of every archive member, in order.
445    fn read_archive(path: &Path) -> Vec<(String, tar::EntryType, u32, u64, String)> {
446        let mut archive = tar::Archive::new(GzDecoder::new(fs::File::open(path).unwrap()));
447        archive
448            .entries()
449            .unwrap()
450            .map(|e| {
451                let mut e = e.unwrap();
452                let name = e.path().unwrap().to_string_lossy().into_owned();
453                let header = e.header().clone();
454                let mut body = String::new();
455                e.read_to_string(&mut body).unwrap();
456                (
457                    name,
458                    header.entry_type(),
459                    header.mode().unwrap(),
460                    header.mtime().unwrap(),
461                    body,
462                )
463            })
464            .collect()
465    }
466
467    #[test]
468    fn write_tar_gz_sorted_entries_then_extra_files() {
469        let dir = source_root();
470        let r = dir.path();
471        let out = tempfile::tempdir().unwrap();
472        let archive = out.path().join("archive.tgz");
473        let tree = SourceTree::walk(r, &[r.join("tmp/cloudrun_x"), r.join("Dockerfile")]).unwrap();
474
475        tree.write_tar_gz(&archive, &[("Dockerfile", b"\nFROM generated")])
476            .unwrap();
477
478        let members = read_archive(&archive);
479        let names: Vec<&str> = members.iter().map(|m| m.0.as_str()).collect();
480        assert_eq!(
481            names,
482            vec![
483                "Cargo.lock",
484                "Cargo.toml",
485                "README",
486                "a",
487                "a/b.rs",
488                "a.txt",
489                "crates",
490                "crates/c",
491                "crates/c/Cargo.toml",
492                "crates/c/Dockerfile",
493                "crates/c/src",
494                "crates/c/src/main.rs",
495                "empty",
496                "tmp",
497                "Dockerfile",
498            ]
499        );
500        let by_name = |n: &str| members.iter().find(|m| m.0 == n).unwrap().clone();
501        let readme = by_name("README");
502        assert_eq!(readme.1, tar::EntryType::Symlink);
503        let main = by_name("crates/c/src/main.rs");
504        assert_eq!((main.2, main.3), (0o755, tar::DETERMINISTIC_TIMESTAMP));
505        assert_eq!(main.4, "fn main() {}\n");
506        assert_eq!(by_name("Cargo.toml").2, 0o644);
507        assert_eq!(by_name("a").1, tar::EntryType::Directory);
508        let dockerfile = members.last().unwrap();
509        assert_eq!(
510            dockerfile,
511            &(
512                "Dockerfile".to_string(),
513                tar::EntryType::Regular,
514                0o644,
515                tar::DETERMINISTIC_TIMESTAMP,
516                "\nFROM generated".to_string()
517            )
518        );
519    }
520
521    #[test]
522    fn make_temp_uses_go_pattern_in_local_time() {
523        let base = tempfile::tempdir().unwrap();
524        let now: DateTime<Utc> = default_now();
525
526        let a = make_temp(base.path(), "cloudrun_", now).unwrap();
527        let b = make_temp(base.path(), "cloudrun_", now).unwrap();
528
529        let prefix = format!(
530            "cloudrun_{}",
531            now.with_timezone(&Local).format("%Y%m%d_%H%M%S__")
532        );
533        for dir in [&a, &b] {
534            assert_eq!(dir.parent(), Some(base.path()));
535            let name = dir.file_name().unwrap().to_string_lossy().into_owned();
536            let suffix = name
537                .strip_prefix(&prefix)
538                .unwrap_or_else(|| panic!("{name}"));
539            assert!(
540                !suffix.is_empty() && suffix.bytes().all(|c| c.is_ascii_digit()),
541                "{name}"
542            );
543            let meta = fs::metadata(dir).unwrap();
544            assert!(meta.is_dir());
545            assert_eq!(meta.permissions().mode() & 0o777, 0o700);
546        }
547        assert_ne!(a, b);
548    }
549
550    #[test]
551    fn make_temp_in_a_missing_base_is_an_error() {
552        let base = tempfile::tempdir().unwrap();
553
554        let err =
555            make_temp(&base.path().join("missing"), "agentEngine_", default_now()).unwrap_err();
556
557        assert_eq!(err.kind(), std::io::ErrorKind::NotFound);
558    }
559}