multipart parsing, request body access, and chunked input stream support

docs/lifecycle/request/REQUEST.md

@@ -0,0 +1,104 @@
+# Request
+
+The `Request` object is the immutable view of an incoming HTTP/1.1 request passed to every
+handler. It is constructed by `RequestParser`, path/query parameters are injected once by the
+router, and then it is handed to your handler unchanged.
+
+```java
+server.get("/users/{id}", (req, res) -> { ... });
+```
+
+---
+
+## Method and path
+
+```java
+HttpMethod method = req.method();  // GET, POST, PUT, …
+String     path   = req.path();    // "/users/42" — decoded UTF-8, no query string
+```
+
+`path()` allocates a `String` by decoding the underlying `ByteView`. It is a convenience for
+handlers that need the raw path; the router itself never calls it (it works on the `ByteView`
+directly for zero-alloc routing).
+
+---
+
+## Headers
+
+```java
+String        ct      = req.header("Content-Type");   // first value, or null
+List<String>  accepts = req.headers("Accept");         // all values in order
+List<String>  all     = req.headers();                 // every header value
+```
+
+Lookup is **case-insensitive**: `"content-type"` and `"Content-Type"` resolve to the same header.
+`header()` returns `null` if the header is absent. `headers()` returns an empty list.
+
+---
+
+## Path parameters
+
+Path parameters are declared in the route pattern with `{name}` syntax and injected by the
+router before the handler runs.
+
+```java
+server.get("/users/{id}/orders/{orderId}", (req, res) -> {
+    String id      = req.param("id");
+    String orderId = req.param("orderId");
+});
+```
+
+`param()` returns `null` if the route has no such parameter or is not parametric at all.
+It never throws.
+
+---
+
+## Query parameters
+
+The query string is parsed lazily on the first `query()` or `queries()` call and cached for
+the lifetime of the request.
+
+```java
+// GET /search?q=flash&page=2&tag=java&tag=jvm
+
+String       q    = req.query("q");       // "flash"
+String       page = req.query("page");    // "2"
+List<String> tags = req.queries("tag");   // ["java", "jvm"]
+String       miss = req.query("absent");  // null
+```
+
+`query()` returns the first value for duplicate keys. `queries()` returns all values in
+declaration order. Both return `null` / empty list for absent parameters, never throw.
+
+---
+
+## Body
+
+See [BODY.md](BODY.md) for a full reference. Quick summary:
+
+```java
+// Small payloads — materialise into byte[]
+byte[] json = req.body().bytes();
+
+// Large payloads — stream without heap allocation
+InputStream in = req.body().stream();
+
+// Check size before choosing
+long size = req.body().contentLength(); // -1 if Transfer-Encoding: chunked
+```
+
+The two modes are **mutually exclusive per request**. Calling `stream()` after `bytes()` returns
+a `ByteArrayInputStream` over the cached array; calling `bytes()` after `stream()` has been
+partially read produces undefined results.
+
+---
+
+## Keep-alive and drain
+
+After the response is fully written to the socket, the server calls `req.drain()` automatically
+on keep-alive connections. This discards any unread body bytes so the socket is correctly
+positioned for the next pipelined request. You never need to call this yourself.
+
+**Important:** drain happens *after* the response write, not immediately after the handler
+returns. This matters for streaming responses that consume the request body on a separate thread
+(e.g. a pipe-fed echo): by the time drain runs, the body has already been consumed.