Merge pull request #413 from ESP32Async/requestmethod-typing

Review HTTP method enum definition to avoid collisions with plaforms ones

Author: willmmiles

docs/backup/wiki.md

@@ -1887,7 +1887,7 @@ void setup(){
   }, onUpload);
 
   // send a file when /index is requested
-  server.on("/index", HTTP_ANY, [](AsyncWebServerRequest *request){
+  server.on("/index", HTTP_ALL, [](AsyncWebServerRequest *request){
     request->send(SPIFFS, "/index.htm");
   });
 
@@ -1974,10 +1974,10 @@ public :
 
   void begin(){
     // attach global request handler
-    classWebServer.on("/example", HTTP_ANY, handleRequest);
+    classWebServer.on("/example", HTTP_ALL, handleRequest);
 
     // attach class request handler
-    classWebServer.on("/example", HTTP_ANY, std::bind(&WebClass::classRequest, this, std::placeholders::_1));
+    classWebServer.on("/example", HTTP_ALL, std::bind(&WebClass::classRequest, this, std::placeholders::_1));
   }
 };
 
@@ -1986,10 +1986,10 @@ WebClass webClassInstance;
 
 void setup() {
   // attach global request handler
-  globalWebServer.on("/example", HTTP_ANY, handleRequest);
+  globalWebServer.on("/example", HTTP_ALL, handleRequest);
 
   // attach class request handler
-  globalWebServer.on("/example", HTTP_ANY, std::bind(&WebClass::classRequest, webClassInstance, std::placeholders::_1));
+  globalWebServer.on("/example", HTTP_ALL, std::bind(&WebClass::classRequest, webClassInstance, std::placeholders::_1));
 }
 
 void loop() {

docs/setup.md

@@ -71,12 +71,12 @@ void setup(){
   }, onUpload);
 
   // send a file when /index is requested (SPIFFS example)
-  server.on("/index", HTTP_ANY, [](AsyncWebServerRequest *request){
+  server.on("/index", HTTP_ALL, [](AsyncWebServerRequest *request){
     request->send(SPIFFS, "/index.htm");
   });
 
   // send a file when /index is requested (LittleFS example)
-  server.on("/index", HTTP_ANY, [](AsyncWebServerRequest *request){
+  server.on("/index", HTTP_ALL, [](AsyncWebServerRequest *request){
     request->send(LittleFS, "/index.htm");
   });
 
@@ -161,10 +161,10 @@ public :
 
   void begin(){
     // attach global request handler
-    classWebServer.on("/example", HTTP_ANY, handleRequest);
+    classWebServer.on("/example", HTTP_ALL, handleRequest);
 
     // attach class request handler
-    classWebServer.on("/example", HTTP_ANY, std::bind(&WebClass::classRequest, this, std::placeholders::_1));
+    classWebServer.on("/example", HTTP_ALL, std::bind(&WebClass::classRequest, this, std::placeholders::_1));
   }
 };
 
@@ -173,10 +173,10 @@ WebClass webClassInstance;
 
 void setup() {
   // attach global request handler
-  globalWebServer.on("/example", HTTP_ANY, handleRequest);
+  globalWebServer.on("/example", HTTP_ALL, handleRequest);
 
   // attach class request handler
-  globalWebServer.on("/example", HTTP_ANY, std::bind(&WebClass::classRequest, webClassInstance, std::placeholders::_1));
+  globalWebServer.on("/example", HTTP_ALL, std::bind(&WebClass::classRequest, webClassInstance, std::placeholders::_1));
 }
 
 void loop() {

examples/HTTPMethods/HTTPMethods.ino …dsWithArduino/HTTPMethodsWithArduino.inoexamples/HTTPMethods/HTTPMethods.ino renamed to examples/HTTPMethodsWithArduino/HTTPMethodsWithArduino.ino examples/HTTPMethods/HTTPMethods.ino renamed to examples/HTTPMethodsWithArduino/HTTPMethodsWithArduino.ino

@@ -2,13 +2,16 @@
 // Copyright 2016-2026 Hristo Gochkov, Mathieu Carbou, Emil Muratov, Will Miles
 
 //
-// HTTP Method usage example and check compatibility with Arduino HTTP Methods
+// HTTP Method usage example and check compatibility with Arduino HTTP Methods when HTTP_Method.h is included.
+// ESP-IDf enums are imported, and HTTP_ANY is defined by Arduino Core.
+// In that case, we cannot use directly asyncws enums: we have to namespace them.
+// Also, asycnws HTTP_ANY is not available sine already defined by Arduino as a macro.
+// So we have to use AsyncWebRequestMethod::HTTP_ALL instead of HTTP_ANY in that case.
 //
 
 #include <Arduino.h>
 
 #if !defined(ESP8266)
-// simulate asyncws project being used with another library using Arduino HTTP Methods
 #include <HTTP_Method.h>
 #endif
 
@@ -42,6 +45,31 @@ static void handlePostTest(AsyncWebServerRequest *req, JsonVariant &json) {
 }
 #endif
 
+// user defined functions that turns out to have similar signatures to the ones in global header
+int stringToMethod(const String &) {
+  return 0;
+}
+const char *methodToString(WebRequestMethod) {
+  return "METHOD";
+}
+bool methodMatches(WebRequestMethodComposite c, WebRequestMethod m) {
+  return false;
+};
+
+static WebRequestMethodComposite allowed = AsyncWebRequestMethod::HTTP_HEAD | AsyncWebRequestMethod::HTTP_OPTIONS;
+
+class MyRequestHandler : public AsyncWebHandler {
+public:
+  bool canHandle(__unused AsyncWebServerRequest *request) const override {
+    // Test backward compatibility with previous way of checking if a method is allowed in a composite using a bit operator
+    return allowed & request->method();
+  }
+
+  void handleRequest(AsyncWebServerRequest *request) override {
+    request->send(200, "text/plain", "Hello from custom handler");
+  }
+};
+
 void setup() {
   Serial.begin(115200);
 
@@ -56,8 +84,8 @@ void setup() {
     request->send(200, "text/plain", "Hello");
   });
 
-  // curl -v http://192.168.4.1/any
-  server.on("/any", WebRequestMethod::HTTP_ANY, [](AsyncWebServerRequest *request) {
+  // curl -v http://192.168.4.1/all
+  server.on("/all", AsyncWebRequestMethod::HTTP_ALL, [](AsyncWebServerRequest *request) {
     request->send(200, "text/plain", "Hello");
   });
 
@@ -68,6 +96,11 @@ void setup() {
   server.addHandler(testHandler);
 #endif
 
+  // curl -v -X HEAD http://192.168.4.1/custom => answers
+  // curl -v -X OPTIONS http://192.168.4.1/custom => answers
+  // curl -v -X POST http://192.168.4.1/custom => no answer
+  server.addHandler(new MyRequestHandler());
+
   server.begin();
 }
 

examples/HTTPMethodsWithESPIDF/HTTPMethodsWithESPIDF.ino

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright 2016-2026 Hristo Gochkov, Mathieu Carbou, Emil Muratov, Will Miles
+
+//
+// HTTP Method usage example and check compatibility with ESP-IDF HTTP Methods when http_parser.h is included.
+// ESP-IDF enums are imported, and HTTP_ANY is NOT defined by ESP-IDF.
+// So asyncws is able to define it.
+// We cannot use directly other asyncws enums to avoid conflicts with ESP-IDF: we have to namespace them.
+//
+
+#include <Arduino.h>
+
+#if !defined(ESP8266)
+#include "http_parser.h"
+#endif
+
+#if defined(ESP32) || defined(LIBRETINY)
+#include <AsyncTCP.h>
+#include <WiFi.h>
+#elif defined(ESP8266)
+#include <ESP8266WiFi.h>
+#include <ESPAsyncTCP.h>
+#elif defined(TARGET_RP2040) || defined(TARGET_RP2350) || defined(PICO_RP2040) || defined(PICO_RP2350)
+#include <RPAsyncTCP.h>
+#include <WiFi.h>
+#endif
+
+#include <ESPAsyncWebServer.h>
+
+static AsyncWebServer server(80);
+
+#if ASYNC_JSON_SUPPORT == 1
+// https://github.com/ESP32Async/ESPAsyncWebServer/issues/404
+static void handlePostTest(AsyncWebServerRequest *req, JsonVariant &json) {
+  AsyncWebServerResponse *response;
+  if (req->method() == WebRequestMethod::HTTP_POST) {
+    response = req->beginResponse(200, "application/json", "{\"msg\": \"OK\"}");
+  } else {
+    response = req->beginResponse(501, "application/json", "{\"msg\": \"Not Implemented\"}");
+  }
+  req->send(response);
+}
+#endif
+
+// user defined functions that turns out to have similar signatures to the ones in global header
+int stringToMethod(const String &) {
+  return 0;
+}
+const char *methodToString(WebRequestMethod) {
+  return "METHOD";
+}
+bool methodMatches(WebRequestMethodComposite c, WebRequestMethod m) {
+  return false;
+};
+
+static WebRequestMethodComposite allowed = AsyncWebRequestMethod::HTTP_HEAD | AsyncWebRequestMethod::HTTP_OPTIONS;
+
+class MyRequestHandler : public AsyncWebHandler {
+public:
+  bool canHandle(__unused AsyncWebServerRequest *request) const override {
+    // Test backward compatibility with previous way of checking if a method is allowed in a composite using a bit operator
+    return allowed & request->method();
+  }
+
+  void handleRequest(AsyncWebServerRequest *request) override {
+    request->send(200, "text/plain", "Hello from custom handler");
+  }
+};
+
+void setup() {
+  Serial.begin(115200);
+
+#if ASYNCWEBSERVER_WIFI_SUPPORTED
+  WiFi.mode(WIFI_AP);
+  WiFi.softAP("esp-captive");
+#endif
+
+  // curl -v http://192.168.4.1/get-or-post
+  // curl -v -X POST -d "a=b" http://192.168.4.1/get-or-post
+  server.on("/get-or-post", AsyncWebRequestMethod::HTTP_GET | AsyncWebRequestMethod::HTTP_POST, [](AsyncWebServerRequest *request) {
+    request->send(200, "text/plain", "Hello");
+  });
+
+  // curl -v http://192.168.4.1/all
+  server.on("/all", AsyncWebRequestMethod::HTTP_ALL, [](AsyncWebServerRequest *request) {
+    request->send(200, "text/plain", "Hello");
+  });
+
+  // will show a deprecation warning
+  server.on("/any", AsyncWebRequestMethod::HTTP_ANY, [](AsyncWebServerRequest *request) {
+    request->send(200, "text/plain", "Hello");
+  });
+
+#if ASYNC_JSON_SUPPORT == 1
+  // curl -v http://192.168.4.1/test => Not Implemented
+  // curl -v -X POST -H 'Content-Type: application/json' -d '{"name":"You"}' http://192.168.4.1/test => OK
+  AsyncCallbackJsonWebHandler *testHandler = new AsyncCallbackJsonWebHandler("/test", handlePostTest);
+  server.addHandler(testHandler);
+#endif
+
+  // curl -v -X HEAD http://192.168.4.1/custom => answers
+  // curl -v -X OPTIONS http://192.168.4.1/custom => answers
+  // curl -v -X POST http://192.168.4.1/custom => no answer
+  server.addHandler(new MyRequestHandler());
+
+  server.begin();
+}
+
+// not needed
+void loop() {
+  delay(100);
+}

platformio.ini

@@ -15,7 +15,8 @@ lib_dir = .
 ; src_dir = examples/FlashResponse
 ; src_dir = examples/HeaderManipulation
 ; src_dir = examples/Headers
-; src_dir = examples/HTTPMethods
+; src_dir = examples/HTTPMethodsWithArduino
+; src_dir = examples/HTTPMethodsWithESPIDF
 ; src_dir = examples/Json
 ; src_dir = examples/LargeResponse
 ; src_dir = examples/Logging

src/AsyncJson.cpp

@@ -112,6 +112,8 @@ size_t AsyncMessagePackResponse::_fillBuffer(uint8_t *data, size_t len) {
 #endif
 
 // Body handler supporting both content types: JSON and MessagePack
+constexpr static WebRequestMethodComposite JsonHandlerMethods =
+  AsyncWebRequestMethod::HTTP_GET | AsyncWebRequestMethod::HTTP_POST | AsyncWebRequestMethod::HTTP_PUT | AsyncWebRequestMethod::HTTP_PATCH;
 
 #if ARDUINOJSON_VERSION_MAJOR == 6
 AsyncCallbackJsonWebHandler::AsyncCallbackJsonWebHandler(AsyncURIMatcher uri, ArJsonRequestHandlerFunction onRequest, size_t maxJsonBufferSize)
@@ -126,7 +128,7 @@ AsyncCallbackJsonWebHandler::AsyncCallbackJsonWebHandler(AsyncURIMatcher uri, Ar
 #endif
 
 bool AsyncCallbackJsonWebHandler::canHandle(AsyncWebServerRequest *request) const {
-  if (!_onRequest || !request->isHTTP() || !(_method & request->method())) {
+  if (!_onRequest || !request->isHTTP() || !_method.matches(request->method())) {
     return false;
   }