core/org.http4s

org.http4s

package org.http4s

Type members

Classlikes

object AuthScheme
object AuthedRequest
object AuthedRoutes
final case class BasicCredentials(username: String, password: String, charset: Charset)
Companion:
object
object BasicCredentials
Companion:
class
case object BuildInfo

This object was generated by sbt-buildinfo.

This object was generated by sbt-buildinfo.

sealed trait CacheDirective extends Product with Renderable
Companion:
object
object CacheDirective

A registry of cache-directives, as listed in http://www.iana.org/assignments/http-cache-directives/http-cache-directives.xhtml

A registry of cache-directives, as listed in http://www.iana.org/assignments/http-cache-directives/http-cache-directives.xhtml

Companion:
class
final case class Challenge(scheme: String, realm: String, params: Map[String, String]) extends Renderable
final case class Charset extends Renderable
Companion:
object
object Charset
Companion:
class
sealed abstract class CharsetRange extends HasQValue with Renderable
Companion:
object
object CharsetRange
Companion:
class
class ContentCoding extends HasQValue with Ordered[ContentCoding] with Renderable
Companion:
object
object ContentCoding
Companion:
class
final case class ContextRequest[F[_], A](context: A, req: Request[F])
Companion:
object
object ContextRequest
Companion:
class
final case class ContextResponse[F[_], A](context: A, response: Response[F])
Companion:
object
object ContextResponse
Companion:
class
object ContextRoutes
sealed abstract class Credentials extends Renderable
Companion:
object
object Credentials
Companion:
class
trait DecodeFailure extends MessageFailure

Indicates a problem decoding a Message. This may either be a problem with the entity headers or with the entity itself.

Indicates a problem decoding a Message. This may either be a problem with the entity headers or with the entity itself.

Companion:
object
object DecodeFailure
Companion:
class
object DecodeResult
sealed trait Entity[+F[_]]
Companion:
object
object Entity
Companion:
class
@implicitNotFound("Cannot decode into a value of type ${T}, because no EntityDecoder[${F}, ${T}] instance could be found.")
trait EntityDecoder[F[_], T]

A type that can be used to decode a Message EntityDecoder is used to attempt to decode a Message returning the entire resulting A. If an error occurs it will result in a failed effect. The default decoders provided here are not streaming, but one could implement a streaming decoder by having the value of A be some kind of streaming construct.

A type that can be used to decode a Message EntityDecoder is used to attempt to decode a Message returning the entire resulting A. If an error occurs it will result in a failed effect. The default decoders provided here are not streaming, but one could implement a streaming decoder by having the value of A be some kind of streaming construct.

Type parameters:
T

result type produced by the decoder

Companion:
object
object EntityDecoder

EntityDecoder is used to attempt to decode an EntityBody This companion object provides a way to create new EntityDecoders along with some commonly used instances which can be resolved implicitly.

EntityDecoder is used to attempt to decode an EntityBody This companion object provides a way to create new EntityDecoders along with some commonly used instances which can be resolved implicitly.

Companion:
class
@implicitNotFound("Cannot convert from ${A} to an Entity, because no EntityEncoder[${F}, ${A}] instance could be found.")
trait EntityEncoder[+F[_], A]
Companion:
object
object EntityEncoder
Companion:
class
final case class EntityTag(tag: String, weakness: Weakness) extends Renderable
Companion:
object
object EntityTag
Companion:
class
sealed trait FormDataDecoder[A]

A decoder ware that uses QueryParamDecoder to decode values in org.http4s.UrlForm

A decoder ware that uses QueryParamDecoder to decode values in org.http4s.UrlForm

Example:
scala> import cats.syntax.all._
scala> import cats.data._
scala> import org.http4s.FormDataDecoder._
scala> import org.http4s.ParseFailure
scala> case class Foo(a: String, b: Boolean)
scala> case class Bar(fs: List[Foo], f: Foo, d: Boolean)
scala>
scala> implicit val fooMapper: FormDataDecoder[Foo] = (
    |   field[String]("a"),
    |   field[Boolean]("b")
    | ).mapN(Foo.apply)
scala>
scala> val barMapper = (
    |   list[Foo]("fs"),
    |   nested[Foo]("f"),
    |   field[Boolean]("d")
    | ).mapN(Bar.apply)
