feat: serde::redacted convenience serialize_with - serialize with…

…out exposing (#46)

* feat: `serde::redacted` convenience `serialize_with` - serialize without exposing

# Todo
- [ ] Document function with rustdoc
- [ ] Update serde section in `README.md`

* Update documentation

* Rename `redacted` -> `redact_secret`

README.md

@@ -66,6 +66,8 @@ struct Payment {
 }
 ```
 
+If you would like to implement `Serialize` without exposing the `Secret` see [serde::redact_secret].
+
 ## Comparison with alternatives
 
 ### [secrecy](https://docs.rs/secrecy/latest/secrecy/)

src/lib.rs

@@ -9,7 +9,7 @@ mod error;
 mod fake;
 mod ops;
 #[cfg(feature = "serde")]
-mod serde;
+pub mod serde;
 
 #[cfg(feature = "serde")]
 pub use crate::serde::expose_secret;

src/serde.rs

@@ -42,14 +42,14 @@ impl<T: Serialize> SerializableSecret<T> for Option<Secret<T>> {
     }
 }
 
-#[cfg(feature = "serde")]
 /// Exposes a [Secret] for serialization.
 ///
 /// For general-purpose secret exposing see [Secret::expose_secret].
 ///
 /// See [module level documentation][crate] for usage example.
 ///
 /// *This API requires the following crate features to be activated: `serde`*
+#[cfg(feature = "serde")]
 #[inline]
 pub fn expose_secret<S: Serializer, T: Serialize>(
     secret: &impl SerializableSecret<T>,
@@ -60,6 +60,24 @@ pub fn expose_secret<S: Serializer, T: Serialize>(
         .serialize(serializer)
 }
 
+/// Serialize a redacted [Secret] without exposing the contained data.
+///
+/// The secret will be serialized as its [`Debug`] output.
+/// Since the data is redacted, it is not possible to deserialize data serialized in this way.
+///
+/// This function is designed to be used with `#[serde(serialize_with)]` in the same way as
+/// [serde::expose_secret][crate::serde::expose_secret].
+///
+/// *This API requires the following crate features to be activated: `serde`*
+#[cfg(feature = "serde")]
+#[inline]
+pub fn redact_secret<S: Serializer, T>(
+    secret: &Secret<T>,
+    serializer: S,
+) -> Result<S::Ok, S::Error> {
+    format!("{secret:?}").serialize(serializer)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;