foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-26 00:59:24 -05:00
Code Issues Packages 1 Wiki Activity

docs: Improve inline docs for permissions (deno run --help) (#18757)

Browse source 
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
This commit is contained in:
Kevin Whinnery 2023-04-26 20:49:59 -04:00 committed by GitHub
parent 1054723a4b
commit a16ad526e9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 100 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

109
cli/args/flags.rs
View file

@ -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")