Expand description
Raw HTML: the one named type for markup written unescaped. Raw HTML: markup forma-server writes into the page exactly as it is given.
Every other value a page carries is escaped for its context. The one place
a handler’s own markup reaches the page unescaped is
PageConfig::body_prefix, and the one
way to say that a string is such markup is RawHtml::trusted. The name
is the control: a reviewer, or a consumer’s CI (forma-raw-lint), finds
every raw entry in an application by searching for RawHtml::trusted, and
nothing else in this crate makes a RawHtml.
§The 0.2.2 bridge
In 0.2.x body_prefix is still an Option<&str>, so every 0.2.1 call keeps
compiling. A RawHtml goes into it as Some(&raw): it dereferences to the
markup, so the field takes it as it is, and the same line compiles in 3.0.0,
where the field takes only a RawHtml. Bind the value first
(let raw = RawHtml::trusted(..);): written inline,
Some(&RawHtml::trusted(..)) borrows a temporary that Rust 1.85,
forma-server’s MSRV, drops at the end of the let config = PageConfig { .. }; statement, so it does not compile there (E0716); newer compilers
extend the temporary, which hides the problem. A plain string still works and is
written exactly as before; in a debug build the first one a process renders
logs one warning, code RAW-101, naming the route:
| Code | Where | Cause |
|---|---|---|
| RAW-101 | PageConfig::body_prefix | A plain string, not a RawHtml, in a debug build |
To tell the two apart, a debug build keeps the address and length of every
live RawHtml’s markup, and a body_prefix that points at exactly one of
them is that RawHtml. A release build keeps no record and checks nothing:
it writes the field exactly as 0.2.1 did.
Structs§
- RawHtml
- Markup a handler vouches for, written into the page unescaped.