Docs: using RESTHeart SSE in Facet templates via native EventSource API

[mkjsix]

Conclusion of analysis

After evaluating HTMX SSE extension (htmx-ext-sse) as the integration path, the conclusion is that it adds unnecessary complexity for Facet's use cases:

• Direct sse-swap with HTML payloads requires server-side per-event interception, which RESTHeart does not currently support (see Feature request: per-event SSE interceptor plugin type restheart#599)
• The fallback pattern (SSE as trigger + hx-get) works but introduces a double round-trip
• For high-frequency event flows, SSR is the wrong tool regardless

The browser's native EventSource API is sufficient, requires no external libraries, and keeps the client-side code straightforward.

What this issue covers

Document how to consume RESTHeart SSE endpoints from Facet templates using plain JavaScript and the native EventSource API. No HTMX SSE extension needed.

Recommended pattern

<tbody id="product-list">
  {% for doc in documents %}
  <tr>...</tr>
  {% endfor %}
</tbody>

<script>
  const source = new EventSource('/mydb/products/_streams/changes');

  source.addEventListener('change', () => {
    // Use HTMX to re-fetch and re-render the fragment
    htmx.ajax('GET', '/mydb/products', { target: '#product-list', swap: 'outerHTML' });
  });

  source.onerror = () => source.close();
</script>

The EventSource handles reconnection automatically. The htmx.ajax() call is optional — plain fetch() + DOM manipulation works equally well for simpler cases.

Deliverables

1. SSE section in docs/DEVELOPERS_GUIDE.md covering:

   • Brief explanation of EventSource API (connect, listen, close, auto-reconnect)
   • RESTHeart SSE endpoint format (/_streams/<name>)
   • The pattern above with a full example
   • When to use SSE vs polling
   • Auth considerations (cookies sent automatically same-origin; query param for JWT)
   • Note on high-frequency flows: use client-side rendering, not SSR

2. Working example in examples/product-catalog (tracked in Docs & example: SSE live updates via native EventSource API #7)

What is out of scope

• HTMX SSE extension (htmx-ext-sse)
• Server-side HTML-over-SSE rendering
• Any new Facet core code — this is documentation only

Acceptance criteria

• SSE docs section added to developer guide
• Pattern documented with a complete working example
• Auth and reconnect behaviour covered
• High-frequency flows guidance included
• Product-catalog example works end to end (Docs & example: SSE live updates via native EventSource API #7)