Manual shutdown

[RomanEmreis]

Summary

Adds a ShutdownHandle API for programmatic graceful shutdown that composes with the existing OS signal handler (Ctrl+C, SIGTERM). Users can now stop a running server from inside
their own code — an /admin/shutdown route, an external IPC, a custom orchestrator, or integration tests that don't use TestServer — without having to send themselves a signal.

The handle is a thin newtype around tokio_util::sync::CancellationToken (already a workspace dependency, already re-exported as volga::CancellationToken). Two ways to use it:

// Framework owns the handle.
let (app, shutdown) = App::with_shutdown();

// Or bring your own.
let handle = ShutdownHandle::new(); // also: from_token, on_signal, From<CancellationToken>
let app = App::new().with_shutdown_signal(handle.clone()); 

Internally the existing tokio::sync::watch::channel<()> shutdown bus is unchanged — shutdown_signal() just races the OS signal against handle.cancelled(), and either path drains in-flight requests via the same code as Ctrl+C today.

Type

• Bug fix
• Feature
• Enhancement
• Performance
• Documentation
• Refactor
• Security
• Breaking change

Checklist

• I added/updated tests where it makes sense
• I updated docs/examples if needed
• This change is backwards-compatible (or clearly marked as breaking)
• I ran formatting/lints locally (if applicable)

Notes for reviewers

• Composition, not replacement. with_shutdown_signal adds a trigger; the OS signal handler is always still active. There's no opt-out yet — if a use case appears, that's a follow-up.
• Graceful only. No shutdown_now() / hard-kill variant. Easy to add later without breaking the current API.
• shutdown_on task lifetime. Each shutdown_on(future) spawns a task that runs the future to completion even if the handle is dropped. The trailing token.cancel() is a no-op in that case — no leak beyond the user-supplied future. Documented in shutdown.rs.
• Test infra. Integration tests in volga/tests/shutdown_tests.rs drive App::run() directly rather than going through TestServer (which has its own shutdown plumbing and wouldn't exercise this path). Helpers pick_free_port/wait_until_listening are kept local to the file.
• pub(crate) mod shutdown. The module is crate-private; only ShutdownHandle is re-exported from volga::. No redundant volga::app::shutdown::ShutdownHandle path.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa9a9b24ba

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[RomanEmreis]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dca2a435d3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[RomanEmreis]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9be4ed66af

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[RomanEmreis]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f1f1e55ca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[RomanEmreis]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f1f1e55ca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[RomanEmreis]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b5e26d3db3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[RomanEmreis]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e09bb37540

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[RomanEmreis]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Delightful!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".