cc core: document http server middlewares

itrofimow · itrofimow · commit 076be39f364a · 2024-03-29T13:28:07.000+03:00
99b79fbde1c2dca2e80ccc93a5dea8ea732d2939
diff --git a/.mapping.json b/.mapping.json
@@ -2772,6 +2772,7 @@
   "scripts/docs/en/userver/functional_testing.md":"taxi/uservices/userver/scripts/docs/en/userver/functional_testing.md",
   "scripts/docs/en/userver/grpc.md":"taxi/uservices/userver/scripts/docs/en/userver/grpc.md",
   "scripts/docs/en/userver/http_server.md":"taxi/uservices/userver/scripts/docs/en/userver/http_server.md",
+  "scripts/docs/en/userver/http_server_middlewares.md":"taxi/uservices/userver/scripts/docs/en/userver/http_server_middlewares.md",
   "scripts/docs/en/userver/intro.md":"taxi/uservices/userver/scripts/docs/en/userver/intro.md",
   "scripts/docs/en/userver/intro_io_bound_coro.md":"taxi/uservices/userver/scripts/docs/en/userver/intro_io_bound_coro.md",
   "scripts/docs/en/userver/log_level_running_service.md":"taxi/uservices/userver/scripts/docs/en/userver/log_level_running_service.md",
diff --git a/core/include/userver/server/middlewares/configuration.hpp b/core/include/userver/server/middlewares/configuration.hpp
@@ -42,7 +42,7 @@ using MiddlewaresList = std::vector<std::string>;
 /// @brief Returns the default userver-provided middleware pipeline.
 MiddlewaresList DefaultPipeline();
 
-/// @ingroup userver_middlewares
+/// @ingroup userver_middlewares userver_base_classes
 ///
 /// @brief Base class to build a server-wide middleware pipeline.
 /// One may inherit from it and implement any custom logic, if desired.
@@ -82,7 +82,7 @@ class PipelineBuilder : public components::LoggableComponentBase {
   MiddlewaresList middlewares_to_append_;
 };
 
-/// @ingroup userver_middlewares
+/// @ingroup userver_middlewares userver_base_classes
 ///
 /// @brief Base class to build a per-handler middleware pipeline.
 /// One may inherit from it and implement any custom logic, if desired.
