picoserve

picoserve is an async no_std HTTP server designed for bare-metal environments. It is heavily inspired by axum and is optimized for embedded runtimes like embassy, specifically targeting hardware like the Raspberry Pi Pico W.

Key Features

• No heap usage: Designed for memory-constrained environments.
• Axum-like Handlers: Handler functions are async functions that accept zero or more extractors as arguments and return a type implementing IntoResponse.
• Data Parsing: Supports Query and Form parsing using serde.
• Response Types: Supports JSON responses, Server-Sent Events (SSE), and Web Sockets.
• Automatic HEAD handling: The HEAD method is automatically handled.

Important Limitations & Security

• Breaking Changes: The project is in 0.*.* versioning; API changes may occur.
• Input Limits: URL-Encoded strings (in Query and Form parsing) have a maximum length of 1024.
• Security Warning: The server has not undergone extensive stress-testing. It is advised to place it behind a proxy (like nginx) rather than exposing it directly to the internet.
• Serialization Consistency: For large payloads, certain serialization methods (like DebugValue or JSON) might be called multiple times. You MUST ensure that the output of serialization remains identical during repeated calls with the same value.
• Content-Length: The framework does not verify that the actual body length matches the value provided in the Content-Length header.

For standard asynchronous environments using the tokio runtime, picoserve offers a wide range of usage patterns:

Routing and Request Handling

• Basic Routing: Setting up a Router (hello_world) or running on a single thread (hello_world_single_thread).
• Advanced Routing: Nesting Routers (nested_router), runtime selection of routers (conditional_routing), and providing a fallback PathRouterService (routing_fallback).
• Data Extraction: Extracting data from path segments (path_parameters), URL search parameters (query), and implementing custom data extraction from requests (custom_extractor).
• Methods and Files: Handling GET/POST methods and serving files (form).

State Management

• Stateful Applications: General stateful apps (state), state derived from the connection (state_local), and using multiple distinct states within a single Router to support separated nested applications (state_multiple).
• State-Aware Responses: Returning responses that utilize the application State when writing to the socket (response_using_state).

Advanced Features and Protocols

• Streaming and Long-lived Connections: Using Transfer-Encoding: chunked (chunked_response), Server-Sent Events (server_sent_events), and WebSockets (web_sockets).
• Middleware and Services: Implementing middleware like request-duration logging (layers) or custom MethodHandlerService for reporting request info (request_info).
• Server Management: Graceful shutdown of the server, including specific handling for SSE (graceful_shutdown_server_sent_events) and WebSocket (graceful_shutdown_web_sockets) connections.
• Static Content: Serving static assets like HTML and CSS (static_content).
• Configuration: Extending read timeouts to support large requests (huge_requests).

A Layer is a middleware component used to intercept and transform the request-response lifecycle. Layers can be used to:

• Inspect requests before they reach the inner handler.
• Transform state: Pass a different NextState to the inner handler than the one provided to the layer.
• Transform path parameters: Pass different NextPathParameters to the inner handler.
• Short-circuit: Send a response immediately instead of passing the request to the inner handler.
• Transform responses: Modify the response returned by the inner handler.

To modify a response, you must create a struct that implements the ResponseWriter trait, wrap the original response_writer, and pass your wrapper to the next.run() method.

Implementation Pattern

To implement a layer, you must define the associated types NextState and NextPathParameters and implement the call_layer method.

// Conceptual implementation of a Layer
impl Layer<State, PathParameters> for MyMiddleware {
    type NextState = NewState;
    type NextPathParameters = NewPathParameters;

    async fn call_layer<
        'a,
        R: Read + 'a,
        NextLayer: Next<'a, R, Self::NextState, Self::NextPathParameters>,
        W: ResponseWriter<Error = R::Error>,
    >( 
        &self, 
        next: NextLayer, 
        state: &State, 
        path_parameters: PathParameters, 
        request_parts: RequestParts<'_>, 
        response_writer: W 
    ) -> Result<ResponseSent, W::Error> {
        // 1. Inspect or modify request_parts
        // 2. Call next.run() with modified state/params or a wrapped response_writer
        next.run(state, path_parameters, response_writer).await
    }
}

While picoserve is designed for no_std environments, you can use it in a std environment with tokio for testing or development. This involves binding a TcpListener, creating a Router, and using picoserve::Server::new_tokio to serve the stream.

Note that picoserve::Server::new_tokio requires a buffer for the server to operate, which in this example is a fixed-size array [0; 2048].

use picoserve::routing::get;

#[tokio::main(flavor = "current_thread")]
async fn main() -> anyhow::Result<()> {
    let port = 8000;

    let app = 
        std::rc::Rc::new(picoserve::Router::new().route("/", get(|| async { "Hello World" })));

    let socket = tokio::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, port)).await?;

    println!("http://localhost:{port}/");

    tokio::task::LocalSet::new()
        .run_until(async {
            loop {
                let (stream, remote_address) = socket.accept().await?;

                println!("Connection from {remote_address}");

                let app = app.clone();

                tokio::task::spawn_local(async move {
                    static CONFIG: picoserve::Config = 
                        picoserve::Config::const_default().keep_connection_alive();

                    match picoserve::Server::new_tokio(&app, &CONFIG, &mut [0; 2048])
                        .serve(stream)
                        .await
                    {
                        Ok(picoserve::DisconnectionInfo {
                            handled_requests_count,
                            ..
                        }) => {
                            println!("{handled_requests_count} requests handled from {remote_address}")
                        }
                        Err(err) => println!("{err:?}"),
                    }
                });
            }
        })
        .await
}

Use the Config struct to define server behavior, specifically timeouts and connection persistence. You can create a configuration with custom timeouts or use the default settings.

Key configuration options:

• timeouts: A Timeouts struct defining durations for start_read_request, persistent_start_read_request, read_request, and write operations.
• connection: A KeepAlive enum determining if the connection stays open after a response (KeepAlive::KeepAlive) or closes (KeepAlive::Close).

By default, picoserve closes the connection after each response. Use .keep_connection_alive() to enable persistent connections.

use picoserve::{Config, Timeouts, KeepAlive};
use time::Duration;

// Custom configuration
let config = Config::new(Timeouts {
    start_read_request: Duration::from_secs(10),
    persistent_start_read_request: Duration::from_secs(2),
    read_request: Duration::from_secs(5),
    write: Duration::from_secs(2),
}).keep_connection_alive();

// Or use defaults
let default_config = Config::default();