97 lines
3.7 KiB
C++
97 lines
3.7 KiB
C++
// SPDX-License-Identifier: LGPL-3.0-or-later
|
|
// Copyright 2016-2026 Hristo Gochkov, Mathieu Carbou, Emil Muratov, Will Miles
|
|
|
|
#include <ESPAsyncWebServer.h>
|
|
|
|
/**
|
|
* @brief Sends a file from the filesystem to the client, with optional gzip compression and ETag-based caching.
|
|
*
|
|
* This method serves files over HTTP from the provided filesystem. If a compressed version of the file
|
|
* (with a `.gz` extension) exists and uncompressed version does not exist, it serves the compressed file.
|
|
* It also handles ETag caching using the CRC32 value from the gzip trailer, responding with `304 Not Modified`
|
|
* if the client's `If-None-Match` header matches the generated ETag.
|
|
*
|
|
* @param fs Reference to the filesystem (SPIFFS, LittleFS, etc.).
|
|
* @param path Path to the file to be served.
|
|
* @param contentType Optional MIME type of the file to be sent.
|
|
* If contentType is "" it will be obtained from the file extension
|
|
* @param download If true, forces the file to be sent as a download.
|
|
* @param callback Optional template processor for dynamic content generation.
|
|
* Templates will not be processed in compressed files.
|
|
*
|
|
* @note If neither the file nor its compressed version exists, responds with `404 Not Found`.
|
|
*/
|
|
void AsyncWebServerRequest::send(FS &fs, const String &path, const char *contentType, bool download, AwsTemplateProcessor callback) {
|
|
// Check uncompressed file first
|
|
if (fs.exists(path)) {
|
|
send(beginResponse(fs, path, contentType, download, callback));
|
|
return;
|
|
}
|
|
|
|
// Handle compressed version
|
|
const String gzPath = path + asyncsrv::T__gz;
|
|
File gzFile = fs.open(gzPath, fs::FileOpenMode::read);
|
|
|
|
// ETag validation
|
|
if (this->hasHeader(asyncsrv::T_INM)) {
|
|
// Generate server ETag from CRC in gzip trailer
|
|
char serverETag[11];
|
|
if (!_getEtag(gzFile, serverETag)) {
|
|
// Compressed file not found or invalid
|
|
send(404);
|
|
gzFile.close();
|
|
return;
|
|
}
|
|
|
|
// Compare with client's ETag
|
|
const AsyncWebHeader *inmHeader = this->getHeader(asyncsrv::T_INM);
|
|
if (inmHeader && inmHeader->value() == serverETag) {
|
|
gzFile.close();
|
|
this->send(304); // Not Modified
|
|
return;
|
|
}
|
|
}
|
|
|
|
// Send compressed file response
|
|
gzFile.close();
|
|
send(beginResponse(fs, path, contentType, download, callback));
|
|
}
|
|
|
|
/**
|
|
* @brief Generates an ETag string (enclosed into quotes) from the CRC32 trailer of a GZIP file.
|
|
*
|
|
* This function reads the CRC32 checksum (4 bytes) located at the end of a GZIP-compressed file
|
|
* and converts it into an 8-character hexadecimal ETag string (enclosed in double quotes and null-terminated).
|
|
* Double quotes for ETag value are required by RFC9110 section 8.8.3.
|
|
*
|
|
* @param gzFile Opened file handle pointing to the GZIP file.
|
|
* @param eTag Output buffer to store the generated ETag.
|
|
* Must be pre-allocated with at least 11 bytes (8 for hex digits + 2 for quotes + 1 for null terminator).
|
|
*
|
|
* @return true if the ETag was successfully generated, false otherwise (e.g., file too short or seek failed).
|
|
*/
|
|
bool AsyncWebServerRequest::_getEtag(File gzFile, char *etag) {
|
|
static constexpr char hexChars[] = "0123456789ABCDEF";
|
|
|
|
if (!gzFile.seek(gzFile.size() - 8)) {
|
|
return false;
|
|
}
|
|
|
|
uint32_t crc;
|
|
gzFile.read(reinterpret_cast<uint8_t *>(&crc), sizeof(crc));
|
|
|
|
etag[0] = '"';
|
|
etag[1] = hexChars[(crc >> 4) & 0x0F];
|
|
etag[2] = hexChars[crc & 0x0F];
|
|
etag[3] = hexChars[(crc >> 12) & 0x0F];
|
|
etag[4] = hexChars[(crc >> 8) & 0x0F];
|
|
etag[5] = hexChars[(crc >> 20) & 0x0F];
|
|
etag[6] = hexChars[(crc >> 16) & 0x0F];
|
|
etag[7] = hexChars[(crc >> 28)];
|
|
etag[8] = hexChars[(crc >> 24) & 0x0F];
|
|
etag[9] = '"';
|
|
etag[10] = '\0';
|
|
|
|
return true;
|
|
}
|