This PR adds a feature in middleware to add, modify, or delete request headers. This feature is quite useful to pass data from middleware to Serverless/Edge API routes.
### Questions for Reviewers
- Should we deny modifying standard request headers like `Transfer-Encoding`?
- Should we throw an error if the header is too large? Real-world HTTP servers will accept up to only 8KB - 32KB.
### New APIs
Adds a new option `request.headers` to the `MiddlewareResponseInit` parameter in `NextResponse.next()` and `NextResponse.rewrite()`. It's a [`Header`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) object holding *all* request headers. Specifically:
```ts
interface MiddlewareResponseInit extends ResponseInit {
request?: {
headers?: Headers
}
}
```
### Example
```ts
// pages/api/hello.ts
export default (req, res) => {
const valueFromMiddleware = req.headers['x-hello-from-middleware']
return res.send(valueFromMiddleware)
}
// middleware.ts
import { NextRequest, NextResponse } from 'next/server'
export default function middleware(request: NextRequest) {
// Clone request headers
const headers = new Headers(request.headers);
// Add a new request header
headers.set('x-hello-from-middleware', 'foo');
// Delete a request header from the client
headers.delete('x-from-client');
const resp = NextResponse.next({
// New option `request.headers` which accepts a Headers object
// overrides request headers with the specified new ones.
request: {
headers
}
});
// You can still set *response* headers to the client, as before.
resp.headers.set('x-hello-client', 'bar');
return resp;
}
```
### New middleware headers
- `x-middleware-override-headers`: A comma separated list of *all* request header names. Headers not listed will be deleted.
- `x-middleware-request-<name>`: A new value for the header `<name>`.
## Related Discussions
- https://github.com/vercel/next.js/discussions/31188
- https://github.com/vercel/next.js/discussions/39300
## Bug
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have a helpful link attached, see `contributing.md`
## Feature
- [x] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [x] Integration tests added
- [x] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have a helpful link attached, see `contributing.md`
## Documentation / Examples
- [ ] Make sure the linting passes by running `pnpm lint`
- [ ] The "examples guidelines" are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)
