From a00aaee76c1b6dd3c8e9f8a336b72c03cf90c088 Mon Sep 17 00:00:00 2001
From: Milad Khajavi <khajavi@gmail.com>
Date: Sat, 6 Dec 2025 18:09:01 +0330
Subject: [PATCH] ensure header middleware.

---
 docs/reference/aop/middleware.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/reference/aop/middleware.md b/docs/reference/aop/middleware.md
index 0fd125d2f..c6c3873f4 100644
--- a/docs/reference/aop/middleware.md
+++ b/docs/reference/aop/middleware.md
@@ -343,6 +343,36 @@ import utils._
 printSource("zio-http-example/src/main/scala/example/StaticFiles.scala")
 ```
 
+### Ensure Header Middleware
+
+The `Middleware.ensureHeader` middleware guarantees that a specific header is present in incoming requests. If the header already exists, the request passes through unchanged. If the header is missing, the middleware adds it with a provided default value.
+
+This middleware comes in two variants:
+
+1. **Type-safe variant** - Uses ZIO HTTP's `Header.HeaderType` for compile-time type safety:
+
+   ```scala mdoc:compile-only
+   Middleware.ensureHeader(Header.ContentType)(MediaType.application.json)
+   ```
+
+2. **String-based variant** - Uses header name and value as strings for flexibility:
+
+   ```scala mdoc:compile-only
+   Middleware.ensureHeader("X-Request-ID")("default-request-id")
+   ```
+
+A common use case for this middleware is to ensure that every incoming request contains a unique correlation ID, which is essential for distributed tracing in microservices architectures:
+
+```scala mdoc:compile-only
+import java.util.UUID
+
+val routes = Routes(
+  Method.GET / "api" / trailing -> handler {
+    Response.text("API response")
+  }
+) @@ Middleware.ensureHeader("X-Request-ID")(UUID.randomUUID().toString)
+```
+
 ### Forwarding Headers Middleware
 
 The `Middleware.forwardHeaders` middleware is used to forward headers from the incoming request to the outgoing request when using the ZIO HTTP Client. This is useful when we want to forward headers like `Authorization`, `X-Request-ID`, and so on. It takes a set of header names to be forwarded: