feat: Add force parameter to close method for immediate shutdown

[Copilot]

Description

Adds optional force parameter to server close() method enabling immediate shutdown that terminates in-flight requests. Defaults to false to preserve existing graceful shutdown behavior.

Changes:

• Added force parameter (default: false) to Adapter.close() abstract method
• Updated IOAdapter.close() to pass through to HttpServer.close(force:)
• Propagated force parameter through all RelicServer implementations (_RelicServer, _IsolatedRelicServer, _MultiIsolateRelicServer)
• Added 2 focused tests for force close behavior (with in-flight requests and on idle server)
• Updated test mock _FakeAdapter to match new signature

Usage:

// Graceful shutdown with timeout fallback
await Future.any([
  server.close(),  // Waits for in-flight requests
  Future.delayed(Duration(seconds: 30)).then((_) => server.close(force: true))
]);

Related Issues

Related to PR #292 (graceful shutdown testing)

Pre-Launch Checklist

• This update focuses on a single feature or bug fix.
• I have read and followed the Dart Style Guide and formatted the code using dart format.
• I have referenced at least one issue this PR fixes or is related to.
• I have updated/added relevant documentation (doc comments with ///), ensuring consistency with existing project documentation.
• I have added new tests to verify the changes.
• All existing and new tests pass successfully.
• I have documented any breaking changes below.

Breaking Changes

• Includes breaking changes.
• No breaking changes.

Additional Notes

Requested by @nielsenko. Enables custom timeout implementations for production environments where predictable shutdown timing is required.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Feature: Add force parameter to close method for immediate shutdown</issue_title>
<issue_description>## Feature Request

Add a force parameter to the server's close() method to allow immediate shutdown that forcefully terminates in-flight requests.

Motivation

Currently, in-flight requests can potentially keep the server alive indefinitely during shutdown. While this may not be an issue in environments like Serverpod Cloud (where containers are force-terminated after a timeout), having a force parameter would make the API more complete and give users better control over shutdown behavior.

Proposed Solution

Add a force parameter (default: false) to the close() method that:

• When false (default): Waits for in-flight requests to complete (current behavior)
• When true: Immediately closes the server and forcefully terminates remaining connections

This approach allows users to implement their own timeout logic if needed:

// Example: Close with a 30-second timeout
Future.any([
  server.close(),
  Future.delayed(Duration(seconds: 30)).then((_) => server.close(force: true))
]);

Use Case

This is particularly useful for:

• Self-hosted deployments where container orchestration behavior may vary
• Scenarios where long-running requests should not delay server shutdown indefinitely
• Production environments requiring predictable shutdown timing
• Custom timeout implementations based on specific application needs

Context

This enhancement was suggested during testing of graceful shutdown behavior in PR #292, which verified that in-flight requests complete successfully during shutdown.

Related

• PR: test: Add test to verify graceful shutdown of in-flight requests #292
• Requested by: @nielsenko</issue_description>

Comments on the Issue (you are @copilot in this section)

@SandPod This would already be supported if we add a `force` parameter to the close method. Then the user could simply add a timeout for the close future that then calls `close(force: true)`. @SandPod @coderabbitai - Please update this feature request so that it request a `force` parameter to the close method instead as suggested by the comment above.

• Fixes Feature: Add force parameter to close method for immediate shutdown #294

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.97%. Comparing base (dbfd440) to head (f8f45c7).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #314   +/-   ##
=======================================
  Coverage   91.97%   91.97%           
=======================================
  Files          97       97           
  Lines        3728     3728           
  Branches     1904     1904           
=======================================
  Hits         3429     3429           
  Misses        299      299           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nielsenko]

This is a bad group title. There is already 'Given a RelicServer with in-flight requests' group use that instead.

[Copilot]

Fixed in f8f45c7. Moved force close tests into the existing "Given a RelicServer with in-flight requests" group.

[nielsenko]

This test duplicates an existing test.

[Copilot]

Removed in f8f45c7. The test was redundant since the default behavior already tests graceful shutdown with in-flight requests.

[nielsenko]

This feels overkill. Implicitly testing default value for force is false.

[Copilot]

Removed in f8f45c7. The default value for force is implicitly tested by the existing graceful shutdown test.