Material doc site

Author: mathieucarbou

.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: Publish Docs
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -3,3 +3,5 @@
 /.pio
 /.vscode
 /logs
+/site
+/venv

docs/code_of_conduct.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socioeconomic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+https://sidweb.nl/cms3/en/contact.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

docs/concepts.md

@@ -0,0 +1,74 @@
+# Concepts
+
+## Principles of operation
+
+### The Async Web server
+
+- Listens for connections
+- Wraps the new clients into `Request`
+- Keeps track of clients and cleans memory
+- Manages `Rewrites` and apply them on the request url
+- Manages `Handlers` and attaches them to Requests
+
+### Request Life Cycle
+
+- TCP connection is received by the server
+- The connection is wrapped inside `Request` object
+- When the request head is received (type, url, get params, http version and host),
+  the server goes through all `Rewrites` (in the order they were added) to rewrite the url and inject query parameters,
+  next, it goes through all attached `Handlers`(in the order they were added) trying to find one
+  that `canHandle` the given request. If none are found, the default(catch-all) handler is attached.
+- The rest of the request is received, calling the `handleUpload` or `handleBody` methods of the `Handler` if they are needed (POST+File/Body)
+- When the whole request is parsed, the result is given to the `handleRequest` method of the `Handler` and is ready to be responded to
+- In the `handleRequest` method, to the `Request` is attached a `Response` object (see below) that will serve the response data back to the client
+- When the `Response` is sent, the client is closed and freed from the memory
+
+### Rewrites and how do they work
+
+- The `Rewrites` are used to rewrite the request url and/or inject get parameters for a specific request url path.
+- All `Rewrites` are evaluated on the request in the order they have been added to the server.
+- The `Rewrite` will change the request url only if the request url (excluding get parameters) is fully match
+  the rewrite url, and when the optional `Filter` callback return true.
+- Setting a `Filter` to the `Rewrite` enables to control when to apply the rewrite, decision can be based on
+  request url, http version, request host/port/target host, get parameters or the request client's localIP or remoteIP.
+- Two filter callbacks are provided: `ON_AP_FILTER` to execute the rewrite when request is made to the AP interface,
+  `ON_STA_FILTER` to execute the rewrite when request is made to the STA interface.
+- The `Rewrite` can specify a target url with optional get parameters, e.g. `/to-url?with=params`
+
+### Handlers and how do they work
+
+- The `Handlers` are used for executing specific actions to particular requests
+- One `Handler` instance can be attached to any request and lives together with the server
+- Setting a `Filter` to the `Handler` enables to control when to apply the handler, decision can be based on
+  request url, http version, request host/port/target host, get parameters or the request client's localIP or remoteIP.
+- Two filter callbacks are provided: `ON_AP_FILTER` to execute the rewrite when request is made to the AP interface,
+  `ON_STA_FILTER` to execute the rewrite when request is made to the STA interface.
+- The `canHandle` method is used for handler specific control on whether the requests can be handled
+  and for declaring any interesting headers that the `Request` should parse. Decision can be based on request
+  method, request url, http version, request host/port/target host and get parameters
+- Once a `Handler` is attached to given `Request` (`canHandle` returned true)
+  that `Handler` takes care to receive any file/data upload and attach a `Response`
+  once the `Request` has been fully parsed
+- `Handlers` are evaluated in the order they are attached to the server. The `canHandle` is called only
+  if the `Filter` that was set to the `Handler` return true.
+- The first `Handler` that can handle the request is selected, not further `Filter` and `canHandle` are called.
+
+### Responses and how do they work
+
+- The `Response` objects are used to send the response data back to the client
+- The `Response` object lives with the `Request` and is freed on end or disconnect
+- Different techniques are used depending on the response type to send the data in packets
+  returning back almost immediately and sending the next packet when this one is received.
+  Any time in between is spent to run the user loop and handle other network packets
+- Responding asynchronously is probably the most difficult thing for most to understand
+- Many different options exist for the user to make responding a background task
+
+### Template processing
+
+- ESPAsyncWebserver contains simple template processing engine.
+- Template processing can be added to most response types.
+- Currently it supports only replacing template placeholders with actual values. No conditional processing, cycles, etc.
+- Placeholders are delimited with `%` symbols. Like this: `%TEMPLATE_PLACEHOLDER%`.
+- It works by extracting placeholder name from response text and passing it to user provided function which should return actual value to be used instead of placeholder.
+- Since it's user provided function, it is possible for library users to implement conditional processing and cycles themselves.
+- Since it's impossible to know the actual response size after template processing step in advance (and, therefore, to include it in response headers), the response becomes [chunked](#chunked-response).

docs/configuration.md

