feat: opt-in heartbeat liveness detection with fail-fast connection errors #4

Merged

w33ble merged 6 commits from feat/heartbeat into main

2026-09-29 12:03:53 -06:00

hijynx commented

2026-09-29 11:58:39 -06:00

Collaborator

Summary

Opt-in heartbeat liveness detection (--heartbeat, --heartbeat-interval, --heartbeat-timeout): idle connections get an MCP ping, a missed pong drops into the normal reconnect path. Ping responses are never forwarded to stdout.
Reconnect with backoff and session re-establishment: replays stored initialize, flushes buffered stdin, honors --max-disconnected-time / --initial-retry-interval.
Fail fast instead of hanging: probe 401/403 is a fatal auth error, probe 404 reports endpoint-not-found, probe 5xx reports remote server error; auth failures on write/replay paths bypass the retry loop; any failure before the first live session exits non-zero.

Why

With bad/missing credentials the bridge logged connected, got Forbidden on the initialize write, then retried forever without ever answering the client, so mcp-cli timed out and appeared hung (reproduced against the pit endpoint). Failures now surface immediately on stderr with a clear message; post-connect transient drops still retry as before.

Verification

go build ./..., go vet ./..., golangci-lint run (0 issues), go test ./... all pass. Verified live via mcp-cli against the pit endpoint: whoami returns the client identity.

## Summary - Opt-in heartbeat liveness detection (`--heartbeat`, `--heartbeat-interval`, `--heartbeat-timeout`): idle connections get an MCP ping, a missed pong drops into the normal reconnect path. Ping responses are never forwarded to stdout. - Reconnect with backoff and session re-establishment: replays stored `initialize`, flushes buffered stdin, honors `--max-disconnected-time` / `--initial-retry-interval`. - Fail fast instead of hanging: probe 401/403 is a fatal auth error, probe 404 reports endpoint-not-found, probe 5xx reports remote server error; auth failures on write/replay paths bypass the retry loop; any failure before the first live session exits non-zero. ## Why With bad/missing credentials the bridge logged `connected`, got `Forbidden` on the `initialize` write, then retried forever without ever answering the client, so mcp-cli timed out and appeared hung (reproduced against the pit endpoint). Failures now surface immediately on stderr with a clear message; post-connect transient drops still retry as before. ## Verification `go build ./...`, `go vet ./...`, `golangci-lint run` (0 issues), `go test ./...` all pass. Verified live via mcp-cli against the pit endpoint: `whoami` returns the client identity.

hijynx added 6 commits

2026-09-29 11:58:39 -06:00

feat: opt-in heartbeat liveness detection

CI / Build, vet, test, lint (pull_request) Successful in 57s

Details

32e4ecea26

Disabled by default. With --heartbeat, the bridge pings the
remote after --heartbeat-interval (default 30s) with no traffic
in either direction; a pong missing past --heartbeat-timeout
(default 10s) drops the connection into the normal reconnect
path. Ping responses are matched by exact ID and never forwarded
to the client. All flags have MCP_BRIDGE_* env fallbacks.

fix: reset heartbeat idle clock on rejected ping, drop dead retire state d8356757dc

fix: reject non-positive heartbeat interval/timeout when enabled a5137899fc

refactor: explicit wrote flag, plain int64 activity 8ecbb32e3c

test: cover heartbeat tick, abandon, and validation paths

CI / Build, vet, test, lint (pull_request) Successful in 1m0s

Details

0405595e45

fix: fail fast on auth and probe failures instead of retrying forever

CI / Build, vet, test, lint (pull_request) Successful in 2m50s

Details

bd871dddce