Skip to content

feat(lightning): add ThunderHub health endpoint for monitoring#182

Merged
TaprootFreak merged 1 commit intodevelopfrom
feat/thunderhub-health-endpoint
May 8, 2026
Merged

feat(lightning): add ThunderHub health endpoint for monitoring#182
TaprootFreak merged 1 commit intodevelopfrom
feat/thunderhub-health-endpoint

Conversation

@TaprootFreak
Copy link
Copy Markdown
Contributor

Was

Neuer Endpoint GET /v1/thunderhub/health — gibt 200 { "up": true } wenn der upstream-ThunderHub-Container erreichbar ist, 503 wenn nicht.

Warum

Aus der DFX-Server-Migration (DFXServer/server, Stage 2.1 live seit 2026-05-08): Uptime Kuma hat 14 LDS-DEV-Monitore, alle nach demselben Pattern — https://dev.lightning.space/v1/<path>, mit lds-api als Forwarder zu lnbits / boltz-backend / claim-graphql.

ThunderHub war der einzige LDS-Service ohne Kuma-Coverage, weil:

  • Container ist nur intern via nginx auf 127.0.0.1:6123 exposed (SSH-Tunnel-Only Access für Operatoren)
  • Cloudflare-Tunnel zeigt nur auf lds-api (http://localhost:6125), nicht auf nginx

Ergebnis: mehrfach hat erst ein toter Tunnel-Reconnect des thunderhub-remote-Skripts dem Operator gezeigt, dass der Container über Stunden down war.

Konsistent zu den existing 13 Monitoren ist der Probe via lds-api. Dieser PR fügt diesen Endpoint hinzu.

Wie

@Get('health')
async health(): Promise<{ up: true }> {
  const url = Config.blockchain.lightning.thunderhub.apiUrl;
  if (!url) throw 503;
  try {
    await this.http.request({ url, method: 'GET', responseType: 'text', timeout: 5000,
      validateStatus: (status) => status >= 200 && status < 500 });
    return { up: true };
  } catch (e) {
    throw 503; // mit Error-Body
  }
}
  • validateStatus: 2xx-4xx heisst: ThunderHub-Login-Redirect (302) oder 401-Forderung wird als UP gewertet — wir prüfen Erreichbarkeit, nicht Auth-Status.
  • 5s Timeout — kurz genug damit Kuma DOWN binnen eines Probe-Intervalls sieht.
  • Kein Body-Leak: Endpoint gibt nur {up: true} oder {up: false, error} zurück, niemals Upstream-Inhalt.
  • Kein Auth: Endpoint exposed nur einen Boolean, keine internal state.

Konfiguration

Neue env-var LIGHTNING_THUNDERHUB_URL in den 4 Vault-Items:

  • LDS DEV - API Environment Variables (Org DFX-dev-infra) → http://thunderhub:3000
  • LDS PRD - API Environment Variables (Org DFX-prd-infra) → http://thunderhub:3000

Default ist leer → Endpoint antwortet 503 mit LIGHTNING_THUNDERHUB_URL not configured. Damit ist es safe wenn die Vault-Items vor dem Vault-Update bereits ge-mergt sind.

Test plan

  • nest build kompiliert ohne Errors
  • Prettier sauber, ESLint sauber
  • Nach DEV-Deploy: curl https://dev.lightning.space/v1/thunderhub/health → 200 {"up":true}
  • Test DOWN-Pfad: docker stop lds-thunderhub-1curl ... → 503 mit Error
  • Kuma-Monitor "LDS - thunderhub - DEV" hinzufügen (separater Schritt im DFXServer/server)

Sicherheit

  • Kein Privat-Material berührt. Endpoint exposed nur up/down Boolean.
  • Konsistent zu den existing 13 lds-api-forwarders, die alle die selbe HttpService-Pattern nutzen.

Adds GET /v1/thunderhub/health which proxies an HTTP check to the
upstream ThunderHub container and returns 200 {"up": true} when
reachable, 503 with the error otherwise.

Why: Uptime Kuma already monitors all 14 LDS services on dev.lightning.space
via lds-api-forwarded paths (/v1/lndhub/getinfo, /v1/swap/v2/...). ThunderHub
was the one service without coverage because it only listens on the internal
nginx port 6123 (127.0.0.1 on dfxdev) and is reachable to operators only via
the SSH-tunneled `thunderhub-remote` script in the server repo. Several
times now a tunnel reconnect has been the only signal that the underlying
container has been down for hours. The Kuma-consistent fix is to expose a
narrow health probe through the same lds-api forwarding pattern the other
13 monitors already use.

Configuration:
- New env var LIGHTNING_THUNDERHUB_URL (default: empty → 503).
  In the DFX server repo's compose, this should be set to
  http://thunderhub:3000 (intra-stack docker DNS, no SSL — same pattern
  as the existing LIGHTNING_LNBITS_*_URL after the recent HTTP-intra-stack
  switch in DFXServer/server PR #133).

Endpoint behavior:
- 200 { "up": true } when ThunderHub responds with any 2xx/3xx/4xx
  (validateStatus rules out 5xx), so login-redirect is treated as up.
- 503 { "up": false, "error": "..." } on connect failure / 5xx / timeout.
- 5s timeout — short enough that Kuma sees DOWN within one probe interval.

No auth on the endpoint by design: it returns only a boolean, no internal
state, no upstream response body. Safe to be public.
@TaprootFreak TaprootFreak requested a review from Danswar May 8, 2026 11:10
@TaprootFreak TaprootFreak marked this pull request as ready for review May 8, 2026 11:10
@TaprootFreak TaprootFreak merged commit df49329 into develop May 8, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant