WiFiServer - implementation aligned with Arduino.cc. With example. (breaking change)

[JAndrassy]

implements available() as documented here https://www.arduino.cc/reference/en/libraries/wifi/server.available/

implements print-to-all-clients as documented here https://www.arduino.cc/reference/en/libraries/wifi/server.print/

adds WiFiPagerServer example to demonstrate how server.available() and server.print() work.

Requires #9029

[github-actions]

Warnings

⚠️

Some issues found for the commit messages in this PR: the commit message "WiFiServer - implementation aligned with Arduino.cc with example": summary looks empty type/action looks empty 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).

👋 Hello JAndrassy, 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 1975eb1

[VojtechBartoska]

Thanks @JAndrassy for the PR, we will review it soon. Probably in January due to Christmas and New Years Eve vacations.

We are trying to find the best approach for Wifi refactoring so hopefully we will end up in some reasonable solutions which will be also acceptable for you. :) It is a bit challenging.

[JAndrassy]

The server.available() method was what started me to evaluate differences between Arduino networking libraries. Almost two years ago we found a solution for the esp8266 WiFi library: deprecating available() and providing a separate ArduinoWiFiServer class for available() and print-to-all-clients.

In August this year I stared to write down all my experience with creating and maintaining Arduino networking libraries, because new libraries appear and have the same mistakes I try to eliminate in old libraries. But writing the Guide let to necessity of defining the networking API by analyzing the significant libraries. I found many often simple differences so I started to do PR in all repositories. Then I wrote test sketches for basic functions and those found more errors in implementations than I would expect (even in my libraries.). So more PR.

https://github.com/JAndrassy/Arduino-Networking-API

[VojtechBartoska]

