or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

http-methods.mdindex.mdpath-matching.mdresponse-generation.md
tile.json

tessl/maven-org-http4s--http4s-dsl_3

Simple DSL for writing http4s services with idiomatic Scala pattern matching for requests and responses

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.http4s/http4s-dsl_3@0.23.x

To install, run

npx @tessl/cli install tessl/maven-org-http4s--http4s-dsl_3@0.23.0

index.mddocs/

Http4s DSL

Http4s DSL provides a simple, expressive domain-specific language for building HTTP services in Scala. It offers idiomatic Scala constructs for handling HTTP requests and responses, including pattern matching on request methods, paths, and query parameters. The DSL enables developers to write clean, composable HTTP route definitions using familiar Scala syntax.

Package Information

  • Package Name: org.http4s:http4s-dsl_3
  • Package Type: maven
  • Language: Scala 3
  • Installation: libraryDependencies += "org.http4s" %% "http4s-dsl" % "0.23.30"

Core Imports

import org.http4s.dsl.io._
import cats.effect.IO

For other effect types:

import org.http4s.dsl.Http4sDsl
// Create instance for your effect type F[_]
val dsl = Http4sDsl[F]
import dsl._

For effect-agnostic imports (request-only DSL):

import org.http4s.dsl.request._

Basic Usage

import org.http4s.dsl.io._
import org.http4s.HttpRoutes
import cats.effect.IO

val routes = HttpRoutes.of[IO] {
  // Simple GET route
  case GET -> Root / "hello" => 
    Ok("Hello, World!")
    
  // Path parameter extraction
  case GET -> Root / "users" / IntVar(userId) =>
    Ok(s"User ID: $userId")
    
  // Query parameter extraction
  case GET -> Root / "search" :? QueryParam("q", query) =>
    Ok(s"Search query: $query")
    
  // Multiple HTTP methods
  case req @ (GET | POST) -> Root / "api" / "data" =>
    req.method match {
      case GET => Ok("Getting data")
      case POST => Ok("Creating data")
    }
}

Architecture

The http4s DSL is built around several key components:

  • Pattern Matching: Uses Scala extractors for declarative route matching
  • Path Extractors: Composable operators for URL path decomposition (/, Root, path variables)
  • Query Parameter Matchers: Type-safe query parameter extraction and validation
  • Response Generators: Fluent API for creating HTTP responses with proper status codes
  • Effect Type Polymorphism: Works with any effect type F[_] with appropriate type class instances

Capabilities

HTTP Methods

Standard HTTP method constants for pattern matching in routes.

val GET: Method.GET.type
val POST: Method.POST.type
val PUT: Method.PUT.type
val DELETE: Method.DELETE.type
val HEAD: Method.HEAD.type
val OPTIONS: Method.OPTIONS.type
val PATCH: Method.PATCH.type
val CONNECT: Method.CONNECT.type
val TRACE: Method.TRACE.type

HTTP Methods

Path Matching and Extraction

Powerful path decomposition and parameter extraction system for building REST APIs with type-safe URL routing.

val Root: Uri.Path.Root.type
val / : impl./.type
val -> : impl.->.type
val IntVar: impl.IntVar.type
val LongVar: impl.LongVar.type
val UUIDVar: impl.UUIDVar.type

Path Matching

Response Generation

Complete HTTP status code constants and response builders for creating well-formed HTTP responses.

// Success responses
val Ok: Status.Ok.type
val Created: Status.Created.type
val NoContent: Status.NoContent.type

// Client error responses  
val BadRequest: Status.BadRequest.type
val NotFound: Status.NotFound.type
val Unauthorized: Status.Unauthorized.type

// Server error responses
val InternalServerError: Status.InternalServerError.type
val ServiceUnavailable: Status.ServiceUnavailable.type

Response Generation

Types

Core DSL Types

trait Http4sDsl[F[_]] extends Http4sDsl2[F, F] with RequestDsl {
  val liftG: FunctionK[F, F]
}

trait RequestDsl extends Methods with Auth {
  type Path = Uri.Path
  type Root = Uri.Path.Root.type
  type MethodConcat = impl.MethodConcat
  
  // Path extractors
  val Path: Uri.Path.type
  val Root: Uri.Path.Root.type
  val / : impl./.type
  val :? : impl.:?.type
  val ~ : impl.~.type
  val -> : impl.->.type
  val /: : impl./:.type
  val +& : impl.+&.type
  
  // Variable extractors
  val IntVar: impl.IntVar.type
  val LongVar: impl.LongVar.type
  val UUIDVar: impl.UUIDVar.type
}

Method Combination

class MethodConcat(val methods: Set[Method]) {
  def unapply(method: Method): Option[Method]
}

// Extension methods for combining HTTP methods
implicit class MethodOps(val method: Method) extends AnyVal {
  def |(another: Method): MethodConcat
}

implicit class MethodConcatOps(val methods: MethodConcat) extends AnyVal {
  def |(another: Method): MethodConcat  
}

Pattern Matching Extractors

// Query parameter extractor
object :? {
  def unapply[F[_]](req: Request[F]): Some[(Request[F], Map[String, collection.Seq[String]])]
}

// Method and path extractor  
object -> {
  def unapply[F[_]](req: Request[F]): Some[(Method, Path)]
}

// Path segment extractor
object / {
  def unapply(path: Path): Option[(Path, String)]
}

// File extension extractor
object ~ {
  def unapply(path: Path): Option[(Path, String)]
  def unapply(fileName: String): Option[(String, String)]
}