Merge pull request #509 from dgibson/frontend

Split CLI parsing front end into a separate crate

.gitignore

@@ -14,4 +14,6 @@ youki
 !youki/
 youki_integration_test
 
-.vscode
+.vscode
+
+*~

build.sh

@@ -1,20 +1,17 @@
 #!/bin/bash
 
+set -e
+
 TARGET=${TARGET-x86_64-unknown-linux-gnu}
 if [ "$TARGET" != "" ]; then
     TGT="--target $TARGET"
 fi
 VERSION=debug
-if [[ "$1" == "--release" ]]; then
+if [ "$1" == "--release" ]; then
     VERSION=release
 fi
 
 cargo build --verbose $TGT $1
-if [ ! -e ./youki ]; then
-    rm -f youki
-fi 
-if [ ! -e ./youki_integration_test ]; then
-    rm -f youki_integration_test
-fi
+
 cp target/$TARGET/$VERSION/youki .
 cp target/$TARGET/$VERSION/integration_test ./youki_integration_test

crates/liboci-cli/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "liboci-cli"
+version = "0.0.1"
+authors = ["youki team"]
+edition = "2021"
+description = "Parse command line arguments for OCI container runtimes"
+readme = "README.md"
+
+[dependencies.clap]
+version = "3.0.0-beta.5"
+default-features = false
+features = ["std", "suggestions", "derive", "cargo"]

crates/liboci-cli/README.md

