safehtml 0.1.0

A high-performance, no_std Rust library for Type-Driven Security (XSS and injection prevention).
Documentation
//! The [`SafeHtmlPart`] trait: values that can be interpolated into safe
//! HTML by the [`safe_html_cat!`](crate::safe_html_cat) and
//! [`safe_html_write!`](crate::safe_html_write) macros.
//!
//! Safe types ([`SafeHtmlStr`], [`SafeHtml`](crate::SafeHtml),
//! [`Identifier`](crate::Identifier)) pass through verbatim; raw strings and
//! characters are HTML-escaped; numbers and booleans are formatted (their
//! output is HTML-inert). The trait writes to any [`core::fmt::Write`], so
//! it works without `alloc`.

use crate::str_types::SafeHtmlStr;

/// A piece that can be written into a safe HTML output.
///
/// Implementations either emit their value verbatim (already-safe types) or
/// escape it (untrusted text). Used by
/// [`safe_html_cat!`](crate::safe_html_cat) and
/// [`safe_html_write!`](crate::safe_html_write).
pub trait SafeHtmlPart {
    /// Writes the escaped (or already-safe) representation of `self`.
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result;
}

impl SafeHtmlPart for &str {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        crate::escape_html_and_coerce_to(self, w)
    }
}

impl SafeHtmlPart for char {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        let mut tmp = [0; 4];
        crate::escape_html_and_coerce_to(self.encode_utf8(&mut tmp), w)
    }
}

impl SafeHtmlPart for &SafeHtmlStr {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        w.write_str(self.as_str())
    }
}

impl SafeHtmlPart for &crate::IdentifierStr {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        // Identifier characters ([A-Za-z][A-Za-z0-9_-]*) are HTML-inert.
        w.write_str(self.as_str())
    }
}

macro_rules! impl_safe_html_part_for_display {
    ($($t:ty)*) => {
        $(
            impl SafeHtmlPart for $t {
                fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
                    write!(w, "{}", self)
                }
            }
        )*
    };
}

impl_safe_html_part_for_display!(i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize f32 f64 bool);

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for alloc::string::String {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        crate::escape_html_and_coerce_to(self.as_str(), w)
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for crate::types::SafeHtml {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        w.write_str(self.as_str())
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for &crate::types::SafeHtml {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        w.write_str(self.as_str())
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for crate::types::Identifier {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        w.write_str(self.as_str())
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for &crate::types::Identifier {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        w.write_str(self.as_str())
    }
}

// URL types interpolate with HTML escaping applied: their contract is URL
// safety, not HTML safety, and a safe URL may still contain `&` or `'`
// which must be escaped in an HTML context. Escaping is semantics-preserving
// for URLs, so the result is a correct, safe href/src value.

impl SafeHtmlPart for &crate::SafeUrlStr {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        crate::escape_html_and_coerce_to(self.as_str(), w)
    }
}

impl SafeHtmlPart for &crate::TrustedResourceUrlStr {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        crate::escape_html_and_coerce_to(self.as_str(), w)
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for crate::types::SafeUrl {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        crate::escape_html_and_coerce_to(self.as_str(), w)
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for &crate::types::SafeUrl {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        crate::escape_html_and_coerce_to(self.as_str(), w)
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for crate::types::TrustedResourceUrl {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        crate::escape_html_and_coerce_to(self.as_str(), w)
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl SafeHtmlPart for &crate::types::TrustedResourceUrl {
    fn write_to<W: core::fmt::Write>(&self, w: &mut W) -> core::fmt::Result {
        crate::escape_html_and_coerce_to(self.as_str(), w)
    }
}