useSubscriptionHealth
Which of an api's calls are currently refused — the state a screen cannot derive from its own hook.
A refused subscription is terminal for its transport. It does not retry, so
there is no second error event to react to — and SubscriptionFailed presents
data: undefined, which is the value most reading layers derive loading from.
A component that branches on data === undefined therefore shows a spinner from
then on, indefinitely. The state union models this correctly (failed: true,
loading: false); what loses it is the wrapper hook in between, and a wrapper
that passes { data, loading } through is the natural shape to write.
useSubscriptionHealth answers the question no single hook can: is anything on
this api currently refused, and what.
import { useSubscriptionHealth } from '@voltro/client'
const SessionBar = () => {
const { healthy, failed } = useSubscriptionHealth('app')
if (healthy) return null
return <Banner>Not loading: {failed.map((f) => f.tag).join(', ')}</Banner>
}A tag enters failed when a call for it fails and leaves when a call for the
same tag succeeds. It is keyed by tag rather than counted, because the
question a screen asks is "is this working now" and two failures of one call are
one broken thing. healthy is the positive form of the same fact, so a component
reads if (!healthy) instead of if (failed.length > 0).
That contract crosses reconnects. The api owns one error bus for its whole mounted lifetime, while socket runtimes and subscription caches may be replaced. If the outgoing client reports a transport failure and the replacement subscription then delivers successfully, that success removes the old failure. The banner therefore describes the current calls, not the socket generation that happened to report them.
Each entry is { tag, source, error, at } — at is the timestamp of the
failure, so a bar can say since 12:04 rather than only broken.
What it does not do
The hook is not a retry mechanism and not an error boundary. Recovery belongs to
the client stack: an Unauthenticated failure makes the framework re-resolve
the credential and rebuild the connection; after a socket transport failure,
the cache re-issues active failed fibers once the next socket is protocol-ready
and the previous transport error has been cleared. A raw WebSocket open alone
is not that guarantee. Recovery preserves the fibers' last base and revision,
so a resumed delta can continue without a skeleton.
Declared handler failures are not retried by a socket open. Nothing in your app
wires any of this.
The register is scoped to the logical api mount, not one transport runtime. It
survives ordinary socket recovery, refreshAuth(), and subject reconnects so the
replacement call can resolve the previous call's health. It is still only an
observation surface: the hook itself does not reconnect, retry, or reload the
page.