contracts.rules_sse

Remove Kida + HTML comments so element scans ignore illustrative markup.

Replace Kida expressions so route-pattern matching still works.

Extract all sse-swap event names from source (comments stripped).

Return(confident, value)for a string keyword argument.

Find user-accessor calls and long-lived loops inside a generator body.

found records whether get_user() / current_user()is called anywhere in the walked tree;in_long_lived_looprecords whether any such call sits inside awhile / for / async for(the long-lived SSE pump where connect-time identity pinning becomes a staleness caveat). A bare user read at generator top-level (outside any loop) is treated as short-lived — it resolves once and the stream ends.

Return the single positional argument of the firstEventStream(...)call.

EventStream(generate()) -> the generate()call node; EventStream(gen) -> the gen Name node. Returns Nonewhen no EventStream(...)call with a first positional arg is found.

Resolve the generator-producing name from anEventStream(...)arg.

generate() -> "generate"; gen -> "gen". Nonefor any other shape (e.g. an inline comprehension or a method call) — the caller falls back to walking the whole handler tree.

Find a nestedasync def/defnamed name inside tree.

Resolve a MODULE-LEVEL generator function by name via__globals__.

The handler-source AST walk only sees generators defined as NESTED functions inside the handler. A module-levelasync def gen()passed as EventStream(gen())is NOT in the handler source — so we resolve the bare name against the handler's__globals__and parse THAT function's source. ReturnsNonewhen the name is not a module-level function, or its source is unavailable.

Return a populated_UserReadFinderfor an EventStream route's generator.

ReturnsNone when the route is NOT an EventStreamroute, or its source/generator cannot be statically resolved (errs toward silence). The generator is resolved in two scopes:

1. NESTED — an inlineasync def generate()inside the handler (the common case). Walked directly from the handler tree.
2. MODULE-LEVEL — a bare name passed asEventStream(gen())resolved via the handler's__globals__and parsed separately (see _resolve_module_level_generator()).

Falls back to walking the WHOLE handler tree when the generator argument's shape is not a plain name/call (e.g. an inline comprehension) so an inline user read is still seen.

Flag an EventStream generator that reads the user with noAuthMiddleware.

AnEventStream route whose generator calls get_user()/ current_user()resolves the connect-time-pinned user — but only when AuthMiddleware is wired. Without it the captured user is AnonymousUser for the entire stream, so an auth-sensitive SSE feed silently serves the anonymous view to everyone. Parallelsauth_middleware: env-aware (ERROR production / WARNING staging / silent development — the dev behavior surfaces locally), detected by middleware class NAME.

SCOPE: the static AST walk resolves the generator in two scopes — an inline nestedasync def inside the handler, AND a module-level async def passed asEventStream(gen()) (resolved via the handler __globals__). A generator built by any other indirection (a factory, a method, a value threaded through another call) is not statically resolvable and is silently skipped — errs toward silence, never a false ERROR.

Nudge that SSE user identity is connect-time-pinned in a long-lived stream.

POST-FIX residual guard, NOT a broken-pattern flag: reading the user inside anEventStreamgenerator now WORKS (connect-time capture). This only surfaces the semantic caveat — when the user is read inside a LONG-LIVED loop (while / async for / for), the identity is pinned at connect and is NOT refreshed on a mid-stream logout / permission change for the life of the connection. WARNING (env-aware: silent development, WARNING staging / production); never ERROR — the pattern is correct, this is a known-semantic nudge for auth-sensitive long-lived streams.

Same two-scope resolution (and the same single-indirection blind spot) as check_sse_auth_gate(). A short-lived top-level user read (outside any loop) is NOT nudged — it resolves once and the stream ends.

Infer literal SSE event names emitted by a route handler.

ReturnsNonewhen source is unavailable or a relevant event name is dynamic. Dynamic cases are skipped by the cross-reference check so the contract errs toward silence instead of false positives.

Error when sse-swap appears on same element as sse-connect.

Warn when sse-connect is inside broad hx-target scope without mitigation.

Cross-reference sse-swap values against declared and inferred events.