or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

http-methods.mddocs/

HTTP Methods

HTTP method constants and operations for pattern matching in http4s routes. These provide type-safe method matching and combination capabilities.

Capabilities

Standard HTTP Methods

Constants for all standard HTTP methods used in RESTful services.

/**
 * Standard HTTP method constants for pattern matching
 */
val GET: Method.GET.type
val HEAD: Method.HEAD.type  
val POST: Method.POST.type
val PUT: Method.PUT.type
val DELETE: Method.DELETE.type
val CONNECT: Method.CONNECT.type
val OPTIONS: Method.OPTIONS.type
val TRACE: Method.TRACE.type
val PATCH: Method.PATCH.type

Usage Examples:

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

val routes = HttpRoutes.of[IO] {
  case GET -> Root / "users" => 
    Ok("List users")
    
  case POST -> Root / "users" =>
    Ok("Create user")
    
  case PUT -> Root / "users" / IntVar(id) =>
    Ok(s"Update user $id")
    
  case DELETE -> Root / "users" / IntVar(id) =>
    Ok(s"Delete user $id")
}

Method Combination

Combine multiple HTTP methods for shared route handling using the | operator.

/**
 * Method combination for OR matching multiple HTTP methods
 */
final class MethodConcat(val methods: Set[Method]) {
  /** Check if the given method matches any in this combination */
  def unapply(method: Method): Option[Method]
}

final class MethodOps(val method: Method) extends AnyVal {
  /** Combine this method with another to create a MethodConcat */
  def |(another: Method): MethodConcat
}

final class MethodConcatOps(val methods: MethodConcat) extends AnyVal {
  /** Add another method to this combination */
  def |(another: Method): MethodConcat
}

Usage Examples:

import org.http4s.dsl.io._

val routes = HttpRoutes.of[IO] {
  // Handle GET or POST on the same endpoint
  case req @ (GET | POST) -> Root / "api" / "data" =>
    req.method match {
      case GET => Ok("Getting data")
      case POST => Ok("Creating data")
    }
    
  // Handle multiple methods with different logic
  case req @ (PUT | PATCH) -> Root / "users" / IntVar(id) =>
    req.method match {
      case PUT => Ok(s"Replacing user $id")
      case PATCH => Ok(s"Updating user $id")
    }
    
  // Complex method combinations
  case req @ (GET | POST | PUT) -> Root / "resources" =>
    req.method match {
      case GET => Ok("List resources")
      case POST => Created("Resource created")
      case PUT => Ok("Resource updated")
    }
}

Method-Path Extraction

Extract both HTTP method and path information from requests using the -> operator.

/**
 * HTTP method and path extractor for pattern matching
 */
object -> {
  /** Extract method and path from a request */
  def unapply[F[_]](req: Request[F]): Some[(Method, Path)]
}

/** Unicode alias for -> operator */
val → : impl.->.type

Usage Examples:

import org.http4s.dsl.io._

val routes = HttpRoutes.of[IO] {
  // Standard arrow operator
  case GET -> Root / "hello" =>
    Ok("Hello!")
    
  // Unicode arrow (lower precedence - use parentheses)
  case req @ (Method.GET → (Root / "test.json")) =>
    Ok("Test JSON")
    
  // Extract method and path separately
  case req => 
    req match {
      case method -> path =>
        Ok(s"Method: $method, Path: $path")
    }
}

Advanced Method Matching

The DSL also provides the ->> operator for comprehensive method handling with automatic error responses.

/**
 * Method enumeration extractor with automatic error responses
 */
object ->> {
  def unapply[F[_]: Applicative](
    req: Request[F]
  ): Some[(PartialFunction[Method, F[Response[F]]] => F[Response[F]], Path)]
}

Usage Examples:

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

val routes = HttpRoutes.of[IO] {
  case withMethod ->> Root / "api" / "resource" => withMethod {
    case GET => Ok("Get resource")
    case POST => Created("Created resource")
    case PUT => Ok("Updated resource")
    // Automatically returns 405 Method Not Allowed for other methods
    // with proper Allow header listing supported methods
  }
}

Error Handling

The DSL automatically handles method-related HTTP errors:

  • 405 Method Not Allowed: Returned by ->> when method is not handled, includes Allow header with supported methods
  • 501 Not Implemented: Returned by ->> for unrecognized HTTP methods

Type Safety Notes

  • All method constants are singleton types, ensuring compile-time safety
  • Method combinations preserve type information for pattern matching
  • The -> extractor works with any effect type F[_]
  • Method matching integrates seamlessly with path and query parameter extraction