@zio.dev/zio-blocks 0.0.28 → 0.0.29

package/reference/http-model.md

@@ -0,0 +1,1716 @@
+---
+id: http-model
+title: "HTTP Model"
+---
+
+`zio-http-model` is a **pure, zero-dependency HTTP data model** for building HTTP clients and servers. It provides immutable types representing requests, responses, headers, URLs, paths, query parameters, and all HTTP primitives.
+
+The module is designed as a pure data layer:
+
+- **Zero effects**: no streaming, no I/O, no mutable state (except monotonic lazy-parse caches in `Headers`)
+- **Zero ZIO dependency**: uses `zio.blocks.chunk.Chunk`, not `zio.Chunk`
+- **Single encoding contract**: `Path` and `QueryParams` store values decoded internally, encode only on output
+- **Cross-platform**: JVM and Scala.js support
+- **Cross-version**: Scala 2.13 and 3.x support
+
+```scala
+package zio.http
+
+// Core request/response types
+final case class Request(method: Method, url: URL, headers: Headers, body: Body, version: Version)
+final case class Response(status: Status, headers: Headers, body: Body, version: Version)
+
+// URL structure
+final case class URL(scheme: Option[Scheme], host: Option[String], port: Option[Int],
+                     path: Path, queryParams: QueryParams, fragment: Option[String])
+
+final case class Path(segments: Chunk[String], hasLeadingSlash: Boolean, trailingSlash: Boolean)
+final class QueryParams private[http] (...)
+
+// HTTP primitives
+sealed abstract class Method(val name: String, val ordinal: Int)
+opaque type Status = Int  // Scala 3
+sealed abstract class Version(val major: Int, val minor: Int)
+sealed trait Scheme
+
+// Headers and body
+final class Headers private[http] (...)
+sealed trait Header
+final class Body private (val data: Chunk[Byte], val contentType: ContentType)
+
+// Supporting types
+final case class ContentType(mediaType: MediaType, boundary: Option[Boundary], charset: Option[Charset])
+final case class ResponseCookie(...), RequestCookie(name: String, value: String)
+final case class Form(entries: Chunk[(String, String)])
+```
+
+## Motivation
+
+HTTP libraries often couple protocol concerns with effects and streaming, making it difficult to:
+
+- Share data structures across client and server implementations
+- Serialize requests/responses for caching or testing
+- Work with HTTP primitives without committing to a specific effect system
+
+`zio-http-model` solves this by providing pure data types that:
+
+- Represent all HTTP concepts as immutable values
+- Encode only on output (decode on input, store decoded)
+- Parse incrementally with lazy caching (`Headers` parses typed headers on first access and caches the result)
+- Work with any effect system or none at all
+
+## Installation
+
+Add the following to your `build.sbt`:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-http-model" % "<version>"
+```
+
+For cross-platform projects (Scala.js):
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-http-model" % "<version>"
+```
+
+Supported Scala versions: 2.13.x and 3.x
+
+## Quick Start
+
+Creating a request with query parameters:
+
+```scala
+import zio.http._
+
+val url = URL.parse("https://api.example.com/users?active=true").toOption.get
+val request = Request.get(url)
+
+val withHeader = request.addHeader("authorization", "Bearer token123")
+```
+
+Creating a JSON response:
+
+```scala
+import zio.http._
+
+val jsonBody = Body.fromString("""{"message":"ok"}""", Charset.UTF8)
+val response = Response(
+  status = Status.Ok,
+  body = jsonBody,
+  headers = Headers("content-type" -> "application/json")
+)
+```
+
+## Method
+
+`Method` represents standard HTTP methods as case objects:
+
+```scala
+sealed abstract class Method(val name: String, val ordinal: Int)
+```
+
+### Predefined Methods
+
+```scala
+import zio.http.Method
+
+val get     = Method.GET
+val post    = Method.POST
+val put     = Method.PUT
+val delete  = Method.DELETE
+val patch   = Method.PATCH
+val head    = Method.HEAD
+val options = Method.OPTIONS
+val trace   = Method.TRACE
+val connect = Method.CONNECT
+```
+
+### Parsing
+
+```scala
+import zio.http.Method
+
+Method.fromString("GET")    // Some(Method.GET)
+Method.fromString("POST")   // Some(Method.POST)
+Method.fromString("CUSTOM") // None (unknown method)
+```
+
+### Rendering
+
+```scala
+import zio.http.Method
+
+Method.render(Method.GET)  // "GET"
+Method.GET.name            // "GET"
+Method.GET.toString        // "GET"
+```
+
+## Status
+
+`Status` is an opaque type alias for `Int` in Scala 3 (AnyVal wrapper in Scala 2.13), providing zero-allocation status codes with predefined constants.
+
+```scala
+opaque type Status = Int  // Scala 3
+```
+
+### Predefined Status Codes
+
+Status codes are organized by category:
+
+```scala
+import zio.http.Status
+
+// 1xx Informational
+Status.Continue           // 100
+Status.SwitchingProtocols // 101
+
+// 2xx Success
+Status.Ok                 // 200
+Status.Created            // 201
+Status.NoContent          // 204
+
+// 3xx Redirection
+Status.MovedPermanently   // 301
+Status.Found              // 302
+Status.SeeOther           // 303
+Status.NotModified        // 304
+
+// 4xx Client Errors
+Status.BadRequest         // 400
+Status.Unauthorized       // 401
+Status.Forbidden          // 403
+Status.NotFound           // 404
+
+// 5xx Server Errors
+Status.InternalServerError // 500
+Status.BadGateway          // 502
+Status.ServiceUnavailable  // 503
+```
+
+### Creating Status Codes
+
+```scala
+import zio.http.Status
+
+val custom = Status(418)          // I'm a teapot
+val ok     = Status.fromInt(200)  // Status.Ok
+```
+
+### Status Code Operations
+
+```scala
+import zio.http.Status
+
+val status = Status.Ok
+
+status.code              // 200
+status.text              // "OK"
+status.isSuccess         // true (2xx)
+status.isInformational   // false (1xx)
+status.isRedirection     // false (3xx)
+status.isClientError     // false (4xx)
+status.isServerError     // false (5xx)
+status.isError           // false (4xx or 5xx)
+```
+
+## Version
+
+`Version` represents HTTP protocol versions:
+
+```scala
+sealed abstract class Version(val major: Int, val minor: Int)
+```
+
+### Predefined Versions
+
+```scala
+import zio.http.Version
+
+val v10 = Version.`HTTP/1.0`
+val v11 = Version.`HTTP/1.1`
+val v20 = Version.`HTTP/2.0`
+val v30 = Version.`HTTP/3.0`
+```
+
+### Parsing and Rendering
+
+```scala
+import zio.http.Version
+
+Version.fromString("HTTP/1.1") // Some(Version.`HTTP/1.1`)
+Version.fromString("HTTP/2")   // Some(Version.`HTTP/2.0`)
+Version.fromString("HTTP/3")   // Some(Version.`HTTP/3.0`)
+
+Version.render(Version.`HTTP/1.1`) // "HTTP/1.1"
+Version.`HTTP/2.0`.text            // "HTTP/2.0"
+```
+
+## Scheme
+
+`Scheme` represents URL schemes with support for HTTP, HTTPS, WebSocket (WS, WSS), and custom schemes:
+
+```scala
+sealed trait Scheme {
+  def text: String
+  def defaultPort: Option[Int]
+  def isSecure: Boolean
+  def isWebSocket: Boolean
+}
+```
+
+### Predefined Schemes
+
+```scala
+import zio.http.Scheme
+
+val http  = Scheme.HTTP   // http://, port 80
+val https = Scheme.HTTPS  // https://, port 443
+val ws    = Scheme.WS     // ws://, port 80
+val wss   = Scheme.WSS    // wss://, port 443
+```
+
+### Scheme Properties
+
+```scala
+import zio.http.Scheme
+
+Scheme.HTTPS.isSecure      // true
+Scheme.WS.isWebSocket      // true
+Scheme.HTTP.defaultPort    // Some(80)
+```
+
+### Custom Schemes
+
+```scala
+import zio.http.Scheme
+
+val custom = Scheme.Custom("git+ssh")
+custom.text         // "git+ssh"
+custom.defaultPort  // None
+```
+
+### Parsing
+
+```scala
+import zio.http.Scheme
+
+Scheme.fromString("https")    // Scheme.HTTPS
+Scheme.fromString("wss")      // Scheme.WSS
+Scheme.fromString("custom")   // Scheme.Custom("custom")
+```
+
+## Charset
+
+`Charset` represents character encodings with JVM-only conversion to `java.nio.charset.Charset`:
+
+```scala
+sealed abstract class Charset(val name: String)
+```
+
+### Predefined Charsets
+
+```scala
+import zio.http.Charset
+
+val utf8      = Charset.UTF8       // "UTF-8"
+val ascii     = Charset.ASCII      // "US-ASCII"
+val iso88591  = Charset.ISO_8859_1 // "ISO-8859-1"
+val utf16     = Charset.UTF16      // "UTF-16"
+val utf16be   = Charset.UTF16BE    // "UTF-16BE"
+val utf16le   = Charset.UTF16LE    // "UTF-16LE"
+```
+
+### Parsing
+
+```scala
+import zio.http.Charset
+
+Charset.fromString("UTF-8")      // Some(Charset.UTF8)
+Charset.fromString("utf8")       // Some(Charset.UTF8) (case-insensitive)
+Charset.fromString("ISO-8859-1") // Some(Charset.ISO_8859_1)
+Charset.fromString("LATIN1")     // Some(Charset.ISO_8859_1) (alias)
+```
+
+## Boundary
+
+`Boundary` represents multipart form-data boundaries:
+
+```scala
+import zio.http.Boundary
+
+val boundary = Boundary("----WebKitFormBoundary7MA4YWxkTrZu0gW")
+boundary.value    // "----WebKitFormBoundary7MA4YWxkTrZu0gW"
+boundary.toString // "----WebKitFormBoundary7MA4YWxkTrZu0gW"
+```
+
+### Generating Boundaries
+
+```scala
+import zio.http.Boundary
+
+val generated = Boundary.generate  // random 24-character alphanumeric string
+```
+
+## PercentEncoder
+
+`PercentEncoder` provides RFC 3986 percent-encoding for URL components. Each URL component has different encoding rules:
+
+```scala
+import zio.http.PercentEncoder
+import zio.http.PercentEncoder.ComponentType
+
+val segment = PercentEncoder.encode("hello world", ComponentType.PathSegment)
+// "hello%20world"
+
+val queryKey = PercentEncoder.encode("filter[name]", ComponentType.QueryKey)
+// "filter%5Bname%5D"
+
+val decoded = PercentEncoder.decode("hello%20world")
+// "hello world"
+```
+
+### Component Types
+
+The encoder recognizes these component types:
+
+- `PathSegment`: path segments between `/`
+- `QueryKey`: query parameter names
+- `QueryValue`: query parameter values
+- `Fragment`: fragment identifiers after `#`
+- `UserInfo`: userinfo in authority
+
+Each type has specific rules for which characters must be percent-encoded.
+
+## ContentType
+
+`ContentType` combines a media type with optional charset and boundary parameters:
+
+```scala
+import zio.http.{ContentType, Charset, Boundary}
+import zio.blocks.mediatype.MediaTypes
+
+val json = ContentType(MediaTypes.application.`json`)
+
+val htmlUtf8 = ContentType(
+  mediaType = MediaTypes.text.`html`,
+  charset = Some(Charset.UTF8)
+)
+
+val multipart = ContentType(
+  mediaType = MediaTypes.multipart.`form-data`,
+  boundary = Some(Boundary("----boundary"))
+)
+```
+
+### Parsing
+
+```scala
+import zio.http.ContentType
+
+ContentType.parse("application/json")
+// Right(ContentType(MediaType("application", "json")))
+
+ContentType.parse("text/html; charset=utf-8")
+// Right(ContentType(..., charset = Some(Charset.UTF8)))
+
+ContentType.parse("multipart/form-data; boundary=abc123")
+// Right(ContentType(..., boundary = Some(Boundary("abc123"))))
+
+ContentType.parse("")
+// Left("Invalid content type: cannot be empty")
+```
+
+### Rendering
+
+```scala
+import zio.http.{ContentType, Charset}
+import zio.blocks.mediatype.MediaTypes
+
+val ct = ContentType(
+  MediaTypes.text.`plain`,
+  charset = Some(Charset.UTF8)
+)
+
+ct.render  // "text/plain; charset=UTF-8"
+```
+
+### Predefined Content Types
+
+```scala
+import zio.http.ContentType
+
+val json   = ContentType.`application/json`
+val plain  = ContentType.`text/plain`
+val html   = ContentType.`text/html`
+val binary = ContentType.`application/octet-stream`
+```
+
+## Path
+
+`Path` represents URL paths with decoded segments stored internally:
+
+```scala
+final case class Path(
+  segments: Chunk[String],
+  hasLeadingSlash: Boolean,
+  trailingSlash: Boolean
+)
+```
+
+Paths use a **single encoding contract**: decode on input, store decoded, encode on output.
+
+### Creating Paths
+
+```scala
+import zio.http.Path
+
+val empty = Path.empty                    // ""
+val root  = Path.root                     // "/"
+val users = Path("/users")                // segments: ["users"], leading slash: true
+val api   = Path("api/v1/users/")         // segments: ["api", "v1", "users"], trailing slash: true
+```
+
+### Parsing Encoded Paths
+
+`Path.fromEncoded` decodes percent-encoded segments:
+
+```scala
+import zio.http.Path
+
+val path = Path.fromEncoded("/hello%20world/foo%2Fbar")
+// Path(Chunk("hello world", "foo/bar"), hasLeadingSlash = true, trailingSlash = false)
+
+path.segments(0)  // "hello world" (decoded)
+path.segments(1)  // "foo/bar" (decoded)
+```
+
+### Building Paths
+
+```scala
+import zio.http.Path
+
+val base = Path("/api")
+val extended = base / "users" / "123"  // "/api/users/123"
+
+val combined = Path("/api") ++ Path("v1/users")  // "/api/v1/users"
+```
+
+### Encoding Paths
+
+```scala
+import zio.http.Path
+import zio.blocks.chunk.Chunk
+
+val path = Path(Chunk("hello world", "foo/bar"), hasLeadingSlash = true, trailingSlash = false)
+
+path.encode  // "/hello%20world/foo%2Fbar" (percent-encoded)
+path.render  // "/hello world/foo/bar" (decoded for display)
+```
+
+### Path Properties
+
+```scala
+import zio.http.Path
+
+val path = Path("/api/v1/users/")
+
+path.isEmpty           // false
+path.nonEmpty          // true
+path.length            // 3 (number of segments)
+path.hasLeadingSlash   // true
+path.trailingSlash     // true
+```
+
+### Path Navigation
+
+```scala
+import zio.http.Path
+
+val path = Path("/api/v1/users")
+
+// Slash manipulation
+path.addLeadingSlash     // same (already has one)
+path.dropLeadingSlash    // "api/v1/users" (relative)
+path.addTrailingSlash    // "/api/v1/users/"
+path.dropTrailingSlash   // same (already no trailing slash)
+
+// Inspecting
+path.isRoot              // false (root is "/" with no segments)
+Path.root.isRoot         // true
+
+// Prefix checking
+path.startsWith(Path("api/v1"))  // true
+
+// Slicing
+path.drop(1)       // "/v1/users" (drop first segment)
+path.take(2)       // "/api/v1" (take first 2 segments)
+path.dropRight(1)  // "/api/v1" (drop last segment)
+path.initial       // "/api/v1" (all but last)
+path.last          // Some("users")
+path.reverse       // "/users/v1/api"
+```
+
+## QueryParams
+
+`QueryParams` stores query parameters with multiple values per key:
+
+```scala
+final class QueryParams private[http] (
+  private val keys: Array[String],
+  private val vals: Array[Chunk[String]],
+  val size: Int
+)
+```
+
+Like `Path`, query parameters store decoded values internally and encode only on output.
+
+### Creating QueryParams
+
+```scala
+import zio.http.QueryParams
+
+val empty = QueryParams.empty
+
+val params = QueryParams(
+  "name" -> "Alice",
+  "age" -> "30",
+  "active" -> "true"
+)
+```
+
+### Parsing Encoded Query Strings
+
+```scala
+import zio.http.QueryParams
+
+val params = QueryParams.fromEncoded("name=Alice%20Smith&age=30&active=true")
+
+params.getFirst("name")    // Some("Alice Smith") (decoded)
+params.getFirst("age")     // Some("30")
+params.getFirst("active")  // Some("true")
+```
+
+### Accessing Values
+
+```scala
+import zio.http.QueryParams
+
+val params = QueryParams(
+  "color" -> "red",
+  "color" -> "blue",
+  "size" -> "large"
+)
+
+params.get("color")       // Some(Chunk("red", "blue"))
+params.getFirst("color")  // Some("red")
+params.getFirst("size")   // Some("large")
+params.getFirst("other")  // None
+params.has("color")       // true
+```
+
+### Modifying QueryParams
+
+```scala
+import zio.http.QueryParams
+
+val params = QueryParams("a" -> "1", "b" -> "2")
+
+val added = params.add("c", "3")         // adds "c=3"
+val set   = params.set("a", "100")       // replaces all "a" values
+val removed = params.remove("b")         // removes all "b" entries
+```
+
+### Encoding
+
+```scala
+import zio.http.QueryParams
+
+val params = QueryParams(
+  "name" -> "Alice Smith",
+  "filter[status]" -> "active"
+)
+
+params.encode  // "name=Alice%20Smith&filter%5Bstatus%5D=active"
+```
+
+### Converting to List
+
+```scala
+import zio.http.QueryParams
+
+val params = QueryParams("a" -> "1", "a" -> "2", "b" -> "3")
+params.toList  // List(("a", "1"), ("a", "2"), ("b", "3"))
+```
+
+## URL
+
+`URL` combines scheme, host, port, path, query parameters, and fragment:
+
+```scala
+final case class URL(
+  scheme: Option[Scheme],
+  host: Option[String],
+  port: Option[Int],
+  path: Path,
+  queryParams: QueryParams,
+  fragment: Option[String]
+)
+```
+
+### Parsing URLs
+
+```scala
+import zio.http.URL
+
+val absolute = URL.parse("https://api.example.com:8080/users?active=true#results")
+// Right(URL(
+//   scheme = Some(Scheme.HTTPS),
+//   host = Some("api.example.com"),
+//   port = Some(8080),
+//   path = Path("/users"),
+//   queryParams = QueryParams("active" -> "true"),
+//   fragment = Some("results")
+// ))
+
+val relative = URL.parse("/api/users?page=2")
+// Right(URL(
+//   scheme = None,
+//   host = None,
+//   port = None,
+//   path = Path("/api/users"),
+//   queryParams = QueryParams("page" -> "2"),
+//   fragment = None
+// ))
+```
+
+The parser handles:
+
+- IPv6 hosts in brackets: `http://[::1]:8080/`
+- Userinfo: `https://user:pass@example.com/` (userinfo is skipped)
+- Relative URLs: `/path?query`
+- Fragment identifiers: `#section`
+
+### Building URLs
+
+```scala
+import zio.http.{URL, Path, Scheme}
+
+val base = URL.root  // http://localhost/
+
+val extended = base / "api" / "users"  // adds path segments
+
+val withQuery = extended ?? ("active", "true") ?? ("page", "1")
+// http://localhost/api/users?active=true&page=1
+```
+
+### URL from Path
+
+```scala
+import zio.http.{URL, Path}
+
+val path = Path("/api/users")
+val url = URL.fromPath(path)  // relative URL with just path
+```
+
+### Encoding URLs
+
+```scala
+import zio.http.URL
+
+val url = URL.parse("https://example.com/hello world?name=Alice Smith").toOption.get
+
+url.encode  // "https://example.com/hello%20world?name=Alice%20Smith"
+url.toString  // same as encode
+```
+
+### URL Properties
+
+```scala
+import zio.http.URL
+
+val absolute = URL.parse("https://example.com/").toOption.get
+val relative = URL.parse("/api/users").toOption.get
+
+absolute.isAbsolute  // true (has scheme)
+relative.isRelative  // true (no scheme)
+```
+
+### URL Transformation
+
+```scala
+import zio.http.{URL, Path, Scheme, QueryParams}
+
+val url = URL.parse("https://api.example.com:8080/users?page=1").toOption.get
+
+// Setting components
+url.host("other.com")           // changes host
+url.port(9090)                  // changes port
+url.scheme(Scheme.HTTP)          // changes scheme
+url.path(Path("/v2/users"))      // replaces path
+url.fragment("top")              // sets fragment
+
+// Adding paths
+url.addPath("123")             // appends segment: /users/123
+url.addPath(Path("v2/items"))  // appends multi-segment path
+
+// Query manipulation
+url.addQueryParams(QueryParams("sort" -> "name"))
+url.updateQueryParams(_.remove("page"))
+
+// Slash manipulation (delegates to path)
+url.addLeadingSlash
+url.dropTrailingSlash
+
+// Derived properties
+url.hostPort   // Some("api.example.com:8080")
+url.relative   // strips scheme/host/port, keeps path and query
+```
+
+## Header
+
+`Header` is a trait representing typed HTTP headers:
+
+```scala
+trait Header {
+  def headerName: String
+  def renderedValue: String
+}
+```
+
+Each header type has a companion object implementing `Header.Typed[H]` for parsing and rendering.
+
+### Predefined Header Types
+
+```scala
+import zio.http.{Header => _, *}
+import zio.http.headers
+
+val contentType   = headers.ContentType
+val accept        = headers.Accept
+val authorization = headers.Authorization
+val host          = headers.Host
+val userAgent     = headers.UserAgent
+val cacheControl  = headers.CacheControl
+val contentLength = headers.ContentLength
+val location      = headers.Location
+val setCookie     = headers.SetCookieHeader
+val cookie        = headers.CookieHeader
+```
+
+### Creating Typed Headers
+
+```scala
+import zio.http.{Header => _, ContentType, Charset, *}
+import zio.http.headers
+import zio.blocks.mediatype.MediaTypes
+
+val ct = headers.ContentType(
+  ContentType(MediaTypes.application.`json`, charset = Some(Charset.UTF8))
+)
+
+val auth = headers.Authorization.Bearer("token123")
+
+val host = headers.Host("api.example.com", Some(8080))
+```
+
+### Parsing Headers
+
+```scala
+import zio.http.{Header => _, *}
+import zio.http.headers
+
+headers.ContentType.parse("application/json; charset=utf-8")
+// Right(headers.ContentType(...))
+
+headers.Host.parse("example.com:443")
+// Right(headers.Host("example.com", Some(443)))
+
+headers.ContentLength.parse("1024")
+// Right(headers.ContentLength(1024))
+
+headers.ContentLength.parse("-1")
+// Left("Invalid content-length: -1")
+```
+
+### Custom Headers
+
+```scala
+import zio.http.Header
+
+val custom = Header.Custom("x-request-id", "abc-123")
+custom.headerName     // "x-request-id"
+custom.renderedValue  // "abc-123"
+```
+
+## Headers
+
+`Headers` is a flat array-based collection with lazy monotonic parsing:
+
+```scala
+final class Headers private[http] (
+  private val names: Array[String],
+  private val rawValues: Array[String],
+  private val parsed: Array[AnyRef],  // null -> unparsed, value -> cached
+  val size: Int
+)
+```
+
+When you call `get[H]`, the header is parsed once and cached. Subsequent calls return the cached result.
+
+### Creating Headers
+
+```scala
+import zio.http.Headers
+
+val empty = Headers.empty
+
+val headers = Headers(
+  "content-type" -> "application/json",
+  "authorization" -> "Bearer token",
+  "x-request-id" -> "abc-123"
+)
+```
+
+### Getting Typed Headers
+
+```scala
+import zio.http.{Headers, *}
+import zio.http.{headers => h}
+
+val headers = Headers(
+  "content-type" -> "application/json",
+  "content-length" -> "1024"
+)
+
+val ct = headers.get(h.ContentType)
+// Some(h.ContentType(...)) (parsed and cached)
+
+val cl = headers.get(h.ContentLength)
+// Some(h.ContentLength(1024)) (parsed and cached)
+
+val auth = headers.get(h.Authorization)
+// None (not present)
+```
+
+### Getting Raw Values
+
+```scala
+import zio.http.Headers
+
+val headers = Headers("x-custom" -> "value")
+
+headers.rawGet("x-custom")  // Some("value")
+headers.rawGet("missing")   // None
+```
+
+### Getting All Headers of a Type
+
+Some headers can appear multiple times (like `Set-Cookie`):
+
+```scala
+import zio.http.{Headers, *}
+import zio.http.{headers => h}
+
+val headers = Headers(
+  "set-cookie" -> "session=abc",
+  "set-cookie" -> "preference=dark"
+)
+
+val cookies = headers.getAll(h.SetCookieHeader)
+// Chunk(h.SetCookieHeader(...), h.SetCookieHeader(...))
+```
+
+### Modifying Headers
+
+```scala
+import zio.http.Headers
+
+val headers = Headers("a" -> "1", "b" -> "2")
+
+val added = headers.add("c", "3")        // adds "c: 3"
+val set   = headers.set("a", "100")      // replaces all "a" values
+val removed = headers.remove("b")        // removes all "b" entries
+val has = headers.has("a")               // true
+```
+
+### Converting to List
+
+```scala
+import zio.http.Headers
+
+val headers = Headers("a" -> "1", "b" -> "2")
+headers.toList  // List(("a", "1"), ("b", "2"))
+```
+
+### Combining Headers
+
+```scala
+import zio.http.Headers
+
+val auth = Headers("authorization" -> "Bearer token")
+val cors = Headers("access-control-allow-origin" -> "*")
+
+val combined = auth ++ cors  // Headers(authorization: ..., access-control-allow-origin: ...)
+
+combined.contains("authorization")  // true (alias for `has`)
+combined.toChunk                    // Chunk(("authorization", ...), ("access-control-allow-origin", ...))
+```
+
+## Body
+
+`Body` wraps a materialized `Chunk[Byte]` with a content type:
+
+```scala
+final class Body private (
+  val data: Chunk[Byte],
+  val contentType: ContentType
+)
+```
+
+
+### Creating Bodies
+
+`Body.empty` provides an empty body with default `application/octet-stream` content type:
+
+```scala
+import zio.http.Body
+
+val empty = Body.empty
+// Body(data = Chunk.empty, contentType = application/octet-stream)
+```
+
+`Body.fromString` creates a body with `text/plain` content type:
+
+```scala
+import zio.http.{Body, Charset}
+
+val fromString = Body.fromString("Hello, World!", Charset.UTF8)
+// Content-Type: text/plain; charset=UTF-8
+```
+
+`Body.fromArray` creates a body with default `application/octet-stream` content type:
+
+```scala
+import zio.http.Body
+
+val fromBytes = Body.fromArray(Array[Byte](1, 2, 3))
+// Content-Type: application/octet-stream
+```
+
+`Body.fromChunk` creates a body from a `Chunk[Byte]` with optional content type:
+
+```scala
+import zio.http.{Body, ContentType}
+import zio.blocks.chunk.Chunk
+import zio.blocks.mediatype.MediaTypes
+
+val chunk = Chunk[Byte](1, 2, 3, 4, 5)
+val body = Body.fromChunk(chunk)
+// Content-Type: application/octet-stream (default)
+
+val jsonBody = Body.fromChunk(chunk, ContentType(MediaTypes.application.`json`))
+// Content-Type: application/json
+```
+
+### Reading Bodies
+
+`Body` provides direct access to data and content type:
+
+```scala
+import zio.http.{Body, Charset}
+
+val body = Body.fromString("Hello!", Charset.UTF8)
+
+body.length           // 6
+body.isEmpty          // false
+body.nonEmpty         // true
+body.asString()       // "Hello!" (UTF-8 default)
+body.asString(Charset.ASCII)  // "Hello!" (explicit charset)
+body.data             // Chunk[Byte](72, 101, 108, 108, 111, 33)
+body.contentType      // ContentType(text/plain; charset=UTF-8)
+```
+
+## Cookie
+
+Cookies are split into `RequestCookie` and `ResponseCookie` with different structures:
+
+```scala
+final case class RequestCookie(name: String, value: String)
+
+final case class ResponseCookie(
+  name: String,
+  value: String,
+  domain: Option[String],
+  path: Option[Path],
+  maxAge: Option[Long],
+  isSecure: Boolean,
+  isHttpOnly: Boolean,
+  sameSite: Option[SameSite]
+)
+```
+
+### SameSite
+
+```scala
+import zio.http.SameSite
+
+val strict = SameSite.Strict
+val lax    = SameSite.Lax
+val none   = SameSite.None_  // underscore avoids conflict with scala.None
+```
+
+### Parsing Request Cookies
+
+```scala
+import zio.http.Cookie
+
+val cookies = Cookie.parseRequest("session=abc123; preference=dark")
+// Chunk(RequestCookie("session", "abc123"), RequestCookie("preference", "dark"))
+```
+
+### Parsing Response Cookies
+
+```scala
+import zio.http.Cookie
+
+val cookie = Cookie.parseResponse("session=abc; Domain=example.com; Path=/; Secure; HttpOnly; SameSite=Strict")
+// Right(ResponseCookie(
+//   name = "session",
+//   value = "abc",
+//   domain = Some("example.com"),
+//   path = Some(Path("/")),
+//   isSecure = true,
+//   isHttpOnly = true,
+//   sameSite = Some(SameSite.Strict)
+// ))
+```
+
+### Rendering Cookies
+
+```scala
+import zio.http.{Cookie, RequestCookie, ResponseCookie, SameSite, Path}
+import zio.blocks.chunk.Chunk
+
+val requestCookies = Chunk(
+  RequestCookie("session", "abc"),
+  RequestCookie("theme", "dark")
+)
+Cookie.renderRequest(requestCookies)
+// "session=abc; theme=dark"
+
+val responseCookie = ResponseCookie(
+  name = "session",
+  value = "xyz",
+  domain = Some("example.com"),
+  path = Some(Path("/")),
+  maxAge = Some(3600),
+  isSecure = true,
+  isHttpOnly = true,
+  sameSite = Some(SameSite.Strict)
+)
+Cookie.renderResponse(responseCookie)
+// "session=xyz; Domain=example.com; Path=/; Max-Age=3600; Secure; HttpOnly; SameSite=Strict"
+```
+
+## Form
+
+`Form` represents URL-encoded form data:
+
+```scala
+final case class Form(entries: Chunk[(String, String)])
+```
+
+### Creating Forms
+
+```scala
+import zio.http.Form
+
+val empty = Form.empty
+
+val form = Form(
+  "username" -> "alice",
+  "password" -> "secret",
+  "remember" -> "true"
+)
+```
+
+### Accessing Form Data
+
+```scala
+import zio.http.Form
+
+val form = Form(
+  "tag" -> "scala",
+  "tag" -> "functional",
+  "page" -> "1"
+)
+
+form.get("tag")      // Some("scala") (first value)
+form.getAll("tag")   // Chunk("scala", "functional")
+form.get("page")     // Some("1")
+form.get("missing")  // None
+```
+
+### Modifying Forms
+
+```scala
+import zio.http.Form
+
+val form = Form("a" -> "1")
+val added = form.add("b", "2")  // Form(("a", "1"), ("b", "2"))
+```
+
+### Encoding and Parsing
+
+```scala
+import zio.http.Form
+
+val form = Form(
+  "name" -> "Alice Smith",
+  "email" -> "alice@example.com"
+)
+
+val encoded = form.encode
+// "name=Alice%20Smith&email=alice%40example.com"
+
+val parsed = Form.fromString(encoded)
+// Form with decoded entries
+```
+
+## FormField
+
+`FormField` is a sealed trait for multipart form fields, supporting simple key-value pairs, text parts with optional metadata, and binary parts:
+
+```scala
+import zio.http._
+import zio.blocks.chunk.Chunk
+import zio.blocks.mediatype.MediaTypes
+
+// Simple key-value field
+val simple = FormField.Simple("username", "alice")
+
+// Text field with optional content type and filename
+val text = FormField.Text(
+  name = "bio",
+  value = "Hello world",
+  contentType = Some(ContentType(MediaTypes.text.`plain`)),
+  filename = None
+)
+
+// Binary field with content type and optional filename
+val binary = FormField.Binary(
+  name = "avatar",
+  data = Chunk.fromArray(Array[Byte](1, 2, 3)),
+  contentType = ContentType(MediaTypes.image.`png`),
+  filename = Some("avatar.png")
+)
+
+// All variants share a common `name` accessor
+simple.name  // "username"
+text.name    // "bio"
+binary.name  // "avatar"
+```
+
+## Request
+
+`Request` combines all HTTP request components:
+
+```scala
+final case class Request(
+  method: Method,
+  url: URL,
+  headers: Headers,
+  body: Body,
+  version: Version
+)
+```
+
+### Creating Requests
+
+```scala
+import zio.http._
+
+val url = URL.parse("https://api.example.com/users").toOption.get
+val getRequest = Request.get(url)
+
+val jsonBody = Body.fromString("""{"name":"Alice"}""", Charset.UTF8)
+val postRequest = Request.post(url, jsonBody)
+```
+
+### Request Factory Methods
+
+```scala
+import zio.http._
+
+val url = URL.parse("https://api.example.com/resource/1").toOption.get
+val body = Body.fromString("""{"name":"updated"}""")
+
+Request.get(url)              // GET with empty body
+Request.post(url, body)       // POST with body
+Request.put(url, body)        // PUT with body
+Request.patch(url, body)      // PATCH with body
+Request.delete(url)           // DELETE with empty body
+Request.head(url)             // HEAD with empty body
+Request.options(url)          // OPTIONS with empty body
+```
+
+### Modifying Requests
+
+All modification methods return a new `Request`—the original is unchanged:
+
+```scala
+import zio.http._
+
+val request = Request.get(URL.parse("https://api.example.com/users").toOption.get)
+
+// Adding/modifying headers
+request.addHeader("Accept", "application/json")
+request.addHeaders(Headers("X-A" -> "1", "X-B" -> "2"))
+request.setHeader("Accept", "text/html")       // replaces existing
+request.removeHeader("Accept")
+
+// Replacing components
+request.body(Body.fromString("data"))
+request.url(URL.parse("/other").toOption.get)
+request.method(Method.POST)
+request.version(Version.`HTTP/2.0`)
+// Functional updates
+request.updateHeaders(_.add("X-Custom", "value"))
+request.updateUrl(_ / "123")   // appends path segment
+```
+
+Full control:
+
+```scala
+import zio.http._
+
+val url = URL.parse("https://api.example.com/users").toOption.get
+val body = Body.fromString("""{"name":"Alice"}""", Charset.UTF8)
+
+val request = Request(
+  method = Method.POST,
+  url = url,
+  headers = Headers(
+    "content-type" -> "application/json",
+    "authorization" -> "Bearer token123"
+  ),
+  body = body,
+  version = Version.`HTTP/1.1`
+)
+```
+
+### Accessing Request Data
+
+```scala
+import zio.http._
+import zio.http.{headers => h}
+
+val request = Request.get(URL.parse("/api/users?page=1").toOption.get)
+
+request.path         // Path("/api/users")
+request.queryParams  // QueryParams("page" -> "1")
+request.contentType  // Option[ContentType]
+request.header(h.Authorization)  // Option[h.Authorization]
+```
+
+## Response
+
+`Response` represents HTTP responses:
+
+```scala
+final case class Response(
+  status: Status,
+  headers: Headers,
+  body: Body,
+  version: Version
+)
+```
+
+### Creating Responses
+
+```scala
+import zio.http._
+
+val ok = Response.ok  // 200 OK, empty body
+
+val notFound = Response.notFound  // 404 Not Found, empty body
+```
+
+### Response Factory Methods
+
+```scala
+import zio.http._
+
+// Status-only responses
+Response.ok                    // 200
+Response.notFound              // 404
+Response.badRequest            // 400
+Response.unauthorized          // 401
+Response.forbidden             // 403
+Response.internalServerError   // 500
+Response.serviceUnavailable    // 503
+
+// Responses with bodies
+Response.text("Hello, World!")    // 200 with text/plain body
+Response.json("""{'ok':true}""")  // 200 with application/json in headers and body
+// Redirects
+Response.redirect("/new-location")                     // 307 Temporary Redirect
+Response.redirect("/new-location", isPermanent = true) // 308 Permanent Redirect
+Response.seeOther("/other")                            // 303 See Other
+```
+
+Note that `Response.json` creates bodies with `application/json` content-type on the `Body` itself, not just in the headers.
+
+### Modifying Responses
+
+```scala
+import zio.http._
+
+val response = Response.ok
+
+// Adding/modifying headers
+response.addHeader("X-Custom", "value")
+response.setHeader("X-Custom", "new-value")
+response.removeHeader("X-Custom")
+
+// Replacing components
+response.body(Body.fromString("data"))
+response.status(Status.Created)
+response.version(Version.`HTTP/2.0`)
+// Functional update
+response.updateHeaders(_.add("X-Request-Id", "abc"))
+
+// Add a Set-Cookie header
+response.addCookie(ResponseCookie("session", "abc123"))
+```
+
+Full control:
+
+```scala
+import zio.http._
+
+val jsonBody = Body.fromString("""{"message":"created"}""", Charset.UTF8)
+
+val response = Response(
+  status = Status.Created,
+  headers = Headers(
+    "content-type" -> "application/json",
+    "location" -> "/users/123"
+  ),
+  body = jsonBody,
+  version = Version.`HTTP/1.1`
+)
+```
+
+### Accessing Response Data
+
+```scala
+import zio.http._
+import zio.http.{headers => h}
+
+val response = Response.ok
+
+response.status.code                      // 200
+response.status.isSuccess                 // true
+response.contentType                      // Option[ContentType]
+response.header(h.ContentType)       // Option[h.ContentType]
+response.header(h.Location)          // Option[h.Location]
+```
+
+## Advanced Usage
+
+### Building a Complete HTTP Exchange
+
+```scala
+import zio.http._
+
+// Build request
+val url = URL.parse("https://api.example.com/users").toOption.get
+val requestBody = Body.fromString("""{"name":"Alice","age":30}""", Charset.UTF8)
+
+val request = Request(
+  method = Method.POST,
+  url = url,
+  headers = Headers(
+    "content-type" -> "application/json",
+    "authorization" -> "Bearer abc123",
+    "user-agent" -> "MyClient/1.0"
+  ),
+  body = requestBody,
+  version = Version.`HTTP/1.1`
+)
+
+// Build response
+val responseBody = Body.fromString("""{"id":123,"name":"Alice","age":30}""", Charset.UTF8)
+
+val response = Response(
+  status = Status.Created,
+  headers = Headers(
+    "content-type" -> "application/json",
+    "location" -> "/users/123"
+  ),
+  body = responseBody,
+  version = Version.`HTTP/1.1`
+)
+```
+
+### URL Building with Fluent API
+
+```scala
+import zio.http._
+
+val url = URL.parse("https://api.example.com").toOption.get
+
+val extended = (url / "v1" / "users" / "123") ?? ("include", "profile") ?? ("include", "posts")
+
+extended.encode
+// "https://api.example.com/v1/users/123?include=profile&include=posts"
+```
+
+### Typed Header Access
+
+```scala
+import zio.http._
+import zio.http.{headers => h}
+
+val headers = Headers(
+  "content-type" -> "application/json; charset=utf-8",
+  "content-length" -> "1024",
+  "authorization" -> "Bearer token"
+)
+
+// Type-safe header access with parsing
+val ct = headers.get(h.ContentType)
+ct.map(_.value.charset)  // Some(Some(Charset.UTF8))
+
+val cl = headers.get(h.ContentLength)
+cl.map(_.length)  // Some(1024)
+
+// Raw access
+headers.rawGet("authorization")  // Some("Bearer token")
+```
+
+### Cookie Management
+
+```scala
+import zio.http._
+import zio.blocks.chunk.Chunk
+
+// Parse cookies from request header
+val cookieHeader = "session=abc; theme=dark"
+val requestCookies = Cookie.parseRequest(cookieHeader)
+
+// Create response with Set-Cookie headers
+val sessionCookie = ResponseCookie(
+  name = "session",
+  value = "xyz123",
+  path = Some(Path("/")),
+  maxAge = Some(3600),
+  isSecure = true,
+  isHttpOnly = true,
+  sameSite = Some(SameSite.Strict)
+)
+
+val response = Response(
+  status = Status.Ok,
+  headers = Headers(
+    "set-cookie" -> Cookie.renderResponse(sessionCookie)
+  ),
+  body = Body.empty
+)
+```
+
+### Form Submission
+
+```scala
+import zio.http._
+
+val form = Form(
+  "username" -> "alice",
+  "password" -> "secret",
+  "remember" -> "true"
+)
+
+val formBody = Body.fromString(form.encode, Charset.UTF8)
+
+val request = Request(
+  method = Method.POST,
+  url = URL.parse("/login").toOption.get,
+  headers = Headers(
+    "content-type" -> "application/x-www-form-urlencoded"
+  ),
+  body = formBody,
+  version = Version.`HTTP/1.1`
+)
+```
+
+## Design Principles
+
+### Single Encoding Contract
+
+`Path` and `QueryParams` store decoded values internally. Encoding happens only at output boundaries:
+
+- `Path.fromEncoded(s)` decodes, stores decoded segments
+- `Path.encode` encodes segments for transmission
+- `QueryParams.fromEncoded(s)` decodes, stores decoded key-value pairs
+- `QueryParams.encode` encodes for transmission
+
+This eliminates double-encoding bugs and clarifies responsibilities.
+
+### Lazy Header Parsing
+
+`Headers` stores raw string values and parses typed headers on first access. Parsed results are cached in a parallel `Array[AnyRef]` for O(1) subsequent lookups. This design:
+
+- Avoids parsing headers that are never accessed
+- Avoids re-parsing the same header multiple times
+- Supports unknown/custom headers without parsing failures
+
+### No Streaming
+
+Bodies are fully materialized `Chunk[Byte]`. Streaming is left to higher-level HTTP libraries that compose with this data model. This keeps the model simple and effect-free.
+
+### Zero ZIO Dependency
+
+The module uses `zio.blocks.chunk.Chunk` instead of `zio.Chunk`, making it usable in any Scala project without ZIO.
+
+## Schema-Based Typed Access (zio-http-model-schema)
+
+The `zio-http-model-schema` module provides schema-based extraction of query parameters and headers with automatic decoding and validation.
+
+### Installation
+
+Add the following to your `build.sbt`:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-http-model-schema" % "<version>"
+```
+
+For cross-platform projects (Scala.js):
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-http-model-schema" % "<version>"
+```
+
+### Imports
+
+Import the schema module to enable extension methods:
+
+```scala
+import zio.http.schema._
+import zio.blocks.schema.Schema
+```
+
+### Query Parameter Extraction
+
+`QueryParams` gains schema-based extraction methods via implicit conversions:
+
+```scala
+import zio.http.{QueryParams, URL}
+import zio.http.schema._
+import zio.blocks.schema.Schema
+
+val url = URL.parse("/api/users?page=2&tag=scala&tag=fp").toOption.get
+val params = url.queryParams
+
+// Extract single value with automatic decoding
+params.query[Int]("page")
+// Right(2)
+
+// Extract all values for a key
+params.queryAll[String]("tag")
+// Right(Chunk("scala", "fp"))
+
+// Extract with default fallback
+params.queryOrElse[Int]("limit", 10)
+// 10 - uses default since "limit" not present
+```
+
+### Header Extraction
+
+`Headers` gains schema-based extraction methods:
+
+```scala
+import zio.http.{Headers, Request, URL}
+import zio.http.schema._
+import zio.blocks.schema.Schema
+
+val request = Request.get(URL.parse("/").toOption.get)
+  .addHeader("x-page", "5")
+  .addHeader("x-tag", "scala")
+  .addHeader("x-tag", "functional")
+
+val headers = request.headers
+
+// Extract single header value
+headers.header[Int]("x-page")
+// Right(5)
+
+// Extract all header values
+headers.headerAll[String]("x-tag")
+// Right(Chunk("scala", "functional"))
+
+// Extract with default fallback
+headers.headerOrElse[Int]("x-limit", 100)
+// 100
+```
+
+### Request and Response Extensions
+
+`Request` and `Response` gain schema-based extraction methods that delegate to their query parameters and headers:
+
+```scala
+import zio.http.{Request, Response, URL}
+import zio.http.schema._
+import zio.blocks.schema.Schema
+
+// Request query parameter extraction
+val request = Request.get(URL.parse("/search?q=zio&limit=20").toOption.get)
+
+request.query[String]("q")
+// Right("zio")
+
+request.query[Int]("limit")
+// Right(20)
+
+// Response header extraction via schema
+val response = Response.ok.addHeader("x-correlation-id", "abc-123")
+
+val responseOps = new ResponseSchemaOps(response)
+responseOps.header[String]("x-correlation-id")
+```
+
+### Error Handling
+
+Schema-based extraction returns `Either[QueryParamError, A]` or `Either[HeaderError, A]` for explicit error handling:
+
+```scala
+import zio.http.{QueryParams, URL}
+import zio.http.schema._
+import zio.blocks.schema.Schema
+
+val params = QueryParams("name" -> "Alice", "age" -> "invalid")
+
+params.query[String]("name") match {
+  case Right(name) => println(s"Name: $name")
+  case Left(QueryParamError.Missing(key)) => println(s"Missing key: $key")
+  case Left(QueryParamError.Malformed(key, value, cause)) =>
+    println(s"Failed to parse $key=$value: $cause")
+}
+
+params.query[Int]("age") match {
+  case Right(age) => println(s"Age: $age")
+  case Left(QueryParamError.Missing(key)) => println(s"Missing key: $key")
+  case Left(QueryParamError.Malformed(key, value, cause)) =>
+    println(s"Failed to parse $key=$value: $cause")
+}
+```
+
+### Supported Types
+
+The schema module provides built-in `Schema` instances for common types. Any type with a `Schema[T]` can be extracted:
+
+- **Primitives**: `String`, `Int`, `Long`, `Boolean`, `Double`, `Float`, `Short`, `Byte`, `Char`
+- **Big Numbers**: `BigInt`, `BigDecimal`
+- **UUID**: `java.util.UUID`
+
+For custom types, define a `Schema[T]` instance using schema derivation or manual construction.