@@ -0,0 +1,26 @@
+# liboci-cli
+
+This is a crate to parse command line arguments for OCI container
+runtimes as specified in the [OCI Runtime Command Line
+Interface][https://github.com/opencontainers/runtime-tools/blob/master/docs/command-line-interface.md).
+
+## Implemented subcommands
+
+| Command    | liboci-cli | CLI Specification | runc | crun | youki |
+| :--------: | :--------: | :---------------: | :--: | :--: | :---: |
+| create     | ✅         | ✅                | ✅   | ✅   | ✅    |
+| start      | ✅         | ✅                | ✅   | ✅   | ✅    |
+| state      | ✅         | ✅                | ✅   | ✅   | ✅    |
+| kill       | ✅         | ✅                | ✅   | ✅   | ✅    |
+| delete     | ✅         | ✅                | ✅   | ✅   | ✅    |
+| checkpoint |            |                   | ✅   | ✅   |       |
+| events     | ✅         |                   | ✅   |      | ✅    |
+| exec       | ✅         |                   | ✅   | ✅   | ✅    |
+| list       | ✅         |                   | ✅   | ✅   | ✅    |
+| pause      | ✅         |                   | ✅   | ✅   | ✅    |
+| ps         | ✅         |                   | ✅   | ✅   | ✅    |
+| restore    |            |                   | ✅   | ✅   |       |
+| resume     | ✅         |                   | ✅   | ✅   | ✅    |
+| run        | ✅         |                   | ✅   | ✅   | ✅    |
+| spec       | ✅         |                   | ✅   | ✅   | ✅    |
+| update     |            |                   | ✅   | ✅   |       |

crates/liboci-cli/src/create.rs

@@ -0,0 +1,24 @@
+//! Handles the creation of a new container
+use clap::Parser;
+use std::path::PathBuf;
+
+/// Create a container
+#[derive(Parser, Debug)]
+pub struct Create {
+    /// File to write pid of the container created
+    // note that in the end, container is just another process
+    #[clap(short, long)]
+    pub pid_file: Option<PathBuf>,
+    /// path to the bundle directory, containing config.json and root filesystem
+    #[clap(short, long, default_value = ".")]
+    pub bundle: PathBuf,
+    /// Unix socket (file) path , which will receive file descriptor of the writing end of the pseudoterminal
+    #[clap(short, long)]
+    pub console_socket: Option<PathBuf>,
+    /// Pass N additional file descriptors to the container (stdio + $LISTEN_FDS + N in total)
+    #[clap(long, default_value = "0")]
+    pub preserve_fds: i32,
+    /// name of the container instance to be started
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+}

crates/liboci-cli/src/delete.rs

@@ -0,0 +1,11 @@
+use clap::Parser;
+
+/// Release any resources held by the container
+#[derive(Parser, Debug)]
+pub struct Delete {
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+    /// forces deletion of the container if it is still running (using SIGKILL)
+    #[clap(short, long)]
+    pub force: bool,
+}

crates/liboci-cli/src/events.rs

@@ -0,0 +1,15 @@
+use clap::Parser;
+
+/// Show resource statistics for the container
+#[derive(Parser, Debug)]
+pub struct Events {
+    /// Sets the stats collection interval in seconds (default: 5s)
+    #[clap(long, default_value = "5")]
+    pub interval: u32,
+    /// Display the container stats only once
+    #[clap(long)]
+    pub stats: bool,
+    /// Name of the container instance
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+}

crates/liboci-cli/src/exec.rs

@@ -0,0 +1,51 @@
+use std::error::Error;
+use std::path::PathBuf;
+
+use clap::Parser;
+
+/// Execute a process within an existing container
+#[derive(Parser, Debug)]
+pub struct Exec {
+    /// Unix socket (file) path , which will receive file descriptor of the writing end of the pseudoterminal
+    #[clap(long)]
+    pub console_socket: Option<PathBuf>,
+    #[clap(short, long)]
+    pub tty: bool,
+    #[clap(long)]
+    /// Current working directory of the container
+    pub cwd: Option<PathBuf>,
+    #[clap(long)]
+    /// The file to which the pid of the container process should be written to
+    pub pid_file: Option<PathBuf>,
+    /// Environment variables that should be set in the container
+    #[clap(short, long, parse(try_from_str = parse_key_val), number_of_values = 1)]
+    pub env: Vec<(String, String)>,
+    /// Prevent the process from gaining additional privileges
+    #[clap(long)]
+    pub no_new_privs: bool,
+    /// Path to process.json
+    #[clap(short, long)]
+    pub process: Option<PathBuf>,
+    /// Detach from the container process
+    #[clap(short, long)]
+    pub detach: bool,
+    /// Identifier of the container
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+    /// Command that should be executed in the container
+    #[clap(required = false)]
+    pub command: Vec<String>,
+}
+
+fn parse_key_val<T, U>(s: &str) -> Result<(T, U), Box<dyn Error + Send + Sync + 'static>>
+where
+    T: std::str::FromStr,
+    T::Err: Error + Send + Sync + 'static,
+    U: std::str::FromStr,
+    U::Err: Error + Send + Sync + 'static,
+{
+    let pos = s
+        .find('=')
+        .ok_or_else(|| format!("invalid KEY=value: no `=` found in `{}`", s))?;
+    Ok((s[..pos].parse()?, s[pos + 1..].parse()?))
+}

crates/liboci-cli/src/info.rs

@@ -0,0 +1,5 @@
+use clap::Parser;
+
+/// Show information about the system
+#[derive(Parser, Debug)]
+pub struct Info {}

crates/liboci-cli/src/kill.rs

@@ -0,0 +1,9 @@
+use clap::Parser;
+
+/// Send the specified signal to the container
+#[derive(Parser, Debug)]
+pub struct Kill {
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+    pub signal: String,
+}

crates/liboci-cli/src/lib.rs

@@ -0,0 +1,79 @@
+use std::fmt::Debug;
+use std::path::PathBuf;
+
+use clap::Parser;
+
+// Subcommands that are specified in https://github.com/opencontainers/runtime-tools/blob/master/docs/command-line-interface.md
+
+mod create;
+mod delete;
+mod kill;
+mod start;
+mod state;
+
+pub use {create::Create, delete::Delete, kill::Kill, start::Start, state::State};
+
+// Other common subcommands that aren't specified in the document
+mod events;
+mod exec;
+mod list;
+mod pause;
+mod ps;
+mod resume;
+mod run;
+mod spec;
+
+pub use {
+    events::Events, exec::Exec, list::List, pause::Pause, ps::Ps, resume::Resume, run::Run,
+    spec::Spec,
+};
+
+// Subcommands parsed by liboci-cli, based on the [OCI
+// runtime-spec](https://github.com/opencontainers/runtime-spec/blob/master/runtime.md)
+// and specifically the [OCI Command Line
+// Interface](https://github.com/opencontainers/runtime-tools/blob/master/docs/command-line-interface.md)
+#[derive(Parser, Debug)]
+pub enum StandardCmd {
+    Create(Create),
+    Start(Start),
+    State(State),
+    Kill(Kill),
+    Delete(Delete),
+}
+
+// Extra subcommands not documented in the OCI Command Line Interface,
+// but found in
+// [runc](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)
+// and other runtimes.
+#[derive(Parser, Debug)]
+pub enum CommonCmd {
+    Events(Events),
+    Exec(Exec),
+    List(List),
+    Pause(Pause),
+    #[clap(setting=clap::AppSettings::AllowLeadingHyphen)]
+    Ps(Ps),
+    Resume(Resume),
+    Run(Run),
+    Spec(Spec),
+}
+
+// The OCI Command Line Interface document doesn't define any global
+// flags, but these are commonly accepted by runtimes
+#[derive(Parser, Debug)]
+pub struct GlobalOpts {
+    /// change log level to debug.
+    // Example in future : '--debug     change log level to debug. (default: "warn")'
+    #[clap(long)]
+    pub debug: bool,
+    #[clap(short, long)]
+    pub log: Option<PathBuf>,
+    #[clap(long)]
+    pub log_format: Option<String>,
+    /// root directory to store container state
+    #[clap(short, long)]
+    pub root: Option<PathBuf>,
+    /// Enable systemd cgroup manager, rather then use the cgroupfs directly.
+    #[clap(short, long)]
+    pub systemd_cgroup: bool,
+}

crates/liboci-cli/src/list.rs

@@ -0,0 +1,5 @@
+use clap::Parser;
+
+/// List created containers
+#[derive(Parser, Debug)]
+pub struct List {}

crates/liboci-cli/src/pause.rs

@@ -0,0 +1,8 @@
+use clap::Parser;
+
+/// Suspend the processes within the container
+#[derive(Parser, Debug)]
+pub struct Pause {
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+}

crates/liboci-cli/src/ps.rs

@@ -0,0 +1,14 @@
+use clap::{self, Parser};
+
+/// Display the processes inside the container
+#[derive(Parser, Debug)]
+pub struct Ps {
+    /// format to display processes: table or json (default: "table")
+    #[clap(short, long, default_value = "table")]
+    pub format: String,
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+    /// options will be passed to the ps utility
+    #[clap(setting = clap::ArgSettings::Last)]
+    pub ps_options: Vec<String>,
+}

crates/liboci-cli/src/resume.rs

@@ -0,0 +1,8 @@
+use clap::Parser;
+
+/// Resume the processes within the container
+#[derive(Parser, Debug)]
+pub struct Resume {
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+}

crates/liboci-cli/src/run.rs

@@ -0,0 +1,23 @@
+use clap::Parser;
+use std::path::PathBuf;
+
+/// Create a container and immediately start it
+#[derive(Parser, Debug)]
+pub struct Run {
+    /// File to write pid of the container created
+    // note that in the end, container is just another process
+    #[clap(short, long)]
+    pub pid_file: Option<PathBuf>,
+    /// path to the bundle directory, containing config.json and root filesystem
+    #[clap(short, long, default_value = ".")]
+    pub bundle: PathBuf,
+    /// Unix socket (file) path , which will receive file descriptor of the writing end of the pseudoterminal
+    #[clap(short, long)]
+    pub console_socket: Option<PathBuf>,
+    /// Pass N additional file descriptors to the container (stdio + $LISTEN_FDS + N in total)
+    #[clap(long, default_value = "0")]
+    pub preserve_fds: i32,
+    /// name of the container instance to be started
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+}

crates/liboci-cli/src/spec.rs

@@ -0,0 +1,9 @@
+use clap::Parser;
+
+/// Command generates a config.json
+#[derive(Parser, Debug)]
+pub struct Spec {
+    /// Generate a configuration for a rootless container
+    #[clap(long)]
+    pub rootless: bool,
+}

crates/liboci-cli/src/start.rs

@@ -0,0 +1,8 @@
+use clap::Parser;
+
+/// Start a previously created container
+#[derive(Parser, Debug)]
+pub struct Start {
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+}

crates/liboci-cli/src/state.rs

@@ -0,0 +1,8 @@
+use clap::Parser;
+
+/// Show the container state
+#[derive(Parser, Debug)]
+pub struct State {
+    #[clap(forbid_empty_values = true, required = true)]
+    pub container_id: String,
+}

crates/youki/Cargo.toml

@@ -16,6 +16,7 @@ anyhow = "1.0"
 chrono = { version="0.4", features = ["serde"] }
 libcgroups = { path = "../libcgroups" }
 libcontainer = { path = "../libcontainer" }
+liboci-cli = { path = "../liboci-cli" }
 log = {version = "0.4", features = ["std"]}
 nix = "0.23.0"
 oci-spec = { git = "https://github.com/containers/oci-spec-rs",  rev = "d6fb1e91742313cd0d0085937e2d6df5d4669720" }