scala>
scala> barMapper(
    |   Map(
    |    "fs[].a" -> Chain("a1", "a2"),
    |    "fs[].b" -> Chain("true", "false"),
    |    "f.a" -> Chain("fa"),
    |    "f.b" -> Chain("false"),
    |    "d" -> Chain("true"))
    | )
res1: ValidatedNel[ParseFailure, Bar] = Valid(Bar(List(Foo(a1,true), Foo(a2,false)),Foo(fa,false),true))

The companion object provides a EntityDecoder from HTML form parameters.

 import org.http4s.FormDataDecoder.formEntityDecoder
 HttpRoutes
  .of[F] {
    case req @ POST -> Root =>
      req.as[MyEntity].flatMap { entity =>
        Ok()
      }
  }

For more examples, check the tests https://github.com/http4s/http4s/blob/main/tests/src/test/scala/org/http4s/FormDataDecoderSpec.scala

Companion:
object
object FormDataDecoder
Companion:
class
trait HasQValue
trait Header[A, T <: Type]

Typeclass representing an HTTP header, which all the http4s default headers satisfy. You can add modelled headers by providing an implicit instance of Header[YourModelledHeader]

Typeclass representing an HTTP header, which all the http4s default headers satisfy. You can add modelled headers by providing an implicit instance of Header[YourModelledHeader]

Companion:
object
object Header
Companion:
class
final class Headers(val headers: List[Raw]) extends AnyVal

A collection of HTTP Headers

A collection of HTTP Headers

Companion:
object
object Headers
Companion:
class
object Http

Functions for creating Http kleislis.

Functions for creating Http kleislis.

final case class Http4sVersion(major: Int, minor: Int)
object HttpApp

Functions for creating HttpApp kleislis.

Functions for creating HttpApp kleislis.

trait HttpCodec[A] extends Renderer[A]
Companion:
object
object HttpCodec
Companion:
class
class HttpDate extends Renderable with Ordered[HttpDate]

An HTTP-date value represents time as an instance of Coordinated Universal Time (UTC). It expresses time at a resolution of one second. By using it over java.time.Instant in the model, we assure that if two headers render equally, their values are equal.

An HTTP-date value represents time as an instance of Coordinated Universal Time (UTC). It expresses time at a resolution of one second. By using it over java.time.Instant in the model, we assure that if two headers render equally, their values are equal.

See also:
Companion:
object
object HttpDate
Companion:
class
object HttpRoutes

Functions for creating HttpRoutes kleislis.

Functions for creating HttpRoutes kleislis.

final case class HttpVersion extends Renderable with Ordered[HttpVersion]

HTTP's version number consists of two decimal digits separated by a "." (period or decimal point). The first digit ("major version") indicates the messaging syntax, whereas the second digit ("minor version") indicates the highest minor version within that major version to which the sender is conformant (able to understand for future communication).

HTTP's version number consists of two decimal digits separated by a "." (period or decimal point). The first digit ("major version") indicates the messaging syntax, whereas the second digit ("minor version") indicates the highest minor version within that major version to which the sender is conformant (able to understand for future communication).

Value parameters:
major

The major version, 0 to 9 inclusive

minor

The minor version, 0 to 9 inclusive

See also:

Semantics, Protocol Versioning

Companion:
object
object HttpVersion
Companion:
class
final case class InvalidBodyException(msg: String) extends Exception with NoStackTrace

Exception dealing with invalid body

Exception dealing with invalid body

Value parameters:
msg

description if what makes the body invalid

final case class InvalidMessageBodyFailure(details: String, cause: Option[Throwable]) extends MessageBodyFailure

Indicates a semantic error decoding the body of an HTTP Message.

Indicates a semantic error decoding the body of an HTTP Message.

final case class InvalidResponseException(msg: String) extends Exception with NoStackTrace

Exception dealing with invalid response

Exception dealing with invalid response

Value parameters:
msg

description if what makes the response invalid

object LanguageTag
Companion:
class
final case class LanguageTag(primaryTag: String, q: QValue, subTags: List[String]) extends Renderable
Companion:
object
final case class MalformedMessageBodyFailure(details: String, cause: Option[Throwable]) extends MessageBodyFailure

Indicates an syntactic error decoding the body of an HTTP Message.

Indicates an syntactic error decoding the body of an HTTP Message.

