Lifetimes in Practice

// No annotation needed - one input reference, one output reference.
// The compiler infers that the output lives as long as the input.
fn first_line(text: &str) -> &str {
    text.lines().next().unwrap_or("")
}

// Annotation needed - two input references, one output.
// Which input does the output reference? The compiler can't guess.
fn longer<'a>(a: &'a str, b: &'a str) -> &'a str {
    if a.len() >= b.len() { a } else { b }
}

// 'a is a lifetime parameter - like a generic type parameter but for lifetimes
fn example<'a>(input: &'a str) -> &'a str { input }
//         ^^          ^^          ^^
//         |           |           |
//     declared    used on      used on
//     here       input         output

// Multiple lifetime parameters
fn pick<'a, 'b>(a: &'a str, b: &'b str, use_first: bool) -> &'a str {
    // Can only return 'a because the return type says 'a
    if use_first { a } else { panic!("must use first") }
}

// 'static - lives for the entire program
let s: &'static str = "I'm a string literal";
// String literals are baked into the binary - they live forever

/// A view into a parsed HTTP request - borrows the raw buffer.
struct RequestView<'a> {
    method: &'a str,
    path: &'a str,
    headers: Vec<(&'a str, &'a str)>,
}

// The struct borrows from 'raw' - it can't outlive the raw string.
fn parse_view(raw: &str) -> Option<RequestView<'_>> {
    let mut lines = raw.split("\r\n");
    let first = lines.next()?;
    let mut parts = first.split_whitespace();

    let method = parts.next()?;
    let path = parts.next()?;

    let headers: Vec<(&str, &str)> = lines
        .take_while(|l| !l.is_empty())
        .filter_map(|l| l.split_once(':'))
        .map(|(k, v)| (k.trim(), v.trim()))
        .collect();

    Some(RequestView { method, path, headers })
}

impl<'a> RequestView<'a> {
    /// Return a header value. The returned &str borrows from
    /// the same buffer as the RequestView itself.
    fn get_header(&self, name: &str) -> Option<&'a str> {
        self.headers.iter()
            .find(|(k, _)| k.eq_ignore_ascii_case(name))
            .map(|(_, v)| *v)
    }

    /// Convert to an owned Request - escape the lifetime.
    fn to_owned(&self) -> Request {
        Request {
            method: Method::from_str(self.method),
            path: self.path.to_string(),
            headers: self.headers.iter()
                .map(|(k, v)| (k.to_string(), v.to_string()))
                .collect(),
        }
    }
}

let raw = "GET / HTTP/1.1\r\nHost: localhost\r\n\r\n";
let host: &str;
{
    let view = parse_view(raw).unwrap();
    host = view.get_header("Host").unwrap();
    // 'view' is dropped here...
}
// ...but 'host' is still valid because it borrows from 'raw', not from 'view'
println!("Host: {}", host);

// These are equivalent:
fn parse_view<'a>(raw: &'a str) -> Option<RequestView<'a>> { ... }
fn parse_view(raw: &str) -> Option<RequestView<'_>> { ... }

// In impl blocks:
impl<'a> RequestView<'a> { ... }
impl RequestView<'_> { ... }  // if 'a isn't needed in method signatures

// This won't compile:
fn build_greeting(name: &str) -> &str {
    let greeting = format!("Hello, {}!", name);
    &greeting  // ERROR: 'greeting' is dropped at the end of the function
}

// Fix: return the owned String
fn build_greeting(name: &str) -> String {
    format!("Hello, {}!", name)
}

// We read bytes into a buffer, parse them, and want to route.
// But the parsed request borrows the buffer...

async fn handle(mut stream: TcpStream, router: &Router) {
    let mut buffer = [0u8; 4096];
    let n = stream.read(&mut buffer).await.unwrap();
    let raw = String::from_utf8_lossy(&buffer[..n]);

    // RequestView borrows 'raw'
    let view = parse_view(&raw).unwrap();

    // If we try to send 'view' to another task:
    // tokio::spawn(async move {
    //     router.route(&view);  // ERROR: view borrows local data
    // });

    // Fix: convert to owned before crossing boundaries
    let request = view.to_owned();
    // Now 'request' owns its data and can go anywhere
}

// Router stores handlers as closures. If a handler borrows
// from its environment, the closure's lifetime matters:

fn build_router() -> Router {
    let mut router = Router::new();

    let template = String::from("<h1>Welcome, {name}</h1>");

    // This won't compile - 'template' is dropped when build_router returns,
    // but the closure borrows it:
    // router.add(Method::Get, "/", |req| {
    //     let html = template.replace("{name}", "user");
    //     Ok(Response::html(&html))
    // });

    // Fix 1: move ownership into the closure
    router.add(Method::Get, "/", move |_req| {
        let html = template.replace("{name}", "user");
        Ok(Response::html(&html))
    });

    // Fix 2: use 'static data
    router.add(Method::Get, "/about", |_req| {
        Ok(Response::html("<h1>About</h1>")) // string literal is 'static
    });

    router
}

// A response builder that borrows from both the request and a template:
struct ResponseBuilder<'req, 'tmpl> {
    request: &'req Request,
    template: &'tmpl str,
}

impl<'req, 'tmpl> ResponseBuilder<'req, 'tmpl> {
    fn build(&self) -> Response {
        let body = self.template
            .replace("{path}", &self.request.path)
            .replace("{method}", &self.request.method.to_string());
        Response::html(&body)
    }
}

// The builder can't outlive either the request OR the template.
// Two separate lifetimes because the data comes from different sources
// and may live for different durations.

// 1. Read bytes into a buffer (owned by the connection handler)
let mut buffer = [0u8; 4096];
let n = stream.read(&mut buffer).await?;
let raw = String::from_utf8_lossy(&buffer[..n]);

// 2. Parse into owned types (allocates Strings)
// We COULD parse into borrowed &str slices, but then
// the Request couldn't outlive this function or be sent
// to a thread pool.
let request = Request::parse(&raw)?;

// 3. Route and build response (borrows the request)
let response = router.route(&request)?;
//                          ^^^^^^^^
//                          borrowed - route just reads it

// 4. Serialize and send (owned bytes)
stream.write_all(&response.to_bytes()).await?;

// Ownership boundary: parse creates owned data,
// routing borrows it, serialization creates owned bytes.