@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/reference/endpoint/auth-type.md

@@ -0,0 +1,146 @@
+---
+id: auth-type
+title: "AuthType"
+---
+
+`AuthType` is a sealed trait that describes an HTTP authentication scheme as a first-class type parameter on `Endpoint`. Each `AuthType` variant carries an associated type `ClientRequirement` — the type of credential the client must provide — and a codec that extracts it from the request. Its definition is:
+
+```scala
+sealed trait AuthType {
+  type ClientRequirement
+  def codec: HttpCodec[CodecKind.Request, ClientRequirement]
+  def unauthorizedStatus: Status
+}
+```
+
+## Motivation
+
+Authentication requirements are often encoded informally — a comment in the handler, a middleware convention, or a bare string header check. `AuthType` makes the auth requirement part of the endpoint's static type. A bearer-secured endpoint has type `Endpoint[..., AuthType.Bearer]`, which means:
+
+- The `auth.codec` field is typed as `HttpCodec[CodecKind.Request, zio.http.Header.Authorization.Bearer]`, not `HttpCodec[..., String]`.
+- Interpreters (server, client, OpenAPI) can inspect the auth type without stringly-typed reflection.
+- Composing auth types with `|` produces a union that the compiler verifies is discriminated.
+
+## Built-in Variants
+
+Each built-in variant maps to a specific HTTP authorization scheme. Use the one that matches your API's authentication model.
+
+### `AuthType.None`
+
+The default auth type — no authentication required. Its `ClientRequirement` is `Unit` and its codec is `HttpCodec.Empty`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val publicEndpoint = Endpoint(Method.GET / "health")
+```
+
+### `AuthType.Basic`
+
+HTTP Basic authentication. The `ClientRequirement` is `zio.http.Header.Authorization.Basic`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val basicEndpoint = Endpoint(Method.GET / "admin")
+  .auth(AuthType.Basic)
+
+val codec = basicEndpoint.auth.codec
+```
+
+### `AuthType.Bearer`
+
+Bearer token authentication (OAuth 2.0 / JWT). The `ClientRequirement` is `zio.http.Header.Authorization.Bearer`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val bearerEndpoint = Endpoint(Method.GET / "me")
+  .auth(AuthType.Bearer)
+```
+
+### `AuthType.Digest`
+
+HTTP Digest authentication. The `ClientRequirement` is `zio.http.Header.Authorization.Digest`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val digestEndpoint = Endpoint(Method.GET / "secure")
+  .auth(AuthType.Digest)
+```
+
+### `AuthType.Custom`
+
+For authentication schemes not covered by the built-in variants, `Custom` wraps any `HttpCodec[CodecKind.Request, ClientReq]`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+final case class ApiKey(value: String)
+
+val apiKeyCodec = HttpCodec.requestHeader("X-Api-Key", Schema.string.transform[ApiKey](ApiKey(_), _.value))
+val apiKeyAuth  = AuthType.Custom(apiKeyCodec)
+val keyEndpoint = Endpoint(Method.GET / "data").auth(apiKeyAuth)
+```
+
+## Composition
+
+`AuthType` values compose in two ways: `|` builds an OR alternative that accepts either scheme, and `Scoped` attaches scope requirements to an existing auth type.
+
+### `AuthType#|` — OR composition
+
+Two `AuthType` values can be combined with `|` to accept either scheme. The result is an `AuthType.Or` whose `ClientRequirement` is the union of both:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val flexEndpoint = Endpoint(Method.GET / "resource")
+  .auth(AuthType.Basic | AuthType.Bearer)
+```
+
+The `|` operator automatically computes the combined `ClientRequirement` type as a union of both requirements. The codec of the resulting `Or` is a `HttpCodec.Fallback` — it tries the left scheme first and falls back to the right.
+
+### `AuthType.Scoped`
+
+To attach OAuth scope requirements to a bearer auth, wrap it in `AuthType.Scoped`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val scopedEndpoint = Endpoint(Method.GET / "admin")
+  .auth(AuthType.Scoped(AuthType.Bearer, List("admin:read", "admin:write")))
+```
+
+`Scoped` does not change the codec — it carries the scopes as metadata for interpreters that perform scope-level authorization checks.
+
+## Unauthorized Status
+
+By default, `AuthType` returns `Status.NotFound` when the client does not meet the auth requirement (to avoid leaking endpoint existence). To change this, use `Endpoint#unauthorizedStatus` or call `AuthType#withUnauthorizedStatus` directly:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Status}
+
+val endpoint = Endpoint(Method.GET / "me")
+  .auth(AuthType.Bearer)
+  .unauthorizedStatus(Status.Unauthorized)
+```
+
+`Or` composition preserves `AuthType#unauthorizedStatus` — it uses the left auth type's status.