I see, I have noticed you contributed to ESP8266 repository, I wasn`t aware about the contributions to other libraries as well. Good to know, we will check it.

[lucasssvaz]

Please fix the errors shown by the CI

[JAndrassy]

@lucasssvaz this PR fixes it #9029

the test failed on compiler warning

warning: implicitly-declared 'WiFiClient::WiFiClient(const WiFiClient&)' is deprecated [-Wdeprecated-copy]
note: because 'WiFiClient' has user-provided 'WiFiClient& WiFiClient::operator=(const WiFiClient&)'

https://en.cppreference.com/w/cpp/language/rule_of_three

[me-no-dev]

@JAndrassy

• what happens to clients that are connected, but have not sent any data?
• how would you implement a protocol that needs to send "HELLO" to every new connection?

[JAndrassy]

what happens to clients that are connected, but have not sent any data?

they stay connected. but it is possible that there is a timeout set in IDF LwIP. the AT firmware has it.

how would you implement a protocol that needs to send "HELLO" to every new connection?

using server.accept(), not server.available().

The server.available() originates in Processing. It is a strange idea to simplify a TCP server for artists. I don't like it. But my PR to deprecate the method name available was reverted.

And rejected PR #9028 is related too

[me-no-dev]

they stay connected. but it is possible that there is a timeout set in IDF LwIP. the AT firmware has it.

This is not a nice solution. Lingering resources with no way to clear them is not good.

using server.accept(), not server.available().

But then the client will not be put in the list and you will not be able to further query it with available()?

I do understand very well your point, but I must be sure that this will cause more good than harm if merged :)

[me-no-dev]

CONFIG_LWIP_MAX_SOCKETS is 16, meaning there can be more than 5 monitored clients. What happens with the rest?

[JAndrassy]

accept() is only invoked if there is a free position in the array.
I could change it to CONFIG_LWIP_MAX_SOCKETS

[JAndrassy]

I do understand very well your point, but I must be sure that this will cause more good than harm if merged :)

I would prefer deprecation. as I already wrote on multiple places, nobody expects what available() does in Arduino libraries. basically developers at Arduino don't know it and do it wrong in new libraries (arduino/uno-r4-wifi-usb-bridge#20, arduino/ArduinoCore-mbed#793)

the link to deprecation PR was wrong in my previous comment. it is #8860

[me-no-dev]

Ok :) before we can consider this for merging, here are some suggestions:

• Track all clients, not just the ones you accept through available
• Access to the list of clients must be guarded with semaphore (read/write)
• Add documentation explaining the changes and some small examples to show what to update in the code
• Make sure that all relevant examples are updated

[JAndrassy]

examples are already updated to accept(). that was not reverted from the deprecation PR. this PR adds an example for server.available().
users will have to change their code from server.available() to server.accept() to have the same functionality as with 'old' available(). I guess we have no way to warn them about that at compile time (as the deprecation would do)

[JAndrassy]

now I realized there is a problem. Arduino doc instructs to stop() the connection returned by the server when it is handled. but client.stop() in this library does nothing and the connection is closed from local side only when the last copy of WiFiClient is destroyed. So the copy in WiFiServer will hold the connection.

can we please deprecate server.available and be done. nobody will miss it

[me-no-dev]

so you are good to close this if we deprecate available?

[JAndrassy]

so you are good to close this if we deprecate available?

I already did the deprecation. it was reverted with the argument about "aligned with Arduino.cc"

I am fan of accept(). I added it to all libraries by Arduino. some PR are merged, some are at least approved for merge

[me-no-dev]

I just need the full picture. Nobody has complained about this in the last 10 years, so if we are to break something, there ought to be a good reason. Since available is just an alias to accept, deprecating it will only force people to use accept, which will bring nothing to either party. Can't we just document that both do the same and that available is there for compatibility?

[JAndrassy]

and #9028 ?

[Jason2866]

Maybe i misunderstood the goal of the PR completely wrong. Drop available and replace with accept and break every existing code which uses available?
Doing this "just" to be compatible?! Nobody had an problem the last year's doing this way. Imho a really not needed breaking change, a less invasive solution should be found.

[JAndrassy]

Maybe i misunderstood the goal of the PR completely wrong

the goal of this PR was to show what does it mean to implement proper available() and print-to-all-clients
In my view it is the only alternative to available() marked as deprecated to clearly say that it is not the same as in other Arduino libraries.

in esp8266 WiFi library the deprecation of server.available() was done two years ago.
and here server.accept() was in WiFiServer from the start

[me-no-dev]

show what does it mean to implement proper available() and print-to-all-clients

I agreed with that and listed the required changes necessary to make it mergeable. We are on FreeRTOS with multiple cores and threads, so safety is important. Current code will not do. Also some connections are saved and others not is also not a solution. Either all or none.

[Jason2866]

@JAndrassy Thx, for clarification. @me-no-dev thats my fear, esp32 is different to all others Arduino supported MCUs. Code can not be always align.

[JAndrassy]

some connections are saved and others not is also not a solution.

using CONFIG_LWIP_MAX_SOCKETS for SERVER_MAX_MONITORED_CLIENTS would solve that. semaphore could be done too.

but what with stop()? why stop() doesn't close the connection?

I coded the available() and print-to-all-clients enhancement of WiFiServer added in this PR 3 years ago for my TelnetStream library. Now it is in my NetApiHelpers library. It doesn't have to be in the specific WiFi or Ethernet library.

[me-no-dev]

@JAndrassy if you are willing to implement what is outlined here, then we can discuss merging :)

[JAndrassy]

Add documentation explaining the changes and some small examples to show what to update in the code

to migration guide?

how to fix the failing check? why does it compile a WiFi example for H2?

[me-no-dev]

how to fix the failing check? why does it compile a WiFi example for H2?

You add a file named .skip.esp32h2 in the sketch folder.

to migration guide?

And to the library documentation (if there is such)

[JAndrassy]

You add a file named .skip.esp32h2 in the sketch folder.

now I see it. I had .* files hidden in Eclipse, while I was looking at the other examples

And to the library documentation (if there is such)

There isn't. Only WiFi STA and WiFi SoftAP are documented. WiFiClient, WiFiUDP and WiFiServer are not documented in ESP32 Arduino doc

[me-no-dev]

there is still the issue of clients acquired by accept() are not added to the list. I suggest you rename accept() to _accept(), set it also as protected and use it instead of accept() internally. Then create a new accept() , that will call _accept() and also add to the list and can be mass-written to.

[JAndrassy]

directly accepted clients should not be added to the list, handled with print-to-all-clients and closed in end()
https://www.arduino.cc/reference/en/libraries/ethernet/server.accept/

(so then again. why not just deprecate available() and remove inheritance from Print (disguised as Server)?)

I wrote a guide for Arduino networking API
https://github.com/JAndrassy/Arduino-Networking-API/blob/main/ArduinoNetAPIDev.md

[me-no-dev]

so then again. why not just deprecate available() and remove inheritance from Print (disguised as Server)?

OK, you made your point :) Let's go with that instead

[me-no-dev]

Please open a new one with the deprecation