Module

middleware.debug_fragment_validator

Debug-mode validator for fragment responses.

Catches silent failure modes where a fragment response would paint a broken page in the browser:

  • <!DOCTYPEin fragment body (a full page rendered into an outlet).
  • Duplicateid="..."for registered shell-region ids (would collide with the live DOM after the swap).

Only active whenAppConfig.debug=True; auto-registered during _collect_builtin_middlewarewhen an OOB registry is present. Warns by default;strict=Trueraises instead for CI enforcement.

2Classes2Functions

Classes

FragmentValidationError 0 ▼
Raised by ``DebugFragmentValidator`` in strict mode when a fragment response leaks full-page markup…

Raised byDebugFragmentValidatorin strict mode when a fragment response leaks full-page markup or duplicate ids.

DebugFragmentValidator 2 ▼
Middleware that inspects fragment responses for breakage patterns. Only inspects buffered ``Respon…

Middleware that inspects fragment responses for breakage patterns.

Only inspects bufferedResponse objects with text/htmlcontent whenrender_intent == "fragment" (or "unknown"on an htmx request, matchingHTMLInject's skip rule).

Streaming responses are skipped — buffering them would defeat the point of streaming and the body is rarely available as a single string anyway.

Methods

Internal Methods 2 ▼
__init__ 2 ▼
def __init__(self, oob_registry: OOBRegistry, *, strict: bool = False) -> None
Parameters
Name Type Description
oob_registry —
strict — Default:False
__call__ 2 AnyResponse ▼
async
async def __call__(self, request: Request, next: Next) -> AnyResponse
Parameters
Name Type Description
request —
next —
Returns
AnyResponse

Functions

_count_id_occurrences 2 int ▼
Count ``id="target_id"`` and ``id='target_id'`` occurrences.
def _count_id_occurrences(body: str, target_id: str) -> int
Parameters
Name Type Description
body str
target_id str
Returns
int
_is_selectable_shell_outlet_response 2 bool ▼
True for app-shell boosted responses meant to be narrowed by hx-select. The br…
def _is_selectable_shell_outlet_response(body: str, request: Request) -> bool

True for app-shell boosted responses meant to be narrowed by hx-select.

The browser owns the inheritedhx-select="#page-content"attribute; it is not sent as a request header. In debug mode this validator sees the pre-selection response, so a correctly selectable shell-outlet response can look like a full document with duplicate shell-region ids. Treat the canonical app-shell shape as valid when the response contains the selector target htmx will extract.

Parameters
Name Type Description
body str
request Request
Returns
bool