trait Media[+F[_]]
Companion:
object
object Media
Companion:
class
sealed class MediaRange
Companion:
object
object MediaRange
Companion:
class
sealed class MediaType(mainType: String, val subType: String, val compressible: Boolean, val binary: Boolean, val fileExtensions: List[String], extensions: Map[String, String]) extends MediaRange
Companion:
object
object MediaType
Companion:
class
final case class MediaTypeMismatch(messageType: MediaType, expected: Set[MediaRange]) extends UnsupportedMediaTypeFailure

Indicates that no EntityDecoder matches the MediaType of the Message being decoded

Indicates that no EntityDecoder matches the MediaType of the Message being decoded

final case class MediaTypeMissing(expected: Set[MediaRange]) extends UnsupportedMediaTypeFailure

Indicates that a Message attempting to be decoded has no MediaType and no EntityDecoder was lenient enough to accept it.

Indicates that a Message attempting to be decoded has no MediaType and no EntityDecoder was lenient enough to accept it.

sealed trait Message[+F[_]] extends Media[F]

Represents a HTTP Message. The interesting subclasses are Request and Response.

Represents a HTTP Message. The interesting subclasses are Request and Response.

Companion:
object
object Message
Companion:
class
trait MessageBodyFailure extends DecodeFailure

Indicates a problem decoding a Message body.

Indicates a problem decoding a Message body.

trait MessageFailure extends RuntimeException

Indicates a failure to handle an HTTP Message.

Indicates a failure to handle an HTTP Message.

final class Method extends Renderable with Serializable

An HTTP method.

An HTTP method.

Value parameters:
isIdempotent

A request method is considered "idempotent" if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request.

isSafe

Request methods are considered "safe" if their defined semantics are essentially read-only; i.e., the client does not request, and does not expect, any state change on the origin server as a result of applying a safe method to a target resource.

name

The name of the method

See also:
Companion:
object
object Method
Companion:
class
final case class ParseFailure(sanitized: String, details: String) extends MessageFailure with NoStackTrace

Indicates an error parsing an HTTP Message.

Indicates an error parsing an HTTP Message.

Value parameters:
details

Contains any relevant details omitted from the sanitized version of the error. This may freely echo a Request.

sanitized

May safely be displayed to a client to describe an error condition. Should not echo any part of a Request.

Companion:
object
object ParseFailure
Companion:
class
object ParseResult
final case class ProductComment(value: String) extends ProductIdOrComment
Companion:
object
object ProductComment
Companion:
class
final case class ProductId(value: String, version: Option[String]) extends ProductIdOrComment
Companion:
object
object ProductId
Companion:
class
sealed trait ProductIdOrComment extends Renderable
Companion:
object
object ProductIdOrComment
Companion:
class
final case class Protocol(name: CIString, version: Option[CIString])
Companion:
object
object Protocol
Companion:
class
final class QValue extends AnyVal with Ordered[QValue]

A Quality Value. Represented as thousandths for an exact representation rounded to three decimal places.

A Quality Value. Represented as thousandths for an exact representation rounded to three decimal places.

Value parameters:
thousandths

between 0 (for q=0) and 1000 (for q=1)

See also:
Companion:
object
object QValue extends QValuePlatform
Companion:
class
trait QValuePlatform
final class Query extends QueryOps with Renderable

Collection representation of a query string

Collection representation of a query string

It is a indexed sequence of key and maybe a value pairs which maps precisely to a query string, modulo percent-encoding.

When rendered, the resulting String will have the pairs separated by '&' while the key is separated from the value with '='

Companion:
object
object Query
Companion:
class
trait QueryOps
trait QueryParam[T] extends QueryParamKeyLike[T]

type class defining the key of a query parameter Usually used in conjunction with QueryParamEncoder and QueryParamDecoder

type class defining the key of a query parameter Usually used in conjunction with QueryParamEncoder and QueryParamDecoder

Any QueryParam instance is also a valid QueryParamKeyLike instance where the same key is used for all values.

Companion:
object
object QueryParam
Companion:
class
trait QueryParamCodec[T] extends QueryParamEncoder[T] with QueryParamDecoder[T]
Companion:
object
object QueryParamCodec
Companion:
class
trait QueryParamDecoder[T]

Type class defining how to decode a QueryParameterValue into a T

Type class defining how to decode a QueryParameterValue into a T

See also:

QueryParamCodecLaws

Companion:
object
object QueryParamDecoder
Companion:
class
trait QueryParamEncoder[T]

