feat: added support for filters in WebServer library

[ayushsharma82]

Description of Change

This PR implements support for setFilter in WebServer library, particularly useful for conditional processing of routes based on filter functions set by user.

• on methods now return RequestHandler which also provides another way for users to remove routes. ( Ref: Added support for removing routes in WebServer library #9832 )
• Updated RequestHandler & FunctionRequestHandler class to add setFilter function.
• Added 2 default filters: ON_STA_FILTER & ON_AP_FILTER

Tests scenarios

I've tested this on arduino-esp32 core v3.0.1 - ESP32 ( Wemos D1 Mini ESP32 board ).

Important

Potential Bug: @me-no-dev , NetworkClient's localIP() method always returns IPAddress(0,0,0,0) no matter through which interface the client's request came. This breaks the ON_STA_FILTER & ON_AP_FILTER filters as we can't detect the right interface correctly.

Eg. In all scenarios (WIFI_STA / WIFI_AP / WIFI_AP_STA), the client.localIP() method return 0.0.0.0).
Issue: #9843

This PR is ready to be merged once the above bug is fixed.

Above issue is fixed and PR is ready to be merged.

Related links

--

[github-actions]

	Warnings
⚠️	Some issues found for the commit messages in this PR: the commit message "chore: grammar": summary looks too short type/action should be one of [change, ci, docs, feat, fix, refactor, remove, revert, test] Please fix these commit messages - here are some basic tips: follow Conventional Commits style correct format of commit message should be: <type/action>(<scope/component>): <summary>, for example fix(esp32): Fixed startup timeout issue allowed types are: change,ci,docs,feat,fix,refactor,remove,revert,test sufficiently descriptive message summary should be between 20 to 72 characters and start with upper case letter avoid Jira references in commit messages (unavailable/irrelevant for our customers) TIP: Install pre-commit hooks and run this check when committing (uses the Conventional Precommit Linter).
⚠️	Please consider squashing your 11 commits (simplifying branch history).

👋 Hello ayushsharma82, we appreciate your contribution to this project!

---

Click to see more instructions ...

This automated output is generated by the PR linter DangerJS, which checks if your Pull Request meets the project's requirements and helps you fix potential issues.

DangerJS is triggered with each push event to a Pull Request and modify the contents of this comment.

Please consider the following:
- Danger mainly focuses on the PR structure and formatting and can't understand the meaning behind your code or changes.
- Danger is not a substitute for human code reviews; it's still important to request a code review from your colleagues.
- Resolve all warnings (⚠️ ) before requesting a review from human reviewers - they will appreciate it.
- To manually retry these Danger checks, please navigate to the Actions tab and re-run last Danger workflow.

Review and merge process you can expect ...

We do welcome contributions in the form of bug reports, feature requests and pull requests.

1. An internal issue has been created for the PR, we assign it to the relevant engineer.
2. They review the PR and either approve it or ask you for changes or clarifications.
3. Once the GitHub PR is approved we do the final review, collect approvals from core owners and make sure all the automated tests are passing.
- At this point we may do some adjustments to the proposed change, or extend it by adding tests or documentation.
4. If the change is approved and passes the tests it is merged into the default branch.

Generated by 🚫 dangerJS against 7f11be6

[github-actions]

Test Results

 56 files   56 suites   5m 11s ⏱️
 21 tests  21 ✅ 0 💤 0 ❌
135 runs  135 ✅ 0 💤 0 ❌

Results for commit 7f11be6.

♻️ This comment has been updated with latest results.

[me-no-dev]

to implement ON_STA_FILTER and ON_AP_FILTER you are changing the API much. I suggest to split that in another PR that we could add to 3.1 or whenever makes sense to add such breaking change.

[ayushsharma82]

I guess everything's backward compatible with current state of this PR? But, yeah if you want, let me know what I should split.

[me-no-dev]

Yes, please split them, because if someone has custom handlers, they will now break. We can add as breaking change when possible

