[mathieucarbou]

Summary

This PR implements Phase 2 — a route table refactoring that decouples URI/method matching from handler objects. One handler object can now serve multiple routes, combining Phase 1's ownership control with Phase 2's routing flexibility.

Builds on #493 (Phase 1: non-owning handler registration). Fully backward compatible.

Motivation

In the #468 discussion, @inF1704 pointed out that URI matching lives inside handler objects (AsyncCallbackWebHandler carries _uri and _method), which prevents one handler from serving multiple routes. This PR moves URI/method matching into the server's routing table.

API Changes

Route Registration

Call	Ownership
server.addRoute(uri, method, new MyHandler())	Server owns (default)
server.addRoute(uri, method, ptr, false)	Non-owning (pointer)
server.addRoute(uri, method, myHandler)	Non-owning (reference)

Route Removal

Call	Effect
server.removeRoute(uri, method)	Remove a specific route
server.removeHandler(&handler)	Removes ALL routes + legacy handler entries for that handler

Usage

One Handler, Multiple Routes

static AsyncWebServer server(80);

// One handler object — lives in static RAM (Phase 1)
static AsyncCallbackWebHandler greetHandler;

void setup() {
  greetHandler.onRequest([](AsyncWebServerRequest *request) {
    request->send(200, "text/plain", "Hello from " + request->url());
  });

  // Same handler on three different routes (Phase 2):
  server.addRoute(AsyncURIMatcher::exact("/hello"), HTTP_GET, greetHandler);
  server.addRoute(AsyncURIMatcher::exact("/hi"), HTTP_GET, greetHandler);
  server.addRoute(AsyncURIMatcher::prefix("/greet/"), HTTP_GET, greetHandler);

  server.begin();
}

PSRAM Handler on Multiple Routes (ESP32)

#include <esp_heap_caps.h>

void *mem = heap_caps_malloc(sizeof(AsyncCallbackWebHandler), MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
auto *handler = new (mem) AsyncCallbackWebHandler();
handler->onRequest([](AsyncWebServerRequest *request) {
  request->send(200, "application/json", "{\"ok\":true}");
});

// Same PSRAM handler on two routes — non-owning:
server.addRoute(AsyncURIMatcher::prefix("/api/"), HTTP_GET, handler, false);
server.addRoute(AsyncURIMatcher::exact("/status"), HTTP_GET, handler, false);

Method-Based Routing

The route table filters by HTTP method — a GET route won't match a POST request:

server.addRoute(AsyncURIMatcher::exact("/data"), HTTP_GET, handler);
// POST /data falls through to the next handler or catch-all

Design

Request received
  → Rewrites applied
  → Route table checked first (Phase 2):
      for each route: method matches? URI matches? filter passes? → attach handler
  → Legacy handlers checked (Phase 1, backward compat):
      for each handler: filter passes? canHandle() returns true? → attach handler
  → Catch-all handler (or bare 501 if none)

Internal Changes

Component	Change
RouteEntry struct	{ AsyncURIMatcher uri, WebRequestMethodComposite method, bool hasMatcher, HandlerEntry entry }
_routes	std::list<RouteEntry> — evaluated before _handlers
_attachHandler()	Routes first (URI+method match), then legacy handlers (canHandle)
AsyncCallbackWebHandler::_routeManaged	When true, canHandle() skips URI/method checks
AsyncURIMatcher::operator==	Value comparison for removeRoute()
removeHandler()	Also removes routes pointing to that handler
reset()	Clears both _routes and _handlers

Backward Compatibility

✅ 100% additive — all existing code works identically:

• server.on() / serveStatic() / addHandler() — unchanged
• Handlers registered via addHandler() use canHandle() dispatch (legacy path)
• Handlers registered via addRoute() use route table dispatch (new path)
• Both paths coexist; routes take priority
• Existing examples compile without modification

Files Changed

File	Change
src/ESPAsyncWebServer.h	RouteEntry struct, addRoute/removeRoute declarations, AsyncURIMatcher::operator==
src/WebServer.cpp	Route table dispatch in _attachHandler, addRoute/removeRoute impl, removeHandler extended
src/WebHandlerImpl.h	AsyncCallbackWebHandler::_routeManaged flag, _setRouteManaged()
src/WebHandlers.cpp	canHandle() checks _routeManaged to skip URI/method matching
examples/arduino/MultiRoute/MultiRoute.ino	New example: one handler on 3 routes, PSRAM on 2 routes, classic on()
docs/routing.md	Route Table section with examples
docs/configuration.md	Route table section
docs/concepts.md	Route table note
platformio.ini	MultiRoute example entry

Related

• Builds on feat: user-controlled handler allocation (non-owning registration) #493 (Phase 1: non-owning handler registration)
• Addresses @inF1704's observation in feat: opt-in ASYNCWEBSERVER_USE_PSRAM - allocate handler objects in PSRAM (ESP32) #468: "URI currently lives inside the handler"
• Phase 2 mentioned in feat: user-controlled handler allocation (non-owning registration) #493's roadmap comment

Checklist

• Fully backward compatible (Phase 1 + existing APIs)
• Compiles on host emulator (Arduino-Emulator + CMake)
• New example follows existing conventions (AP mode, ASYNCWEBSERVER_WIFI_SUPPORTED guards)
• Documentation updated (routing.md, configuration.md, concepts.md)
• Routes evaluated before legacy handlers
• removeHandler() works for both route-registered and legacy handlers

[mathieucarbou]

Closing in favor of #495 — this PR was created before the branch was squashed into a single clean commit. #495 contains identical changes with passing CI on all platforms.