proton-bridge: gRPC metrics exporter (prototype)

[mgarratt]

Summary

Prototype of Option B from the metrics discussion: replace the external black-box probe approach (the stale feat/proton-bridge-metrics branch) with an in-container Prometheus exporter that scrapes Bridge's gRPC frontend, so we get per-account login state and dropped-auth signals — not just transport readiness.

Opened as a draft: the live gRPC path is proven, but the account/event metrics need a real Proton login to exercise (see below).

Approach

• Run bridge as --grpc by default (BRIDGE_MODE=grpc). This serves the exact same mail bridge as --noninteractive plus the gRPC machine API the desktop GUI uses. --parent-pid defaults to -1, so the GUI watchdog that would otherwise shut it down stays disabled. noninteractive/cli remain selectable.
• exporter/ Go module reads grpcServerConfig.json, dials the unix socket, pins Bridge's self-signed TLS cert (CN 127.0.0.1) and presents the server-token — same handshake as the GUI. It polls GetUserList/Version and subscribes to RunEventStream.
• Vendored gRPC stubs (exporter/bridgepb/, GPL-3.0, taken verbatim from upstream with only the Go package renamed) — avoids a protoc toolchain in the build. Re-vendor step documented in exporter/README.md for each version bump (the gRPC API is Bridge's internal GUI contract and can shift between releases).
• Dedicated exporter build stage; new exporter s6 service; healthcheck now also checks the service + /metrics 200; CONTAINER_METRICS_PORT (default 9154).

Metrics

proton_bridge_up, proton_bridge_info{version}, proton_bridge_accounts_total, proton_bridge_account_connected{account}, proton_bridge_account_state{account,state}, proton_bridge_account_used_bytes/_total_bytes{account}, proton_bridge_internet_connected, and counters proton_bridge_user_disconnected_total / user_bad_event_total / imap_login_failed_total (+ exporter_scrape_errors_total).

Validation (local, linux/arm64)

Check	Result
Image build (multi-stage incl. Go exporter)	✅
hadolint + shellcheck (incl. service scripts)	✅ clean
bridge --grpc bootstraps headless, writes config, no watchdog kill	✅ (~13s)
Exporter connects (TLS-pinned + token, unix socket)	✅ proton_bridge_up 1, scrape_errors 0
/metrics serves 200; proton_bridge_info{version="3.25.0+git"}	✅
Container HEALTHCHECK	✅ healthy

Not yet exercised: account/event series (account_connected, *_disconnected_total, …) need a real logged-in Proton account — they're registered but emit no samples until then. CI will also run the full multi-arch build.

Follow-ups before un-drafting

• Validate against a real account (confirm account_state transitions + a forced disconnect increments the counter).
• Decide whether --grpc should be the default or opt-in.

🤖 Generated with Claude Code