From f5cfe970e9892c5609bc00e2a589a14feca56fbc Mon Sep 17 00:00:00 2001 From: Tushar Singla Date: Sun, 11 Sep 2022 16:21:38 +0530 Subject: [PATCH 1/3] Adding Description for resource_download.rs --- docs/vmm-reference-resource-download.md | 112 ++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/vmm-reference-resource-download.md diff --git a/docs/vmm-reference-resource-download.md b/docs/vmm-reference-resource-download.md new file mode 100644 index 0000000..5486e6a --- /dev/null +++ b/docs/vmm-reference-resource-download.md @@ -0,0 +1,112 @@ +# [Resource Download](/vmm-reference/src/utils/src/resource_download.rs) + +`resource_download.rs` calls [s3_download.py](/vmm-reference/tests/tools/s3_download.py) to download a resource from resource_manifest.json + +``` rs +pub fn s3_download(r_type: &str, r_tags: Option<&str>) -> Result +``` + +1. `r_type`: argument for the type of the resource {"kernel, "core"} + +2. `r_tags`: Optional tags to filter the resources for example: "halt-after-boot: true", "image format: elf" etc. + +
+ +```rs +pub fn s3_download(r_type: &str, r_tags: Option<&str>) -> Result { + let dld_script = format!( + "{}/../../tests/tools/s3_download.py", + env!("CARGO_MANIFEST_DIR") + ); + + let output = Command::new(dld_script.as_str()) + .arg("-t") + .arg(r_type) + .arg("--tags") + .arg(r_tags.unwrap_or("{}")) + .arg("-1") + .output() + .expect("failed to execute process"); + + if !output.status.success() { + return Err(Error::DownloadError( + String::from_utf8(output.stderr).unwrap(), + )); + } + + let res: String = String::from_utf8(output.stdout) + .unwrap() + .split('\n') + .map(String::from) + .next() + .ok_or_else(|| Error::DownloadError(String::from("Not found.")))?; + Ok(PathBuf::from(res)) +} +``` + +1. `dld_script`: variable to store the relative path to s3_download.py + +2. `output`: store the output of the command run to download resources of the given type and according to the given tags + +3. if the download fails for some reason the function returns the error received + +4. if the download is a success the function returns the path of the result + +
+ +```rs +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_error_cases() { + assert!(matches!( + s3_download("", None).unwrap_err(), + Error::DownloadError(e) if e.contains("Missing required parameter") + )); + + assert!(matches!( + s3_download("random", None).unwrap_err(), + Error::DownloadError(e) if e.contains("No resources found") + )); + } +} +``` + +Unit test for checking cases when s3_download returns errors + +The above function checks for error in case of missing resource type parameter(which is a required parameter) and it also checks for error in case of no resource is found to download. + +
+ +## Usage + +1. Multiple usages in integration tests: vmm-reference/src/vmm/tests/integration_tests.rs + +```rs +fn test_dummy_vmm_elf() { + let tags = r#" + { + "halt_after_boot": true, + "image_format": "elf" + } + "#; + + let elf_halt = s3_download("kernel", Some(tags)).unwrap(); + run_vmm(elf_halt); +} +``` +2. Multiple Usages in vmm-reference/src/vmm/src/lib.rs + +```rs +fn default_bzimage_path() -> PathBuf { + let tags = r#" + { + "halt_after_boot": true, + "image_format": "bzimage" + } + "#; + s3_download("kernel", Some(tags)).unwrap() +} +``` \ No newline at end of file From 16c708da96362aad0da8413966fc745c3daaae40 Mon Sep 17 00:00:00 2001 From: Tushar Singla Date: Sun, 11 Sep 2022 16:27:37 +0530 Subject: [PATCH 2/3] Updates --- docs/vmm-reference-resource-download.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/vmm-reference-resource-download.md b/docs/vmm-reference-resource-download.md index 5486e6a..1d923cc 100644 --- a/docs/vmm-reference-resource-download.md +++ b/docs/vmm-reference-resource-download.md @@ -10,6 +10,8 @@ pub fn s3_download(r_type: &str, r_tags: Option<&str>) -> Result 2. `r_tags`: Optional tags to filter the resources for example: "halt-after-boot: true", "image format: elf" etc. +3. `Result`: Result is a type that returns type T value on success, type E error otherwise. +
```rs @@ -109,4 +111,4 @@ fn default_bzimage_path() -> PathBuf { "#; s3_download("kernel", Some(tags)).unwrap() } -``` \ No newline at end of file +``` From 54c4202c5a848726d4386ba636968fff89c3c227 Mon Sep 17 00:00:00 2001 From: Tushar Singla Date: Sun, 11 Sep 2022 16:55:33 +0530 Subject: [PATCH 3/3] Adding definition of DownloadError --- docs/vmm-reference-resource-download.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/vmm-reference-resource-download.md b/docs/vmm-reference-resource-download.md index 1d923cc..546c814 100644 --- a/docs/vmm-reference-resource-download.md +++ b/docs/vmm-reference-resource-download.md @@ -1,6 +1,15 @@ # [Resource Download](/vmm-reference/src/utils/src/resource_download.rs) -`resource_download.rs` calls [s3_download.py](/vmm-reference/tests/tools/s3_download.py) to download a resource from resource_manifest.json +`resource_download.rs` calls [s3_download.py](/vmm-reference/tests/tools/s3_download.py) to download a resource from resource_manifest.json, which can be found in /vmm-reference/tests/tools/s3 folder. + +```rs +pub enum Error { + DownloadError(String), +} +``` +Defining an enum for DownloadError that would be used to return error value in case resource download fails. + +
``` rs pub fn s3_download(r_type: &str, r_tags: Option<&str>) -> Result @@ -48,11 +57,11 @@ pub fn s3_download(r_type: &str, r_tags: Option<&str>) -> Result 1. `dld_script`: variable to store the relative path to s3_download.py -2. `output`: store the output of the command run to download resources of the given type and according to the given tags +2. `output`: store the output of the command run to download resources of the given type and according to the given tags, `Command` is an rust api for a process builder. 3. if the download fails for some reason the function returns the error received -4. if the download is a success the function returns the path of the result +4. if the download is a success the function returns the path of the resultant image, the path can be used to run the image. `PathBuf` is a rust struct to store mutable paths which can be dereferenced.