feat(http): Skipping Middleware

- Allow to skip global server middleware on any handler
- Allow to access the catch-all handler to add middlewares on it

Author: mathieucarbou

examples/SkipServerMiddleware/SkipServerMiddleware.ino

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright 2016-2025 Hristo Gochkov, Mathieu Carbou, Emil Muratov
+
+//
+// Authentication and authorization middlewares
+//
+
+#include <Arduino.h>
+#ifdef ESP32
+#include <AsyncTCP.h>
+#include <WiFi.h>
+#elif defined(ESP8266)
+#include <ESP8266WiFi.h>
+#include <ESPAsyncTCP.h>
+#elif defined(TARGET_RP2040)
+#include <WebServer.h>
+#include <WiFi.h>
+#endif
+
+#include <ESPAsyncWebServer.h>
+
+static AsyncWebServer server(80);
+
+static AsyncAuthenticationMiddleware basicAuth;
+static AsyncLoggingMiddleware logging;
+
+void setup() {
+  Serial.begin(115200);
+
+#ifndef CONFIG_IDF_TARGET_ESP32H2
+  WiFi.mode(WIFI_AP);
+  WiFi.softAP("esp-captive");
+#endif
+
+  // basic authentication
+  basicAuth.setUsername("admin");
+  basicAuth.setPassword("admin");
+  basicAuth.setRealm("MyApp");
+  basicAuth.setAuthFailureMessage("Authentication failed");
+  basicAuth.setAuthType(AsyncAuthType::AUTH_BASIC);
+  basicAuth.generateHash();  // precompute hash (optional but recommended)
+
+  // logging middleware
+  logging.setEnabled(true);
+  logging.setOutput(Serial);
+
+  // we apply auth middleware to the server globally
+  server.addMiddleware(&basicAuth);
+
+  // protected endpoint: requires basic authentication
+  // curl -v -u admin:admin  http://192.168.4.1/
+  server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
+    request->send(200, "text/plain", "Hello, world!");
+  });
+
+  // we skip all global middleware from the catchall handler
+  server.catchAllHandler().skipServerMiddlewares();
+  // we apply a specific middleware to the catchall handler only to log requests without a handler defined
+  server.catchAllHandler().addMiddleware(&logging);
+
+  // standard 404 handler: will display the request in the console i na curl-like style
+  // curl -v -H "Foo: Bar"  http://192.168.4.1/foo
+  server.onNotFound([](AsyncWebServerRequest *request) {
+    request->send(404, "text/plain", "Not found");
+  });
+
+  server.begin();
+}
+
+// not needed
+void loop() {}

platformio.ini

@@ -22,6 +22,7 @@ src_dir = examples/PerfTests
 ; src_dir = examples/ResumableDownload
 ; src_dir = examples/Rewrite
 ; src_dir = examples/ServerSentEvents
+; src_dir = examples/SkipServerMiddleware
 ; src_dir = examples/SlowChunkResponse
 ; src_dir = examples/StaticFile
 ; src_dir = examples/Templates

src/ESPAsyncWebServer.h

@@ -906,6 +906,7 @@ class AsyncWebHandler : public AsyncMiddlewareChain {
 protected:
   ArRequestFilterFunction _filter = nullptr;
   AsyncAuthenticationMiddleware *_authMiddleware = nullptr;
+  bool _skipServerMiddlewares = false;
 
 public:
   AsyncWebHandler() {}
@@ -915,6 +916,17 @@ class AsyncWebHandler : public AsyncMiddlewareChain {
   AsyncWebHandler &setAuthentication(const String &username, const String &password, AsyncAuthType authMethod = AsyncAuthType::AUTH_DIGEST) {
     return setAuthentication(username.c_str(), password.c_str(), authMethod);
   };
+  AsyncWebHandler &setSkipServerMiddlewares(bool state) {
+    _skipServerMiddlewares = state;
+    return *this;
+  }
+  // skip all glboally defined server middlewares for this handler and only execute those defined for this handler specifically
+  AsyncWebHandler &skipServerMiddlewares() {
+    return setSkipServerMiddlewares(true);
+  }
+  bool mustSkipServerMiddlewares() const {
+    return _skipServerMiddlewares;
+  }
   bool filter(AsyncWebServerRequest *request) {
     return _filter == NULL || _filter(request);
   }
@@ -1096,6 +1108,8 @@ class AsyncWebServer : public AsyncMiddlewareChain {
   void onNotFound(ArRequestHandlerFunction fn);   // called when handler is not assigned
   void onFileUpload(ArUploadHandlerFunction fn);  // handle file uploads
   void onRequestBody(ArBodyHandlerFunction fn);   // handle posts with plain body content (JSON often transmitted this way as a request)
+  // give access to the handler used to catch all requests, so that middleware can be added to it
+  AsyncWebHandler &catchAllHandler() const;
 
   void reset();  // remove all writers and handlers, with onNotFound/onFileUpload/onRequestBody
 

src/WebRequest.cpp

@@ -660,13 +660,19 @@ void AsyncWebServerRequest::_parseLine() {
 }
 
 void AsyncWebServerRequest::_runMiddlewareChain() {
-  _server->_runChain(this, [this]() {
-    if (_handler) {
-      _handler->_runChain(this, [this]() {
-        _handler->handleRequest(this);
-      });
-    }
-  });
+  if (_handler && _handler->mustSkipServerMiddlewares()) {
+    _handler->_runChain(this, [this]() {
+      _handler->handleRequest(this);
+    });
+  } else {
+    _server->_runChain(this, [this]() {
+      if (_handler) {
+        _handler->_runChain(this, [this]() {
+          _handler->handleRequest(this);
+        });
+      }
+    });
+  }
 }
 
 void AsyncWebServerRequest::_send() {

src/WebServer.cpp

@@ -175,6 +175,10 @@ void AsyncWebServer::onRequestBody(ArBodyHandlerFunction fn) {
   _catchAllHandler->onBody(fn);
 }
 
+AsyncWebHandler &AsyncWebServer::catchAllHandler() const {
+  return *_catchAllHandler;
+}
+
 void AsyncWebServer::reset() {
   _rewrites.clear();
   _handlers.clear();