# Response

The `Response` object is the mutable view of an outgoing HTTP/1.1 response. It is
pre-initialised by the server (`200 / text/plain`) and passed to every handler as `res`.
All mutating methods return `this` for fluent chaining.

```java
server.get("/hello", (req, res) -> res.body("hello"));
server.post("/items", (req, res) -> res.status(HttpStatus.CREATED).body("created"));
```

---

## Status code

```java
res.status(404)                   // int overload — phrase looked up via HttpStatus.bytesForCode()
res.status(HttpStatus.NOT_FOUND)  // enum overload — pre-encoded bytes written directly, zero lookup
```

Prefer the `HttpStatus` overload on hot paths: the pre-encoded `byte[]` is written to the socket
without any lookup. The `int` overload falls back to an O(1) array lookup — still zero allocation,
just one extra indirection.

---

## Content type

```java
res.type(ContentType.JSON)           // enum — pre-encoded bytes, zero allocation
res.type("application/octet-stream") // String — encoded once at call time
```

Same pattern as `status`: the `ContentType` enum carries pre-encoded bytes; the `String` overload
encodes once and stores the result.

---

## Body modes

Three mutually exclusive modes. The last one set wins.

### Fixed body

```java
res.body("hello")           // String → UTF-8 bytes
res.body(new byte[]{...})   // raw bytes
```

Written with `Content-Length`. The byte array is stored as-is; no copy on the write path.

### Known-length stream

```java
res.stream(Files.newInputStream(path), Files.size(path))
```

Written with `Content-Length`. The stream is drained directly to the socket in the write path —
zero intermediate buffer beyond the OS socket buffer.

### Unknown-length stream (chunked)

```java
res.chunked(source)
```

Written with `Transfer-Encoding: chunked`. The server reads 8 KB at a time from `source`,
writes each chunk with its hex-encoded length, and closes with the terminal `0\r\n\r\n`.
No `Content-Length` header is emitted.

Use when the body length is not known upfront: generated content, pipe-fed streams, proxied
responses.

---

## Custom headers

```java
res.header("X-Request-Id", "abc123")
   .header("Cache-Control", "no-store")
```

Each header is encoded as `"Name: Value\r\n"` bytes **at call time** and stored in a list.
On the write path the pre-encoded arrays are written directly — zero allocation per request.

---

## Fluent chaining

All mutating methods return `this`. A complete response in one expression:

```java
return res.status(HttpStatus.CREATED)
          .type(ContentType.JSON)
          .header("X-Trace-Id", traceId)
          .body(json);
```

---

## Body mode decision guide

| Payload                          | Mode                          | Header emitted          |
|----------------------------------|-------------------------------|-------------------------|
| Small / fully known              | `body()`                      | `Content-Length`        |
| File or stream with known size   | `stream(is, length)`          | `Content-Length`        |
| Generated / piped / unknown size | `chunked(is)`                 | `Transfer-Encoding: chunked` |

---

## Memory model

| Call                        | Allocation                                      |
|-----------------------------|-------------------------------------------------|
| `status(HttpStatus)`        | none — writes pre-encoded `byte[]` from enum    |
| `status(int)`               | none — O(1) array lookup at write time          |
| `type(ContentType)`         | none — pre-encoded `byte[]` from enum           |
| `type(String)`              | encodes once at call time, stored as `byte[]`   |
| `body(String)`              | one UTF-8 encode at call time                   |
| `body(byte[])`              | none — array stored by reference                |
| `stream(is, len)`           | none — stream drained directly to socket        |
| `chunked(is)`               | 8 KB read buffer per write call (stack-local)   |
| `header(name, value)`       | one UTF-8 encode at call time per header        |