Struct HttpServer

pub struct HttpServer { /* private fields */ }

Available on crate feature esp only.

When developing for embedded systems, you cannot, as of now, use asynchronous TcpListeners and thus one of the most popular HttpServers. But this does not immediately mean that you have to miss out on all of the features provided by axum. The solution is to do everything with a synchronous TcpListener.

Additional info for use in embedded development

stack overflow in pthread

Because this HttpServer uses async functions and the spawn function from tokio, you may get this error:

***ERROR*** A stack overflow in task pthread has been detected.

Fortunately, all you have to do is adjust the following value in your sdkconfig.defaults which should have been generated when you used this ESP32 template:

CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT=10000    # 10000 has worked for my project so far
                                                # but you can probably set it far lower

Reducing binary size

When using this library and other libraries, you may encounter another problem: you run out of memory. To fix this, you need to change some compiler settings. For that, I would suggest to have a look at this and this guide.

Known Bug

When connecting to this HttpServer, it can happen that the connection just blocks and never processes the request. To reduce the probability of this happing you can increase the following value in your sdkconfig.defaults which should have been generated when you used this ESP32 template:

CONFIG_FREERTOS_HZ=1000

How to use this HttpServer

First, you will need a Router. You can use the macros from this library:

// In this example, we will create a simple router with one route
router! {
    router {
        get_list, get;  // The route will be called get_list and will only accept get requests.
                        // For more details on the implementation of this route handler, see
                        // this macro documentation.
    }
}

After creating a router, we can bind and serve our HttpServer:

let router = router(); // The macro above has only generated a function.
                       // Only after calling it, we can get our router.

let http_server = HttpServer::bind("0.0.0.0:80");
http_server.serve(router).unwrap();

Implementations

impl HttpServer

pub fn bind<A: ToSocketAddrs>( addr: A, name: Option<&str>, refresh_rate: Option<Duration>, ) -> Self

Create and set an address for a new HttpServer.

Default values

Identifier	Value	Description
name	“HttpServer”	The name of this HttpServer, which gets used in log messages.
refresh_rate	10ms	The time this HttpServer sleeps between two accept() calls.

pub async fn shutdown(&mut self)

This method will close the internal TCPListener and all of its connections by killing the task they are running on.
If this HttpServer was already offline, this method will do nothing.

pub fn serve(&mut self, router: Router) -> Result<()>

Serve the given HttpServer with the given Router.
This function is non-blocking.

Errors

An error is returned if the TcpListener failed to bind to the given address.