From a16ad526e94304063f8efba710503bfd288d0248 Mon Sep 17 00:00:00 2001 From: Kevin Whinnery Date: Wed, 26 Apr 2023 20:49:59 -0400 Subject: [PATCH] docs: Improve inline docs for permissions (deno run --help) (#18757) Hey there! I took a crack at improving these embedded docs [as requested here](https://github.com/denoland/deno/issues/18685). These should accurately reflect the functionality of the permission-related flags for `deno run`. ### Highlights * Adds human-readable argument string in the format [prescribed in the docs](https://docs.rs/clap/latest/clap/struct.Arg.html#method.value_name) * Keeps text description terse, but includes a relevant copy/pasteable docs link * Includes example argument usage/formatting --- cli/args/flags.rs | 109 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 100 insertions(+), 9 deletions(-) diff --git a/cli/args/flags.rs b/cli/args/flags.rs index 0efaa5ea3d..3d88cda913 100644 --- a/cli/args/flags.rs +++ b/cli/args/flags.rs @@ -1882,6 +1882,90 @@ fn compile_args_without_check_args(app: Command) -> Command { .arg(ca_file_arg()) } +static ALLOW_READ_HELP: &str = concat!( + "Allow file system read access. Optionally specify allowed paths.\n", + "Docs: https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n", + "Examples:\n", + " --allow-read\n", + " --allow-read=\"/etc,/var/log.txt\"" +); + +static ALLOW_WRITE_HELP: &str = concat!( + "Allow file system write access. Optionally specify allowed paths.\n", + "Docs: https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n", + "Examples:\n", + " --allow-write\n", + " --allow-write=\"/etc,/var/log.txt\"" +); + +static ALLOW_NET_HELP: &str = concat!( + "Allow network access. Optionally specify allowed IP addresses and host names, with ports as necessary.\n", + "Docs: https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n", + "Examples:\n", + " --allow-net\n", + " --allow-net=\"localhost:8080,deno.land\"" +); + +static ALLOW_ENV_HELP: &str = concat!( + "Allow access to system environment information. Optionally specify accessible environment variables.\n", + "Docs: https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n", + "Examples:\n", + " --allow-env\n", + " --allow-env=\"PORT,HOME,PATH\"" +); + +static ALLOW_SYS_HELP: &str = concat!( + "Allow access to OS information. Optionally allow specific APIs by function name.\n", + "Docs: https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n", + "Examples:\n", + " --allow-sys\n", + " --allow-sys=\"systemMemoryInfo,osRelease\"" +); + +static ALLOW_RUN_HELP: &str = concat!( + "Allow running subprocesses. Optionally specify allowed runnable program names.\n", + "Docs: https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n", + "Examples:\n", + " --allow-run\n", + " --allow-run=\"whoami,ps\"" +); + +static ALLOW_FFI_HELP: &str = concat!( + "(Unstable) Allow loading dynamic libraries. Optionally specify allowed directories or files.\n", + "Docs: https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n", + "Examples:\n", + " --allow-ffi\n", + " --allow-ffi=\"./libfoo.so\"" +); + +static ALLOW_HRTIME_HELP: &str = concat!( + "Allow high-resolution time measurement. Note: this can enable timing attacks and fingerprinting.\n", + "Docs: https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n" +); + +static ALLOW_ALL_HELP: &str = concat!( + "Allow all permissions. Learn more about permissions in Deno:\n", + "https://deno.land/manual@v", + env!("CARGO_PKG_VERSION"), + "/basics/permissions\n" +); + fn permission_args(app: Command) -> Command { app .arg( @@ -1890,7 +1974,8 @@ fn permission_args(app: Command) -> Command { .num_args(0..) .use_value_delimiter(true) .require_equals(true) - .help("Allow file system read access") + .value_name("PATH") + .help(ALLOW_READ_HELP) .value_parser(value_parser!(PathBuf)) .value_hint(ValueHint::AnyPath), ) @@ -1900,7 +1985,8 @@ fn permission_args(app: Command) -> Command { .num_args(0..) .use_value_delimiter(true) .require_equals(true) - .help("Allow file system write access") + .value_name("PATH") + .help(ALLOW_WRITE_HELP) .value_parser(value_parser!(PathBuf)) .value_hint(ValueHint::AnyPath), ) @@ -1910,7 +1996,8 @@ fn permission_args(app: Command) -> Command { .num_args(0..) .use_value_delimiter(true) .require_equals(true) - .help("Allow network access") + .value_name("IP_OR_HOSTNAME") + .help(ALLOW_NET_HELP) .value_parser(flags_allow_net::validator), ) .arg(unsafely_ignore_certificate_errors_arg()) @@ -1920,7 +2007,8 @@ fn permission_args(app: Command) -> Command { .num_args(0..) .use_value_delimiter(true) .require_equals(true) - .help("Allow environment access") + .value_name("VARIABLE_NAME") + .help(ALLOW_ENV_HELP) .value_parser(|key: &str| { if key.is_empty() || key.contains(&['=', '\0'] as &[char]) { return Err(format!("invalid key \"{key}\"")); @@ -1939,7 +2027,8 @@ fn permission_args(app: Command) -> Command { .num_args(0..) .use_value_delimiter(true) .require_equals(true) - .help("Allow access to system info") + .value_name("API_NAME") + .help(ALLOW_SYS_HELP) .value_parser(|key: &str| parse_sys_kind(key).map(ToString::to_string)), ) .arg( @@ -1948,7 +2037,8 @@ fn permission_args(app: Command) -> Command { .num_args(0..) .use_value_delimiter(true) .require_equals(true) - .help("Allow running subprocesses"), + .value_name("PROGRAM_NAME") + .help(ALLOW_RUN_HELP), ) .arg( Arg::new("allow-ffi") @@ -1956,7 +2046,8 @@ fn permission_args(app: Command) -> Command { .num_args(0..) .use_value_delimiter(true) .require_equals(true) - .help("Allow loading dynamic libraries") + .value_name("PATH") + .help(ALLOW_FFI_HELP) .value_parser(value_parser!(PathBuf)) .value_hint(ValueHint::AnyPath), ) @@ -1964,14 +2055,14 @@ fn permission_args(app: Command) -> Command { Arg::new("allow-hrtime") .long("allow-hrtime") .action(ArgAction::SetTrue) - .help("Allow high resolution time measurement"), + .help(ALLOW_HRTIME_HELP), ) .arg( Arg::new("allow-all") .short('A') .long("allow-all") .action(ArgAction::SetTrue) - .help("Allow all permissions"), + .help(ALLOW_ALL_HELP), ) .arg( Arg::new("prompt")