HTTP server - URI handler return value

[herhor67]

Hello,
I want to ask, what should be the return value of URI handlers?
Or rather, which errors from which functions should be forwarded, and what can be safely ignored?

Looking at the docs, I can see that only httpd_req_recv has this requirement:

If an error is returned, the URI handler must further return an error. This will ensure that the erroneous socket is closed and cleaned up by the web server.

However, in the examples the error is returned quite arbitrarily: ESP_ERR_NO_MEM, ESP_ERR_INVALID_ARG, ESP_FAIL, ESP_ERR_NOT_FOUND, possibly others.
Functions for sending data like httpd_resp_send are never checked for errors...

How does the returned value influence the working of the server?

[MicroController]

How does the returned value influence the working of the server?

Very simple: ESP_OK indicates to the server that everything is ok with the connection/socket and it may be kept open for further requests ("keep-alive"), any other return code causes the server to close the socket.
The latter will be necessary if the HTTP part of the request cannot be parsed (mostly done by the HTTP server already), or if sending the response failed or only partially succeeded, or if the client failed to present a valid HTTP request, like sending less data than it said it would, detected via e.g. a read timeout. In these cases, the state of the HTTP connection may be inconsistent and unlikely to be recoverable. This concerns only the TCP/IP and HTTP layers of the protocol.
On the other hand, if, for example, a requested file cannot be found, you can send a 404 error response and return ESP_OK, because the HTTP connection itself is still intact (assuming the error response was successfully sent.)

[herhor67]

So it is fine to check the send functions too? Why are they not tested in examples, for brevity?

Btw, if I understand correctly, the Connection: keep-alive is the same as keep-alive packets?
If I want to keep connections alive as long as there is something to transfer (multipart) but not after the transfer, should I just return errors in any case? Or is this configurable somehow?
I'm honestly confused

[MicroController]

So it is fine to check the send functions too? Why are they not tested in examples, for brevity?

Not 100% sure, but, since sending happens 'through' the HTTP server, I imagine the server will detect (some) transmission errors and close the socket itself.

Btw, if I understand correctly, the Connection: keep-alive is the same as keep-alive packets?

Not necessarily. Originally, HTTP required that only one request would be sent per connection. Closing the connection from the server side signalled the end of the response data. For better efficiency, persistent connections were introduced with HTTP/1.1 which allow multiple requests to be sent and responded to over a single connection. The client advertises its support/wish for a persistent connection via the Connection: keep-alive header, and, in the most basic implementation, the server just 'reacts' to this by simply not closing the connection after each request.

If I want to keep connections alive as long as there is something to transfer (multipart) but not after the transfer, should I just return errors in any case? Or is this configurable somehow?

Normally it would be the client which closes the connection when it has no more use for it. The HTTP server can also automatically 'purge' unused connections.
You could also use httpd_req_to_sockfd() and httpd_sess_trigger_close() to 'manually' close the socket from the server.
The same may work by returning an error from the URI handler, but I'm not sure about how the server will handle any yet unsent response data in that case. Might have to also enable SO_LINGER in the server config.

[herhor67]

My use-case is that the webserver receives a "program" (list of "commands") to execute, which involves GPIO, I2C, SPI and other peripherals. That's why I can only handle 1 request at a time, and why the HTTPD config has only 1 socket allowed.
However, as soon as the request is completed, I want to make it available for other requesters, that's why I thought about closing the socket. But maybe LRU is the way to go. Or would you suggest some other way?