Type class defining how to encode a T as a QueryParameterValues

Type class defining how to encode a T as a QueryParameterValues

See also:

QueryParamCodecLaws

Companion:
object
object QueryParamEncoder
Companion:
class
trait QueryParamKeyLike[T]
Companion:
object
object QueryParamKeyLike
Companion:
class
final case class QueryParameterKey(value: String) extends AnyVal
Companion:
object
object QueryParameterKey
Companion:
class
final case class QueryParameterValue(value: String) extends AnyVal
Companion:
object
object QueryParameterValue
Companion:
class
object RangeUnit
Companion:
class
final case class RangeUnit(value: String) extends Renderable
Companion:
object
final class Request[+F[_]] extends Message[F] with Product with Serializable

Representation of an incoming HTTP message

Representation of an incoming HTTP message

A Request encapsulates the entirety of the incoming HTTP request including the status line, headers, and a possible request body.

Value parameters:
attributes

Immutable Map used for carrying additional information in a type safe fashion

entity

Entity defining the body of the request

headers

collection of Headers

httpVersion

the HTTP version

method

Method.GET, Method.POST, etc.

uri

representation of the request URI

Companion:
object
object Request
Companion:
class
final case class RequestCookie(name: String, content: String) extends Renderable
Companion:
object
object RequestCookie
Companion:
class
sealed abstract class RequestPrelude extends Product with Serializable

A projection of a Request without the body.

A projection of a Request without the body.

Note:

The Request#attributes are omitted in this encoding because they do not (and can not) have a cats.kernel.Order instance. If they were included here, then we could not write a cats.kernel.Order instance for RequestPrelude, limiting some of its utility, e.g. it could not be used in a cats.data.NonEmptySet.

Companion:
object
object RequestPrelude
Companion:
class
final class Response[+F[_]] extends Message[F] with Product with Serializable

Representation of the HTTP response to send back to the client

Representation of the HTTP response to send back to the client

Value parameters:
attributes

org.typelevel.vault.Vault containing additional parameters which may be used by the http4s backend for additional processing such as java.io.File object

entity

Entity representing the possible body of the response

headers

Headers containing all response headers

status

Status code and message

Companion:
object
object Response extends KleisliSyntax
Companion:
class
final case class ResponseCookie(name: String, content: String, expires: Option[HttpDate], maxAge: Option[Long], domain: Option[String], path: Option[String], sameSite: Option[SameSite], secure: Boolean, httpOnly: Boolean, extension: Option[String]) extends Renderable
Value parameters:
extension

The extension attributes of the cookie. If there is more than one, they are joined by semi-colon, which must not appear in an attribute value.

Companion:
object
object ResponseCookie
Companion:
class
sealed abstract class ResponsePrelude extends Product with Serializable

A projection of a Response without the body.

A projection of a Response without the body.

Note:

The Response#attributes are omitted in this encoding because they do not (and can not) have a cats.kernel.Order instance. If they were included here, then we could not write a cats.kernel.Order instance for ResponsePrelude, limiting some of its utility, e.g. it could not be used in a cats.data.NonEmptySet.

Companion:
object
object ResponsePrelude
Companion:
class
sealed trait SameSite extends Renderable

RFC6265 SameSite cookie attribute values.

RFC6265 SameSite cookie attribute values.

Companion:
object
object SameSite
Companion:
class
final case class ServerSentEvent(data: Option[String], eventType: Option[String], id: Option[EventId], retry: Option[FiniteDuration], comment: Option[String]) extends Renderable
Companion:
object
object ServerSentEvent
Companion:
class
final case class ServerSoftware(product: String, productVersion: Option[String], comment: Option[String])
Companion:
object
object ServerSoftware
Companion:
class
object StaticFile
sealed abstract case class Status extends Ordered[Status] with Renderable

Representation of the HTTP response code and reason

Representation of the HTTP response code and reason

'''Note: ''' the reason is not important to the protocol and is not considered in equality checks.

Value parameters:
code

HTTP status code

reason

reason for the response. eg, OK

See also:
Companion:
object
object Status
Companion:
class
class TransferCoding extends Ordered[TransferCoding] with Renderable
Companion:
object
object TransferCoding
Companion:
class
sealed abstract class UnsupportedMediaTypeFailure extends DecodeFailure with NoStackTrace

Indicates that a Message came with no supported MediaType.

