or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdhttp-methods-routing.mdindex.mdpath-matching.mdquery-parameters.mdstatus-codes-responses.md
tile.json

tessl/maven-org-http4s--http4s-dsl_2-13

A Domain Specific Language (DSL) for building HTTP services in Scala with type-safe route definition, status code generation, and composable request/response handling

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

To install, run

npx @tessl/cli install tessl/maven-org-http4s--http4s-dsl_2-13@0.23.0

index.mddocs/

HTTP4S DSL

The http4s-dsl package provides a Domain Specific Language (DSL) for building HTTP services in Scala. It offers intuitive syntax for route definition using pattern matching on HTTP methods and paths, status code generation through named objects, and composable request/response handling with built-in support for content negotiation and entity encoding/decoding.

Package Information

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

Core Imports

import org.http4s.dsl.io._

For custom effect types:

import cats.effect.IO
import org.http4s.dsl.Http4sDsl

// Create DSL instance for your effect type
val dsl = Http4sDsl[IO]
import dsl._

Basic Usage

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

// Define routes using pattern matching
val routes = HttpRoutes.of[IO] {
  case GET -> Root / "hello" => 
    Ok("Hello, World!")
    
  case GET -> Root / "users" / IntVar(userId) =>
    Ok(s"User ID: $userId")
    
  case POST -> Root / "users" =>
    Created("User created")
    
  case req @ POST -> Root / "data" =>
    req.as[String].flatMap { body =>
      Ok(s"Received: $body")
    }
}

Architecture

The http4s-dsl is built around several key components:

  • Pattern Matching DSL: Combines HTTP methods and path patterns for route definition
  • Status Code Generators: Type-safe response builders for all HTTP status codes
  • Path Extractors: Pattern matching utilities for URL paths and path variables
  • Query Parameter Matchers: Type-safe query string parsing and validation
  • Request Processing: Utilities for handling request bodies, headers, and authentication
  • Response Building: Fluent API for constructing HTTP responses with proper headers

Capabilities

HTTP Methods and Route Matching

Core HTTP method constants and path pattern matching for defining web service routes. Enables clean, readable route definitions using Scala's pattern matching syntax.

// HTTP Methods
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

// Route matching operators
val -> : impl.->.type  // Method and path matcher
val → : impl.->.type   // Unicode alias for ->
val ->> : impl.->>.type // Method enumeration matcher

HTTP Methods and Routing

Path Pattern Matching

Path construction and variable extraction utilities for URL routing. Provides type-safe path segment matching and variable extraction from URL paths.

// Path components
val Path: Uri.Path.type
val Root: Uri.Path.Root.type
val / : impl./.type  // Path segment separator

// Path extractors
val /: : impl./:.type  // Path head/tail extractor
val IntVar: impl.IntVar.type    // Integer path variable
val LongVar: impl.LongVar.type  // Long path variable
val UUIDVar: impl.UUIDVar.type  // UUID path variable

// File extensions
val ~ : impl.~.type  // File extension extractor

Path Pattern Matching

HTTP Status Codes and Response Generation

Complete set of HTTP status codes with fluent response generation API. Each status code provides type-safe methods for creating responses with or without bodies.

// 2xx Success responses
val Ok: Status.Ok.type
val Created: Status.Created.type
val Accepted: Status.Accepted.type
val NoContent: Status.NoContent.type

// 3xx Redirection responses
val MovedPermanently: Status.MovedPermanently.type
val Found: Status.Found.type
val SeeOther: Status.SeeOther.type
val NotModified: Status.NotModified.type

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

// 5xx Server error responses
val InternalServerError: Status.InternalServerError.type
val NotImplemented: Status.NotImplemented.type
val ServiceUnavailable: Status.ServiceUnavailable.type

Status Codes and Response Generation

Query Parameter Processing

Type-safe query parameter extraction and validation with support for optional parameters, multi-value parameters, and custom decoders.

val :? : impl.:?.type  // Query parameter extractor
val +& : impl.+&.type  // Multiple parameter combinator

// Query parameter matcher types
type QueryParamDecoderMatcher[T]
type OptionalQueryParamDecoderMatcher[T]
type QueryParamDecoderMatcherWithDefault[T]
type ValidatingQueryParamDecoderMatcher[T]
type FlagQueryParamMatcher

Query Parameter Processing

Authentication Support

Authentication context extraction utilities for working with authenticated requests and user context.

// Authentication extractor
object as {
  def unapply[F[_], A](ar: AuthedRequest[F, A]): Option[(Request[F], A)]
}

Authentication Support

Pattern Matching Utilities

Additional utilities for advanced pattern matching in route definitions.

// Conjunction extractor for pattern matching combinations
object & {
  def unapply[A](a: A): Some[(A, A)]
}

Common Types

// Core path types
type Path = Uri.Path
type Root = Uri.Path.Root.type

// Method concatenation for multiple method matching
type MethodConcat = impl.MethodConcat

// Response generator base types
trait ResponseGenerator {
  def status: Status
}

trait EntityResponseGenerator[F[_], G[_]] extends ResponseGenerator {
  def liftG: G ~> F
  def apply(): F[Response[G]]
  def apply[A](body: A, headers: Header.ToRaw*): F[Response[G]]
}