The http4s DSL
Recall from earlier that an HttpService
is just a type alias for
Kleisli[Task, Request, Response]
. This provides a minimal
foundation for declaring services and executing them on blaze or a
servlet container. While this foundation is composeable, it is not
highly productive. Most service authors will seek a higher level DSL.
Add the http4s-dsl to your build
One option is the http4s-dsl. It is officially supported by the http4s team, but kept separate from core in order to encourage multiple approaches for different needs.
This tutorial assumes that http4s-dsl is on your classpath. Add the following to your build.sbt:
libraryDependencies ++= Seq(
"org.http4s" %% "http4s-dsl" % http4sVersion,
)
All we need is a REPL to follow along at home:
$ sbt console
The simplest service
We’ll need the following imports to get started:
import org.http4s._, org.http4s.dsl._
// import org.http4s._
// import org.http4s.dsl._
import fs2.Task
// import fs2.Task
The central concept of http4s-dsl is pattern matching. An
HttpService
is declared as a simple series of case statements. Each
case statement attempts to match and optionally extract from an
incoming Request
. The code associated with the first matching case
is used to generate a Task[Response]
.
The simplest case statement matches all requests without extracting
anything. The right hand side of the request must return a
Task[Response]
.
val service = HttpService {
case _ =>
Task.delay(Response(Status.Ok))
}
// service: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31351/1040060313@38a2aa40)
Testing the Service
One beautiful thing about the HttpService
model is that we don’t
need a server to test our route. We can construct our own request
and experiment directly in the REPL.
scala> val getRoot = Request(Method.GET, uri("/"))
getRoot: org.http4s.Request = Request(method=GET, uri=/, headers=Headers())
scala> val task = service.run(getRoot)
task: fs2.Task[org.http4s.MaybeResponse] = Task
Where is our Response
? It hasn’t been created yet. We wrapped it
in a Task
. In a real service, generating a Response
is likely to
be an asynchronous operation with side effects, such as invoking
another web service or querying a database, or maybe both. Operating
in a Task
gives us control over the sequencing of operations and
lets us reason about our code like good functional programmers. It is
the HttpService
’s job to describe the task, and the server’s job to
run it.
But here in the REPL, it’s up to us to run it:
scala> val response = task.unsafeRun
response: org.http4s.MaybeResponse = Response(status=200, headers=Headers())
Cool.
Generating responses
We’ll circle back to more sophisticated pattern matching of requests,
but it will be a tedious affair until we learn a more succinct way of
generating Task[Response]
s.
Status codes
http4s-dsl provides a shortcut to create a Task[Response]
by
applying a status code:
scala> val okTask = Ok()
okTask: fs2.Task[org.http4s.Response] = Task
scala> val ok = okTask.unsafeRun
ok: org.http4s.Response = Response(status=200, headers=Headers(Content-Length: 0))
This simple Ok()
expression succinctly says what we mean in a
service:
HttpService {
case _ => Ok()
}.run(getRoot).unsafeRun
// res0: org.http4s.MaybeResponse = Response(status=200, headers=Headers(Content-Length: 0))
This syntax works for other status codes as well. In our example, we
don’t return a body, so a 204 No Content
would be a more appropriate
response:
HttpService {
case _ => NoContent()
}.run(getRoot).unsafeRun
// res1: org.http4s.MaybeResponse = Response(status=204, headers=Headers())
Headers
http4s adds a minimum set of headers depending on the response, e.g:
scala> Ok("Ok response.").unsafeRun.headers
res2: org.http4s.Headers = Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 12)
Extra headers can be added using putHeaders
, for example to specify cache policies:
import org.http4s.headers.`Cache-Control`
// import org.http4s.headers.Cache$minusControl
import org.http4s.CacheDirective.`no-cache`
// import org.http4s.CacheDirective.no$minuscache
import cats.data.NonEmptyList
// import cats.data.NonEmptyList
import org.http4s.util.nonEmptyList
// import org.http4s.util.nonEmptyList
scala> Ok("Ok response.").putHeaders(`Cache-Control`(NonEmptyList(`no-cache`(), Nil))).unsafeRun.headers
res3: org.http4s.Headers = Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 12, Cache-Control: no-cache)
http4s defines all the well known headers directly, but sometimes you need to
define custom headers, typically prefixed by an X-
. In simple cases you can
construct a Header
instance by hand
scala> Ok("Ok response.").putHeaders(Header("X-Auth-Token", "value")).unsafeRun.headers
res4: org.http4s.Headers = Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 12, X-Auth-Token: value)
Cookies
http4s has special support for Cookie headers using the Cookie
type to add
and invalidate cookies. Adding a cookie will generate the correct Set-Cookie
header:
scala> Ok("Ok response.").addCookie(Cookie("foo", "bar")).unsafeRun.headers
res5: org.http4s.Headers = Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 12, Set-Cookie: foo=bar)
Cookie
can be further customized to set, e.g., expiration, the secure flag, httpOnly, flag, etc
scala> Ok("Ok response.").addCookie(Cookie("foo", "bar", expires = Some(HttpDate.now), httpOnly = true, secure = true)).unsafeRun.headers
res6: org.http4s.Headers = Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 12, Set-Cookie: foo=bar; Expires=Sun, 25 Mar 2018 02:00:12 GMT; Secure; HttpOnly)
To request a cookie to be removed on the client, you need to set the cookie value
to empty. http4s can do that with removeCookie
scala> Ok("Ok response.").removeCookie("foo").unsafeRun.headers
res7: org.http4s.Headers = Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 12, Set-Cookie: foo=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=0)
Responding with a body
Simple bodies
Most status codes take an argument as a body. In http4s, Request
and Response
bodies are represented as a
fs2.Stream[Task, ByteVector]
. It’s also considered good
HTTP manners to provide a Content-Type
and, where known in advance,
Content-Length
header in one’s responses.
All of this hassle is neatly handled by http4s’ EntityEncoders.
We’ll cover these in more depth in another tut. The important point
for now is that a response body can be generated for any type with an
implicit EntityEncoder
in scope. http4s provides several out of the
box:
scala> Ok("Received request.").unsafeRun
res8: org.http4s.Response = Response(status=200, headers=Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 17))
scala> import java.nio.charset.StandardCharsets.UTF_8
import java.nio.charset.StandardCharsets.UTF_8
scala> Ok("binary".getBytes(UTF_8)).unsafeRun
res9: org.http4s.Response = Response(status=200, headers=Headers(Content-Type: application/octet-stream, Content-Length: 6))
Per the HTTP specification, some status codes don’t support a body. http4s prevents such nonsense at compile time:
scala> NoContent("does not compile")
<console>:25: error: no arguments allowed for nullary method apply: ()fs2.Task[org.http4s.Response] in trait EmptyResponseGenerator
NoContent("does not compile")
^
Asynchronous responses
While http4s prefers Task
, you may be working with libraries that
use standard library [Future]s. Some relevant imports:
import scala.concurrent.Future
// import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global
// import scala.concurrent.ExecutionContext.Implicits.global
You can seamlessly respond with a Future
of any type that has an
EntityEncoder
.
scala> val task = Ok(Future {
| println("I run when the future is constructed.")
| "Greetings from the future!"
| })
task: fs2.Task[org.http4s.Response] = Task
scala> task.unsafeRun
I run when the future is constructed.
res11: org.http4s.Response = Response(status=200, headers=Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 26))
As good functional programmers who like to delay our side effects, we of course prefer to operate in [Task]s:
scala> implicit val strategy = fs2.Strategy.fromFixedDaemonPool(2, threadName = "strategy")
strategy: fs2.Strategy = Strategy
scala> val task = Ok(Task {
| println("I run when the Task is run.")
| "Mission accomplished!"
| })
task: fs2.Task[org.http4s.Response] = Task
scala> task.unsafeRun
I run when the Task is run.
res12: org.http4s.Response = Response(status=200, headers=Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 21))
Note that in both cases, a Content-Length
header is calculated.
http4s waits for the Future
or Task
to complete before wrapping it
in its HTTP envelope, and thus has what it needs to calculate a
Content-Length
.
Streaming bodies
Streaming bodies are supported by returning a fs2.Stream
.
Like Future
s and Task
s, the stream may be of any type that has an
EntityEncoder
.
An intro to Stream
is out of scope, but we can glimpse the
power here. This stream emits the elapsed time every 100 milliseconds
for one second:
implicit val scheduler = fs2.Scheduler.fromFixedDaemonPool(2, threadName = "scheduler")
// scheduler: fs2.Scheduler = Scheduler(java.util.concurrent.ScheduledThreadPoolExecutor@6619eae[Running, pool size = 0, active threads = 0, queued tasks = 0, completed tasks = 0])
val drip = {
import scala.concurrent.duration._
fs2.time.awakeEvery[Task](100.millis).map(_.toString).take(10)
}
// drip: fs2.Stream[fs2.Task,String] = evalScope(<scope>).flatMap(<function1>)
We can see it for ourselves in the REPL:
scala> val dripOutTask = drip.through(fs2.text.lines).through(_.evalMap(s => {Task.delay{println(s); s}})).run
dripOutTask: fs2.Task[Unit] = Task
scala> dripOutTask.unsafeRun
101912037 nanoseconds201918551 nanoseconds301914412 nanoseconds401855241 nanoseconds501851163 nanoseconds601843182 nanoseconds701852992 nanoseconds801843957 nanoseconds901843720 nanoseconds1001820273 nanoseconds
When wrapped in a Response
, http4s will flush each chunk of a
Stream
as they are emitted. Note that a stream’s length can’t
generally be anticipated before it runs, so this triggers chunked
transfer encoding:
scala> Ok(drip).unsafeRun
res14: org.http4s.Response = Response(status=200, headers=Headers(Content-Type: text/plain; charset=UTF-8, Transfer-Encoding: chunked))
Matching and extracting requests
A Request
is a regular case class
- you can destructure it to extract its
values. By extension, you can also match/case
it with different possible
destructurings. To build these different extractors, you can make use of the
DSL.
Most often, you extract the Request
into a HTTP Method
(verb) and the path,
via the ->
object. On the left side, you’ll have the HTTP Method
, on the
other side the path. Naturally, _
is a valid matcher too, so any call to
/api
can be blocked, regardless of Method
:
scala> HttpService {
| case request @ _ -> Root / "api" => Forbidden()
| }
res15: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31351/1040060313@44117da8)
To also block all subcalls /api/...
, you’ll need /:
, which is right
associative, and matches everything after, and not just the next element:
scala> HttpService {
| case request @ _ -> "api" /: _ => Forbidden()
| }
res16: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31351/1040060313@3d6daf04)
For matching more than one Method
, there’s |
:
scala> HttpService {
| case request @ (GET | POST) -> Root / "api" => ???
| }
res17: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31351/1040060313@66b83cee)
Honorable mention: ~
, for matching file extensions.
scala> HttpService {
| case GET -> Root / file ~ "json" => Ok(s"""{"response": "You asked for $file"}""")
| }
res18: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31351/1040060313@5bc412a4)
Handling path parameters
Path params can be extracted and converted to a specific type but are
String
s by default. There are numeric extractors provided in the form
of IntVar
and LongVar
.
import fs2.Task
// import fs2.Task
def getUserName(userId: Int): Task[String] = ???
// getUserName: (userId: Int)fs2.Task[String]
val usersService = HttpService {
case request @ GET -> Root / "users" / IntVar(userId) =>
Ok(getUserName(userId))
}
// usersService: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31351/1040060313@7eb373da)
If you want to extract a variable of type T
, you can provide a custom extractor
object which implements def unapply(str: String): Option[T]
, similar to the way
in which IntVar
does it.
import java.time.LocalDate
// import java.time.LocalDate
import scala.util.Try
// import scala.util.Try
import fs2.Task
// import fs2.Task
import org.http4s.client._
// import org.http4s.client._
object LocalDateVar {
def unapply(str: String): Option[LocalDate] = {
if (!str.isEmpty)
Try(LocalDate.parse(str)).toOption
else
None
}
}
// defined object LocalDateVar
def getTemperatureForecast(date: LocalDate): Task[Double] = Task(42.23)
// getTemperatureForecast: (date: java.time.LocalDate)fs2.Task[Double]
val dailyWeatherService = HttpService {
case request @ GET -> Root / "weather" / "temperature" / LocalDateVar(localDate) =>
Ok(getTemperatureForecast(localDate).map(s"The temperature on $localDate will be: " + _))
}
// dailyWeatherService: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31351/1040060313@71f46a3e)
println(GET(Uri.uri("/weather/temperature/2016-11-05")).flatMap(dailyWeatherService(_)).unsafeRun)
// Response(status=200, headers=Headers(Content-Type: text/plain; charset=UTF-8, Content-Length: 44))
Handling query parameters
A query parameter needs to have a QueryParamDecoderMatcher
provided to
extract it. In order for the QueryParamDecoderMatcher
to work there needs to
be an implicit QueryParamDecoder[T]
in scope. QueryParamDecoder
s for simple
types can be found in the QueryParamDecoder
object. There are also
QueryParamDecoderMatcher
s available which can be used to
return optional or validated parameter values.
In the example below we’re finding query params named country
and year
and
then parsing them as a String
and java.time.Year
.
import java.time.Year
// import java.time.Year
import cats.data.ValidatedNel
// import cats.data.ValidatedNel
object CountryQueryParamMatcher extends QueryParamDecoderMatcher[String]("country")
// defined object CountryQueryParamMatcher
implicit val yearQueryParamDecoder: QueryParamDecoder[Year] =
QueryParamDecoder[Int].map(Year.of)
// yearQueryParamDecoder: org.http4s.QueryParamDecoder[java.time.Year] = org.http4s.QueryParamDecoder$$anon$8@6ffa76bd
object YearQueryParamMatcher extends QueryParamDecoderMatcher[Year]("year")
// defined object YearQueryParamMatcher
def getAverageTemperatureForCountryAndYear(country: String, year: Year): Task[Double] = ???
// getAverageTemperatureForCountryAndYear: (country: String, year: java.time.Year)fs2.Task[Double]
val averageTemperatureService = HttpService {
case request @ GET -> Root / "weather" / "temperature" :? CountryQueryParamMatcher(country) +& YearQueryParamMatcher(year) =>
Ok(getAverageTemperatureForCountryAndYear(country, year).map(s"Average temperature for $country in $year was: " + _))
}
// averageTemperatureService: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31351/1040060313@6fe1ac2d)