Omit fields when deriving SafeDebug by default (#2516)

* Omit fields when deriving SafeDebug by default

Resolves #1707. Callers can enable the `debug` feature of `typespec_client_core` or `azure_core` to emit normal `core::fmt::Debug` formatting.

* Add/support more test cases

* Refactor to support future `safe` attribute helper

* Use older versions of some deps for 1.80

* Use `DebugTuple::finish()` on 1.80

`DebugTuple::finish_non_exhaustive()` wasn't added till 1.82.

* Remove `SafeDebug` trait

A derive macro doesn't need the trait, nor do we have need for one currently.

* Add "msrv" to cspell dictionary words

Author: heaths

.vscode/cspell.json

@@ -51,6 +51,7 @@
     "maxresults",
     "maxsize",
     "msrc",
+    "msrv",
     "newtonsoft",
     "oidc",
     "pageable",

Cargo.lock

@@ -10,6 +10,8 @@
 
 ### Other Changes
 
+- Deriving `SafeDebug` formats non-exhaustive types by default. Enable `debug` feature to format normal `Debug` output.
+
 ## 0.23.0 (2025-04-08)
 
 ### Features Added

sdk/core/azure_core/CHANGELOG.md

@@ -48,6 +48,7 @@ default = [
   "reqwest_gzip",
 ]
 azurite_workaround = []
+debug = ["typespec_client_core/debug"]
 hmac_openssl = ["dep:openssl"]
 hmac_rust = ["dep:sha2", "dep:hmac"]
 reqwest = ["typespec_client_core/reqwest"]

sdk/core/azure_core/Cargo.toml

@@ -71,7 +71,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     };
 
     let client = SecretClient::new(
-        "https://your-key-vault-name.vault.azure.net/",
+        "https://<your-key-vault-name>.vault.azure.net/",
         credential.clone(),
         Some(options),
     )?;
@@ -96,7 +96,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // create a client
     let credential = DefaultAzureCredential::new()?;
     let client = SecretClient::new(
-        "https://your-key-vault-name.vault.azure.net/",
+        "https://<your-key-vault-name>.vault.azure.net/",
         credential.clone(),
         None,
     )?;
@@ -140,7 +140,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // create a client
     let credential = DefaultAzureCredential::new()?;
     let client = SecretClient::new(
-        "https://your-key-vault-name.vault.azure.net/",
+        "https://<your-key-vault-name>.vault.azure.net/",
         credential.clone(),
         None,
     )?;
@@ -178,7 +178,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // create a client
     let credential = DefaultAzureCredential::new()?;
     let client = SecretClient::new(
-        "https://your-key-vault-name.vault.azure.net/",
+        "https://<your-key-vault-name>.vault.azure.net/",
         credential.clone(),
         None,
     )?;
@@ -201,7 +201,49 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-<!-- ## Troubleshooting -->
+## Troubleshooting
+
+### Logging
+
+To help protected end users from accidental Personally-Identifiable Information (PII) from leaking into logs or traces, models' default implementation of `core::fmt::Debug` formats as non-exhaustive structure tuple e.g.,
+
+```rust no_run
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_secrets::{ResourceExt, SecretClient};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // create a client
+    let credential = DefaultAzureCredential::new()?;
+    let client = SecretClient::new(
+        "https://<your-key-vault-name>.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    // get a secret
+    let secret = client.get_secret("secret-name", "", None)
+        .await?
+        .into_body()
+        .await?;
+
+    println!("{secret:#?}");
+
+    Ok(())
+}
+```
+
+By default this will print:
+
+```text
+Secret { .. }
+```
+
+Though not recommended for production, you can enable normal `core::fmt::Debug` formatting complete with field names and values by enabling the `debug` feature of `azure_core` e.g.,
+
+```sh
+cargo add azure_core -F debug
+```
 
 ## Contributing
 

sdk/core/azure_core/README.md

@@ -10,6 +10,8 @@
 
 ### Other Changes
 
+- Deriving `SafeDebug` formats non-exhaustive types by default. Enable `debug` feature to format normal `Debug` output.
+
 ## 0.2.0 (2025-04-08)
 
 ### Breaking Changes

sdk/typespec/typespec_client_core/CHANGELOG.md

@@ -45,6 +45,7 @@ typespec_macros.path = "../typespec_macros"
 
 [features]
 default = ["http", "json", "reqwest", "reqwest_deflate", "reqwest_gzip"]
+debug = ["typespec_macros?/debug"]
 derive = ["dep:typespec_macros"]
 http = ["typespec/http"]
 json = ["typespec/json"]

sdk/typespec/typespec_client_core/Cargo.toml

