feat: Allow re-run of RelicApp

[nielsenko]

Description

Fixes a bug where RelicApp could not be restarted after calling close().

Related Issues

• Fixes: Support restarting RelicApp after close #258

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

• No breaking changes.

Additional Notes

This came up while working on serverpod/serverpod#4101

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Enhanced resource cleanup and application stability by ensuring internal state references are properly reset when the application closes. This prevents potential issues caused by lingering references to closed objects.

• Tests

  • Added tests to validate repeated serve behavior and the ability to reliably restart serving after closure, ensuring robust application restart capabilities and state management.

[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.

📝 Walkthrough

Walkthrough

Modified RelicApp.close to explicitly reset internal state by setting _reloadSubscription and _server to null after closing resources. Added two tests validating repeated serve behavior and serve-close-serve restart cycles.

Changes

Cohort / File(s)	Summary
RelicApp lifecycle cleanup lib/src/router/relic_app.dart	Modified close() method to null out _reloadSubscription and _server after canceling and closing them, ensuring internal state is cleared alongside resource cleanup
RelicApp lifecycle tests test/router/relic_app_test.dart	Added two new test cases: one validating that calling serve() twice on the same instance throws StateError, and another testing the full serve→close→serve restart cycle completes successfully

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Single-purpose state cleanup with straightforward null assignments
• Two new tests follow existing test patterns
• Changes are homogeneous and low-complexity

Possibly related PRs

• feat: RelicApp now supports hot-reload #226: Introduced _reloadSubscription and _server state management along with the initial close/restart logic that this PR directly modifies
• feat!: Introduce RelicApp #212: Introduced RelicApp lifecycle methods (run/serve/close) and the foundational serve/close tests that this PR extends

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	No pull request description was provided by the author. The repository requires a detailed description following a specific template that includes multiple required sections: Description, Related Issues, Pre-Launch Checklist, Breaking Changes, and Additional Notes. The complete absence of any description content means the pull request does not meet the repository's documentation requirements and lacks critical information such as issue references, testing confirmation, and style guide compliance assertions.	Add a comprehensive pull request description following the repository template. Include a detailed explanation of what the changes enable (restarting RelicApp after closure), link any related GitHub issues using the "Closes/Fixes" syntax, confirm completion of the pre-launch checklist items, and document whether this introduces breaking changes. Since this is a draft PR, these details should be completed before requesting final review.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "feat: Allow re-run of RelicApp" directly and clearly reflects the main purpose of the changes. The modifications enable RelicApp to be restarted after being closed by resetting internal state and adding tests that validate serve-close-serve cycles. The title is concise, uses standard semantic commit conventions, and would help teammates quickly understand the primary change when reviewing history.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{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.48%. Comparing base (227fee7) to head (b9de5e2).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #257      +/-   ##
==========================================
+ Coverage   91.44%   91.48%   +0.03%     
==========================================
  Files          89       89              
  Lines        3473     3475       +2     
  Branches     1769     1769              
==========================================
+ Hits         3176     3179       +3     
+ Misses        297      296       -1     

☔ 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]

@CodeRabbit review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nielsenko]

@CodeRabbit Create an issue to match this PR in hindsight

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Read the changed files to understand the implementation
echo "=== lib/src/router/relic_app.dart ==="
cat lib/src/router/relic_app.dart

echo -e "\n\n=== test/router/relic_app_test.dart ==="
cat test/router/relic_app_test.dart

Length of output: 8603

---

🏁 Script executed:

#!/bin/bash
# Create a GitHub issue describing the feature need
gh issue create \
  --title "Support restarting RelicApp after close" \
  --body "## Problem

Currently, a \`RelicApp\` instance cannot be reused after calling \`close()\`. If you try to call \`run()\` or \`serve()\` again, it throws a \`StateError\` because the internal \`_server\` reference is not cleared.

## Use Case

There are scenarios where restarting a server instance is desirable:
- Testing scenarios where you want to start/stop the server multiple times
- Development workflows that require programmatic server restarts
- Applications that need to temporarily stop and restart the HTTP server

## Solution

Reset internal state (\`_server\` and \`_reloadSubscription\`) to \`null\` in the \`close()\` method, allowing the app to be reinitialized and restarted.

## Related

- Implemented in PR #257
- Comment: https://github.com/serverpod/relic/pull/257#issuecomment-$(gh api repos/serverpod/relic/pulls/257/comments --jq '.[0].id // empty')" \
  --assignee nielsenko \
  --repo serverpod/relic

Length of output: 45

---

@nielsenko: I've created issue #258 to document the feature need that PR #257 addresses. The issue describes the problem of not being able to restart a RelicApp after closing it, the use cases for this functionality, and references your PR as the implementation.

You can view the issue here: #258

ヽ(•‿•)ノ

---

🧠 Learnings used

Learnt from: nielsenko
PR: serverpod/relic#146
File: lib/src/headers/typed/headers/vary_header.dart:56-67
Timestamp: 2025-09-05T08:40:01.698Z
Learning: When users respond to code review feedback with "Tracked in #[issue_number]", they are acknowledging the feedback and indicating it will be addressed in a separate issue rather than the current PR. This is an appropriate way to handle review comments that are out of scope for the current changes.

---

Learnt from: nielsenko
PR: serverpod/relic#0
File: :0-0
Timestamp: 2025-09-05T08:35:13.942Z
Learning: When a user requests to defer formatting concerns (casing, whitespace, ordering) to separate issues instead of addressing them in the current PR, create generic GitHub issues for each concern type and assign them to the user. This helps maintain PR focus on core functionality while tracking formatting improvements for future work.

---

Learnt from: nielsenko
PR: serverpod/relic#48
File: lib/src/handler/handler.dart:59-67
Timestamp: 2025-04-25T07:39:38.915Z
Learning: Nielsenko prefers using switch statements with pattern matching over if statements when working with sealed classes in Dart, as they provide exhaustiveness checking at compile time and can be more concise.

[SandPod]

👍