package/reference/endpoint/bulk-creation.md

@@ -0,0 +1,96 @@
+---
+id: bulk-creation
+title: "Bulk Endpoint Creation"
+---
+
+## Bulk endpoint creation with `endpoints { ... }`
+
+The `endpoints` macro (Scala 3.8+ with `-experimental` for `NamedTuple`, also works on Scala 3.7 with `-experimental`) lets you define multiple `Endpoint` values in a block and access them by name on the returned `NamedTuple`. Member names are either explicit `val` names or auto-generated from the `RoutePattern.render` string (method prefix + path template). Prefix grouping via `/` (`"api" / endpoints { ... }`, `PathCodec.int("id") / endpoints { ... }`) is available via the default `import zio.blocks.endpoint.*` — no extra import is needed. All examples below assume `import zio.blocks.endpoint.*` and `scalacOptions += "-experimental"`.
+
+String prefixes such as `"api"` are auto-converted to a literal `PathCodec[Unit]` via a `Conversion[String, PathCodec[Unit]]` provided by `zio.blocks.endpoint.*` — there is no String-specific `/` operator; constant prefixes auto-convert and use the same grouping `/` as capturing prefixes.
+
+> **Inline-only:** prefix grouping (`prefix / endpoints { ... }`) requires an inline `endpoints { ... }` block. Binding the group to a value first (`val g = endpoints { ... }; "api" / g`) is not supported — the macro must see the block literal to compose prefixes.
+
+```scala
+import zio.blocks.endpoint.*
+import zio.blocks.endpoint.RoutePattern.*
+import zio.http.Method
+
+val api = "api" / endpoints {
+  val customer = Endpoint(Method.GET / "customers")
+  Endpoint(Method.GET / "health")
+}
+```
+
+Member access is static (zero runtime cost):
+
+```scala
+import zio.blocks.endpoint.*
+import zio.blocks.endpoint.RoutePattern.*
+import zio.http.Method
+
+val api = "api" / endpoints {
+  val customer = Endpoint(Method.GET / "customers")
+  Endpoint(Method.GET / "health")
+}
+val c: Endpoint[Unit, Unit, Unit, Unit, AuthType.None.type] = api.customer
+val h: Endpoint[Unit, Unit, Unit, Unit, AuthType.None.type] = api.`GET /health`
+```
+
+Auto-naming follows `RoutePattern.render` exactly:
+
+- `GET /user/{userId}` for path variables (RFC 6570 `{var}`)
+- `GET#|POST /orders` for multi-method
+- `v{major}` for `~` concat segments
+- `...` for trailing segments
+- `.unused` renders as `{name}`
+
+Constant-prefix nesting bakes the prefix into each child's `RoutePattern` at the description level; grouping nodes have no path themselves:
+
+```scala
+import zio.blocks.endpoint.*
+import zio.blocks.endpoint.RoutePattern.*
+import zio.http.Method
+
+val nested = "api" / endpoints {
+  "v1" / endpoints {
+    val users = Endpoint(Method.GET / "users")
+  }
+}
+val u = nested.v1.users // route.render == "GET /api/v1/users"
+```
+
+Path-variable prefixes are implemented the same way. A capturing prefix contributes its segment to every child's path, while children keep their relative auto-names:
+
+```scala
+import zio.blocks.endpoint.*
+import zio.blocks.endpoint.RoutePattern.*
+import zio.http.Method
+
+val byId = PathCodec.int("id") / endpoints {
+  val get = Endpoint(Method.GET / "orders")
+  Endpoint(Method.DELETE / "orders") // auto-named `DELETE /orders`
+}
+
+val getOrder: Endpoint[Int, Unit, Unit, Unit, AuthType.None.type] = byId.get
+val delOrder = byId.`DELETE /orders`
+```
+
+Both children carry the captured segment: `byId.get.route.render == "GET /{id}/orders"` and the auto-named member renders `"DELETE /{id}/orders"`. Static types are preserved — `byId.get` is an `Endpoint[Int, Unit, Unit, Unit, AuthType.None.type]`, so the captured `id` will be delivered to handlers when routes are created on the zio-http side. A child with its own path variables composes positionally: under `int("id")`, `Endpoint(Method.GET / "orders" / PathCodec.int("orderId"))` renders as `GET /{id}/orders/{orderId}` and carries `(Int, Int)`:
+
+```scala
+import zio.blocks.endpoint.*
+import zio.blocks.endpoint.RoutePattern.*
+import zio.http.Method
+
+val ordersById = PathCodec.int("id") / endpoints {
+  val o = Endpoint(Method.GET / "orders" / PathCodec.int("orderId"))
+}
+
+val lookup: Endpoint[(Int, Int), Unit, Unit, Unit, AuthType.None.type] = ordersById.o
+// lookup.route.render == "GET /{id}/orders/{orderId}"
+```
+
+Variable prefixes should be bound to an explicit `val` — the val names the subgroup whose members you access through it (`byId.get`, `ordersById.o`). Constant-prefix and capturing-prefix subgroups can be freely nested inside each other: `"api" / endpoints { PathCodec.int("id") / endpoints { ... } }` composes both prefixes into every leaf route at compile time.
+
+The returned type is a Scala 3 `NamedTuple` — static member access, erased at runtime. The DSL is Scala 3 only (3.7+ with `-experimental` for named tuples). All examples above compile against the `endpoint` module on Scala 3.8.3 with `scalacOptions += "-experimental"`.

