#[cfg(not(target_arch = "wasm32"))]
mod progressive;
#[cfg(not(target_arch = "wasm32"))]
pub(crate) use progressive::{defer_boundary, register_server_loader, stream_active};
#[cfg(all(feature = "rest", not(target_arch = "wasm32")))]
pub use progressive::{render_to_stream, render_to_stream_with, RenderStream, StreamOptions};
#[cfg(not(target_arch = "wasm32"))]
pub use progressive::{STREAM_SWAP_SCRIPT, STREAM_SWAP_SCRIPT_PATH};
#[cfg(not(target_arch = "wasm32"))]
use crate::Render;
use std::collections::HashMap;
#[cfg(not(target_arch = "wasm32"))]
use std::time::Instant;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SuspenseState {
Pending,
Resolved,
Error,
}
impl SuspenseState {
#[cfg(not(target_arch = "wasm32"))]
fn as_str(self) -> &'static str {
match self {
SuspenseState::Pending => "pending",
SuspenseState::Resolved => "resolved",
SuspenseState::Error => "error",
}
}
fn parse(value: &str) -> Option<Self> {
match value {
"pending" => Some(Self::Pending),
"resolved" => Some(Self::Resolved),
"error" => Some(Self::Error),
_ => None,
}
}
}
fn parse_suspense_marker(input: &str) -> Option<(&str, SuspenseState)> {
let trimmed = input.trim();
let body = trimmed
.strip_prefix("<!--")
.and_then(|v| v.strip_suffix("-->"))
.unwrap_or(trimmed);
let mut parts = body.split(':');
let prefix = parts.next()?;
let kind = parts.next()?;
let boundary_id = parts.next()?.trim();
let state_raw = parts.next()?.trim();
if prefix != "krab" || kind != "suspense" || boundary_id.is_empty() {
return None;
}
Some((boundary_id, SuspenseState::parse(state_raw)?))
}
pub fn is_finalized_ssr_snapshot(html: &str) -> bool {
let mut boundary_state: HashMap<&str, (usize, usize, usize)> = HashMap::new();
for segment in html.split("<!--").skip(1) {
let Some(comment_end) = segment.find("-->") else {
continue;
};
let Some((boundary_id, state)) = parse_suspense_marker(&segment[..comment_end]) else {
continue;
};
let counts = boundary_state
.entry(boundary_id)
.or_insert((0usize, 0usize, 0usize));
match state {
SuspenseState::Pending => counts.0 += 1,
SuspenseState::Resolved => counts.1 += 1,
SuspenseState::Error => counts.2 += 1,
}
}
if boundary_state.is_empty() {
return true;
}
boundary_state
.values()
.all(|(pending, resolved, error)| *pending > 0 && *pending == (*resolved + *error))
}
#[cfg(not(target_arch = "wasm32"))]
fn has_visible_text(html: &str) -> bool {
let mut rest = html;
while !rest.is_empty() {
if let Some(after) = rest.strip_prefix("<!--") {
match after.find("-->") {
Some(end) => rest = &after[end + 3..],
None => return false,
}
} else if rest.starts_with('<') {
match rest.find('>') {
Some(end) => rest = &rest[end + 1..],
None => return false,
}
} else {
let text_end = rest.find('<').unwrap_or(rest.len());
if rest[..text_end].chars().any(|c| !c.is_whitespace()) {
return true;
}
rest = &rest[text_end..];
}
}
false
}
#[derive(Debug, Clone)]
#[cfg(not(target_arch = "wasm32"))]
pub struct StreamTelemetry {
pub ttfb_ms: Option<u128>,
pub first_visible_chunk_ms: Option<u128>,
pub full_stream_complete_ms: Option<u128>,
pub emitted_bytes: usize,
pub flush_count: usize,
pub suspense_marker_count: usize,
pub boundary_events: HashMap<String, usize>,
pub budget_limit_bytes: Option<usize>,
pub budget_exceeded: bool,
pub stream_cancelled: bool,
pub cancel_reason: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg(not(target_arch = "wasm32"))]
pub struct FinishedStream {
pub chunks: Vec<String>,
pub budget_exceeded: bool,
pub cancelled: bool,
}
#[cfg(not(target_arch = "wasm32"))]
impl FinishedStream {
pub fn chunks(&self) -> &[String] {
&self.chunks
}
pub fn into_chunks(self) -> Vec<String> {
self.chunks
}
pub fn concat(&self) -> String {
self.chunks.concat()
}
pub fn budget_exceeded(&self) -> bool {
self.budget_exceeded
}
pub fn cancelled(&self) -> bool {
self.cancelled
}
pub fn is_complete(&self) -> bool {
!self.budget_exceeded && !self.cancelled
}
}
#[derive(Debug, Clone)]
#[cfg(not(target_arch = "wasm32"))]
pub struct ChunkedStreamWriter {
chunk_size: usize,
flush_threshold: usize,
pending: String,
chunks: Vec<String>,
flush_count: usize,
created_at: Instant,
first_write_at: Option<Instant>,
first_flush_at: Option<Instant>,
first_visible_flush_at: Option<Instant>,
emitted_bytes: usize,
suspense_marker_count: usize,
boundary_events: HashMap<String, usize>,
max_total_bytes: Option<usize>,
budget_exceeded: bool,
stream_cancelled: bool,
cancel_reason: Option<String>,
}
#[cfg(not(target_arch = "wasm32"))]
impl Default for ChunkedStreamWriter {
fn default() -> Self {
Self::new(1024, 4096)
}
}
#[cfg(not(target_arch = "wasm32"))]
impl ChunkedStreamWriter {
pub fn new(chunk_size: usize, flush_threshold: usize) -> Self {
Self {
chunk_size: chunk_size.max(128),
flush_threshold: flush_threshold.max(chunk_size.max(128)),
pending: String::new(),
chunks: Vec::new(),
flush_count: 0,
created_at: Instant::now(),
first_write_at: None,
first_flush_at: None,
first_visible_flush_at: None,
emitted_bytes: 0,
suspense_marker_count: 0,
boundary_events: HashMap::new(),
max_total_bytes: None,
budget_exceeded: false,
stream_cancelled: false,
cancel_reason: None,
}
}
pub fn with_max_total_bytes(mut self, max_total_bytes: usize) -> Self {
self.max_total_bytes = Some(max_total_bytes.max(1));
self
}
pub fn set_max_total_bytes(&mut self, max_total_bytes: usize) {
self.max_total_bytes = Some(max_total_bytes.max(1));
}
#[must_use = "a false return means the output was dropped (budget exceeded or stream cancelled)"]
pub fn write(&mut self, input: &str) -> bool {
if self.budget_exceeded || self.stream_cancelled {
return false;
}
if let Some(limit) = self.max_total_bytes {
let projected = self.emitted_bytes + self.pending.len() + input.len();
if projected > limit {
self.budget_exceeded = true;
tracing::warn!(
emitted_bytes = self.emitted_bytes,
pending_bytes = self.pending.len(),
dropped_bytes = input.len(),
limit,
"render_budget_exceeded"
);
return false;
}
}
if self.first_write_at.is_none() {
self.first_write_at = Some(Instant::now());
}
self.pending.push_str(input);
self.flush_if_ready();
true
}
#[must_use = "a false return means the marker was dropped (budget exceeded or stream cancelled)"]
pub fn write_suspense_marker(&mut self, boundary_id: &str, state: SuspenseState) -> bool {
let accepted = self.write(&format!(
"<!--krab:suspense:{}:{}-->",
boundary_id,
state.as_str()
));
if accepted {
self.suspense_marker_count += 1;
*self
.boundary_events
.entry(boundary_id.to_string())
.or_insert(0) += 1;
}
accepted
}
pub fn flush(&mut self) {
if self.pending.is_empty() || self.stream_cancelled {
return;
}
let first_new_chunk = self.chunks.len();
while self.pending.len() > self.chunk_size {
let split_at = nearest_char_boundary(&self.pending, self.chunk_size);
let chunk = self.pending[..split_at].to_string();
self.emitted_bytes += chunk.len();
self.chunks.push(chunk);
self.pending = self.pending[split_at..].to_string();
}
if !self.pending.is_empty() {
let chunk = std::mem::take(&mut self.pending);
self.emitted_bytes += chunk.len();
self.chunks.push(chunk);
}
let now = Instant::now();
if self.first_flush_at.is_none() {
self.first_flush_at = Some(now);
}
if self.first_visible_flush_at.is_none()
&& has_visible_text(&self.chunks[first_new_chunk..].concat())
{
self.first_visible_flush_at = Some(now);
}
self.flush_count += 1;
}
pub fn finish(mut self) -> FinishedStream {
self.flush();
FinishedStream {
budget_exceeded: self.budget_exceeded,
cancelled: self.stream_cancelled,
chunks: self.chunks,
}
}
pub fn flush_count(&self) -> usize {
self.flush_count
}
pub fn telemetry_snapshot(&self) -> StreamTelemetry {
let now = Instant::now();
StreamTelemetry {
ttfb_ms: self
.first_flush_at
.map(|t| t.duration_since(self.created_at).as_millis()),
first_visible_chunk_ms: self
.first_visible_flush_at
.map(|t| t.duration_since(self.created_at).as_millis()),
full_stream_complete_ms: if self.flush_count > 0 {
Some(now.duration_since(self.created_at).as_millis())
} else {
None
},
emitted_bytes: self.emitted_bytes,
flush_count: self.flush_count,
suspense_marker_count: self.suspense_marker_count,
boundary_events: self.boundary_events.clone(),
budget_limit_bytes: self.max_total_bytes,
budget_exceeded: self.budget_exceeded,
stream_cancelled: self.stream_cancelled,
cancel_reason: self.cancel_reason.clone(),
}
}
pub fn cancel(&mut self, reason: impl Into<String>) {
if !self.pending.is_empty() {
self.flush();
}
self.stream_cancelled = true;
self.cancel_reason = Some(reason.into());
}
pub fn is_cancelled(&self) -> bool {
self.stream_cancelled
}
fn flush_if_ready(&mut self) {
if self.pending.len() >= self.flush_threshold {
self.flush();
}
}
}
#[cfg(not(target_arch = "wasm32"))]
pub fn render_to_chunk_stream(renderable: &impl Render, writer: &mut ChunkedStreamWriter) -> bool {
writer.write(&renderable.render())
}
#[cfg(not(target_arch = "wasm32"))]
fn nearest_char_boundary(s: &str, target: usize) -> usize {
if target >= s.len() {
return s.len();
}
let mut i = target;
while !s.is_char_boundary(i) {
i -= 1;
}
i
}
#[cfg(all(test, not(target_arch = "wasm32")))]
mod tests {
use super::*;
use crate::{annotate_hydration_tree, Element, Node};
#[test]
fn chunk_writer_splits_and_flushes() {
let mut writer = ChunkedStreamWriter::new(128, 256);
assert!(writer.write(&"a".repeat(300)));
let finished = writer.finish();
assert!(finished.chunks.len() >= 3);
assert_eq!(finished.concat(), "a".repeat(300));
assert!(finished.is_complete());
assert!(!finished.budget_exceeded());
assert!(!finished.cancelled());
}
#[test]
fn finalized_snapshot_with_all_boundaries_resolved() {
let html = concat!(
"<html><body>",
"<!--krab:suspense:home:pending-->",
"<div data-krab-hydration=\"home\">fallback</div>",
"<!--krab:suspense:home:resolved-->",
"</body></html>"
);
assert!(is_finalized_ssr_snapshot(html));
}
#[test]
fn unfinalized_snapshot_without_resolution() {
let html = concat!(
"<html><body>",
"<!--krab:suspense:home:pending-->",
"<div>fallback</div>",
"</body></html>"
);
assert!(!is_finalized_ssr_snapshot(html));
}
#[test]
fn unfinalized_snapshot_with_error_boundary_matches_resolution() {
let html = concat!(
"<!--krab:suspense:home:pending-->",
"<!--krab:suspense:home:error-->"
);
assert!(is_finalized_ssr_snapshot(html));
}
#[test]
fn snapshot_with_no_markers_is_finalized() {
assert!(is_finalized_ssr_snapshot("<html><body>plain</body></html>"));
assert!(is_finalized_ssr_snapshot(""));
}
#[test]
fn suspense_markers_are_hydration_compatible_comments() {
let mut writer = ChunkedStreamWriter::new(32, 64);
let _ = writer.write_suspense_marker("home-data", SuspenseState::Pending);
let _ = writer.write("<div data-krab-hydration=\"home-data\">fallback</div>");
let _ = writer.write_suspense_marker("home-data", SuspenseState::Resolved);
let html = writer.finish().concat();
assert!(html.contains("<!--krab:suspense:home-data:pending-->"));
assert!(html.contains("data-krab-hydration=\"home-data\""));
assert!(html.contains("<!--krab:suspense:home-data:resolved-->"));
}
#[test]
fn suspense_marker_parser_handles_comment_and_raw_body() {
assert_eq!(
parse_suspense_marker("<!--krab:suspense:home:pending-->"),
Some(("home", SuspenseState::Pending))
);
assert_eq!(
parse_suspense_marker("krab:suspense:profile:resolved"),
Some(("profile", SuspenseState::Resolved))
);
assert_eq!(parse_suspense_marker("krab:other:profile:resolved"), None);
assert_eq!(parse_suspense_marker("krab:suspense::resolved"), None);
assert_eq!(parse_suspense_marker("krab:suspense:home:unknown"), None);
}
#[test]
fn hydration_node_markers_survive_chunk_stream_rendering() {
let renderable = annotate_hydration_tree(
Node::Element(Element {
tag: "section".to_string(),
attributes: vec![],
children: vec![Node::Element(Element {
tag: "div".to_string(),
attributes: vec![],
children: vec![Node::Text("streamed".to_string())],
events: vec![],
})],
events: vec![],
}),
"stream-home:1",
);
let mut writer = ChunkedStreamWriter::new(16, 16);
render_to_chunk_stream(&renderable, &mut writer);
let html = writer.finish().concat();
assert!(html.contains("data-krab-node-id=\"stream-home:1/0\""));
assert!(html.contains("data-krab-node-id=\"stream-home:1/0.0\""));
assert!(html.contains(">streamed</div>"));
}
#[test]
fn backpressure_flushes_when_threshold_reached() {
let mut writer = ChunkedStreamWriter::new(128, 128);
let _ = writer.write("hello");
assert_eq!(writer.flush_count(), 0);
let _ = writer.write(&"x".repeat(130));
assert!(writer.flush_count() >= 1);
}
#[test]
fn telemetry_snapshot_tracks_stream_events() {
let mut writer = ChunkedStreamWriter::new(64, 64);
let _ = writer.write("<!DOCTYPE html>");
let _ = writer.write_suspense_marker("home", SuspenseState::Pending);
let _ = writer.write("<div>hello</div>");
let _ = writer.write_suspense_marker("home", SuspenseState::Resolved);
writer.flush();
let telemetry = writer.telemetry_snapshot();
assert!(telemetry.flush_count >= 1);
assert_eq!(telemetry.suspense_marker_count, 2);
assert_eq!(telemetry.boundary_events.get("home"), Some(&2));
assert!(telemetry.ttfb_ms.is_some());
assert_eq!(telemetry.budget_limit_bytes, None);
assert!(!telemetry.budget_exceeded);
}
#[test]
fn first_visible_chunk_waits_for_paintable_text() {
let mut writer = ChunkedStreamWriter::new(128, 128);
let _ = writer.write("<!DOCTYPE html><html><head><title>");
let _ = writer.write_suspense_marker("home", SuspenseState::Pending);
writer.flush();
let early = writer.telemetry_snapshot();
assert!(early.ttfb_ms.is_some(), "a chunk went out");
assert!(
early.first_visible_chunk_ms.is_none(),
"markup, doctype and comments alone are not visible"
);
let _ = writer.write("</title></head><body><p>hello</p>");
writer.flush();
assert!(writer.telemetry_snapshot().first_visible_chunk_ms.is_some());
}
#[test]
fn visible_text_detection_skips_markup() {
assert!(!has_visible_text("<!DOCTYPE html>\n<html> <head>"));
assert!(!has_visible_text("<!--krab:suspense:a:pending--> "));
assert!(!has_visible_text("<div class=\"x\">"));
assert!(has_visible_text("<p>hi</p>"));
assert!(has_visible_text("tail text"));
assert!(!has_visible_text("<!-- open"));
assert!(!has_visible_text("<div class=\"x"));
}
#[test]
fn budget_guard_blocks_writes_once_exceeded() {
let mut writer = ChunkedStreamWriter::new(128, 256).with_max_total_bytes(10);
assert!(writer.write("12345"));
assert!(writer.write("67890"));
assert!(!writer.write("EXTRA")); writer.flush();
let telemetry = writer.telemetry_snapshot();
let finished = writer.finish();
assert_eq!(finished.concat(), "1234567890");
assert!(finished.budget_exceeded);
assert!(!finished.cancelled);
assert!(!finished.is_complete());
assert_eq!(telemetry.budget_limit_bytes, Some(10));
assert!(telemetry.budget_exceeded);
assert!(!telemetry.stream_cancelled);
}
#[test]
fn suspense_marker_dropped_by_budget_is_not_counted() {
let pending_marker = "<!--krab:suspense:home:pending-->";
let mut writer =
ChunkedStreamWriter::new(128, 256).with_max_total_bytes(pending_marker.len());
assert!(writer.write_suspense_marker("home", SuspenseState::Pending));
assert!(!writer.write_suspense_marker("home", SuspenseState::Resolved));
let telemetry = writer.telemetry_snapshot();
assert_eq!(telemetry.suspense_marker_count, 1);
assert_eq!(telemetry.boundary_events.get("home"), Some(&1));
let finished = writer.finish();
assert!(finished.budget_exceeded);
assert_eq!(finished.concat(), pending_marker);
}
#[test]
fn suspense_marker_after_cancel_is_not_counted() {
let mut writer = ChunkedStreamWriter::new(64, 64);
assert!(writer.write_suspense_marker("home", SuspenseState::Pending));
writer.cancel("client disconnected");
assert!(!writer.write_suspense_marker("home", SuspenseState::Resolved));
let telemetry = writer.telemetry_snapshot();
assert_eq!(telemetry.suspense_marker_count, 1);
assert_eq!(telemetry.boundary_events.get("home"), Some(&1));
}
#[test]
fn budget_guard_can_be_set_after_initialization() {
let mut writer = ChunkedStreamWriter::new(128, 256);
writer.set_max_total_bytes(4);
assert!(writer.write("abcd"));
assert!(!writer.write("e")); writer.flush();
let telemetry = writer.telemetry_snapshot();
let finished = writer.finish();
assert!(finished.budget_exceeded);
assert_eq!(finished.concat(), "abcd");
assert_eq!(telemetry.budget_limit_bytes, Some(4));
assert!(telemetry.budget_exceeded);
assert!(!telemetry.stream_cancelled);
}
#[test]
fn cancellation_stops_future_writes_and_exposes_reason() {
let mut writer = ChunkedStreamWriter::new(64, 64);
assert!(writer.write("<html>"));
writer.cancel("client disconnected");
assert!(!writer.write("<body>should-not-appear</body>"));
writer.flush();
let telemetry = writer.telemetry_snapshot();
assert!(writer.is_cancelled());
assert!(telemetry.stream_cancelled);
assert_eq!(
telemetry.cancel_reason.as_deref(),
Some("client disconnected")
);
let finished = writer.finish();
assert!(finished.cancelled);
assert!(!finished.budget_exceeded);
assert!(!finished.is_complete());
assert_eq!(finished.concat(), "<html>");
}
}