Add test to verify graceful shutdown of in-flight requests

[nielsenko]

Problem to Solve

Currently, there is a concern that the HTTP server may cut open connections immediately during shutdown rather than allowing in-flight requests to complete gracefully. The Dart SDK's HTTP server documentation suggests it should close gracefully, but testing has shown that calling close() seems to cut open connections immediately, even without the force parameter.

We need to ensure that Relic's server shutdown behavior is tested and verified to handle in-flight requests properly.

Proposal

Add a test to Relic to ensure that in-flight requests are not terminated immediately during server shutdown, but are allowed to finish up to a timeout duration.

The test should:

1. Start a Relic HTTP server
2. Initiate one or more long-running requests (e.g., requests that take several seconds to complete)
3. Trigger server shutdown while requests are in-flight
4. Verify that the in-flight requests complete successfully before the server fully shuts down
5. Verify that the shutdown respects a maximum timeout duration

Use Case

This is critical for production deployments where:

• Users have active HTTP requests when a server restart or deployment occurs
• Rolling updates need to ensure zero downtime
• Long-running API calls (e.g., file uploads, data processing endpoints) should not be abruptly terminated
• Graceful shutdown is expected as part of container orchestration (Kubernetes, Docker, etc.)

Example scenario: A user is uploading a large file when a deployment is triggered. The current request should be allowed to complete (up to a reasonable timeout) rather than being cut off mid-upload.

Alternatives

Alternative approaches considered:

1. Document the current behavior and accept immediate connection termination - rejected because this leads to poor user experience
2. Implement custom connection tracking outside of the Dart SDK's HTTP server - could be done if the SDK doesn't support graceful shutdown, but should first verify the actual behavior with tests
3. Use a reverse proxy (like nginx) to handle graceful shutdown - adds complexity and doesn't solve the underlying issue

The proposed test will help determine if the issue is with Relic's implementation or the Dart SDK itself, and guide the appropriate solution.

Additional context

This issue originated from a discussion about observed behavior where the Dart SDK's HTTP server appeared to contradict its own documentation regarding graceful shutdown. The test will provide concrete evidence of the actual shutdown behavior and serve as a regression test once the issue is resolved.

Related concerns:

• SIGINT/SIGTERM signal handling
• The behavior of HttpServer.close(force: false)
• Maximum timeout duration for graceful shutdown (needs to be configurable)

[coderabbitai]

A summary of the changes CodeRabbit can apply:

• Add a new comprehensive graceful-shutdown test suite (test/relic_server_graceful_shutdown_test.dart) plus accompanying documentation (test/relic_server_graceful_shutdown_test.md) that implement tests and helpers to verify that the Relic HTTP server (single- and multi-isolate) allows in‑flight requests and streaming responses to complete, rejects new connections after shutdown begins, tracks connection state, and handles edge cases like double-close and mount/close races.

• Add new test file test/relic_server_graceful_shutdown_test.dart implementing comprehensive RelicServer graceful-shutdown tests by creating delayed and streaming handlers and adding multiple test cases (in-flight single/multiple requests, reject new requests after shutdown, streaming during shutdown, immediate close with no requests, multi-isolate behavior, handler errors, connectionsInfo state, and shutdown edge cases like double-close and close-before-mount) to validate server close semantics and connection reporting.

• ✅ Create PR with these edits
• 📋 Get copyable edits