diff --git a/core/include/userver/server/middlewares/http_middleware_base.hpp b/core/include/userver/server/middlewares/http_middleware_base.hpp
@@ -27,15 +27,20 @@ class HttpHandlerBase;
 
 namespace middlewares {
 
+/// @ingroup userver_middlewares userver_base_classes
+///
+/// @brief Base class for a http middleware
 class HttpMiddlewareBase {
  public:
   HttpMiddlewareBase();
   virtual ~HttpMiddlewareBase();
 
  protected:
+  /// @brief Override this method to implement a middleware logic
   virtual void HandleRequest(http::HttpRequest& request,
                              request::RequestContext& context) const = 0;
 
+  /// @brief The method to invoke the next middleware in a pipeline
   void Next(http::HttpRequest& request, request::RequestContext& context) const;
 
  private:
@@ -44,6 +49,9 @@ class HttpMiddlewareBase {
   std::unique_ptr<HttpMiddlewareBase> next_{nullptr};
 };
 
+/// @ingroup userver_middlewares userver_base_classes
+///
+/// @brief Base class for a http middleware-factory
 class HttpMiddlewareFactoryBase : public components::LoggableComponentBase {
  public:
   HttpMiddlewareFactoryBase(const components::ComponentConfig&,
@@ -54,15 +62,21 @@ class HttpMiddlewareFactoryBase : public components::LoggableComponentBase {
       yaml_config::YamlConfig middleware_config) const;
 
  protected:
+  /// @brief This method should return the schema of a middleware configuration,
+  /// if any. You may override it
   virtual yaml_config::Schema GetMiddlewareConfigSchema() const {
     return yaml_config::Schema::EmptyObject();
   }
 
+  /// @brief Override this method to create an instance of a middleware
   virtual std::unique_ptr<HttpMiddlewareBase> Create(
       const handlers::HttpHandlerBase&,
       yaml_config::YamlConfig middleware_config) const = 0;
 };
 
+/// @ingroup userver_middlewares
+///
+/// @brief A short-cut for defining a middleware-factory
 template <typename Middleware>
 class SimpleHttpMiddlewareFactory final : public HttpMiddlewareFactoryBase {
  public:
diff --git a/core/src/server/middlewares/configuration.cpp b/core/src/server/middlewares/configuration.cpp
@@ -18,27 +18,33 @@ USERVER_NAMESPACE_BEGIN
 
 namespace server::middlewares {
 
+/// [Middlewares sample - default pipeline]
 MiddlewaresList DefaultPipeline() {
   return {
       // Metrics should go before everything else, basically.
       std::string{HandlerMetrics::kName},
       // Tracing should go before UnknownExceptionsHandlingMiddleware because it
-      // adds some headers, which otherwise might be cleared.
+      // adds some headers, which otherwise might be cleared
       std::string{Tracing::kName},
-      // Ditto.
+      // Ditto
       std::string{SetAcceptEncoding::kName},
 
+      // Every exception caught here is transformed into Http500 without context
       std::string{UnknownExceptionsHandling::kName},
 
+      // Should be self-explanatory
       std::string{RateLimit::kName},
       std::string{DeadlinePropagation::kName},
       std::string{Baggage::kName},
       std::string{Auth::kName},
       std::string{Decompression::kName},
 
+      // Transforms CustomHandlerException into response as specified by the
+      // exception, transforms std::exception into Http500 without context
       std::string{ExceptionsHandling::kName},
   };
 }
+/// [Middlewares sample - default pipeline]
 
 components::ComponentList DefaultMiddlewareComponents() {
   return MinimalMiddlewareComponents()
diff --git a/samples/http_middleware_service/http_middleware_service.cpp b/samples/http_middleware_service/http_middleware_service.cpp
@@ -22,9 +22,38 @@ class Handler final : public server::handlers::HttpHandlerBase {
   }
 };
 
+/// [Middlewares sample - minimal implementation]
+class NoopMiddleware final : public server::middlewares::HttpMiddlewareBase {
+ private:
+  void HandleRequest(server::http::HttpRequest& request,
+                     server::request::RequestContext& context) const override {
+    Next(request, context);
+  }
+};
+/// [Middlewares sample - minimal implementation]
+
+/// [Middlewares sample - minimal factory implementation]
+class NoopMiddlewareFactory final
+    : public server::middlewares::HttpMiddlewareFactoryBase {
+ public:
+  static constexpr std::string_view kName{"noop-middleware"};
+
+  using HttpMiddlewareFactoryBase::HttpMiddlewareFactoryBase;
+
+ private:
+  std::unique_ptr<server::middlewares::HttpMiddlewareBase> Create(
+      const server::handlers::HttpHandlerBase&,
+      yaml_config::YamlConfig) const override {
+    return std::make_unique<NoopMiddleware>();
+  }
+};
+/// [Middlewares sample - minimal factory implementation]
+
+/// [Middlewares sample - some middleware implementation]
 class SomeServerMiddleware final
     : public server::middlewares::HttpMiddlewareBase {
  public:
+  // This will be used as a kName for the SimpleHttpMiddlewareFactory
   static constexpr std::string_view kName{"server-middleware"};
 
   // Handler isn't interesting to us, but we could use it if needed.
@@ -37,17 +66,19 @@ class SomeServerMiddleware final
                      server::request::RequestContext& context) const override {
     Next(request, context);
 
-    // In case the header is needed even in a presence of downstream exceptions,
-    // this should be wrapped in a scope guard (utils::ScopeGuard, for example)
     request.GetHttpResponse().SetHeader(kCustomServerHeader, "1");
   }
 
   static constexpr http::headers::PredefinedHeader kCustomServerHeader{
       "X-Some-Server-Header"};
 };
+/// [Middlewares sample - some middleware implementation]
+/// [Middlewares sample - some middleware factory implementation]
 using SomeServerMiddlewareFactory =
     server::middlewares::SimpleHttpMiddlewareFactory<SomeServerMiddleware>;
+/// [Middlewares sample - some middleware factory implementation]
 
+/// [Middlewares sample - configurable middleware implementation]
 class SomeHandlerMiddleware final
     : public server::middlewares::HttpMiddlewareBase {
  public:
@@ -79,7 +110,9 @@ class SomeHandlerMiddleware final
 
   const std::string header_value_;
 };
+/// [Middlewares sample - configurable middleware implementation]
 
+/// [Middlewares sample - configurable middleware factory implementation]
 class SomeHandlerMiddlewareFactory final
     : public server::middlewares::HttpMiddlewareFactoryBase {
  public:
@@ -108,22 +141,28 @@ additionalProperties: false
         .As<yaml_config::Schema>();
   }
 };
+/// [Middlewares sample - configurable middleware factory implementation]
 
+/// [Middlewares sample - custom handler pipeline builder]
 class CustomHandlerPipelineBuilder final
     : public server::middlewares::HandlerPipelineBuilder {
  public:
   using HandlerPipelineBuilder::HandlerPipelineBuilder;
 
   server::middlewares::MiddlewaresList BuildPipeline(
-      server::middlewares::MiddlewaresList pipeline) const override {
+      server::middlewares::MiddlewaresList server_middleware_pipeline)
+      const override {
     // We could do any kind of transformation here.
     // For the sake of example (and what we assume to be the most common case),
-    // we just add one more middleware to the pipeline.
+    // we just add some middleware to the pipeline.
+    auto& pipeline = server_middleware_pipeline;
     pipeline.emplace_back(SomeHandlerMiddleware::kName);
+    pipeline.emplace_back(NoopMiddlewareFactory::kName);
 
     return pipeline;
   }
 };
+/// [Middlewares sample - custom handler pipeline builder]
 
 }  // namespace samples::http_middlewares
 
@@ -137,6 +176,11 @@ constexpr auto components::kConfigFileMode<
     samples::http_middlewares::SomeHandlerMiddlewareFactory> =
     components::ConfigFileMode::kNotRequired;
 
+template <>
+constexpr auto components::kConfigFileMode<
+    samples::http_middlewares::NoopMiddlewareFactory> =
+    components::ConfigFileMode::kNotRequired;
+
 int main(int argc, char* argv[]) {
   const auto component_list =
       components::MinimalServerComponentList()
@@ -147,11 +191,15 @@ int main(int argc, char* argv[]) {
           .Append<samples::http_middlewares::Handler>(
               "handler-with-another-middleware-configuration")
           // middlewares
+          // clang-format off
+/// [Middlewares sample - custom handler pipeline builder registration]
+          .Append<samples::http_middlewares::CustomHandlerPipelineBuilder>(
+              "custom-handler-pipeline-builder")
+/// [Middlewares sample - custom handler pipeline builder registration]
+          // clang-format on
           .Append<samples::http_middlewares::SomeServerMiddlewareFactory>()
           .Append<samples::http_middlewares::SomeHandlerMiddlewareFactory>()
-          // configuration
-          .Append<samples::http_middlewares::CustomHandlerPipelineBuilder>(
-              "custom-handler-pipeline-builder");
+          .Append<samples::http_middlewares::NoopMiddlewareFactory>();
 
   return utils::DaemonMain(argc, argv, component_list);
 }
diff --git a/samples/http_middleware_service/static_config.yaml b/samples/http_middleware_service/static_config.yaml
@@ -15,9 +15,12 @@ components_manager:
                 port: 8080            # ...to listen on this port and...
                 task_processor: main-task-processor    # ...process incoming requests on this task processor.
 
+# [Middlewares sample - pipeline builder configuration]
+        # yaml
         default-server-middleware-pipeline-builder:
             append:
               - server-middleware     # Or we could implement the same in the code, consider it a shortcut.
+# [Middlewares sample - pipeline builder configuration]
 
         logging:
             fs-task-processor: fs-task-processor
@@ -32,6 +35,8 @@ components_manager:
             method: GET                   # It will only reply to GET (HEAD) requests.
             task_processor: main-task-processor  # Run it on CPU bound task processor
 
+# [Middlewares sample - custom handler pipeline builder configuration]
+        # yaml
         handler-with-custom-middlewares:
             path: /custom-hello
             method: GET
@@ -40,6 +45,7 @@ components_manager:
                 pipeline-builder: custom-handler-pipeline-builder
                 handler-middleware:
                     header-value: some_value
+# [Middlewares sample - custom handler pipeline builder configuration]
 
         handler-with-another-middleware-configuration:
             path: /custom-hello-other
diff --git a/scripts/docs/en/cpp/def_groups.hpp b/scripts/docs/en/cpp/def_groups.hpp
@@ -17,7 +17,7 @@
 /// ----------
 ///
 /// @htmlonly <div class="bottom-nav"> @endhtmlonly
-/// ⇦ @ref userver_clients | @ref scripts/docs/en/userver/synchronization.md ⇨
+/// ⇦ @ref userver_middlewares | @ref scripts/docs/en/userver/synchronization.md ⇨
 /// @htmlonly </div> @endhtmlonly
 
 
@@ -74,7 +74,7 @@
 /// ----------
 ///
 /// @htmlonly <div class="bottom-nav"> @endhtmlonly
-/// ⇦ @ref userver_clients | @ref userver_components ⇨
+/// ⇦ @ref userver_clients | @ref userver_middlewares ⇨
 /// @htmlonly </div> @endhtmlonly
 
 
@@ -139,8 +139,15 @@
 /// @ingroup userver_components
 /// @brief Default names of components that are used in static config files
 
-/// @defgroup userver_middlewares Default middlewares
+/// @defgroup userver_middlewares Http server middlewares
 /// @ingroup userver_components
-/// @brief Default middlewares used in http processing pipeline
+/// @brief Base classes for implementing and configuring http server middlewares
+/// @see @ref scripts/docs/en/userver/http_server_middlewares.md
+///
+/// ----------
+///
+/// @htmlonly <div class="bottom-nav"> @endhtmlonly
+/// ⇦ @ref userver_http_handlers | @ref userver_components ⇨
+/// @htmlonly </div> @endhtmlonly
 
 // clang-format on
diff --git a/scripts/docs/en/index.md b/scripts/docs/en/index.md
@@ -59,6 +59,7 @@ are available at the
 * @ref scripts/docs/en/userver/component_system.md
     * @ref userver_clients "Clients"
     * @ref userver_http_handlers "HTTP Handlers"
+    * @ref userver_middlewares "HTTP Middlewares" 
     * @ref userver_components "Other components"
 * @ref scripts/docs/en/userver/synchronization.md
 * @ref scripts/docs/en/userver/formats.md
diff --git a/scripts/docs/en/userver/http_server.md b/scripts/docs/en/userver/http_server.md
@@ -19,6 +19,7 @@
 * Streaming;
 * @ref scripts/docs/en/userver/tutorial/multipart_service.md "File uploads and multipart/form-data"
 * @ref scripts/docs/en/userver/deadline_propagation.md .
+* @ref scripts/docs/en/userver/http_server_middlewares.md "Middlewares"
 
 ## Streaming API
 
diff --git a/scripts/docs/en/userver/http_server_middlewares.md b/scripts/docs/en/userver/http_server_middlewares.md