@@ -3,17 +3,18 @@
 
 //! Formatting helpers.
 
-use std::{borrow::Cow, fmt::Debug};
+use std::borrow::Cow;
 
-#[cfg(feature = "derive")]
-pub use typespec_macros::SafeDebug;
-
-/// When deriving this trait, helps prevent leaking personally identifiable information (PII) that deriving [`Debug`] might otherwise.
+/// Derive to help prevent leaking personally identifiable information (PII) that deriving [`Debug`](std::fmt::Debug) might otherwise.
+///
+/// `SafeDebug` is not a trait and cannot be implemented, nor should you derive `Debug` explicitly.
+/// Only when you derive `SafeDebug` will types help prevent leaking PII because, by default, only the type name is printed.
+/// Only when you import `typespec_client_core` with feature `debug` will it derive `Debug` normally.
 ///
 /// # Examples
 ///
 /// ```
-/// use typespec_macros::SafeDebug;
+/// use typespec_client_core::fmt::SafeDebug;
 ///
 /// #[derive(SafeDebug)]
 /// struct MyModel {
@@ -23,9 +24,14 @@ pub use typespec_macros::SafeDebug;
 /// let model = MyModel {
 ///     name: Some("Kelly Smith".to_string()),
 /// };
-/// assert_eq!(format!("{model:?}"), "MyModel { .. }");
+/// if cfg!(feature = "debug") {
+///     assert_eq!(format!("{model:?}"), r#"MyModel { name: Some("Kelly Smith") }"#);
+/// } else {
+///     assert_eq!(format!("{model:?}"), "MyModel { .. }");
+/// }
 /// ```
-pub trait SafeDebug: Debug {}
+#[cfg(feature = "derive")]
+pub use typespec_macros::SafeDebug;
 
 /// Converts ASCII characters in `value` to lowercase if required; otherwise, returns the original slice.
 ///

sdk/typespec/typespec_client_core/src/fmt.rs

@@ -10,6 +10,8 @@
 
 ### Other Changes
 
+- Deriving `SafeDebug` formats non-exhaustive types by default. Enable `debug` feature to format normal `Debug` output.
+
 ## 0.2.0 (2025-04-08)
 
 ### Other Changes

sdk/typespec/typespec_macros/CHANGELOG.md

@@ -13,18 +13,25 @@ keywords = ["typespec"]
 [lib]
 proc-macro = true
 
+[features]
+debug = []
+
 [dependencies]
-syn.workspace = true
-quote.workspace = true
 proc-macro2.workspace = true
+quote.workspace = true
+rustc_version.workspace = true
+syn.workspace = true
 
 [dev-dependencies]
+cargo_metadata.workspace = true
+serde.workspace = true
+serde_json.workspace = true
 tokio.workspace = true
 typespec_client_core = { path = "../typespec_client_core", features = [
   "http",
   "json",
   "xml",
 ] }
-serde.workspace = true
-serde_json.workspace = true
-cargo_metadata.workspace = true
+
+[package.metadata.docs.rs]
+features = []

sdk/typespec/typespec_macros/Cargo.toml

@@ -85,10 +85,11 @@ pub fn derive_model(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
     run_derive_macro(input, model::derive_model_impl)
 }
 
-/// Derive macro for implementing the `SafeDebug` trait.
+/// Derive to help prevent leaking personally identifiable information (PII) that deriving [`Debug`](std::fmt::Debug) might otherwise.
 ///
-/// Deriving this trait will derive a [`std::fmt::Debug`] implementation that should not leak personally identifiable information (PII).
-/// By default, only the structure or enumeration name will be returned.
+/// `SafeDebug` is not a trait and cannot be implemented, nor should you derive `Debug` explicitly.
+/// Only when you derive `SafeDebug` will types help prevent leaking PII because, by default, only the type name is printed.
+/// Only when you enable the `debug` feature will it derive `Debug` normally.
 ///
 /// # Examples
 ///
@@ -102,7 +103,11 @@ pub fn derive_model(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
 /// let model = MyModel {
 ///     name: Some("Kelly Smith".to_string()),
 /// };
-/// assert_eq!(format!("{model:?}"), "MyModel { .. }");
+/// if cfg!(feature = "debug") {
+///     assert_eq!(format!("{model:?}"), r#"MyModel { name: Some("Kelly Smith") }"#);
+/// } else {
+///     assert_eq!(format!("{model:?}"), "MyModel { .. }");
+/// }
 /// ```
 #[proc_macro_derive(SafeDebug)]
 pub fn derive_safe_debug(input: proc_macro::TokenStream) -> proc_macro::TokenStream {