Crate forma_server 

Axum middleware for Forma SSR.

Provides page rendering (try_render), content-hashed asset serving, CSP headers with cryptographic nonces, an opt-in service worker (sw), and the Phase 1 (client mount) / Phase 2 (SSR reconcile) rendering pipeline.

Quick Start

use forma_server::{try_render, PageConfig, PageResponse, RenderCtx, RenderError};

Serving a page

try_render returns the page or a coded RenderError; the handler chooses the response. A page’s HTML embeds a per-request nonce that only its policy blesses, so the HTML, the policy and Cache-Control: no-store travel together: a PageResponse, as axum’s IntoResponse, writes all of them and cannot be sent without them. A handler that needs a looser policy adds typed PolicyExtensions through its RenderCtx; it never edits the policy’s text.

use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use forma_server::{try_render, PageConfig, RenderCtx};

fn home(config: &PageConfig) -> Response {
    match try_render(config, &RenderCtx::new()) {
        Ok(page) => page.into_response(),
        Err(_) => StatusCode::INTERNAL_SERVER_ERROR.into_response(),
    }
}

Markup the page carries unescaped is a RawHtml, made only by RawHtml::trusted, so a search for that name finds every raw entry. The route’s modulepreload links come from the build’s manifest and head links have a typed field, both through RenderCtx; data goes through config_json.

Content nobody reviewed renders in the preview frame, whose document PageResponse::frame writes (frame).

A route the build declares ssr: false is served by render_browser_shell. At start, load_ir_modules_strict is the module loader: stop on its errors, before the port binds. IrModules loads the same way and, in a debug build, rereads a page’s module when the build’s watch mode rewrites it. Deprecated in 0.2.2, removed in 3.0.0: render_page and its Phase 1 fallback, render_page_with_nonce, the lenient load_ir_modules, PageOutput’s public fields and headers(), and PageConfig::config_script.

Re-exports

pub use csp::build_csp_header;

pub use csp::generate_csp_nonce;

pub use csp::CspNonce;

pub use csp::InvalidNonce;

pub use csp::NonceError;

pub use csp::PolicyError;

pub use csp::PolicyExtensions;

pub use frame::FrameError;

pub use frame::PreviewFrame;

pub use frame::FRAME_RUNTIME_ASSET;

pub use head::HeadLink;

pub use head::HeadLinkError;

pub use head::ModulePreloads;

pub use ir_compat::load_ir_modules;Deprecated

pub use ir_compat::load_ir_modules_strict;

pub use ir_compat::IrLoadError;

pub use ir_compat::IrModules;

pub use raw::RawHtml;

pub use render::render_browser_shell;

pub use render::try_render;

pub use render::RenderCtx;

pub use render::RenderError;

pub use response::PageParts;

pub use response::PageResponse;

pub use response::RenderCounts;

pub use template::render_page;Deprecated

pub use template::render_page_with_nonce;Deprecated

pub use types::*;

Modules

assets

Serving content-hashed files out of the embedded dist directory.

csp

Content-Security-Policy construction and nonce generation. CSP nonce generation and policy construction: the enforced policy, its typed extensions, and Trusted Types in Report-Only.

frame

The preview frame: a document with an opaque origin, for content nobody reviewed.

head

Typed homes for the page’s head: manifest preloads and head links. Typed homes for what applications put in body_prefix that is not their own markup: the route’s modulepreload links, read from the build’s manifest and nonced here, and the page’s head links.

ir_compat

Loading and version-checking the per-route .ir modules at startup.

raw

Raw HTML: the one named type for markup written unescaped. Raw HTML: markup forma-server writes into the page exactly as it is given.

render

The render that returns its failure: try_render, render_browser_shell. The 0.2.2 render: a page with its counts, or a coded error the handler answers.

response

The page response: HTML that never leaves without its policy. The page response: HTML that never leaves without its policy.

sw

The service worker: opt-in, per application, and retired everywhere else.

template

The HTML page template and the SSR render entry points.

types

Request/response types: page config, manifest, render mode.

Structs

Bytes

Re-exported because it appears in assets::asset_bytes’s signature. A cheaply cloneable and sliceable chunk of contiguous memory.

WalkLimits

Re-exported: RenderCtx::with_limits takes it. Resource budgets for a single walk.