Responses

use axum::{
    Json, Router,
    http::{HeaderName, StatusCode, header},
    response::{AppendHeaders, Html, IntoResponse, NoContent, Redirect},
    routing::{delete, get, post},
};
use serde::Serialize;

#[derive(Serialize)]
struct Book {
    isbn: &'static str,
    title: &'static str,
}

// 201 Created + Location header + JSON body
async fn create_book() -> impl IntoResponse {
    (
        StatusCode::CREATED,
        [(header::LOCATION, "/api/v1/books/9780441013593")],
        Json(Book { isbn: "9780441013593", title: "Dune" }),
    )
}

// several headers, one of them repeated
async fn cover() -> impl IntoResponse {
    (
        [(header::CONTENT_TYPE, "image/svg+xml"), (header::CACHE_CONTROL, "public, max-age=86400")],
        AppendHeaders([
            (HeaderName::from_static("x-shelf"), "science-fiction"),
            (HeaderName::from_static("x-shelf"), "classics"),
        ]),
        "<svg xmlns=\"http://www.w3.org/2000/svg\"/>",
    )
}

async fn remove_book() -> NoContent {
    NoContent
}

async fn old_catalogue() -> Redirect {
    Redirect::permanent("/catalogue")
}

async fn catalogue() -> Html<&'static str> {
    Html("<h1>Catalogue</h1>")
}

fn app() -> Router {
    Router::new()
        .route("/api/v1/books", post(create_book))
        .route("/api/v1/books/{isbn}", delete(remove_book))
        .route("/covers/{isbn}", get(cover))
        .route("/books.html", get(old_catalogue))
        .route("/catalogue", get(catalogue))
}

#[tokio::main]
async fn main() {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app()).await.unwrap();
}

$ curl -si -X POST localhost:3000/api/v1/books
HTTP/1.1 201 Created
content-type: application/json
location: /api/v1/books/9780441013593
content-length: 39

{"isbn":"9780441013593","title":"Dune"}
$ curl -sI localhost:3000/covers/1 | grep -i x-shelf
x-shelf: science-fiction
x-shelf: classics

use axum::{
    Json, Router,
    http::{StatusCode, header},
    response::{IntoResponse, Response},
    routing::get,
};
use serde::Serialize;

#[derive(Serialize)]
struct BookPage {
    items: Vec<String>,
    page: u32,
    total_pages: u32,
}

impl IntoResponse for BookPage {
    fn into_response(self) -> Response {
        let link = format!("</api/v1/books?page={}>; rel=\"next\"", self.page + 1);
        let has_next = self.page < self.total_pages;
        let mut response = Json(self).into_response();
        if has_next {
            response.headers_mut().insert(header::LINK, link.parse().expect("valid header value"));
        }
        response
    }
}

async fn list() -> BookPage {
    BookPage { items: vec!["Dune".into()], page: 1, total_pages: 3 }
}

async fn teapot() -> Response {
    // building a Response manually is always possible
    Response::builder().status(StatusCode::IM_A_TEAPOT).body("no coffee here".into()).unwrap()
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/api/v1/books", get(list)).route("/coffee", get(teapot));
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{
    Json, Router,
    extract::Path,
    http::StatusCode,
    response::{Html, IntoResponse, Redirect, Response},
    routing::get,
};
use axum_extra::either::Either;

// 1. Result: success and error types both implement IntoResponse
async fn by_result(Path(id): Path<u32>) -> Result<Json<u32>, StatusCode> {
    if id == 0 { Err(StatusCode::NOT_FOUND) } else { Ok(Json(id)) }
}

// 2. Response: convert each branch with .into_response()
async fn by_response(Path(id): Path<u32>) -> Response {
    match id {
        0 => Redirect::to("/books").into_response(),
        1 => Html("<p>Dune</p>").into_response(),
        _ => StatusCode::NOT_FOUND.into_response(),
    }
}

// 3. Either: two (or up to eight) concrete types, no conversion calls
async fn by_either(Path(id): Path<u32>) -> Either<Html<&'static str>, Redirect> {
    if id == 1 { Either::E1(Html("<p>Dune</p>")) } else { Either::E2(Redirect::to("/books")) }
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/a/{id}", get(by_result))
        .route("/b/{id}", get(by_response))
        .route("/c/{id}", get(by_either));
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{
    Json, Router,
    extract::Path,
    http::StatusCode,
    response::{ErrorResponse, Result},
    routing::get,
};

fn parse_isbn(text: &str) -> Result<u64, (StatusCode, &'static str)> {
    if text.len() == 13 { text.parse().map_err(|_| (StatusCode::BAD_REQUEST, "digits only")) } else { Err((StatusCode::BAD_REQUEST, "13 digits")) }
}

#[allow(clippy::result_large_err)] // ErrorResponse holds a whole Response (about 128 bytes)
async fn show(Path(isbn): Path<String>) -> Result<Json<u64>> {
    let isbn = parse_isbn(&isbn)?; // (StatusCode, &str) -> ErrorResponse
    if isbn % 2 == 0 {
        return Err(ErrorResponse::from(StatusCode::NOT_FOUND));
    }
    Ok(Json(isbn))
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/books/{isbn}", get(show));
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use std::convert::Infallible;
use std::time::Duration;

use axum::{Router, body::Body, http::header, response::IntoResponse, routing::get};
use futures::StreamExt;
use tokio_stream::wrappers::IntervalStream;

async fn export_catalogue() -> impl IntoResponse {
    let titles = ["Dune", "The Dispossessed", "Kindred"];
    // one CSV line every 100 ms -- imagine rows streamed from the database
    let rows = IntervalStream::new(tokio::time::interval(Duration::from_millis(100)))
        .zip(futures::stream::iter(titles))
        .map(|(_, title)| Ok::<_, Infallible>(format!("{title}\n")));
    ([(header::CONTENT_TYPE, "text/csv")], Body::from_stream(rows))
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/exports/titles.csv", get(export_catalogue));
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use std::hash::{DefaultHasher, Hash, Hasher};

use axum::{
    Router,
    http::{HeaderMap, StatusCode, header},
    response::{IntoResponse, Response},
    routing::get,
};

fn etag_for(body: &str) -> String {
    let mut hasher = DefaultHasher::new();
    body.hash(&mut hasher);
    format!("\"{:016x}\"", hasher.finish()) // strong validator: quoted, no W/ prefix
}

async fn book(headers: HeaderMap) -> Response {
    let body = r#"{"isbn":"9780441013593","title":"Dune","year":1965}"#;
    let etag = etag_for(body);

    let matches = headers
        .get(header::IF_NONE_MATCH)
        .and_then(|v| v.to_str().ok())
        .is_some_and(|v| v == "*" || v.split(',').any(|t| t.trim().trim_start_matches("W/") == etag));
    if matches {
        return (StatusCode::NOT_MODIFIED, [(header::ETAG, etag)]).into_response();
    }
    ([(header::ETAG, etag.as_str()), (header::CONTENT_TYPE, "application/json")], body).into_response()
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/api/v1/books/9780441013593", get(book));
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

$ curl -si localhost:3000/api/v1/books/9780441013593 | grep etag
etag: "a799a717c5539914"
$ curl -si -H 'if-none-match: "a799a717c5539914"' localhost:3000/api/v1/books/9780441013593 | head -1
HTTP/1.1 304 Not Modified