cc docs: graceful shutdown documentation

commit_hash:257141f6811c85a8c2b899b1a980014d4ba76d1c

Author: lexeyo

.mapping.json

@@ -4620,6 +4620,7 @@
   "scripts/docs/en/userver/framework_comparison.md":"taxi/uservices/userver/scripts/docs/en/userver/framework_comparison.md",
   "scripts/docs/en/userver/functional_testing.md":"taxi/uservices/userver/scripts/docs/en/userver/functional_testing.md",
   "scripts/docs/en/userver/gdb_debugging.md":"taxi/uservices/userver/scripts/docs/en/userver/gdb_debugging.md",
+  "scripts/docs/en/userver/graceful_shutdown.md":"taxi/uservices/userver/scripts/docs/en/userver/graceful_shutdown.md",
   "scripts/docs/en/userver/grpc/client_middleware_implementation.md":"taxi/uservices/userver/scripts/docs/en/userver/grpc/client_middleware_implementation.md",
   "scripts/docs/en/userver/grpc/client_middlewares.md":"taxi/uservices/userver/scripts/docs/en/userver/grpc/client_middlewares.md",
   "scripts/docs/en/userver/grpc/grpc.md":"taxi/uservices/userver/scripts/docs/en/userver/grpc/grpc.md",

core/include/userver/components/state.hpp

@@ -66,6 +66,7 @@ enum class ServiceLifetimeStage {
     /// The service waits for `graceful_shutdown_interval` (0 by default) before continuing with the actual service
     /// shutdown in @ref ServiceLifetimeStage::kOnAllComponentsAreStoppingIsRunning.
     ///
+    /// @see @ref scripts/docs/en/userver/graceful_shutdown.md
     /// @see @ref components::ManagerControllerComponent
     ///
     /// Example:

scripts/docs/en/index.md

@@ -138,6 +138,7 @@ and make sure that it builds and passes tests.
 * @ref scripts/docs/en/userver/stack.md
 * @ref scripts/docs/en/userver/dump_coroutines.md
 * @ref scripts/docs/en/userver/long_transactions.md
+* @ref scripts/docs/en/userver/graceful_shutdown.md
 
 
 ## Caches

scripts/docs/en/userver/caches.md

@@ -227,5 +227,5 @@ Each cache automatically collects metrics. See
 ----------
 
 @htmlonly <div class="bottom-nav"> @endhtmlonly
-⇦ @ref scripts/docs/en/userver/long_transactions.md | @ref scripts/docs/en/userver/cache_dumps.md ⇨
+⇦ @ref scripts/docs/en/userver/graceful_shutdown.md | @ref scripts/docs/en/userver/cache_dumps.md ⇨
 @htmlonly </div> @endhtmlonly

scripts/docs/en/userver/graceful_shutdown.md

@@ -0,0 +1,38 @@
+## Graceful shutdown
+
+By default, when a user-based service receives a SIGTERM or SIGINT signal, it swiftly closes all active connections and halts all components.
+
+However, in certain scenarios, a service might need to shut down gracefully. This means it should inform its clients of the impending shutdown, provide them with extra time to submit any pending requests, and attempt to complete all ongoing operations. This process is known as a graceful shutdown.
+
+Graceful shutdown is deactivated by default. It can be activated by setting the `graceful_shutdown_interval` parameter in the configuration of the components::ManagerControllerComponent.
+
+\b static_config.yaml example:
+@snippet core/functional_tests/graceful_shutdown/static_config.yaml graceful_shutdown_interval
+
+With such configurations a service will switch to *graceful shutdown* mode after SIGTERM or SIGINT.
+It corresponds to @ref components::ServiceLifetimeStage::kGracefulShutdown service lifetime stage.
+
+At this stage the service will:
+
+* Start failing HTTP and gRPC health checks:
+  * HTTP @ref scripts/docs/en/userver/tutorial/production_service.md "/ping" handler will return 500 errors.
+  * gRPC `grpc.health.v1.Health` service will return `NOT_SERVING` status.
+* Append @ref graceful_shutdown_headers "special headers" to HTTP responses and gRPC response metadata, 
+  if enabled.
+* Accept new HTTP and gRPC requests and continue processing of ongoing requests for the configured time 
+  interval (10 seconds in the example above).
+
+@anchor graceful_shutdown_headers
+### Graceful shutdown headers
+
+During a graceful shutdown, a service appends special HTTP headers and gRPC metadata to outgoing responses, provided the feature is enabled. Typically, the initial metadata is employed for gRPC. However, if a graceful shutdown is triggered after the initial metadata has already been sent, trailing metadata will be utilized instead.
+
+Graceful shutdown headers are enabled by default. They could be configured or disabled via @ref GRACEFUL_SHUTDOWN_HEADERS dynamic configuration.
+
+@example grpc/functional_tests/middleware_server/tests/test_graceful_shutdown_headers.py
+
+----------
+
+@htmlonly <div class="bottom-nav"> @endhtmlonly
+⇦ @ref scripts/docs/en/userver/long_transactions.md | @ref scripts/docs/en/userver/caches.md ⇨
+@htmlonly </div> @endhtmlonly

scripts/docs/en/userver/long_transactions.md

@@ -73,6 +73,5 @@ To disable the check for the whole service use the `enable_trx_tracker` static c
 ----------
 
 @htmlonly <div class="bottom-nav"> @endhtmlonly
-⇦ @ref scripts/docs/en/userver/dump_coroutines.md | @ref scripts/docs/en/userver/caches.md ⇨
+⇦ @ref scripts/docs/en/userver/dump_coroutines.md | @ref scripts/docs/en/userver/graceful_shutdown.md ⇨
 @htmlonly </div> @endhtmlonly
-