Module

server.speculation_rules

Speculation Rules injection — automatic prefetch/prerender hints from route definitions.

Three modes controlled byAppConfig.speculation_rules:

  • False / "off"— inject nothing (default).
  • True / "conservative"— prefetch linked pages on hover/pointerdown. Safe for all apps.
  • "moderate"— prefetch all static GET routes eagerly, prerender on hover.
  • "eager"— prerender static GET routes eagerly. Use only when routes are side-effect-free and fast.

Injected into full-page HTML responses viaHTMLInjectmiddleware, before</head>.

Chirp generates rules from the router at freeze time:

  • Static GET routes (no path parameters) become"source": "list" candidates.
  • Parametric routes are expressed ashref_matchespatterns.
  • SSE endpoints (referenced=True) and non-GET routes are excluded.
4Functions

Functions

normalize_speculation_rules 1 SpeculationRulesMode ▼
Canonicalize the ``speculation_rules`` config value. Returns one of ``"off"``,…
def normalize_speculation_rules(value: bool | str) -> SpeculationRulesMode

Canonicalize thespeculation_rulesconfig value.

Returns one of"off", "conservative", "moderate", or "eager".

Parameters
Name Type Description
value bool | str
Returns
SpeculationRulesMode
_route_to_href_pattern 1 str ▼
Convert a Chirp route path to a Speculation Rules ``href_matches`` pattern. ``…
def _route_to_href_pattern(path: str) -> str

Convert a Chirp route path to a Speculation Ruleshref_matchespattern.

/users/{id:int} becomes /users/*.

Parameters
Name Type Description
path str
Returns
str
build_speculation_rules_json 2 str ▼
Generate Speculation Rules JSON from the router. Returns empty string for ``"o…
def build_speculation_rules_json(router: object, mode: SpeculationRulesMode) -> str

Generate Speculation Rules JSON from the router.

Returns empty string for"off"mode or when no eligible routes exist.

Parameters
Name Type Description
router object
mode SpeculationRulesMode
Returns
str
build_speculation_rules_snippet 2 str ▼
Build the full ```` snippet. Returns empty string when mode is ``"off"`` or no…
def build_speculation_rules_snippet(router: object, mode: SpeculationRulesMode) -> str

Build the full<script type="speculationrules">snippet.

Returns empty string when mode is"off"or no rules are generated.

Parameters
Name Type Description
router object
mode SpeculationRulesMode
Returns
str