Handle silent SSE connection death on mobile deep-sleep

[bmillare]

Feature Request

Datastar Version: v1.0.3
(AI notice: Everything in this post was typed out manually, I use AI tools but not to explicitly write this post).

Hi Datastar team. Thanks for everything so far. I’ve been building mobile webapps with Datastar and ran into an issue regarding long-lived SSE connections and mobile device lifecycles.

Problem

When a mobile device goes into "deep sleep" (e.g., locked in a pocket for an hour), the OS drops the network connections to save battery.

When the browser wakes up, it is unaware the TCP connection died. The underlying fetch promise for Datastar's long-lived @get actions does NOT reject, and the SSE reader does not error, instead it just hangs.

Because the request never actually settles, Datastar's retry loop is permanently blocked. The user just looks at stale data (e.g. the feed never updates). From what I can see, this cannot be fixed from the backend, instead the recovery must be initiated on the client.

My Current Workaround & Limitations

I currently work around this by listening to OS wake-up signals (like delayed pageshow or Chromium's resume) and firing a duplicate @get request with the exact same URL. This exploits Datastar's built-in global URL dedupe logic to kill the zombie connection and start a fresh one. See https://github.com/bmillare/dj.web/blob/master/src/dj/web/datastar/mobile_resume.clj for my implementation.

This is awkward long-term because:

1. It relies on side-effects. I'm not explicitlly cancelling a request, I'm relying on URL collision logic.
2. There's a strict constraint. Independent DOM elements must use distinct URLs, otherwise they cancel each other out.
3. This requires rendering duplicated Datastar expressions in the DOM to trigger the fix.

My "seed" proposal

(This is more a "seed" proposal to facilitate discussion.)

So I wouldn't want to ask Datastar Core to listen to OS-specific wake-up signals or debouncing visibility changes. Anyone can easily handle the "Policy" side (when to restart) in a plugin or consumer side wrapper.

What I think we are missing is a key "Mechanism".

Ideally I would get an officially supported seam/primitive in Datastar Core that allows a plugin to safely rebuild/restart a specific action. I feel that because Datastar's internal Fetch action already owns the AbortControllers, retry loops, SSE parser, and Last-Event-ID state, we just need a some type of durable API contract (e.g., a restart() handle, or supported Action Composition) to tell Datastar "The OS just woke up. Please safely abort and cycle the action etc."

Best,
Brent Millare

Original post: #1202

Datastar Version

v1.0.3

[bencroker]

It sounds like you already have what you need to make this work. You could handle it entirely with Datastar attributes:

<div data-on:get-updates="@get('/updates')"
     data-on:datastar-ready__document="el.dispatchEvent(new Event('get-updates'))"
     data-on:resume__document="!document.hidden && el.dispatchEvent(new Event('get-updates'))"
     data-on:pageshow__window="!document.hidden && (evt.persisted || performance.now() > 1000) && el.dispatchEvent(new Event('get-updates'))"
></div>

Or by extracting event listeners and logic into a function:

<script type="module">
  const getUpdates = () => !document.hidden && window.dispatchEvent(new Event('get-updates'))

  document.addEventListener('datastar-ready', getUpdates)
  document.addEventListener('resume', getUpdates)
  window.addEventListener('pageshow', event => {
    if (event.persisted || performance.now() > 1000) getUpdates()
  })
</script>

<div data-on:get-updates__window="@get('/updates')"></div>

You could also just reload the page if resetting everything is acceptable. That’s probably the simplest approach, and would ensure all state is refreshed and all requests restarted.