[me-no-dev]

You got some errors compiling: https://github.com/espressif/arduino-esp32/actions/runs/9487829527/job/26146113347?pr=9842#step:7:61

[ayushsharma82]

Okay.

Just a thought, should I try to make handlers backwards compatible 🤓? Your team can then deprecate old handlers with v3.1 or later.

[me-no-dev]

If they are backward compatible, that would be OK

[ayushsharma82]

Btw, were you able to check why client IP is always 0? I looked at this log and it showed 0 too.

https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/src/WebServer.cpp#L349

[me-no-dev]

localIP is fixed in #9845

[me-no-dev]

here is one thing that I did not think about before. Because of ON_STA_FILTER & ON_AP_FILTER, WiFi will always get dragged, compiled and linked, regardless if it's used or not. How about you remove them from the classes and add them in example? Imagine a board with Ethernet. Basic sketch with ETH will be about half a megabyte, while one with WiFi will probably be more than a megabyte.

[ayushsharma82]

I agree.

What about creating separate files for filters which can included by user? Example: WiFiFilters.h or ETHFilters.h.

[me-no-dev]

they are just a few lines each, so better have them inside example.

[github-actions]

Memory usage test (comparing PR against master branch)

The table below shows the summary of memory usage change (decrease - increase) in bytes and percentage for each target.

Memory	FLASH [bytes]		FLASH [%]		RAM [bytes]		RAM [%]
Target	DEC	INC	DEC	INC	DEC	INC	DEC	INC
ESP32S3	0	0	0.00	0.00	0	0	0.00	0.00
ESP32S2	0	0	0.00	0.00	0	0	0.00	0.00
ESP32C3	0	0	0.00	0.00	0	0	0.00	0.00
ESP32C6	0	0	0.00	0.00	0	0	0.00	0.00
ESP32	0	0	0.00	0.00	0	0	0.00	0.00

Click to expand the detailed deltas report [usage change in BYTES]

Target	ESP32S3		ESP32S2		ESP32C3		ESP32C6		ESP32
Example	FLASH	RAM	FLASH	RAM	FLASH	RAM	FLASH	RAM	FLASH	RAM
WebServer/examples/AdvancedWebServer	-	-	-	-	-	-	-	-	-	-
WebServer/examples/FSBrowser	-	-	-	-	-	-	-	-	-	-
WebServer/examples/Filters	-	-	-	-	-	-	-	-	-	-
WebServer/examples/HelloServer	-	-	-	-	-	-	-	-	-	-
WebServer/examples/HttpAdvancedAuth	-	-	-	-	-	-	-	-	-	-
WebServer/examples/HttpAuthCallback	-	-	-	-	-	-	-	-	-	-
WebServer/examples/HttpAuthCallbackInline	-	-	-	-	-	-	-	-	-	-
WebServer/examples/HttpBasicAuth	-	-	-	-	-	-	-	-	-	-
WebServer/examples/HttpBasicAuthSHA1	-	-	-	-	-	-	-	-	-	-
WebServer/examples/HttpBasicAuthSHA1orBearerToken	-	-	-	-	-	-	-	-	-	-
WebServer/examples/MultiHomedServers	-	-	-	-	-	-	-	-	-	-
WebServer/examples/PathArgServer	-	-	-	-	-	-	-	-	-	-
WebServer/examples/SDWebServer	-	-	-	-	-	-	-	-	-	-
WebServer/examples/SimpleAuthentification	-	-	-	-	-	-	-	-	-	-
WebServer/examples/UploadHugeFile	-	-	-	-	-	-	-	-	-	-
WebServer/examples/WebServer	-	-	-	-	-	-	-	-	-	-
WebServer/examples/WebUpdate	-	-	-	-	-	-	-	-	-	-

[me-no-dev]

if you have confirmed that localIP works, could you please edit the PR description?

[ayushsharma82]

Tested and works well.