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.