Readme update - file streaming

README.md

@@ -53,6 +53,7 @@ To use this library you might need to have the latest git versions of [ESP32](ht
     - [Respond with content coming from a File containing templates](#respond-with-content-coming-from-a-file-containing-templates)
     - [Respond with content using a callback](#respond-with-content-using-a-callback)
     - [Respond with content using a callback and extra headers](#respond-with-content-using-a-callback-and-extra-headers)
+    - [Respond with file content using a callback and extra headers](#respond-with-file-content-using-a-callback-and-extra-headers)
     - [Respond with content using a callback containing templates](#respond-with-content-using-a-callback-containing-templates)
     - [Respond with content using a callback containing templates and extra headers](#respond-with-content-using-a-callback-containing-templates-and-extra-headers)
     - [Chunked Response](#chunked-response)
@@ -67,6 +68,7 @@ To use this library you might need to have the latest git versions of [ESP32](ht
     - [Specifying Cache-Control header](#specifying-cache-control-header)
     - [Specifying Date-Modified header](#specifying-date-modified-header)
     - [Specifying Template Processor callback](#specifying-template-processor-callback)
+    - [Serving static files by custom handling](#serving-static-files-by-custom-handling)
   - [Param Rewrite With Matching](#param-rewrite-with-matching)
   - [Using filters](#using-filters)
     - [Serve different site files in AP mode](#serve-different-site-files-in-ap-mode)
@@ -602,6 +604,43 @@ response->addHeader("Server","ESP Async Web Server");
 request->send(response);
 ```
 
+### Respond with file content using a callback and extra headers
+
+With this code your ESP is able to serve even large (large in terms of ESP, e.g. 100kB) files
+without memory problems.
+
+You need to create a file handler in outer function (to have a single one for request) but use
+it in a lambda. The catch is that the lambda has it's own lifecycle which may/will cause it's 
+called after the original function is over thus the original file handle is destroyed. Using the 
+captured `&file` in the lambda then causes segfault (Hello, Exception 9!) and the whole ESP crashes.  
+By using this code, you tell the compiler to move the handle into the lambda so it won't be
+destroyed when outer function (that one where you call `request->send(response)`) ends.
+
+```cpp
+const File file = ... // e.g. SPIFFS.open(path, "r"); 
+
+const contentType = "application/javascript";
+
+AsyncWebServerResponse *response = request->beginResponse(
+  contentType,
+  file.size(),
+  [file](uint8_t *buffer, size_t maxLen, size_t total) mutable -> size_t {
+     int bytes = file.read(buffer, maxLen);
+
+     // close file at the end
+     if (bytes + total == file.size()) file.close();
+
+     return max(0, bytes); // return 0 even when no bytes were loaded
+   }
+);
+
+if (gzipped) {
+  response->addHeader(F("Content-Encoding"), F("gzip"));
+}
+
+request->send(response);
+```
+
 ### Respond with content using a callback containing templates
 ```cpp
 String processor(const String& var)
@@ -858,6 +897,53 @@ String processor(const String& var)
 server.serveStatic("/", SPIFFS, "/www/").setTemplateProcessor(processor);
 ```
 
+### Serving static files by custom handling
+
+It may happen your static files are too big and the ESP will crash the request before it sends the whole file.  
+In that case, you can handle static files with custom file serving through not found handler.
+
+This code below is more-or-less equivalent to this:
+```cpp
+webServer.serveStatic("/", SPIFFS, STATIC_FILES_PREFIX).setDefaultFile("index.html")
+```
+
+First, declare the handling function:
+```cpp
+bool handleStaticFile(AsyncWebServerRequest *request) {
+  String path = STATIC_FILES_PREFIX + request->url();
+
+  if (path.endsWith("/")) path += F("index.html");
+
+  String contentType = getContentType(path);
+  String pathWithGz = path + ".gz";
+
+  if (SPIFFS.exists(pathWithGz) || SPIFFS.exists(path)) {
+    bool gzipped = false;
+    if (SPIFFS.exists(pathWithGz)) {
+        gzipped = true;
+        path += ".gz";
+    }
+
+    // TODO serve the file
+
+    return true;
+  }
+
+  return false;
+}
+```
+And then configure your webserver:
+```cpp
+webServer.onNotFound([](AsyncWebServerRequest *request) {
+  if (handleStaticFile(request)) return;
+
+  request->send(404);
+});
+```
+
+You may want to try [Respond with file content using a callback and extra headers](#respond-with-file-content-using-a-callback-and-extra-headers)
+For actual serving the file.
+
 ## Param Rewrite With Matching
 It is possible to rewrite the request url with parameter matchg. Here is an example with one parameter:
 Rewrite for example "/radio/{frequence}" -> "/radio?f={frequence}"