From a851b6597f7e37d12f9e4632945e8466800eb5ff Mon Sep 17 00:00:00 2001 From: Tony <68118705+Legend-Master@users.noreply.github.com> Date: Sun, 23 Mar 2025 21:35:45 +0800 Subject: [PATCH] enhance: include permission group permissions in the generated schema (#13057) * enhance: include permissions in default permission description * Only include in schema * Remove 'which includes` to tauri's build script * Also bump utils * Clippy My local clippy didn't report this, weird * Use `which enables all commands` for default permissions that enables everything * Extract description into a variable * Generate permissions with or without description * Tweak the docs and generate 'which includes' * Simplify to just `includes` * Docs change change file * Put the change in minor * Update .changes/include-permissions-in-schema.md Co-authored-by: Amr Bashir * Remove unused change file --------- Co-authored-by: Amr Bashir --- .changes/include-permissions-in-schema.md | 6 ++ crates/tauri-utils/src/acl/build.rs | 5 +- crates/tauri-utils/src/acl/schema.rs | 60 ++++++++++++++++++- crates/tauri/build.rs | 28 ++++----- .../app/autogenerated/reference.md | 2 + .../event/autogenerated/reference.md | 4 +- .../image/autogenerated/reference.md | 4 +- .../menu/autogenerated/reference.md | 4 +- .../path/autogenerated/reference.md | 4 +- .../resources/autogenerated/reference.md | 4 +- .../tray/autogenerated/reference.md | 4 +- .../webview/autogenerated/reference.md | 2 + .../window/autogenerated/reference.md | 2 + .../permissions/schemas/schema.json | 12 ++-- 14 files changed, 112 insertions(+), 29 deletions(-) create mode 100644 .changes/include-permissions-in-schema.md diff --git a/.changes/include-permissions-in-schema.md b/.changes/include-permissions-in-schema.md new file mode 100644 index 000000000..e6eb00f74 --- /dev/null +++ b/.changes/include-permissions-in-schema.md @@ -0,0 +1,6 @@ +--- +tauri: minor:enhance +tauri-utils: minor:enhance +--- + +Enhanced the description of generated docs and schema for permission sets to include list of permissions within. diff --git a/crates/tauri-utils/src/acl/build.rs b/crates/tauri-utils/src/acl/build.rs index ed7eec0cc..701843d11 100644 --- a/crates/tauri-utils/src/acl/build.rs +++ b/crates/tauri-utils/src/acl/build.rs @@ -356,9 +356,10 @@ pub fn generate_docs( default_permission.push_str(default.description.as_deref().unwrap_or_default()); default_permission.push('\n'); default_permission.push('\n'); + default_permission.push_str("#### This default permission set includes the following:\n"); + default_permission.push('\n'); for permission in &default.permissions { - default_permission.push_str(&format!("- `{permission}`")); - default_permission.push('\n'); + default_permission.push_str(&format!("- `{permission}`\n")); } } diff --git a/crates/tauri-utils/src/acl/schema.rs b/crates/tauri-utils/src/acl/schema.rs index 24cc07de6..2682b5603 100644 --- a/crates/tauri-utils/src/acl/schema.rs +++ b/crates/tauri-utils/src/acl/schema.rs @@ -42,6 +42,9 @@ pub trait PermissionSchemaGenerator< /// Default permission set description if any. fn default_set_description(&self) -> Option<&str>; + /// Default permission set's permissions if any. + fn default_set_permissions(&self) -> Option<&Vec>; + /// Permissions sets to generate schema for. fn permission_sets(&'a self) -> Ps; @@ -56,6 +59,18 @@ pub trait PermissionSchemaGenerator< _ => id.to_string(), }; + let extensions = if let Some(description) = description { + [( + // This is non-standard, and only used by vscode right now, + // but it does work really well + "markdownDescription".to_string(), + serde_json::Value::String(description.to_string()), + )] + .into() + } else { + Default::default() + }; + Schema::Object(SchemaObject { metadata: Some(Box::new(Metadata { description: description.map(ToString::to_string), @@ -63,6 +78,7 @@ pub trait PermissionSchemaGenerator< })), instance_type: Some(InstanceType::String.into()), const_value: Some(serde_json::Value::String(command_name)), + extensions, ..Default::default() }) } @@ -73,13 +89,22 @@ pub trait PermissionSchemaGenerator< // schema for default set if self.has_default_permission_set() { - let default = Self::perm_id_schema(name, "default", self.default_set_description()); - permission_schemas.push(default); + let description = self.default_set_description().unwrap_or_default(); + let description = if let Some(permissions) = self.default_set_permissions() { + add_permissions_to_description(description, permissions, true) + } else { + description.to_string() + }; + if !description.is_empty() { + let default = Self::perm_id_schema(name, "default", Some(&description)); + permission_schemas.push(default); + } } // schema for each permission set for set in self.permission_sets() { - let schema = Self::perm_id_schema(name, &set.identifier, Some(&set.description)); + let description = add_permissions_to_description(&set.description, &set.permissions, false); + let schema = Self::perm_id_schema(name, &set.identifier, Some(&description)); permission_schemas.push(schema); } @@ -93,6 +118,27 @@ pub trait PermissionSchemaGenerator< } } +fn add_permissions_to_description( + description: &str, + permissions: &[String], + is_default: bool, +) -> String { + if permissions.is_empty() { + return description.to_string(); + } + let permissions_list = permissions + .iter() + .map(|permission| format!("- `{permission}`")) + .collect::>() + .join("\n"); + let default_permission_set = if is_default { + "default permission set" + } else { + "permission set" + }; + format!("{description}\n#### This {default_permission_set} includes:\n\n{permissions_list}") +} + impl<'a> PermissionSchemaGenerator< 'a, @@ -111,6 +157,10 @@ impl<'a> .map(|d| d.description.as_str()) } + fn default_set_permissions(&self) -> Option<&Vec> { + self.default_permission.as_ref().map(|d| &d.permissions) + } + fn permission_sets(&'a self) -> Values<'a, std::string::String, PermissionSet> { self.permission_sets.values() } @@ -131,6 +181,10 @@ impl<'a> PermissionSchemaGenerator<'a, Iter<'a, PermissionSet>, Iter<'a, Permiss self.default.as_ref().and_then(|d| d.description.as_deref()) } + fn default_set_permissions(&self) -> Option<&Vec> { + self.default.as_ref().map(|d| &d.permissions) + } + fn permission_sets(&'a self) -> Iter<'a, PermissionSet> { self.set.iter() } diff --git a/crates/tauri/build.rs b/crates/tauri/build.rs index c8ecada1b..25a67eba2 100644 --- a/crates/tauri/build.rs +++ b/crates/tauri/build.rs @@ -373,9 +373,10 @@ fn define_permissions( LICENSE_HEADER, false, ); - let default_permissions = commands - .iter() - .filter(|(_cmd, default)| *default) + let default_permissions: Vec<_> = commands.iter().filter(|(_cmd, default)| *default).collect(); + let all_commands_enabled_by_default = commands.len() == default_permissions.len(); + let default_permissions = default_permissions + .into_iter() .map(|(cmd, _)| { let slugified_command = cmd.replace('_', "-"); format!("\"allow-{slugified_command}\"") @@ -383,11 +384,17 @@ fn define_permissions( .collect::>() .join(", "); + let all_enable_by_default = if all_commands_enabled_by_default { + ", which enables all commands" + } else { + "" + }; + let default_toml = format!( r###"{LICENSE_HEADER}# Automatically generated - DO NOT EDIT! [default] -description = "Default permissions for the plugin." +description = "Default permissions for the plugin{all_enable_by_default}." permissions = [{default_permissions}] "###, ); @@ -437,22 +444,15 @@ fn define_default_permission_set( let default_toml = permissions_out_dir.join("default.toml"); let toml_content = format!( - r#"# {LICENSE_HEADER} + r#"{LICENSE_HEADER} [default] -description = """Default core plugins set which includes: -{} -""" +description = "Default core plugins set." permissions = [{}] "#, PLUGINS .iter() - .map(|(k, _)| format!("- '{k}:default'")) - .collect::>() - .join("\n"), - PLUGINS - .iter() - .map(|(k, _)| format!("'{k}:default'")) + .map(|(k, _)| format!("\"{k}:default\"")) .collect::>() .join(",") ); diff --git a/crates/tauri/permissions/app/autogenerated/reference.md b/crates/tauri/permissions/app/autogenerated/reference.md index 0aeafa1a5..b169047de 100644 --- a/crates/tauri/permissions/app/autogenerated/reference.md +++ b/crates/tauri/permissions/app/autogenerated/reference.md @@ -2,6 +2,8 @@ Default permissions for the plugin. +#### This default permission set includes the following: + - `allow-version` - `allow-name` - `allow-tauri-version` diff --git a/crates/tauri/permissions/event/autogenerated/reference.md b/crates/tauri/permissions/event/autogenerated/reference.md index 2cb12b7d7..1907b4ac8 100644 --- a/crates/tauri/permissions/event/autogenerated/reference.md +++ b/crates/tauri/permissions/event/autogenerated/reference.md @@ -1,6 +1,8 @@ ## Default Permission -Default permissions for the plugin. +Default permissions for the plugin, which enables all commands. + +#### This default permission set includes the following: - `allow-listen` - `allow-unlisten` diff --git a/crates/tauri/permissions/image/autogenerated/reference.md b/crates/tauri/permissions/image/autogenerated/reference.md index 3084889eb..f66c34cb6 100644 --- a/crates/tauri/permissions/image/autogenerated/reference.md +++ b/crates/tauri/permissions/image/autogenerated/reference.md @@ -1,6 +1,8 @@ ## Default Permission -Default permissions for the plugin. +Default permissions for the plugin, which enables all commands. + +#### This default permission set includes the following: - `allow-new` - `allow-from-bytes` diff --git a/crates/tauri/permissions/menu/autogenerated/reference.md b/crates/tauri/permissions/menu/autogenerated/reference.md index a4dc64985..4638fa9b2 100644 --- a/crates/tauri/permissions/menu/autogenerated/reference.md +++ b/crates/tauri/permissions/menu/autogenerated/reference.md @@ -1,6 +1,8 @@ ## Default Permission -Default permissions for the plugin. +Default permissions for the plugin, which enables all commands. + +#### This default permission set includes the following: - `allow-new` - `allow-append` diff --git a/crates/tauri/permissions/path/autogenerated/reference.md b/crates/tauri/permissions/path/autogenerated/reference.md index 5002f8ecc..fe6ec6f3d 100644 --- a/crates/tauri/permissions/path/autogenerated/reference.md +++ b/crates/tauri/permissions/path/autogenerated/reference.md @@ -1,6 +1,8 @@ ## Default Permission -Default permissions for the plugin. +Default permissions for the plugin, which enables all commands. + +#### This default permission set includes the following: - `allow-resolve-directory` - `allow-resolve` diff --git a/crates/tauri/permissions/resources/autogenerated/reference.md b/crates/tauri/permissions/resources/autogenerated/reference.md index 8fce95334..42fdf1b28 100644 --- a/crates/tauri/permissions/resources/autogenerated/reference.md +++ b/crates/tauri/permissions/resources/autogenerated/reference.md @@ -1,6 +1,8 @@ ## Default Permission -Default permissions for the plugin. +Default permissions for the plugin, which enables all commands. + +#### This default permission set includes the following: - `allow-close` diff --git a/crates/tauri/permissions/tray/autogenerated/reference.md b/crates/tauri/permissions/tray/autogenerated/reference.md index 7489c0eb1..6ea38e1c9 100644 --- a/crates/tauri/permissions/tray/autogenerated/reference.md +++ b/crates/tauri/permissions/tray/autogenerated/reference.md @@ -1,6 +1,8 @@ ## Default Permission -Default permissions for the plugin. +Default permissions for the plugin, which enables all commands. + +#### This default permission set includes the following: - `allow-new` - `allow-get-by-id` diff --git a/crates/tauri/permissions/webview/autogenerated/reference.md b/crates/tauri/permissions/webview/autogenerated/reference.md index 9bb12aab8..151839bab 100644 --- a/crates/tauri/permissions/webview/autogenerated/reference.md +++ b/crates/tauri/permissions/webview/autogenerated/reference.md @@ -2,6 +2,8 @@ Default permissions for the plugin. +#### This default permission set includes the following: + - `allow-get-all-webviews` - `allow-webview-position` - `allow-webview-size` diff --git a/crates/tauri/permissions/window/autogenerated/reference.md b/crates/tauri/permissions/window/autogenerated/reference.md index a2e3305d0..9fefb9d5d 100644 --- a/crates/tauri/permissions/window/autogenerated/reference.md +++ b/crates/tauri/permissions/window/autogenerated/reference.md @@ -2,6 +2,8 @@ Default permissions for the plugin. +#### This default permission set includes the following: + - `allow-get-all-windows` - `allow-scale-factor` - `allow-inner-position` diff --git a/examples/api/src-tauri/tauri-plugin-sample/permissions/schemas/schema.json b/examples/api/src-tauri/tauri-plugin-sample/permissions/schemas/schema.json index 942195b6d..0bc3ba1c4 100644 --- a/examples/api/src-tauri/tauri-plugin-sample/permissions/schemas/schema.json +++ b/examples/api/src-tauri/tauri-plugin-sample/permissions/schemas/schema.json @@ -297,22 +297,26 @@ { "description": "Enables the ping command without any pre-configured scope.", "type": "string", - "const": "allow-ping" + "const": "allow-ping", + "markdownDescription": "Enables the ping command without any pre-configured scope." }, { "description": "Denies the ping command without any pre-configured scope.", "type": "string", - "const": "deny-ping" + "const": "deny-ping", + "markdownDescription": "Denies the ping command without any pre-configured scope." }, { "description": "Sets a global scope.", "type": "string", - "const": "global-scope" + "const": "global-scope", + "markdownDescription": "Sets a global scope." }, { "description": "Enables the ping command with a test scope.", "type": "string", - "const": "allow-ping-scoped" + "const": "allow-ping-scoped", + "markdownDescription": "Enables the ping command with a test scope." } ] }