glory-salvo
Native Salvo 1.0 integration for the current semantic UI and glory-ssr.
This package is an active workspace member. It replaces the former
ServerHolder adapter; no legacy HTML API or feature aliases are retained.
Ordinary SSR
render_response(widget) and render_response_with(|scope| widget) return
glory_ui::Result<salvo::Response>. Construct reactive state with
scope.owner().cage(...) inside the factory. Rendering is synchronous and
request Owners are cleaned up before returning. Async data must be prefetched
or explicitly seeded; this path does not wait for loaders.
document_response(widget, &ssr::Document) renders a complete document.
html_response(html) wraps an already assembled string, including versioned
ssr::snapshot* output. All helpers set HTTP 200 and
Content-Type: text/html; charset=utf-8; rendering failures return a typed error
before producing a response. The application chooses its error status/body.
Optional css forwards Sheet support to SSR. Optional resources exposes
ssr::snapshot_resources_with and ssr::resource_script: export terminal data
while its request App is alive, and place the escaped inert resource script
outside the exclusively hydrated root before wrapping it in html_response.
Progressive SSR
Enable stream. Share a StreamRenderer::new(max_requests)? across routes,
then call renderer.render(StreamPage { document, bootstrap }, factory).await.
The factory returns Result<ssr::stream::Stream, ssr::stream::Error> and calls
ssr::stream_with(Resources::default(), config, |scope, resources| widget).
Create fresh Resources, reactive state, widgets and local futures inside
that factory. Capture only owned Send request inputs; never capture a live
Scope, Cage or Resources from a Salvo handler.
Each admitted request owns one native worker thread and a current-thread Tokio
runtime, so ordinary Tokio timers/network I/O can wake its local resource
futures. The UI never crosses threads. Admission is bounded with no wait queue;
StreamError::Busy can be mapped to HTTP 503. Cloned renderers share the limit.
Choose both that limit and the underlying SSR task/chunk/resource budgets for
the application. Separate renderer instances have separate limits.
StreamRenderer::new leaves request durations unlimited. Applications can opt
into StreamRenderer::with_timeouts(max_requests, StreamTimeouts { request, idle }), where both fields are Option<std::time::Duration>. request bounds
total time from admission, including startup and body work. idle bounds time
without a successfully prepared frame reply after the shell, including waiting
for HTTP body demand or pending resources. A successful frame resets only the
idle deadline. Choose idle limits with expected client backpressure in mind;
both defaults are None. Zero and unrepresentable durations return
StreamError::Config.
Expiration disposes the request on its worker and releases admission after
cleanup, even if the caller retains the response without polling its body.
Startup expiration returns StreamError::Timeout(StreamTimeout::Request);
later body errors distinguish StreamTimeout::Request and StreamTimeout::Idle,
including when a body is first polled after its worker has timed out. No
successful End is emitted. These limits are cooperative: synchronous factories,
serialization, cleanup or blocking loader code cannot be interrupted. An overdue
factory is rejected when it returns; limits cannot bound how long such code
blocks its worker or holds admission. The limits require no changes to SSR core.
The response is prepared after shell construction/serialization, before polling any loader. It starts with the shared SSR document prefix and preload capture script, then the Shell. Subsequent HTTP body polls request one Patch/End at a time; no background producer collects or renders the remaining frames. The bridge has at most one outstanding demand/reply, with no frame backlog. TCP and server buffers may still accept a finite prefix while a client pauses.
Dropping the response/body cancels idle and pending-I/O requests, disposing the App, tasks and resource registrations on their worker. It never blocks the network thread waiting for a join. Cancellation is cooperative: synchronous application code must return/yield; blocking factory/loader code cannot be preempted. Request admission is released after local cleanup and runtime drop.
Startup failures return Err so a handler can select an HTTP error response.
Later rendering/serialization failures become body errors, closing the response
without a successful End. Worker panics close outstanding replies and also
terminate the body; they are not rendered into the page.
Serve the matching glory_web::STREAM_SCRIPT at bootstrap.script_url and
allow it in the application's CSP. The preload script precedes editable shell
DOM; every frame uses the shared inert JSON + parser-blocking external script
format. End carries canonical rekeying and terminal resource seeds for an
optional later WASM hydration. This adapter does not invent another wire format
or automatically initialize WASM. CSP headers and any hydration assets belong
to the application. Document::nonce covers its styles, while
Bootstrap::nonce covers the stream scripts; configure both under your policy.
Responses set Cache-Control: no-store and X-Accel-Buffering: no, without a
Content-Length. Configure middleware, compression and reverse proxies to flush
progressively; the header alone cannot control every intermediary.
Runnable example and checks
The active example serves /plain, /stream and the matching
/stream.js. /stream delivers an immediate shell and two independently
delayed resource updates. Its CSP allows same-origin external scripts and
inline styles; no inline executable JavaScript is needed. It demonstrates
progressive DOM updates and End resource export, without a WASM bundle.
New-Item -ItemType Directory -Force $env:TEMP | Out-Null
cargo metadata --no-deps --format-version 1 # verify target_directory is on D:
cargo run --locked -p glory-salvo --example ssr --features stream
# Optional address: ... --features stream -- 127.0.0.1:5801
cargo test --locked -p glory-salvo --all-features
Tests cover semantic HTML/control escaping, reactive Owner cleanup, snapshot wrapping, document metadata/CSS, resource seeds, first-byte ordering, per-demand backpressure, reverse completion, request isolation, startup/body errors and panics, cancellation during initialization, admission recovery, real Salvo chunked HTTP, TCP disconnect and a paused TCP reader. The browser acceptance script beside the example checks the actual progressive DOM and CSP behavior. Timeout tests also retain unread responses and open sockets while pending resources expire, verify error classification and Owner cleanup, and reuse the released admission slot.
The library and example are native-only (empty on wasm32). Merely using the Glory facade/default/HTML/SSR features does not enable this HTTP integration. Other old Salvo application directories remain extraction references unless explicitly migrated; use this active package's example for the new architecture.