Skip to content

Add opt-in keepalive requests over grpc.health.v1.Health/Check - #7

Open
gartnera wants to merge 1 commit into
mainfrom
claude/jolly-feynman-b89n82
Open

gartnera wants to merge 1 commit into
mainfrom
claude/jolly-feynman-b89n82

Conversation

@gartnera

Copy link
Copy Markdown
Member

Why

A quiet HTTP/2 connection carries no traffic at all. URLSession can't send HTTP/2 PING frames, and this plugin doesn't turn on Cronet's experimental heartbeat. So anything on the path that closes idle connections can close it: an ALB's idle timeout (60 s by default), a NAT mapping, or the server's own. A load balancer that terminates HTTP/2 would also answer PINGs itself, so they'd never reach the server.

This PR only keeps connections busy. Detecting a dead connection is left to the read idle timeout being added separately.

What

NativeHttpConfig.keepAlive, opt-in and the same on both platforms:

NativeHttpConfig(
  http3Origins: {origin},
  keepAlive: const NativeKeepAlive(interval: Duration(seconds: 15), timeout: Duration(seconds: 10)),
)
  • What it sends: a Connect unary grpc.health.v1.Health/Check with an empty HealthCheckRequest, which encodes to no bytes.
  • When: every interval to each origin that has calls open, over the same URLSession or Cronet engine as those calls, so it uses their connection. The first one goes out one interval after the first call opens. Requests stop once no call is open.
  • Limits: one request at a time per origin. A request still running after timeout is canceled.
  • Outcomes: it never fails calls, and any response counts. A response other than HTTP 200 is reported once per origin through FlutterError.onError, since it usually means the server doesn't register the health service.
  • Not affected: keepalive requests don't reach onResponse.
  • Servers need grpchealth.Register(server, grpchealth.NewStaticChecker()), and the load balancer must route /grpc.health.v1.Health/Check like the other procedures. The README has a new "Keepalive" section covering this.

Everything lives in the shared Dart adapter (lib/src/channel/keep_alive.dart and channel_http_client.dart). The Swift and Kotlin bridges are unchanged.

Test server

  • Registers connectrpc.com/grpchealth/v2.
  • Reports each request's client address in X-Remote-Addr.
  • Lists the health checks it has received at GET /health-checks on the admin endpoint.

Tests

  • Dart unit tests (9, test/keep_alive_test.dart): run against the fake Cronet plugin, which moves to test/fake_cronet_plugin.dart. They cover:
    • nothing is sent unless configured;
    • request shape and headers, and that nothing goes out before the first interval;
    • requests repeat while a call is open and stop once none is;
    • a timeout cancels the request without touching the call;
    • a failed request fails no call;
    • one request at a time per origin;
    • close stops requests;
    • durations that aren't positive are rejected;
    • a non-200 answer is reported once.
  • Go: a test that the health service answers with SERVING and is logged, while other calls aren't.
  • Integration (eliza_test.dart): keepalives reach the server on the same connection, matched by client address, as a quiet Converse stream, and the stream still works afterwards.

Run locally:

  • flutter analyze (package and example), dart format, and flutter test: all 49 tests pass, and the keepalive suite passed 8 out of 8 repeated runs.
  • gofmt, go vet and go test ./... pass.
  • I checked the health check and admin log against the built server over HTTP/2 with curl.

I couldn't run the device integration test, because there is no simulator or emulator in my environment. CI's iOS and Android jobs will be its first run.


Generated by Claude Code

A quiet HTTP/2 connection is silent: URLSession can't send HTTP/2 PING frames, and the plugin doesn't turn on
Cronet's experimental heartbeat. Anything on the path that closes idle connections can then close it, such as an
ALB's idle timeout (60 s by default) or a NAT mapping. A load balancer that ends HTTP/2 would answer PINGs itself
anyway.

NativeHttpConfig.keepAlive (NativeKeepAlive: interval, default 15 s; timeout, default 10 s) makes a client send a
Connect unary grpc.health.v1.Health/Check, with an empty HealthCheckRequest, to each origin it has calls open to,
every interval, over the same URLSession or Cronet engine. It sends one request at a time per origin, starting one
interval after the first call opens and stopping once none is open, and cancels a request still running after the
timeout. It only keeps the connection busy: it doesn't fail calls or detect dead connections, which is left to the
read idle timeout being added separately. Any response counts; one other than HTTP 200 is reported once per origin
through FlutterError.onError, since it usually means the server doesn't register the health service. Keepalive
requests don't reach onResponse. It's all in the shared Dart adapter, so nothing changes in the native bridges.

Test server: registers grpchealth v2, reports each request's client address in X-Remote-Addr, and lists the health
checks it received at GET /health-checks on the admin endpoint.

Tests: nine Dart unit tests against the fake plugin, which moves to test/fake_cronet_plugin.dart; a Go test for the
health service and its log; and an integration test that keepalives reach the server on the same connection as a
quiet Converse stream.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BqmpXY8FMm9LGHncDYKbUX
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.

2 participants