feat(signals): deprecate legacy shutdown API

CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.5.0
+
+### Deprecated
+
+The legacy shutdown API in `torrust_server_lib::signals` is deprecated. There are no behaviour
+changes and nothing is removed in this release; using these symbols now emits a compiler warning.
+
+| Deprecated                      | Migrate to                                                                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `Halted`                        | Inject a `tokio_util::sync::CancellationToken`.                                                                            |
+| `shutdown_signal`               | `cancellation_signal(token)`.                                                                                              |
+| `shutdown_signal_with_message`  | `cancellation_signal(token)` followed by your own log line.                                                                |
+| `global_shutdown_signal`        | Libraries must not subscribe to signals. The executable subscribes to SIGINT/SIGTERM and cancels the injected token.       |
+
+`Started` and `cancellation_signal` are not deprecated.
+
+### Migration
+
+1. Replace the `oneshot::Sender<Halted>` / `Receiver<Halted>` pair with a `CancellationToken`
+   shared between the code that requests shutdown and the launcher task.
+2. In the launcher, await `cancellation_signal(token.clone())` where you awaited
+   `shutdown_signal(rx_halt)`; log the message afterwards instead of using `shutdown_signal_with_message`.
+3. In the executable, subscribe to SIGINT/SIGTERM (for example `tokio::signal`) and call
+   `token.cancel()`, instead of relying on `global_shutdown_signal`.
+
+### Support window
+
+The deprecated items remain available, unchanged, for all `0.5.x` releases. They will be removed
+in `0.6.0`, a later breaking release.

Cargo.toml

@@ -12,7 +12,7 @@ publish = true
 readme = "README.md"
 repository = "https://github.com/torrust/torrust-server-lib"
 rust-version = "1.88"
-version = "0.4.0"
+version = "0.5.0"
 
 [dependencies]
 derive_more = { version = "2", features = [ "as_ref", "constructor", "display", "from" ] }

src/signals.rs

@@ -16,6 +16,10 @@ pub struct Started {
 /// This is the message that the "launcher" spawned task receives from the main
 /// application process to notify the service to shutdown.
 ///
+#[deprecated(
+    since = "0.5.0",
+    note = "inject a `tokio_util::sync::CancellationToken` instead of sending `Halted` over a oneshot channel; removal is planned for torrust-server-lib 0.6.0"
+)]
 #[derive(Copy, Clone, Debug, Display)]
 pub enum Halted {
     Normal,
@@ -35,6 +39,10 @@ pub async fn cancellation_signal(cancellation_token: CancellationToken) {
 /// # Panics
 ///
 /// Will panic if the `ctrl_c` or `terminate` signal resolves with an error.
+#[deprecated(
+    since = "0.5.0",
+    note = "libraries must not subscribe to SIGINT/SIGTERM; the executable should subscribe and cancel a `CancellationToken` passed to `cancellation_signal`; removal is planned for torrust-server-lib 0.6.0"
+)]
 #[instrument(skip())]
 pub async fn global_shutdown_signal() {
     let ctrl_c = async {
@@ -63,6 +71,14 @@ pub async fn global_shutdown_signal() {
 /// # Panics
 ///
 /// Will panic if the `stop_receiver` resolves with an error.
+#[deprecated(
+    since = "0.5.0",
+    note = "use `cancellation_signal` with an injected `CancellationToken`; removal is planned for torrust-server-lib 0.6.0"
+)]
+#[allow(
+    deprecated,
+    reason = "the legacy function is implemented with the other legacy symbols until they are removed"
+)]
 #[instrument(skip(rx_halt))]
 pub async fn shutdown_signal(rx_halt: tokio::sync::oneshot::Receiver<Halted>) {
     let halt = async {
@@ -79,6 +95,14 @@ pub async fn shutdown_signal(rx_halt: tokio::sync::oneshot::Receiver<Halted>) {
 }
 
 /// Same as `shutdown_signal()`, but shows a message when it resolves.
+#[deprecated(
+    since = "0.5.0",
+    note = "use `cancellation_signal` with an injected `CancellationToken` and log the message yourself; removal is planned for torrust-server-lib 0.6.0"
+)]
+#[allow(
+    deprecated,
+    reason = "the legacy function is implemented with the other legacy symbols until they are removed"
+)]
 #[instrument(skip(rx_halt))]
 pub async fn shutdown_signal_with_message(rx_halt: tokio::sync::oneshot::Receiver<Halted>, message: String) {
     shutdown_signal(rx_halt).await;
@@ -91,6 +115,7 @@ mod tests {
     use tokio::sync::oneshot;
     use tokio_util::sync::CancellationToken;
 
+    #[allow(deprecated, reason = "the test covers the deprecated legacy API until it is removed")]
     use super::{Halted, cancellation_signal, shutdown_signal};
 
     #[tokio::test]
@@ -107,6 +132,7 @@ mod tests {
         wait_task.await.expect("cancellation wait task should complete");
     }
 
+    #[allow(deprecated, reason = "the test covers the deprecated legacy API until it is removed")]
     #[tokio::test]
     async fn shutdown_signal_should_resolve_when_it_receives_a_legacy_halted_message() {
         let (halt_sender, halt_receiver) = oneshot::channel();