package/reference/endpoint/endpoint.md

@@ -0,0 +1,297 @@
+---
+id: endpoint
+title: "Endpoint"
+---
+
+`Endpoint[PathInput, Input, Err, Output, Auth]` is the top-level descriptor for an HTTP endpoint. It holds a typed route, three independent codec channels (request input, error output, success output), an authentication type, and documentation metadata. `Endpoint` is pure data — it carries no server or client logic and imposes no effect type. Its full shape is:
+
+```scala
+final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
+  route: RoutePattern[PathInput],
+  input: HttpCodec[CodecKind.Request, Input],
+  error: HttpCodec[CodecKind.Response, Err],
+  output: HttpCodec[CodecKind.Response, Output],
+  auth: Auth,
+  doc: Doc
+)
+```
+
+## Motivation
+
+An endpoint descriptor separates the **shape** of an HTTP surface from its **execution**. A single `Endpoint` value can be interpreted by a server to generate routes, by a client generator to produce typed API calls, or by an OpenAPI renderer to produce specification documents. This means the endpoint definition is the single source of truth — change it once and every interpreter updates.
+
+The five type parameters track everything the compiler needs to enforce consistency across the whole stack:
+
+| Parameter   | Meaning                                                    |
+|-------------|------------------------------------------------------------|
+| `PathInput` | Type of values extracted from path segments                |
+| `Input`     | Aggregate type of all request inputs (query, header, body) |
+| `Err`       | Aggregate type of all error response shapes                |
+| `Output`    | Aggregate type of all success response shapes              |
+| `Auth`      | Authentication scheme, carries the client requirement      |
+
+## Construction
+
+We create an `Endpoint` from a `RoutePattern` using `Endpoint.apply`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users" / PathCodec.int("id"))
+```
+
+The route can also be built from a separate `RoutePattern` value:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val route = Method.POST / "orders" / PathCodec.uuid("orderId")
+val ep    = Endpoint(route)
+```
+
+The initial `Endpoint` starts with `Unit` for all three codec channels and `AuthType.None` for auth, so further builder calls always widen the types additively.
+
+## Request Input Builders
+
+Every `Endpoint#in`, `Endpoint#query`, and `Endpoint#header` call adds another input component to the endpoint, widening the `Input` type parameter.
+
+### Body input
+
+To add a request body typed by a `Schema`, use `Endpoint#in`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.POST / "users")
+  .in(Schema.string)
+```
+
+To specify the content type explicitly, pass a `MediaType` as well:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.mediatype.MediaTypes
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.POST / "users")
+  .in(MediaTypes.application.`json`, Schema.string)
+```
+
+To add a raw `HttpCodec.Body` node directly, use `Endpoint#in`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.POST / "users")
+  .in(HttpCodec.requestBody(Schema.string))
+```
+
+### Query parameters
+
+To add a query parameter by name and schema, use `Endpoint#query`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .query("page", Schema.int)
+  .query("limit", Schema.int)
+```
+
+To add a pre-built `HttpCodec.Query` node, use `Endpoint#query`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val pageCodec = HttpCodec.query("page", Schema.int)
+val ep        = Endpoint(Method.GET / "users").query(pageCodec)
+```
+
+### Request headers
+
+To add a request header by name and schema, use `Endpoint#header`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .header("X-Trace-Id", Schema.string)
+```
+
+To add a pre-built `HttpCodec.Header` node, use `Endpoint#header`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val traceCodec = HttpCodec.requestHeader("X-Trace-Id", Schema.string)
+val ep         = Endpoint(Method.GET / "users").header(traceCodec)
+```
+
+## Success Output Builders
+
+Every `Endpoint#out` and `Endpoint#outHeader` call adds a success response alternative or header component, widening `Output`.
+
+### Response body
+
+To add a 200 OK response body, use `Endpoint#out`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .out(Schema.string)
+```
+
+To specify a non-200 status code, use `Endpoint#out` with a `Status`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.{Method, Status}
+
+val ep = Endpoint(Method.POST / "users")
+  .out(Status.Created, Schema.int)
+```
+
+To add content-type negotiation, pass a `MediaType`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.mediatype.MediaTypes
+import zio.blocks.schema.Schema
+import zio.http.{Method, Status}
+
+val ep = Endpoint(Method.GET / "users")
+  .out(MediaTypes.application.`json`, Schema.string)
+  .out(Status.Created, MediaTypes.text.`plain`, Schema.int)
+```
+
+Multiple `Endpoint#out` calls produce alternatives. The output type widens from `Unit` to the first schema type, then to a nested `Either` for each additional alternative.
+
+### Response headers
+
+To add a typed response header, use `Endpoint#outHeader`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .out(Schema.string)
+  .outHeader("X-Total-Count", Schema.int)
+```
+
+## Error Output Builders
+
+Error channels work like success channels but populate the `Err` type parameter. Two variants exist: `Endpoint#outError` (cross-version) and `Endpoint#orOutError` (Scala 3 unions).
+
+### `Endpoint#outError` — cross-version additive errors
+
+To add an error response with a status code and body schema, use `Endpoint#outError`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.{Method, Status}
+
+val ep = Endpoint(Method.GET / "users")
+  .out(Schema.string)
+  .outError(Status.NotFound, Schema.string)
+  .outError(Status.BadRequest, Schema.string)
+```
+
+Each `Endpoint#outError` call widens `Err` by one nested `Either` layer.
+
+### `Endpoint#orOutError` — Scala 3 union errors
+
+On Scala 3, `Endpoint#orOutError` accumulates error types as a native union type instead of nested `Either`s. The first call replaces the initial `Unit` error outright; subsequent calls build a `Fallback` codec backed by `Unions` derivation:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.{Method, Status}
+
+val ep = Endpoint(Method.GET / "users")
+  .orOutError(Status.NotFound, Schema.string)
+  .orOutError(Status.Conflict, Schema.int)
+
+val typed: Endpoint[Unit, Unit, String | Int, Unit, AuthType.None.type] = ep
+```
+
+The compiler rejects overlapping union members — two `Endpoint#orOutError` calls both using `Schema.string` produce a compile error because `String | String` is not a valid discriminated union.
+
+## Authentication
+
+To attach an authentication scheme, use `Endpoint#auth`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val secured = Endpoint(Method.GET / "me")
+  .auth(AuthType.Bearer)
+```
+
+The `Auth` type parameter carries the `ClientRequirement` associated type, so a bearer-secured endpoint exposes `auth.codec` typed as `HttpCodec[CodecKind.Request, zio.http.Header.Authorization.Bearer]`. See [AuthType](./auth-type.md) for all variants.
+
+To override the HTTP status the server sends when the client does not meet the auth requirement, use `Endpoint#unauthorizedStatus`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Status}
+
+val secured = Endpoint(Method.GET / "me")
+  .auth(AuthType.Bearer)
+  .unauthorizedStatus(Status.Unauthorized)
+```
+
+## Documentation
+
+To attach a `Doc` value to the endpoint as a whole, use `Endpoint#doc`:
+
+```scala
+import zio.blocks.docs.Doc
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .doc(Doc.empty)
+```
+
+Documentation attached here flows through to OpenAPI generation and any other documentation interpreters.