Handle collisions with other webservers

Fix HTTP_ANY macro conflict with Arduino core.  Rename the combination
value to HTTP_ALL and make it type-safe as a
WebRequestMethodComposite.  Ensure a warning is generated when
conflicts are detected, and add a deprecation alert to our
compatibility HTTP_ANY value.

Co-authored-by: GitHub Copilot <copilot@github.com>
Co-authored-by: mathieucarbou <61346+mathieucarbou@users.noreply.github.com>

Author: 3 people

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() {

src/ESPAsyncWebServer.h

@@ -66,6 +66,19 @@
 #define ASYNCWEBSERVER_WIFI_SUPPORTED 0
 #endif
 
+// HTTP_ANY is commonly defined as a macro in Arduino core HTTP client libraries (e.g., ESP8266 HTTPClient.h).
+// Macros are expanded by the preprocessor before C++ namespace resolution, so even a namespace-qualified
+// reference like AsyncWebRequestMethod::HTTP_ANY would be incorrectly expanded to AsyncWebRequestMethod::0.
+// In these cases, other HTTP_METHOD symbols will likely also become ambiguous if put in the global namespace.
+// To avoid these conflicts, AsyncWebRequestMethod::HTTP_ANY will only be provided if no conflicting definition
+// is present; and we will disable putting our definitions in the global namespace.
+// If the user explicitly defined ASYNCWEBSERVER_NO_GLOBAL_HTTP_METHODS, we assume they are using safely
+// namespaced references and AsyncWebServerMethod::HTTP_ALL.
+#if defined(HTTP_ANY) && !defined(ASYNCWEBSERVER_NO_GLOBAL_HTTP_METHODS)
+#warning HTTP_ANY definition collision detected - AsyncWebServer HTTP_ methods will not be defined in the global namespace.  Make sure to use AsyncWebServerMethod::HTTP_ALL instead, and define ASYNCWEBSERVER_NO_GLOBAL_HTTP_METHODS to disable this warning.
+#define ASYNCWEBSERVER_NO_GLOBAL_HTTP_METHODS
+#endif
+
 class AsyncWebServer;
 class AsyncWebServerRequest;
 class AsyncWebServerResponse;
@@ -82,29 +95,40 @@ class AsyncMiddlewareChain;
 namespace AsyncWebRequestMethod {
 // The long name here is because we sometimes include this in the global namespace
 enum AsyncWebRequestMethodType {
-  HTTP_GET = 0b0000000000000001,
-  HTTP_POST = 0b0000000000000010,
-  HTTP_DELETE = 0b0000000000000100,
-  HTTP_PUT = 0b0000000000001000,
-  HTTP_PATCH = 0b0000000000010000,
-  HTTP_HEAD = 0b0000000000100000,
-  HTTP_OPTIONS = 0b0000000001000000,
-  HTTP_PROPFIND = 0b0000000010000000,
-  HTTP_LOCK = 0b0000000100000000,
-  HTTP_UNLOCK = 0b0000001000000000,
-  HTTP_PROPPATCH = 0b0000010000000000,
-  HTTP_MKCOL = 0b0000100000000000,
-  HTTP_MOVE = 0b0001000000000000,
-  HTTP_COPY = 0b0010000000000000,
-  HTTP_RESERVED = 0b0100000000000000,
-  HTTP_ANY = 0b0111111111111111,
-  HTTP_INVALID = 0b1000000000000000
+  HTTP_GET = 1 << 0,
+  HTTP_POST = 1 << 1,
+  HTTP_DELETE = 1 << 2,
+  HTTP_PUT = 1 << 3,
+  HTTP_PATCH = 1 << 4,
+  HTTP_HEAD = 1 << 5,
+  HTTP_OPTIONS = 1 << 6,
+  HTTP_PROPFIND = 1 << 7,
+  HTTP_LOCK = 1 << 8,
+  HTTP_UNLOCK = 1 << 9,
+  HTTP_PROPPATCH = 1 << 10,
+  HTTP_MKCOL = 1 << 11,
+  HTTP_MOVE = 1 << 12,
+  HTTP_COPY = 1 << 13,
+  HTTP_RESERVED = 1 << 14,
+
+  HTTP_UNKNOWN = 0,
+  HTTP_INVALID = 1 << 15  // Sentinel
 };
 };  // namespace AsyncWebRequestMethod
 
 typedef AsyncWebRequestMethod::AsyncWebRequestMethodType WebRequestMethod;
 typedef uint16_t WebRequestMethodComposite;
 
+namespace AsyncWebRequestMethod {
+constexpr WebRequestMethodComposite HTTP_ALL = static_cast<WebRequestMethodComposite>(HTTP_INVALID) - 1;
+
+// We used to use HTTP_ANY but some libraries squat on this name with a macro.  Transition to HTTP_ALL instead.
+#ifndef HTTP_ANY
+__attribute__((deprecated("HTTP_ANY is used as a macro by other libraries - use AsyncWebRequestMethod::HTTP_ALL instead."))
+) constexpr WebRequestMethodComposite HTTP_ANY = HTTP_ALL;
+#endif
+}  // namespace AsyncWebRequestMethod
+
 // Type-safe helper functions for composite methods
 constexpr inline WebRequestMethodComposite operator|(WebRequestMethodComposite l, WebRequestMethod r) {
   return l | static_cast<WebRequestMethodComposite>(r);
@@ -1566,7 +1590,7 @@ class AsyncWebServer : public AsyncMiddlewareChain {
   bool removeHandler(AsyncWebHandler *handler);
 
   AsyncCallbackWebHandler &on(AsyncURIMatcher uri, ArRequestHandlerFunction onRequest) {
-    return on(std::move(uri), AsyncWebRequestMethod::HTTP_ANY, onRequest);
+    return on(std::move(uri), AsyncWebRequestMethod::HTTP_ALL, onRequest);
   }
   AsyncCallbackWebHandler &on(
     AsyncURIMatcher uri, WebRequestMethodComposite method, ArRequestHandlerFunction onRequest, ArUploadHandlerFunction onUpload = nullptr,

src/WebHandlerImpl.h

@@ -62,7 +62,7 @@ class AsyncCallbackWebHandler : public AsyncWebHandler {
   bool _isRegex;
 
 public:
-  AsyncCallbackWebHandler() : _uri(), _method(AsyncWebRequestMethod::HTTP_ANY), _onRequest(NULL), _onUpload(NULL), _onBody(NULL), _isRegex(false) {}
+  AsyncCallbackWebHandler() : _uri(), _method(AsyncWebRequestMethod::HTTP_ALL), _onRequest(NULL), _onUpload(NULL), _onBody(NULL), _isRegex(false) {}
   void setUri(AsyncURIMatcher uri);
   void setMethod(WebRequestMethodComposite method) {
     _method = method;

src/WebRequest.cpp

@@ -40,7 +40,7 @@ enum {
 
 AsyncWebServerRequest::AsyncWebServerRequest(AsyncWebServer *s, AsyncClient *c)
   : _client(c), _server(s), _handler(NULL), _response(NULL), _onDisconnectfn(NULL), _temp(), _parseState(PARSE_REQ_START), _version(0),
-    _method(AsyncWebRequestMethod::HTTP_ANY), _url(), _host(), _contentType(), _boundary(), _authorization(), _reqconntype(RCT_HTTP),
+    _method(AsyncWebRequestMethod::HTTP_UNKNOWN), _url(), _host(), _contentType(), _boundary(), _authorization(), _reqconntype(RCT_HTTP),
     _authMethod(AsyncAuthType::AUTH_NONE), _isMultipart(false), _isPlainPost(false), _expectingContinue(false), _contentLength(0), _parsedLength(0),
     _multiParseState(0), _boundaryPosition(0), _itemStartIndex(0), _itemSize(0), _itemName(), _itemFilename(), _itemType(), _itemValue(), _itemBuffer(0),
     _itemBufferIndex(0), _itemIsFile(false), _chunkStartIndex(0), _chunkOffset(0), _chunkSize(0), _chunkedParseState(CHUNK_NONE), _chunkedLastChar(0),
@@ -1357,7 +1357,6 @@ const char *methodToString(WebRequestMethod method) {
     case AsyncWebRequestMethod::HTTP_MKCOL:     return T_MKCOL;
     case AsyncWebRequestMethod::HTTP_MOVE:      return T_MOVE;
     case AsyncWebRequestMethod::HTTP_COPY:      return T_COPY;
-    case AsyncWebRequestMethod::HTTP_ANY:       return T_ANY;
-    default:             return T_UNKNOWN;
+    default:                                    return T_UNKNOWN;
   }
 }

src/literals.h

@@ -104,7 +104,6 @@ static constexpr const char T_WWW_AUTH[] = "WWW-Authenticate";
 static constexpr const char T_X_Expected_Entity_Length[] = "X-Expected-Entity-Length";
 
 // HTTP Methods
-static constexpr const char T_ANY[] = "ANY";
 static constexpr const char T_GET[] = "GET";
 static constexpr const char T_POST[] = "POST";
 static constexpr const char T_PUT[] = "PUT";