@@ -0,0 +1,40 @@
+# Configuration
+
+## Important recommendations for build options
+
+Most of the crashes are caused by improper use or configuration of the AsyncTCP library used for the project.
+Here are some recommendations to avoid them and build-time flags you can change.
+
+- `CONFIG_ASYNC_TCP_MAX_ACK_TIME`: defines a timeout for TCP connection to be considered alive when waiting for data.
+  In some bad network conditions you might consider increasing it.
+
+- `CONFIG_ASYNC_TCP_QUEUE_SIZE`: defines the length of the queue for events related to connections handling.
+  Both the server and AsyncTCP library were optimized to control the queue automatically. Do NOT try blindly increasing the queue size, it does not help you in a way you might think it is. If you receive debug messages about queue throttling, try to optimize your server callbacks code to execute as fast as possible.
+
+- `CONFIG_ASYNC_TCP_RUNNING_CORE`: CPU core thread affinity that runs the queue events handling and executes server callbacks. Default is ANY core, so it means that for dualcore SoCs both cores could handle server activities. If your server's code is too heavy and unoptimized or you see that sometimes
+  server might affect other network activities, you might consider to bind it to the same core that runs Arduino code (1) to minimize affect on radio part. Otherwise you can leave the default to let RTOS decide where to run the thread based on priority
+
+- `CONFIG_ASYNC_TCP_STACK_SIZE`: stack size for the thread that runs sever events and callbacks. Default is 16k that is a way too much waste for well-defined short async code or simple static file handling. You might want to cosider reducing it to 4-8k to same RAM usage. If you do not know what this is or not sure about your callback code demands - leave it as default, should be enough even for very hungry callbacks in most cases.
+
+- `ASYNCWEBSERVER_USE_CHUNK_INFLIGHT`: inflight control for chunked responses.
+  If you need to serve chunk requests with a really low buffer (which should be avoided), you can set `-D ASYNCWEBSERVER_USE_CHUNK_INFLIGHT=0` to disable the in-flight control.
+
+> [!NOTE]
+> This relates to ESP32 only, ESP8266 uses different ESPAsyncTCP lib that does not has this build options
+
+Recommended configurations:
+
+```c++
+  -D CONFIG_ASYNC_TCP_MAX_ACK_TIME=5000   // (keep default)
+  -D CONFIG_ASYNC_TCP_PRIORITY=10         // (keep default)
+  -D CONFIG_ASYNC_TCP_QUEUE_SIZE=64       // (keep default)
+  -D CONFIG_ASYNC_TCP_RUNNING_CORE=1      // force async_tcp task to be on same core as Arduino app (default is any core)
+  -D CONFIG_ASYNC_TCP_STACK_SIZE=4096     // reduce the stack size (default is 16K)
+```
+
+## Important things to remember
+
+- This is fully asynchronous server and as such does not run on the loop thread.
+- You can not use yield or delay or any function that uses them inside the callbacks
+- The server is smart enough to know when to close the connection and free resources
+- You can not send more than one response to a single request

docs/eventsource.md

@@ -0,0 +1,93 @@
+# EventSource
+
+## Async Event Source Plugin
+
+The server includes EventSource (Server-Sent Events) plugin which can be used to send short text events to the browser.
+Difference between EventSource and WebSockets is that EventSource is single direction, text-only protocol.
+
+See the [ServerSentEvents example here](../examples/ServerSentEvents/ServerSentEvents.ino).
+
+### Setup Event Source on the server
+
+```cpp
+AsyncWebServer server(80);
+AsyncEventSource events("/events");
+
+void setup(){
+  // setup ......
+  events.onConnect([](AsyncEventSourceClient *client){
+    if(client->lastId()){
+      Serial.printf("Client reconnected! Last message ID that it got is: %u\n", client->lastId());
+    }
+    //send event with message "hello!", id current millis
+    // and set reconnect delay to 1 second
+    client->send("hello!",NULL,millis(),1000);
+  });
+
+  server.addHandler(&events);
+  // setup ......
+}
+
+void loop(){
+  if(eventTriggered){ // your logic here
+    //send event "myevent"
+    events.send("my event content","myevent",millis());
+  }
+}
+```
+
+**IMPORTANT**: Use `AsyncAuthenticationMiddleware` instead of the deprecated `setAuthentication()` method for authentication.
+
+```cpp
+AsyncAuthenticationMiddleware authMiddleware;
+authMiddleware.setAuthType(AsyncAuthType::AUTH_DIGEST);
+authMiddleware.setRealm("My app name");
+authMiddleware.setUsername("admin");
+authMiddleware.setPassword("admin");
+authMiddleware.generateHash();
+
+events.addMiddleware(&authMiddleware);
+```
+
+### Setup Event Source in the browser
+
+```javascript
+if (!!window.EventSource) {
+  var source = new EventSource("/events");
+
+  source.addEventListener(
+    "open",
+    function (e) {
+      console.log("Events Connected");
+    },
+    false,
+  );
+
+  source.addEventListener(
+    "error",
+    function (e) {
+      if (e.target.readyState != EventSource.OPEN) {
+        console.log("Events Disconnected");
+      }
+    },
+    false,
+  );
+
+  source.addEventListener(
+    "message",
+    function (e) {
+      console.log("message", e.data);
+    },
+    false,
+  );
+
+  source.addEventListener(
+    "myevent",
+    function (e) {
+      console.log("myevent", e.data);
+    },
+    false,
+  );
+}
+```
+