zio.blocks.endpoint

package zio.blocks.endpoint

Members list

Type members

Classlikes

trait Alternator[L, R]

Endpoint-local adapter for fallback output shapes.

Endpoint-local adapter for fallback output shapes.

The endpoint AST stores one abstraction that can be backed by either zio.blocks.combinators.Eithers on all Scala versions or zio.blocks.combinators.Unions on Scala 3. This keeps HttpCodec.Fallback and auth/error composition platform-agnostic while still delegating all combine / separate logic to the combinators block library.

Attributes

Companion
object
Source
Alternator.scala
Supertypes
class Object
trait Matchable
class Any
object Alternator

Attributes

Companion
trait
Source
Alternator.scala
Supertypes
class Object
trait Matchable
class Any
Self type
Alternator.type
object AuthType

Attributes

Companion
trait
Source
AuthType.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
AuthType.type
sealed trait AuthType

Authentication scheme descriptor aligned with zio-http's typed auth model.

Authentication scheme descriptor aligned with zio-http's typed auth model.

When authentication fails, the default response status is Status.NotFound rather than Status.Unauthorized. This is an intentional security pattern (information hiding) that avoids revealing whether a protected resource exists. Override unauthorizedStatus with withUnauthorizedStatus if you want standard 401 Unauthorized behavior instead.

Attributes

Companion
object
Source
AuthType.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Basic
object Bearer
class Custom[ClientReq]
object Digest
object None
class Or[ClientReq1, ClientReq2, ClientReq]
class Scoped[ClientReq]
class WithStatus[ClientReq]
Show all
Self type
case object BuildInfo

This object was generated by sbt-buildinfo.

This object was generated by sbt-buildinfo.

Attributes

Source
BuildInfo.scala
Supertypes
trait Singleton
trait Product
trait Mirror
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Self type
BuildInfo.type
object CodecKind

Attributes

Companion
trait
Source
HttpCodec.scala
Supertypes
class Object
trait Matchable
class Any
Self type
CodecKind.type
sealed trait CodecKind

Phantom type for codec direction.

Phantom type for codec direction.

Attributes

Companion
object
Source
HttpCodec.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait Request
trait Response
object Endpoint

Attributes

Companion
class
Source
Endpoint.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
Endpoint.type
final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](route: RoutePattern[PathInput], input: HttpCodec[Request, Input], error: HttpCodec[Response, Err], output: HttpCodec[Response, Output], auth: Auth, doc: Doc)

Top-level endpoint descriptor. Combines a route pattern with input/output/error HTTP codecs, authentication, and documentation.

Top-level endpoint descriptor. Combines a route pattern with input/output/error HTTP codecs, authentication, and documentation.

Pure data — no implement* methods, no Invocation, no codec errors.

Choosing an out overload — pick the row matching what the response needs:

| want status?          | want media-type? | call                                 |
|-----------------------|------------------|--------------------------------------|
| no (defaults to 200)  | no               | out(schema)                          |
| no (defaults to 200)  | no (+ docs)      | out(schema, doc)                     |
| yes                   | no               | out(status, schema)                  |
| no (defaults to 200)  | yes              | out(mediaType, schema)               |
| yes (+ docs)          | no (+ docs)      | out(status, schema, doc)             |
| no (defaults to 200)  | yes (+ docs)     | out(mediaType, schema, doc)          |
| yes                   | yes              | out(status, mediaType, schema)       |
| yes (+ docs)          | yes (+ docs)     | out(status, mediaType, schema, doc)  |
| (already a codec)     | (already a codec)| out(codec)                           |

Only the out(schema) / out(schema, doc) / out(mediaType, ...) rows default the status to 200 Ok; every overload that takes an explicit status uses exactly that status. The outError / orOutError overloads mirror these rows but always require an explicit status (errors never default to Ok).

Attributes

Companion
object
Source
Endpoint.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object EndpointUnionErrorBuilder

Attributes

Source
EndpointUnionErrorBuilder.scala
Supertypes
class Object
trait Matchable
class Any
Self type
sealed trait HttpCodec[+K <: CodecKind, A]

Composable typed descriptor for HTTP request/response parts.

Composable typed descriptor for HTTP request/response parts.

Most nodes are plain data carrying schemas plus endpoint metadata directly on the atom (doc, examples, deprecated) instead of wrapping in extra annotation layers. Typed header and auth helpers reuse Schema.transform so the descriptor can keep exposing Schema[A] for parsed header values without introducing dedicated interpreter-only AST nodes.

Attributes

Companion
object
Source
HttpCodec.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Body[K, A]
class Combine[K, A, B, C]
object Empty
class Fallback[K, A, B, C]
class Header[K, A]
class Query[A]
class StatusCodec
Show all
Self type
HttpCodec[K, A]
object HttpCodec

Attributes

Companion
trait
Source
HttpCodec.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
HttpCodec.type
sealed trait PathCodec[A]

Composable path descriptor. Segments are combined with / or ++, literal alternatives with orElse. Use decode / format for bidirectional path conversion, and alternatives to expand orElse branches for routing-trie insertion.

Composable path descriptor. Segments are combined with / or ++, literal alternatives with orElse. Use decode / format for bidirectional path conversion, and alternatives to expand orElse branches for routing-trie insertion.

Attributes

Companion
object
Source
PathCodec.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Concat[A, B, C]
class Fallback
class Ignored[A]
class Segment[A]
class Transform[A, B]
Self type
object PathCodec

Attributes

Companion
trait
Source
PathCodec.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
PathCodec.type
object RoutePattern

