ext-web · Reference
Request lifecycle and timeouts
From socket to listener and back: what the server task does, the time limit set by request-timeout, and why every request gets 503 once the program has stopped.
One request
-
The server task reads it
The HTTP server runs on its own task (on ESP32 the
httpdtask, core 0, never calling PHP). It reads the request line, the captured headers and the whole body into memory, then posts the request to the event queue and waits. -
The reactor delivers it
When the request's turn comes, the PHP task builds a
Request, fills the superglobals, setsmax_execution_timetorequest-timeoutand runs theRequestlisteners. -
The response goes back
The returned
Responseis copied out (status, content type, headers, body), the script's ownmax_execution_timeis restored, and the server task sends the reply on the same connection.
The server task handles one request at a time: while it waits for PHP it serves nothing else. A request that
arrives while no small event slot is free (events-small, 64 by default, shared with every other event) is
answered 503 at once, and counted as a drop of Baremetal\Http\Request in Events::stats().
Status codes the server sends itself
| Situation | Status |
|---|---|
| Request header block over 2048 bytes | 431 |
Body larger than post_max_size |
413 |
| Body not received within 10 s plus 1 s per 16 KB | 408 (400 if the connection failed) |
| No free small event slot, or no memory for the request | 503 |
No answer from PHP within request-timeout + 5 s |
503 |
| The program has stopped | 503 |
The answers PHP produces (200, 404, 500, 503 with no listener) are listed in HTTP.
request-timeout
request-timeout is an SDK option (seconds, 0 to 3600, default 30), set in extra.baremetal.options:
{ "options": { "request-timeout": 10 } }
It sets two limits:
| Limit | Value | Where |
|---|---|---|
max_execution_time of a Request listener |
request-timeout |
PHP task. ini_get() reports it inside the handler; set_time_limit() in a handler lasts for that request only. |
| How long the server task waits for the answer | request-timeout + 5 s |
Server task. Then the client gets 503. |
With 0 there is no limit: a handler that never returns keeps the server task waiting for good.
The time is wall-clock time, counted from when the handler starts; sleep() counts but is not interrupted,
and a long call inside C code is not interrupted either.
When a handler goes over the limit
Going over max_execution_time is a fatal error, and in the event-driven runtime every fatal error stops
the program; the board restarts after restart-delay seconds.
- The request whose handler hit the limit gets 500: the reply is prepared before the program stops.
So does a request whose handler calls
exit(). - Requests already waiting, and every request that arrives until the restart, get 503 at once: when the program stops, the HAL marks the server as stopping and stops waiting for a reactor that no longer runs.
- WebSocket clients are not notified.
An uncaught exception is not fatal by itself: the request gets 500, then the SDK option on-error decides
(stop, the default, stops the program the same way; continue prints a warning and keeps serving).
A request that arrives late
If the server task gave up on a request (503 after request-timeout + 5 s) while PHP was still busy with
other events, PHP skips that request when it finally reaches it: no listener runs for it.
Related
- HTTP PHP API
- Errors and limits Reference
- esp32-web-hal HAL