# M4a task 06: HTTP/1.1 requests

**Branch:** `m4a` (run `git switch m4a`; `git status --short` must be empty, otherwise stop)
**Commit subject:** `gatewayd: http, requests over a stream with size caps and rate-limit waits`

## Goal

Mattermost's REST calls are HTTP/1.1, one connection per request (`Connection: close`), over a
`net::Stream`. This module writes a request and reads the response. The server is not trusted: a
response head over 16 KiB or a body over 4 MiB is an error, and every limit is checked **before**
reading or allocating. The WebSocket handshake (task 07) reuses `read_head`, which therefore must
not read a byte past the blank line that ends the head: the WebSocket's first frame may follow at
once.

## Files

- Copy: `crates/gatewayd/tests/http.rs`, and the skeleton `crates/gatewayd/src/http.rs`
- Modify: `crates/gatewayd/src/lib.rs` (`pub mod http;`), `docs/implementer-log.md`

## The skeleton

Written: the constants `MAX_HEAD` (16 KiB), `MAX_BODY` (4 MiB) and `MAX_RATE_WAIT` (60 s);
`HttpError` (`Io`, `Protocol(String)`, `TooLarge(&'static str)`) with `Display` and
`From<std::io::Error>`; `Head { status, headers }` and `Response { head, body }`.

To fill, each with its steps above it: `Head::header`, `write_request`, `request`, `read_head`,
`read_body`, `read_line`, `read_chunked`, `rate_limit_wait`.

Rules that apply to all of them:

- `read_head` reads **one byte at a time**. That is slow and it is right: it must stop exactly at
  the end of the head.
- A retry on `ErrorKind::Interrupted`, and nowhere else.
- No subtraction that can wrap and no indexing that can go out of bounds: `saturating_sub`, `get`,
  `get_mut`. `raw.truncate(raw.len() - 2)` is fine only right after checking `raw.ends_with(b"\r\n")`.
- `rate_limit_wait` is about Mattermost's `X-Ratelimit-Reset`, which is a Unix time in seconds; the
  test also gives it a small number of seconds, which some servers send.

## Steps

- [ ] **1. Copy.** `git switch m4a`, then
  `cp docs/plans/M4a/files/crates/gatewayd/tests/http.rs crates/gatewayd/tests/ && cp docs/plans/M4a/files/crates/gatewayd/src/http.rs crates/gatewayd/src/`.
  Add `pub mod http;` to `lib.rs`.
- [ ] **2. See it fail.** `cargo test -p gatewayd --test http`. Expected: it compiles and 6 tests
  fail.
- [ ] **3. Fill the functions in the order above**, `cargo check -p gatewayd` after each.
- [ ] **4. See it pass.** `cargo test -p gatewayd --test http`. Expected: 6 passed.
- [ ] **5. Run the gate.** `cargo fmt --all`, then `make gate`. Expected last line: `gate: ok`.
- [ ] **6. Log and commit.** `git add crates/gatewayd docs/implementer-log.md Cargo.lock && git commit`

## Done when

- `cargo test -p gatewayd --test http` passes; `make gate` prints `gate: ok`.

## Stop and report if

- A test needs `read_head` to read ahead into a buffer.