Diferrent not found file and directory file for serveStatic

[kumardeo]

I am using a multi page framework which generates assets with following structure (which is copied to data/www):

|-index.html
|-404.html
|-about
|  |-index.html
|-another-page.html
|-_static
|  |-style.hash.css
|  |-script.hash.js

Is there any way to achieve the following using server.serveStatic()?

request path -> points to file
/ -> /index.html
/index.html -> /index.html (or redirects to /)
/about -> /about/index.html
/about/ -> /about/index.html (or redirects to /about)
/about/index.html -> /about/index.html (or redirects to /about)
/another-page -> /another-page.html
/another-page/ -> /another-page.html (or redirects to /another-path)
/not-matching-path -> /404.html or /404/index.html (one of matched with 404 status and no caching)

I have implemeted it with all assets embedded in c++ codes itself. Now, I wish to use filesystem to achieve the same so I thought server.serveStatic() should work but it lacks options or fallbacks options.

I have tried:

server.serveStatic("/", LittleFS, "/www/").setDefaultFile("index.html"); // probably for SPA apps, no 404 page handling options

// what if following or similar options?
// .setDirectoryFile("index.html")
// .setNotFoundFile("404.html");

Here is my sample code I use for embedded assets:

www.h

/**
 * !WARNING: Auto-generated file
 * Last updated on: 2025-05-31 10:11:46.793399
 */

#pragma once

#include "pgmspace.h"
#include "stdint.h"

namespace www_data {
struct file {
  const char* path;
  const char* type;
  const bool gzipped;
  const uint8_t* contents;
  const uint32_t size;
  const char* modified;
  const char* etag;
};

const uint16_t num_of_files PROGMEM = 2;
const file files[num_of_files] PROGMEM = {
    {
        .path = /* ... */,
        .type =  /* ... */,
        .gzipped =  /* ... */,
        .contents =  /* ... */,
        .size =  /* ... */,
        .modified = /* ... */,
        .etag = /* ... */,
    },
    {
        .path = /* ... */,
        .type =  /* ... */,
        .gzipped =  /* ... */,
        .contents =  /* ... */,
        .size =  /* ... */,
        .modified = /* ... */,
        .etag = /* ... */,
    },
};
}  // namespace www_data

main.cpp

#include <Arduino.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>

#include "www.h"

AsyncWebServer server(80);

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);

  Serial.begin(115200);

  WiFi.setSleep(WIFI_PS_NONE);
  WiFi.softAP("Arduino Nano ESP32", "12345678");

  server.addMiddleware([](AsyncWebServerRequest* request, ArMiddlewareNext next) {
    next();

    Serial.printf("> %s %s %d\n", request->methodToString(), request->url().c_str(), request->getResponse()->code());
  });

  server.onNotFound([](AsyncWebServerRequest* request) {
    if (request->method() != HTTP_GET && request->method() != HTTP_HEAD) {
      request->send(404);
      return;
    }

    const char* directoryFilename = "index.html";
    const String notFoundHTML = "/404.html";
    const String notFoundDirectory = String("/404/") + directoryFilename;

    const String asset_path = request->url();
    const bool hasTrailingSlash = asset_path[asset_path.length() - 1] == '/';

    String directory_asset_path = asset_path;
    if (!hasTrailingSlash) {
      directory_asset_path += '/';
    }
    directory_asset_path += directoryFilename;

    String html_asset_path = asset_path;
    if (hasTrailingSlash) {
      html_asset_path.remove(html_asset_path.length() - 1);
    }
    html_asset_path += ".html";

    uint16_t final_asset_index = UINT16_MAX;
    uint16_t directory_asset_index = UINT16_MAX;
    uint16_t html_asset_index = UINT16_MAX;
    uint16_t not_found_asset_index = UINT16_MAX;

    for (int i = 0; i < www_data::num_of_files; ++i) {
      const char* path = www_data::files[i].path;
      if (asset_path.equals(path)) {
        final_asset_index = i;
        break;
      }
      if (directory_asset_index == UINT16_MAX && directory_asset_path.equals(path)) {
        directory_asset_index = i;
      }
      if (html_asset_index == UINT16_MAX && html_asset_path.equals(path)) {
        html_asset_index = i;
      }
      if (not_found_asset_index == UINT16_MAX && (notFoundHTML.equals(path) || notFoundDirectory.equals(path))) {
        not_found_asset_index = i;
      }
    }

    if (final_asset_index == UINT16_MAX) {
      final_asset_index = hasTrailingSlash
                              ? (directory_asset_index != UINT16_MAX ? directory_asset_index : html_asset_index)
                              : (html_asset_index != UINT16_MAX ? html_asset_index : directory_asset_index);
    }

    if (final_asset_index == UINT16_MAX) {
      final_asset_index = not_found_asset_index;
    }

    if (final_asset_index == UINT16_MAX) {
      request->send(404);
      return;
    }

    const bool isNotFoundAsset = final_asset_index == not_found_asset_index;

    const www_data::file file = www_data::files[final_asset_index];

    if (!isNotFoundAsset &&
        ((request->hasHeader("if-none-match") && request->header("if-none-match") == file.etag) ||
         (request->hasHeader("if-modified-since") && request->header("if-modified-since") == file.modified))) {
      AsyncWebServerResponse* response = request->beginResponse(304);
      response->addHeader("etag", file.etag);
      response->addHeader("last-modified", file.modified);
      response->addHeader("cache-control", "public, max-age=2592000");
      request->send(response);
      return;
    }

    String contentType = String(file.type);
    if ((contentType.startsWith("text/") || contentType == "application/javascript" ||
         contentType == "application/xml" || contentType == "application/xhtml+xml") &&
        !contentType.endsWith("; charset=utf-8")) {
      contentType += "; charset=utf-8";
    }
    AsyncWebServerResponse* response = request->beginResponse(
        (isNotFoundAsset ? 404 : 200), contentType, (request->method() == HTTP_GET ? file.contents : NULL), file.size
    );

    if (file.gzipped) {
      response->addHeader("content-encoding", "gzip");
    }
    if (!isNotFoundAsset) {
      response->addHeader("etag", file.etag);
      response->addHeader("last-modified", file.modified);
      response->addHeader("cache-control", "public, max-age=2592000");
    }
    request->send(response);
  });

  server.begin();
}

void loop() {
}