Indicates that a Message came with no supported MediaType.

final case class Uri(scheme: Option[Scheme], authority: Option[Authority], path: Path, query: Query, fragment: Option[Fragment]) extends QueryOps with Renderable

Representation of the Request URI

Representation of the Request URI

Value parameters:
authority

optional Uri Authority. eg, localhost:8080, www.foo.bar

fragment

optional Uri Fragment. url-encoded.

path

url-encoded string representation of the path component of the Uri.

query

optional Query. url-encoded.

scheme

optional Uri Scheme. eg, http, https

Companion:
object
object Uri extends UriPlatform
Companion:
class
trait UriPlatform
final case class UriTemplate(scheme: Option[Scheme], authority: Option[Authority], path: Path, query: Query, fragment: Fragment)

Simple representation of a URI Template that can be rendered as RFC6570 conform string.

Simple representation of a URI Template that can be rendered as RFC6570 conform string.

This model reflects only a subset of RFC6570.

Level 1 and Level 2 are completely modeled and Level 3 features are limited to:

  • Path segments, slash-prefixed
  • Form-style query, ampersand-separated
  • Fragment expansion
Companion:
object
object UriTemplate
Companion:
class
final class UrlForm extends AnyVal
Companion:
object
object UrlForm
Companion:
class
object implicits extends AllSyntax

Deprecated classlikes

@deprecated("Misspelled, never documented, and obsolete", "0.22.2")
trait MediaTypePlaform
Deprecated
@deprecated("Use the CookieJar middleware instead", "0.21.20")
object RequestCookieJar
Companion:
class
Deprecated
@deprecated("Use the CookieJar middleware instead", "0.21.20")
final class RequestCookieJar extends AnyVal
Companion:
object
Deprecated

Types

type AuthScheme = CIString
type AuthedRequest[F[_], T] = ContextRequest[F, T]
type AuthedRoutes[T, F[_]] = Kleisli[[_] =>> OptionT[F, _$10], ContextRequest[F, T], Response[F]]

The type parameters need to be in this order to make partial unification trigger. See https://github.com/http4s/http4s/issues/1506

The type parameters need to be in this order to make partial unification trigger. See https://github.com/http4s/http4s/issues/1506

type Callback[A] = Either[Throwable, A] => Unit
type ContextRoutes[T, F[_]] = Kleisli[[_] =>> OptionT[F, _$12], ContextRequest[F, T], Response[F]]
type DecodeResult[F[_], A] = EitherT[F, DecodeFailure, A]
type EntityBody[+F[_]] = Stream[F, Byte]
type EventStream[F[_]] = Stream[F, ServerSentEvent]

A stream of server-sent events

A stream of server-sent events

type Http[F[_], G[_]] = Kleisli[F, Request[G], Response[G]]

A kleisli with a Request input and a Response output. This type is useful for writing middleware that are polymorphic over the return type F.

A kleisli with a Request input and a Response output. This type is useful for writing middleware that are polymorphic over the return type F.

Type parameters:
F

the effect type in which the Response is returned

G

the effect type of the Request and Response bodies

type HttpApp[F[_]] = Http[F, F]

A kleisli with a Request input and a Response output, such that the response effect is the same as the request and response bodies'. An HTTP app is total on its inputs. An HTTP app may be run by a server, and a client can be converted to or from an HTTP app.

A kleisli with a Request input and a Response output, such that the response effect is the same as the request and response bodies'. An HTTP app is total on its inputs. An HTTP app may be run by a server, and a client can be converted to or from an HTTP app.

Type parameters:
F

the effect type in which the Response is returned, and also of the Request and Response bodies.

type HttpRoutes[F[_]] = Http[[_] =>> OptionT[F, _$7], F]

A kleisli with a Request input and a Response output, such that the response effect is an optional inside the effect of the request and response bodies. HTTP routes can conveniently be constructed from a partial function and combined as a SemigroupK.

A kleisli with a Request input and a Response output, such that the response effect is an optional inside the effect of the request and response bodies. HTTP routes can conveniently be constructed from a partial function and combined as a SemigroupK.

Type parameters:
F

the effect type of the Request and Response bodies, and the base monad of the OptionT in which the response is returned.

Value members

Concrete fields

Deprecated fields

@deprecated("Use Charset.`UTF-8` directly", "0.22.8")
val DefaultCharset: Charset
Deprecated