Add bail-out handler API for flushing buffered state on graceful bail-out.

Graceful bail-out (`MemoryLimitExceeded` or `ContentHandlerError` with the
matching flag on) flushes the unparsed input remainder raw to the sink and
propagates the error. That is enough for handlers that only transform tokens
they see, but handlers that buffer state across the document (e.g. ROFL's
email-obfuscation module, which holds up to ~128 chars in a text buffer while
deciding whether they belong to an email) lose that state on bail-out and
produce a response with a gap.

This commit adds a hook that fires once on a graceful bail-out, immediately
before the raw flush, and lets handlers append final bytes to the sink:

1. New rewritable unit `BailOut` with a single method
   `append(content, content_type)`, modelled after `DocumentEnd::append`. The
   wrapper carries the rewriter's current encoding (after any
   `<meta charset>`-driven change), so encoding-correctness is automatic.
2. New builder method `Settings::append_bail_out_handler` (and the
   `RewriteStrSettings` mirror) plus `bail_out!` macro for type-hint
   ergonomics, parallel to the existing `element!` / `end!` macros.
3. `HandlerTypes` grows a `BailOutHandler<'h>` associated type, with
   `LocalHandlerTypes` aliasing `BailOutHandler<'h>` and `SendHandlerTypes`
   aliasing `BailOutHandlerSend<'h>`. Matching `IntoHandler` impls cover both
   bare-closure cases.
4. `TransformController` grows a `handle_bail_out` method with an empty
   default impl so existing implementors (test fixtures, parser-trace tool)
   keep compiling. `HtmlRewriteController` overrides it to iterate the
   user-registered handlers in registration order.
5. `Dispatcher::run_bail_out_handlers` constructs the `BailOut` wrapper and
   delegates to the controller. It is invoked from every existing graceful
   bail-out site in `TransformStream::write()` (3 sites: `Arena::append`,
   `Parser::parse`, `Arena::init_with`) and `TransformStream::end()` (1 site),
   gated on `should_bail_out_for(&err)`. Hook output therefore lands in the
   sink as `[transformed prefix] + [hook output] + [raw remainder]`.
6. `RewritingError` is marked `#[non_exhaustive]` so we can add variants in
   future minor releases. `match`es still work; only exhaustive external
   matches need a catch-all arm.

The `end()` bail-out site is defensive: it is symmetric with the `write()`
sites but is not reachable through normal input. EOF-in-tag / -attribute /
-comment emits as text per HTML5, so content-handler errors don't fire from
`parser.parse(_, true)`, and memory errors fire earlier in `write()`. Tested
implicitly via the shared call path.

Author: orium

CHANGELOG.md

@@ -11,6 +11,17 @@
   rewriter flushes remaining input bytes before propagating a handler error, preserving
   the response. Currently exposed via the Rust API only; the C API still uses the original
   behavior.
+- Added `Settings::append_bail_out_handler()` and the matching `bail_out!` macro,
+  `BailOut` rewritable unit, and `BailOutHandler` / `BailOutHandlerSend` type aliases.
+  Bail-out handlers fire immediately before the raw flush of remaining unparsed input on a
+  graceful bail-out (memory or content-handler error). Handlers receive the
+  `RewritingError` and a `BailOut` through which they can append final bytes to the sink
+  via `BailOut::append(content, content_type)`. Intended for handlers that buffer state
+  across the document (e.g. text-buffering handlers that defer emission) and need to
+  flush that state on bail-out.
+- Marked `RewritingError` `#[non_exhaustive]` so future error variants can be added without
+  a major version bump. External callers can still `match` on it, but must include a
+  catch-all `_ =>` arm.
 - Reworked `Settings`, `MemorySettings` and `RewriteStrSettings` to use a consuming-builder
   API. Fields are now private; construction is via `::new()` plus chained `with_*` setters
   and `append_*` methods for the content-handler vectors. This makes future field additions

src/lib.rs

@@ -41,10 +41,10 @@ mod transform_stream;
 use cfg_if::cfg_if;
 
 pub use self::rewriter::{
-    AsciiCompatibleEncoding, CommentHandler, DoctypeHandler, DocumentContentHandlers,
-    ElementContentHandlers, ElementHandler, EndHandler, EndTagHandler, HandlerResult, HandlerTypes,
-    HtmlRewriter, LocalHandlerTypes, MemorySettings, RewriteStrSettings, Settings, TextHandler,
-    rewrite_str,
+    AsciiCompatibleEncoding, BailOutHandler, CommentHandler, DoctypeHandler,
+    DocumentContentHandlers, ElementContentHandlers, ElementHandler, EndHandler, EndTagHandler,
+    HandlerResult, HandlerTypes, HtmlRewriter, LocalHandlerTypes, MemorySettings,
+    RewriteStrSettings, Settings, TextHandler, rewrite_str,
 };
 pub use self::selectors_vm::Selector;
 pub use self::transform_stream::OutputSink;
