+htp #20198 onCompleteWithBreaker directive (#20402)

akka-docs/rst/scala/http/routing-dsl/directives/alphabetically.rst

@@ -134,6 +134,9 @@ Directive                                   Description
 :ref:`-method-`                             Rejects all requests whose HTTP method does not match the given one
 :ref:`-onComplete-`                         "Unwraps" a ``Future[T]`` and runs the inner route after future completion
                                             with the future's value as an extraction of type ``Try[T]``
+:ref:`-onCompleteWithBreaker-`              "Unwraps" a ``Future[T]`` inside a ``CircuitBreaker`` and runs the inner
+                                            route after future completion with the future's value as an extraction of
+                                            type ``Try[T]``
 :ref:`-onSuccess-`                          "Unwraps" a ``Future[T]`` and runs the inner route after future completion
                                             with the future's value as an extraction of type ``T``
 :ref:`-optionalCookie-`                     Extracts the ``HttpCookiePair`` with the given name as an

akka-docs/rst/scala/http/routing-dsl/directives/future-directives/index.rst

@@ -9,6 +9,7 @@ Future directives can be used to run inner routes once the provided ``Future[T]`
    :maxdepth: 1
 
    onComplete
+   onCompleteWithBreaker
    onSuccess
    completeOrRecoverWith
 

akka-docs/rst/scala/http/routing-dsl/directives/future-directives/onCompleteWithBreaker.rst

@@ -0,0 +1,27 @@
+.. _-onCompleteWithBreaker-:
+
+onCompleteWithBreaker
+=====================
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/FutureDirectives.scala
+   :snippet: onCompleteWithBreaker
+
+Description
+-----------
+Evaluates its parameter of type ``Future[T]`` protecting it with the specified ``CircuitBreaker``.
+Refer to :ref:`Akka Circuit Breaker<circuit-breaker>` for a detailed description of this pattern.
+
+If the ``CircuitBreaker`` is open, the request is rejected with a ``CircuitBreakerOpenRejection``.
+Note that in this case the request's entity databytes stream is cancelled, and the connection is closed
+as a consequence.
+
+Otherwise, the same behaviour provided by :ref:`-onComplete-` is to be expected.
+
+Example
+-------
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
+   :snippet: onCompleteWithBreaker