ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
web_server_base.h
Go to the documentation of this file.
1#pragma once
3#if defined(USE_NETWORK) && !defined(USE_ZEPHYR) && !defined(USE_HOST)
4#include <vector>
5
7#include "origin.h"
8
9#if USE_ESP32
10#include "esphome/core/hal.h"
12#else
13#include <ESPAsyncWebServer.h>
14#endif
15
16#if USE_ESP32
17using PlatformString = std::string;
18#elif USE_ARDUINO
19using PlatformString = String;
20#endif
21
23
24class WebServerBase;
25extern WebServerBase *global_web_server_base; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
26
27namespace internal {
28
29class MiddlewareHandler : public AsyncWebHandler {
30 public:
31 MiddlewareHandler(AsyncWebHandler *next) : next_(next) {}
32
33 bool canHandle(AsyncWebServerRequest *request) const override { return next_->canHandle(request); }
34 void handleRequest(AsyncWebServerRequest *request) override { next_->handleRequest(request); }
35 void handleUpload(AsyncWebServerRequest *request, const PlatformString &filename, size_t index, uint8_t *data,
36 size_t len, bool final) override {
37 next_->handleUpload(request, filename, index, data, len, final);
38 }
39 void handleBody(AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index, size_t total) override {
40 next_->handleBody(request, data, len, index, total);
41 }
42 bool isRequestHandlerTrivial() const override { return next_->isRequestHandlerTrivial(); }
43
44 protected:
45 AsyncWebHandler *next_;
46};
47
48#ifdef USE_WEBSERVER_AUTH
49// All fields point to string literals in generated code; nothing is copied.
51#if USE_ESP32 || defined(USE_WEBSERVER_AUTH_DIGEST)
52 const char *username{nullptr};
53 const char *password{nullptr};
54 bool is_set() const { return username != nullptr; }
55#else
56 // base64("username:password"), precomputed at codegen time. Used by every non-ESP32 basic
57 // auth build. The ESP8266 and RP2040 core libb64 wraps base64 output every 72 chars, so
58 // letting the library encode and compare fails for long credentials; instead the header
59 // payload is compared against this hash.
60 const char *basic_auth_hash{nullptr};
61 bool is_set() const { return basic_auth_hash != nullptr; }
62#endif
63};
64#endif
65
66// Wraps every handler added through WebServerBase::add_handler(): rejects cross-origin browser
67// requests the origin policy does not allow, then checks credentials when auth is configured.
68// It holds only the next handler; the policy lives in global_web_server_base.
70 public:
72
73 void handleRequest(AsyncWebServerRequest *request) override;
74 void handleUpload(AsyncWebServerRequest *request, const PlatformString &filename, size_t index, uint8_t *data,
75 size_t len, bool final) override;
76 void handleBody(AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index, size_t total) override;
77
78 protected:
79 // Upload and body chunks arrive before handleRequest(), which sends the 403 for a rejected origin.
80 bool check_chunk_(AsyncWebServerRequest *request, size_t index);
81 bool check_origin_(AsyncWebServerRequest *request);
82 // Always true when auth is not compiled in.
83 bool check_auth_(AsyncWebServerRequest *request);
84
85 // Request whose first chunk passed the checks; see check_chunk_().
86 const AsyncWebServerRequest *passed_{nullptr};
87};
88
89} // namespace internal
90
91class WebServerBase final {
92 public:
93 // The AsyncWebServer is created once and intentionally never deleted: on Arduino
94 // platforms ESPAsyncWebServer owns its registered handlers, so destroying it would
95 // also destroy live components (e.g. the captive portal) out from under us.
96 // init()/deinit() refcount users and start/stop the listener; handlers are
97 // registered once at creation and survive listener restarts.
98 void init() {
99 this->initialized_++;
100 if (this->server_ != nullptr) {
101 if (this->initialized_ == 1) {
102 // Restart the listener after a previous deinit()
103 this->server_->begin();
104 }
105 return;
106 }
107 this->server_ = new AsyncWebServer(this->port_);
108 // All content is controlled and created by user - so allowing all origins is fine here.
109 // NOTE: Currently 1 header. If more are added, update in __init__.py:
110 // cg.add_define("WEB_SERVER_DEFAULT_HEADERS_COUNT", 1)
111 DefaultHeaders::Instance().addHeader(ESPHOME_F("Access-Control-Allow-Origin"), ESPHOME_F("*"));
112 this->server_->begin();
113
114 for (auto *handler : this->handlers_)
115 this->server_->addHandler(handler);
116 }
117 void deinit() {
118 if (this->initialized_ == 0)
119 return; // unbalanced deinit()
120 this->initialized_--;
121 if (this->initialized_ == 0) {
122 this->server_->end();
123 }
124 }
125 AsyncWebServer *get_server() const { return this->server_; }
126
127#ifdef USE_WEBSERVER_AUTH
128#if USE_ESP32 || defined(USE_WEBSERVER_AUTH_DIGEST)
129 void set_auth_username(const char *auth_username) { credentials_.username = auth_username; }
130 void set_auth_password(const char *auth_password) { credentials_.password = auth_password; }
131#else
132 void set_auth_basic_hash(const char *hash) { credentials_.basic_auth_hash = hash; }
133#endif
134#endif
135#ifdef USE_WEBSERVER_ALLOWED_ORIGINS
143 void set_allowed_origins(const char *const *origins) { this->allowed_origins_ = origins; }
144#endif
145
146 void add_handler(AsyncWebHandler *handler);
156 void add_handler_without_auth(AsyncWebHandler *handler);
157
158 void set_port(uint16_t port) { port_ = port; }
159 uint16_t get_port() const { return port_; }
160
161 protected:
162 uint8_t initialized_{0};
163 uint16_t port_{80}; // Keep in sync with DEFAULT_PORT in web_server/__init__.py
164 AsyncWebServer *server_{nullptr};
165 std::vector<AsyncWebHandler *> handlers_;
166#ifdef USE_WEBSERVER_AUTH
168#endif
169#ifdef USE_WEBSERVER_ALLOWED_ORIGINS
170 const char *const *allowed_origins_{nullptr};
171#endif
172
174};
175
176} // namespace esphome::web_server_base
177#endif // USE_NETWORK && !USE_ZEPHYR
void add_handler_without_auth(AsyncWebHandler *handler)
WARNING: Registers a handler that bypasses the auth and origin middleware.
void set_allowed_origins(const char *const *origins)
Set the extra origins browsers may make cross-origin requests from, for every handler added through a...
void set_auth_username(const char *auth_username)
void set_auth_password(const char *auth_password)
void add_handler(AsyncWebHandler *handler)
std::vector< AsyncWebHandler * > handlers_
void handleUpload(AsyncWebServerRequest *request, const PlatformString &filename, size_t index, uint8_t *data, size_t len, bool final) override
bool check_chunk_(AsyncWebServerRequest *request, size_t index)
void handleBody(AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index, size_t total) override
void handleRequest(AsyncWebServerRequest *request) override
bool canHandle(AsyncWebServerRequest *request) const override
void handleUpload(AsyncWebServerRequest *request, const PlatformString &filename, size_t index, uint8_t *data, size_t len, bool final) override
void handleRequest(AsyncWebServerRequest *request) override
void handleBody(AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index, size_t total) override
NameCopy * next
WebServerBase * global_web_server_base
const void size_t len
Definition hal.h:68
std::string PlatformString