Attributes

Companion
class
Source
RoutePattern.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class RoutePattern[A](method: Method, pathCodec: PathCodec[A], doc: Doc = ...)

HTTP method paired with a typed path pattern. The primary constructor is Method.GET / "users" / PathCodec.int("id"). Use alternatives to expand orElse branches, RoutePattern.any(Method) or RoutePattern.any for catch-all trailing routes, and nest to prepend a path prefix.

HTTP method paired with a typed path pattern. The primary constructor is Method.GET / "users" / PathCodec.int("id"). Use alternatives to expand orElse branches, RoutePattern.any(Method) or RoutePattern.any for catch-all trailing routes, and nest to prepend a path prefix.

Attributes

Companion
object
Source
RoutePattern.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object RouteTree

Attributes

Companion
class
Source
RouteTree.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
RouteTree.type
final case class RouteTree[A](roots: Map[Method, SegmentSubtree[A]])

Routing trie keyed by HTTP method, then by path segments. Literals are matched first, then dynamic segments in priority order (int > long > uuid > bool > string > combined > trailing). HEAD requests fall back to GET handlers. Merge prefers right-hand-side values on conflict.

Routing trie keyed by HTTP method, then by path segments. Literals are matched first, then dynamic segments in priority order (int > long > uuid > bool > string > combined > trailing). HEAD requests fall back to GET handlers. Merge prefers right-hand-side values on conflict.

Trailing fallback: when the path segments are exhausted at a level with no exact value, lookup falls through to a Trailing branch below that level — so a trailing route also matches its own prefix path (a /assets/... route matches /assets), and it shadows a missing exact match at that level. This is intentional (a trailing route is a prefix catch-all by design): register exact routes alongside trailing ones when both must coexist. Literals are still tried first at every level that has segments left, and per-branch matching itself never allocates (see SegmentCodec.matches).

Attributes

Companion
object
Source
RouteTree.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Self type
sealed trait SegmentCodec[A]

Typed descriptor for a single URL path segment. Subtypes include Literal, Int, String, Combined (intra-segment composition via ~), and Trailing (captures remaining path).

Typed descriptor for a single URL path segment. Subtypes include Literal, Int, String, Combined (intra-segment composition via ~), and Trailing (captures remaining path).

Combine representation first, then transform: ~ composes only physical SegmentCodec structure, while transform / transformOrFail lift the segment into a PathCodec (making ~ unavailable afterwards — a transformed wire codec is a domain value, not intra-segment structure).

Attributes

Companion
object
Source
SegmentCodec.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class BoolSeg[N]
class Combined[A, B, C]
object Empty
class IntSeg[N]
class Literal
class LongSeg[N]
class StringSeg[N]
object Trailing
class UUIDSeg[N]
Show all
Self type
object SegmentCodec

Attributes

Companion
trait
Source
SegmentCodec.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class SegmentSubtree[A](literals: Map[String, SegmentSubtree[A]], others: ListMap[Key, (SegmentCodec[_], SegmentSubtree[A])], value: Option[A])

A single level of the routing trie. literals holds exact-match branches, others holds dynamic segment branches keyed by SegmentCodec.Key and ordered by match priority.

A single level of the routing trie. literals holds exact-match branches, others holds dynamic segment branches keyed by SegmentCodec.Key and ordered by match priority.

Attributes

Companion
object
Source
RouteTree.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Self type
object SegmentSubtree

Attributes

Companion
class
Source
RouteTree.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type

Value members

Concrete methods

transparent inline def endpoints(inline body: Any): Any

Defines a group of HTTP endpoints in a single block and returns them as a statically-typed scala.NamedTuple.

Defines a group of HTTP endpoints in a single block and returns them as a statically-typed scala.NamedTuple.

Each statement in the block must be either:

  • val name = Endpoint(...) — exposed as member .name
  • a bare Endpoint(...) expression — auto-named from its route render, e.g. .`GET /user/{userId}` (RFC 6570 {var} style, method prefix, multi-method rendered as GET#|POST)

Constant-prefix nesting ("api" / endpoints { ... }) composes prefixes into every child route at the description level. Capturing prefixes (PathCodec.int("id") / endpoints { ... }) additionally widen each child's static PathInput.

Value parameters

body

the block of endpoint declarations; every statement must be an Endpoint(...) construction, optionally bound to a val

Attributes

Returns

a NamedTuple[Names, Values] pairing each declared name with its fully-typed Endpoint

Note

Scala 3.7+ only (named tuples); prefix grouping ("api" / endpoints { ... } or PathCodec.int("id") / endpoints { ... }) is available via import zio.blocks.endpoint.* (no extra import required).

Source
EndpointGroupSyntax.scala

Extensions

Extensions

extension [A](codec: PathCodec[A])
transparent inline def /[N <: Tuple, V <: Tuple](inline nt: NamedTuple[N, V]): Any

Symbolic alias for nest — codec / endpoints { ... }.

Symbolic alias for nest — codec / endpoints { ... }.

Attributes

Source
EndpointGroupSyntax.scala
transparent inline def nest[N <: Tuple, V <: Tuple](inline nt: NamedTuple[N, V]): Any

Prefix a bulk group with a capturing path codec — named alias for /.

Prefix a bulk group with a capturing path codec — named alias for /.

Value parameters

nt

the endpoints { ... } group

Attributes

Returns

the same group with codec's segment prepended to every leaf; static PathInput is widened positionally (e.g. Int prefix + Int child yields (Int, Int))

Source
EndpointGroupSyntax.scala