@@ -56,9 +56,10 @@ pub use self::transform_stream::OutputSink;
 /// Rewriting is sequential, so there's no benefit from using the `Send`-compatible rewriter.
 pub mod send {
     pub use crate::rewriter::{
-        CommentHandlerSend as CommentHandler, DoctypeHandlerSend as DoctypeHandler,
-        ElementHandlerSend as ElementHandler, EndHandlerSend as EndHandler,
-        EndTagHandlerSend as EndTagHandler, TextHandlerSend as TextHandler,
+        BailOutHandlerSend as BailOutHandler, CommentHandlerSend as CommentHandler,
+        DoctypeHandlerSend as DoctypeHandler, ElementHandlerSend as ElementHandler,
+        EndHandlerSend as EndHandler, EndTagHandlerSend as EndTagHandler,
+        TextHandlerSend as TextHandler,
     };
     pub use crate::rewriter::{IntoHandler, SendHandlerTypes};
 
@@ -95,7 +96,7 @@ pub mod errors {
 /// HTML content descriptors that can be produced and modified by a rewriter.
 pub mod html_content {
     pub use super::rewritable_units::{
-        Attribute, Comment, ContentType, Doctype, DocumentEnd, Element, EndTag, StartTag,
+        Attribute, BailOut, Comment, ContentType, Doctype, DocumentEnd, Element, EndTag, StartTag,
         StreamingHandler, StreamingHandlerSink, TextChunk, UserData,
     };
 

src/rewritable_units/bail_out.rs

@@ -0,0 +1,72 @@
+use super::{ContentType, StreamingHandlerSink};
+use crate::transform_stream::OutputSink;
+use encoding_rs::Encoding;
+
+/// A rewritable unit that represents the moment the rewriter is about to abandon
+/// processing through a graceful bail-out.
+///
+/// Bail-out handlers registered via [`Settings::append_bail_out_handler()`] receive a
+/// `&mut BailOut` and can emit final bytes into the output sink via [`append()`]. This
+/// is the only opportunity for content other handlers have buffered (e.g. text withheld
+/// pending a future chunk) to land in the response when the rewriter aborts.
+///
+/// Bytes appended via this unit are written *before* the rewriter's own raw flush of
+/// remaining unparsed input. The resulting sink order is:
+///
+/// 1. Transformed bytes the rewriter already emitted normally.
+/// 2. Bytes appended by bail-out handlers, in registration order.
+/// 3. The rewriter's raw flush of the chunk's unparsed suffix.
+///
+/// [`Settings::append_bail_out_handler()`]:
+///     crate::Settings::append_bail_out_handler
+/// [`append()`]: Self::append
+pub struct BailOut<'a> {
+    output_sink: &'a mut dyn OutputSink,
+    encoding: &'static Encoding,
+}
+
+impl<'a> BailOut<'a> {
+    #[inline]
+    #[must_use]
+    pub(crate) fn new(output_sink: &'a mut dyn OutputSink, encoding: &'static Encoding) -> Self {
+        Self {
+            output_sink,
+            encoding,
+        }
+    }
+
+    /// Appends `content` at the bail-out point.
+    ///
+    /// Subsequent calls to this method append `content` to the previously inserted
+    /// content within the same bail-out invocation. When multiple bail-out handlers are
+    /// registered, their `append` calls are concatenated in registration order.
+    ///
+    /// `content_type` controls how the content is interpreted before being written to
+    /// the sink. See [`ContentType`].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use lol_html::{bail_out, Settings};
+    /// use lol_html::errors::RewritingError;
+    /// use lol_html::html_content::ContentType;
+    ///
+    /// // A handler that, on content-handler-error bail-out, drops a notice into the sink
+    /// // before the rewriter's own raw flush of remaining unparsed input.
+    /// let settings = Settings::new()
+    ///     .with_graceful_bail_out_on_content_handler_error(true)
+    ///     .append_bail_out_handler(bail_out!(|err, bail_out| {
+    ///         if matches!(err, RewritingError::ContentHandlerError(_)) {
+    ///             bail_out.append("<!-- bailed out -->", ContentType::Html);
+    ///         }
+    ///     }));
+    /// # let _ = settings;
+    /// ```
+    #[inline]
+    pub fn append(&mut self, content: &str, content_type: ContentType) {
+        StreamingHandlerSink::new(self.encoding, &mut |c| {
+            self.output_sink.handle_chunk(c);
+        })
+        .write_str(content, content_type);
+    }
+}

src/rewritable_units/mod.rs

@@ -4,6 +4,7 @@ pub(crate) use self::mutations::{Mutations, StringChunk};
 pub(crate) use self::text_decoder::TextDecoder;
 pub(crate) use self::text_encoder::{IncompleteUtf8Resync, TextEncoder};
 
+pub use self::bail_out::*;
 pub use self::document_end::*;
 pub use self::element::*;
 pub use self::mutations::{ContentType, StreamingHandler};
@@ -83,6 +84,7 @@ macro_rules! impl_user_data {
 #[macro_use]
 mod mutations;
 
+mod bail_out;
 mod document_end;
 mod element;
 mod streaming_sink;