Skip to main content

hearth_api/
http.rs

1//! Enough HTTP/1.1 to be an honest gateway, and no more.
2//!
3//! Same reasoning as everywhere else in this workspace: `probe.rs` writes a raw
4//! GET because a health check is a status line; `hearth-pull` drives `curl`
5//! because a registry download needs TLS and resume, which is a real library's
6//! job. This is the third case — a server on localhost speaking to clients that
7//! already exist, where the whole surface is *read a request, write a response,
8//! and relay bytes*. A framework would bring an async runtime and a dependency
9//! tree to do what four hundred lines of std does, and the parsing is the only
10//! part with a rule in it, so it lives here, pure and tested.
11//!
12//! What this deliberately does NOT do: TLS (put it behind a proxy, and the
13//! default bind is loopback so there is nothing to expose), HTTP/2, or
14//! keep-alive pipelining. A model gateway handles a few requests per second
15//! that each take seconds; connection setup is not the cost.
16
17use std::collections::HashMap;
18use std::io::{BufRead, BufReader, Read, Write};
19use std::net::{TcpListener, TcpStream};
20use std::time::Duration;
21
22/// A parsed request. Headers are lowercased on the way in, because HTTP header
23/// names are case-insensitive and half of the clients disagree about casing.
24#[derive(Debug, Clone, PartialEq, Eq, Default)]
25pub struct Request {
26    pub method: String,
27    pub path: String,
28    pub headers: HashMap<String, String>,
29    pub body: String,
30}
31
32impl Request {
33    pub fn header(&self, name: &str) -> Option<&str> {
34        self.headers
35            .get(&name.to_ascii_lowercase())
36            .map(|s| s.as_str())
37    }
38
39    /// Does the body ask for a streamed response? Streaming changes how the
40    /// proxy relays: a buffered read would hold every token until the model
41    /// finished, turning a live stream into a long pause and a wall of text.
42    pub fn wants_stream(&self) -> bool {
43        serde_json::from_str::<serde_json::Value>(&self.body)
44            .ok()
45            .and_then(|v| v.get("stream").and_then(|s| s.as_bool()))
46            .unwrap_or(false)
47    }
48}
49
50/// Parse a request line. Pure — `GET /v1/models HTTP/1.1`.
51pub fn parse_request_line(line: &str) -> Option<(String, String)> {
52    let mut parts = line.split_whitespace();
53    let method = parts.next()?.to_ascii_uppercase();
54    let path = parts.next()?.to_string();
55    let version = parts.next()?;
56    if !version.starts_with("HTTP/1.") {
57        return None;
58    }
59    Some((method, path))
60}
61
62/// Parse one header line into a lowercased name and a trimmed value.
63pub fn parse_header(line: &str) -> Option<(String, String)> {
64    let (name, value) = line.split_once(':')?;
65    let name = name.trim().to_ascii_lowercase();
66    if name.is_empty() {
67        return None;
68    }
69    Some((name, value.trim().to_string()))
70}
71
72/// Serialize a response we generated ourselves.
73pub fn render_response(status: u16, body: &str, retry_after: Option<u32>) -> String {
74    let reason = match status {
75        200 => "OK",
76        400 => "Bad Request",
77        404 => "Not Found",
78        409 => "Conflict",
79        500 => "Internal Server Error",
80        502 => "Bad Gateway",
81        503 => "Service Unavailable",
82        _ => "Status",
83    };
84    let mut head = format!(
85        "HTTP/1.1 {status} {reason}\r\n\
86         content-type: application/json\r\n\
87         content-length: {}\r\n\
88         connection: close\r\n",
89        body.len()
90    );
91    if let Some(secs) = retry_after {
92        // Only ever set when coming back later could actually work. A
93        // Retry-After on a permanent condition invites the retry storm the
94        // status code was chosen to prevent.
95        head.push_str(&format!("retry-after: {secs}\r\n"));
96    }
97    head.push_str("\r\n");
98    head.push_str(body);
99    head
100}
101
102/// Read one request off a stream.
103///
104/// `content-length` is honoured exactly. Reading "until it stops" would work
105/// right up until a client keeps the connection open, and then the gateway
106/// blocks forever on a request it already has in full.
107pub fn read_request(stream: &TcpStream) -> Result<Request, String> {
108    let mut reader = BufReader::new(stream);
109    let mut line = String::new();
110    reader
111        .read_line(&mut line)
112        .map_err(|e| format!("reading request line: {e}"))?;
113    let (method, path) =
114        parse_request_line(line.trim_end()).ok_or_else(|| format!("bad request line: {line:?}"))?;
115
116    let mut headers = HashMap::new();
117    loop {
118        let mut h = String::new();
119        let n = reader
120            .read_line(&mut h)
121            .map_err(|e| format!("reading headers: {e}"))?;
122        if n == 0 || h.trim().is_empty() {
123            break;
124        }
125        if let Some((k, v)) = parse_header(h.trim_end()) {
126            headers.insert(k, v);
127        }
128        if headers.len() > 100 {
129            return Err("too many headers".into());
130        }
131    }
132
133    let len: usize = headers
134        .get("content-length")
135        .and_then(|v| v.parse().ok())
136        .unwrap_or(0);
137    let mut body = vec![0u8; len];
138    if len > 0 {
139        reader
140            .read_exact(&mut body)
141            .map_err(|e| format!("reading body ({len} bytes): {e}"))?;
142    }
143
144    Ok(Request {
145        method,
146        path,
147        headers,
148        body: String::from_utf8_lossy(&body).to_string(),
149    })
150}
151
152/// Forward a request to a model's endpoint and relay the response back.
153///
154/// Relayed in chunks rather than buffered, so a streamed completion reaches the
155/// caller token by token. Buffering here would hold every token until the model
156/// finished — turning a live stream into a long silence followed by a wall of
157/// text, which is the single most noticeable way a gateway ruins a chat UI.
158pub fn proxy(
159    upstream: &str,
160    req: &Request,
161    client: &mut TcpStream,
162    connect_timeout: Duration,
163) -> Result<(), String> {
164    let addr = upstream
165        .parse()
166        .map_err(|e| format!("bad upstream address {upstream}: {e}"))?;
167    let mut up = TcpStream::connect_timeout(&addr, connect_timeout)
168        .map_err(|e| format!("could not reach {upstream}: {e}"))?;
169    // No read timeout on the upstream: generation legitimately takes minutes,
170    // and a deadline here would cut off a working response — the same "nothing
171    // fails on a clock" rule the supervisor follows.
172    up.set_write_timeout(Some(connect_timeout)).ok();
173
174    let mut head = format!(
175        "{} {} HTTP/1.1\r\nhost: {}\r\ncontent-length: {}\r\nconnection: close\r\n",
176        req.method,
177        req.path,
178        upstream,
179        req.body.len()
180    );
181    for (k, v) in &req.headers {
182        // Hop-by-hop headers describe OUR connection to the client, not ours
183        // to the model. Forwarding them makes the upstream misread the
184        // conversation it is in.
185        if matches!(
186            k.as_str(),
187            "host" | "content-length" | "connection" | "keep-alive" | "transfer-encoding"
188        ) {
189            continue;
190        }
191        head.push_str(&format!("{k}: {v}\r\n"));
192    }
193    head.push_str("\r\n");
194
195    up.write_all(head.as_bytes())
196        .and_then(|_| up.write_all(req.body.as_bytes()))
197        .and_then(|_| up.flush())
198        .map_err(|e| format!("writing to {upstream}: {e}"))?;
199
200    let mut buf = [0u8; 16 * 1024];
201    loop {
202        match up.read(&mut buf) {
203            Ok(0) => break,
204            Ok(n) => {
205                if client.write_all(&buf[..n]).is_err() {
206                    // The caller hung up mid-stream. Normal — someone closed a
207                    // tab. Not worth an error.
208                    break;
209                }
210                // Flush per chunk or the relay buffers the stream right back
211                // up again and undoes the point of relaying it.
212                let _ = client.flush();
213            }
214            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
215            Err(e) => return Err(format!("reading from {upstream}: {e}")),
216        }
217    }
218    Ok(())
219}
220
221/// The listening socket.
222pub struct Server {
223    listener: TcpListener,
224}
225
226impl Server {
227    /// Bind. Loopback by default at the call site — a gateway on 0.0.0.0 hands
228    /// anyone on the network an unauthenticated GPU.
229    pub fn bind(addr: &str) -> Result<Server, String> {
230        let listener =
231            TcpListener::bind(addr).map_err(|e| format!("could not bind {addr}: {e}"))?;
232        Ok(Server { listener })
233    }
234
235    pub fn local_addr(&self) -> String {
236        self.listener
237            .local_addr()
238            .map(|a| a.to_string())
239            .unwrap_or_default()
240    }
241
242    /// Accept one connection, non-blocking-ish via a poll timeout, so the
243    /// caller's supervise loop keeps ticking instead of being held here.
244    pub fn incoming(&self) -> impl Iterator<Item = std::io::Result<TcpStream>> + '_ {
245        self.listener.incoming()
246    }
247}
248
249#[cfg(test)]
250mod tests {
251    use super::*;
252
253    #[test]
254    fn a_request_line_parses() {
255        assert_eq!(
256            parse_request_line("POST /v1/chat/completions HTTP/1.1"),
257            Some(("POST".into(), "/v1/chat/completions".into()))
258        );
259        assert_eq!(
260            parse_request_line("get /health HTTP/1.0"),
261            Some(("GET".into(), "/health".into())),
262            "the method is case-insensitive on the wire"
263        );
264    }
265
266    #[test]
267    fn garbage_is_not_a_request_line() {
268        // Something that is not HTTP arriving on the port — a health checker
269        // speaking TLS to a plaintext socket does this.
270        assert_eq!(parse_request_line("SSH-2.0-OpenSSH_9.6"), None);
271        assert_eq!(parse_request_line(""), None);
272        assert_eq!(parse_request_line("GET /only-two-parts"), None);
273    }
274
275    #[test]
276    fn header_names_are_lowercased_because_clients_disagree_about_casing() {
277        assert_eq!(
278            parse_header("Content-Type: application/json"),
279            Some(("content-type".into(), "application/json".into()))
280        );
281        assert_eq!(
282            parse_header("AUTHORIZATION:   Bearer sk-x  "),
283            Some(("authorization".into(), "Bearer sk-x".into()))
284        );
285        assert_eq!(parse_header("no colon here"), None);
286        assert_eq!(parse_header(": empty name"), None);
287    }
288
289    #[test]
290    fn a_header_value_may_contain_colons() {
291        // `host: 127.0.0.1:8090` splits on the FIRST colon or the port is lost.
292        assert_eq!(
293            parse_header("host: 127.0.0.1:8090"),
294            Some(("host".into(), "127.0.0.1:8090".into()))
295        );
296    }
297
298    #[test]
299    fn a_rendered_response_has_a_content_length_that_matches() {
300        // A wrong content-length hangs the client waiting for bytes that are
301        // never coming, which reads as "hearth is slow".
302        let body = r#"{"status":"ok"}"#;
303        let out = render_response(200, body, None);
304        assert!(out.starts_with("HTTP/1.1 200 OK\r\n"));
305        assert!(out.contains(&format!("content-length: {}", body.len())));
306        assert!(out.ends_with(body));
307        assert!(!out.contains("retry-after"));
308    }
309
310    #[test]
311    fn retry_after_appears_only_when_it_was_asked_for() {
312        // On a permanent condition it would invite exactly the retry storm the
313        // status code was chosen to prevent.
314        assert!(render_response(503, "{}", Some(5)).contains("retry-after: 5"));
315        assert!(!render_response(409, "{}", None).contains("retry-after"));
316    }
317
318    #[test]
319    fn every_status_the_gateway_emits_has_a_reason_phrase() {
320        for s in [200u16, 400, 404, 409, 502, 503] {
321            let out = render_response(s, "{}", None);
322            let line = out.lines().next().unwrap();
323            assert!(
324                !line.ends_with("Status"),
325                "status {s} fell through to the generic phrase: {line}"
326            );
327        }
328    }
329
330    #[test]
331    fn a_streaming_request_is_recognised_from_its_body() {
332        let mut r = Request {
333            body: r#"{"model":"m","stream":true}"#.into(),
334            ..Default::default()
335        };
336        assert!(r.wants_stream());
337        r.body = r#"{"model":"m","stream":false}"#.into();
338        assert!(!r.wants_stream());
339        r.body = r#"{"model":"m"}"#.into();
340        assert!(!r.wants_stream(), "absent means not streaming");
341        r.body = "not json".into();
342        assert!(!r.wants_stream(), "and unreadable must not panic");
343    }
344
345    #[test]
346    fn headers_are_looked_up_case_insensitively() {
347        let mut headers = HashMap::new();
348        headers.insert("authorization".to_string(), "Bearer x".to_string());
349        let r = Request {
350            headers,
351            ..Default::default()
352        };
353        assert_eq!(r.header("Authorization"), Some("Bearer x"));
354        assert_eq!(r.header("AUTHORIZATION"), Some("Bearer x"));
355        assert_eq!(r.header("nope"), None);
356    }
357}