Middleware

A middleware is a wrapper around a service that provides a means of manipulating the Request sent to service, and/or the Response returned by the service. In some cases, such as Authentication, middleware may even prevent the service from being called.

At its most basic, middleware is simply a function that takes one Service as a parameter and returns another Service. In addition to the Service, the middleware function can take any additional parameters it needs to perform its task. Let’s look at a simple example.

For this, we’ll need a dependency on the http4s dsl.

libraryDependencies ++= Seq(
  "org.http4s" %% "http4s-dsl" % http4sVersion
)

and some imports.

import cats.data.Kleisli
import cats.effect._
import cats.implicits._
import org.http4s._
import org.http4s.dsl.io._
import org.http4s.implicits._

Then, we can create a middleware that adds a header to successful responses from the wrapped service like this.

def myMiddle(service: HttpRoutes[IO], header: Header): HttpRoutes[IO] = Kleisli { req: Request[IO] =>
  service(req).map {
    case Status.Successful(resp) =>
      resp.putHeaders(header)
    case resp =>
      resp
  }
}
// myMiddle: (service: org.http4s.HttpRoutes[cats.effect.IO], header: org.http4s.Header)org.http4s.HttpRoutes[cats.effect.IO]

All we do here is pass the request to the service, which returns an F[Response]. So, we use map to get the request out of the task, add the header if the response is a success, and then pass the response on. We could just as easily modify the request before we passed it to the service.

Now, let’s create a simple service. As mentioned between service and dsl, because Service is implemented as a Kleisli, which is just a function at heart, we can test a service without a server. Because an HttpService[F] returns a F[Response[F]], we need to call unsafeRunSync on the result of the function to extract the Response[F].

val service = HttpRoutes.of[IO] {
  case GET -> Root / "bad" =>
    BadRequest()
  case _ =>
    Ok()
}
// service: org.http4s.HttpRoutes[cats.effect.IO] = Kleisli(org.http4s.HttpRoutes$$$Lambda$28199/8722311@105db71d)

val goodRequest = Request[IO](Method.GET, Uri.uri("/"))
// goodRequest: org.http4s.Request[cats.effect.IO] = Request(method=GET, uri=/, headers=Headers())

val badRequest = Request[IO](Method.GET, Uri.uri("/bad"))
// badRequest: org.http4s.Request[cats.effect.IO] = Request(method=GET, uri=/bad, headers=Headers())

service.orNotFound(goodRequest).unsafeRunSync
// res0: org.http4s.Response[cats.effect.IO] = Response(status=200, headers=Headers(Content-Length: 0))

service.orNotFound(badRequest).unsafeRunSync
// res1: org.http4s.Response[cats.effect.IO] = Response(status=400, headers=Headers(Content-Length: 0))

Now, we’ll wrap the service in our middleware to create a new service, and try it out.

val wrappedService = myMiddle(service, Header("SomeKey", "SomeValue"));
// wrappedService: org.http4s.HttpRoutes[cats.effect.IO] = Kleisli($Lambda$28296/1422468545@f63c0bd)

wrappedService.orNotFound(goodRequest).unsafeRunSync
// res2: org.http4s.Response[cats.effect.IO] = Response(status=200, headers=Headers(Content-Length: 0, SomeKey: SomeValue))

wrappedService.orNotFound(badRequest).unsafeRunSync
// res3: org.http4s.Response[cats.effect.IO] = Response(status=400, headers=Headers(Content-Length: 0))

Note that the successful response has your header added to it.

If you intend to use you middleware in multiple places, you may want to implement it as an object and use the apply method.

object MyMiddle {
  def addHeader(resp: Response[IO], header: Header) =
    resp match {
      case Status.Successful(resp) => resp.putHeaders(header)
      case resp => resp
    }

  def apply(service: HttpRoutes[IO], header: Header) =
    service.map(addHeader(_, header))
}
// defined object MyMiddle

val newService = MyMiddle(service, Header("SomeKey", "SomeValue"))
// newService: cats.data.Kleisli[[β$0$]cats.data.OptionT[cats.effect.IO,β$0$],org.http4s.Request[cats.effect.IO],org.http4s.Response[cats.effect.IO]] = Kleisli(cats.data.Kleisli$$Lambda$28315/1476963506@3f6f1e9f)

newService.orNotFound(goodRequest).unsafeRunSync
// res4: org.http4s.Response[cats.effect.IO] = Response(status=200, headers=Headers(Content-Length: 0, SomeKey: SomeValue))

newService.orNotFound(badRequest).unsafeRunSync
// res5: org.http4s.Response[cats.effect.IO] = Response(status=400, headers=Headers(Content-Length: 0))

It is possible for the wrapped Service to have different Request and Response types than the middleware. Authentication is, again, a good example. Authentication middleware is an HttpService (an alias for Service[Request, Response]) that wraps an AuthedService (an alias for Service[AuthedRequest[T], Response]. There is a type defined for this in the http4s.server package:

type AuthMiddleware[F, T] = Middleware[AuthedRequest[F, T], Response[F], Request[F], Response[F]]

See the Authentication documentation for more details.

Composing Services with Middleware

Because middleware returns a Service, you can compose services wrapped in middleware with other, unwrapped, services, or services wrapped in other middleware. You can also wrap a single service in multiple layers of middleware. For example:

val apiService = HttpRoutes.of[IO] {
  case GET -> Root / "api" =>
    Ok()
}
// apiService: org.http4s.HttpRoutes[cats.effect.IO] = Kleisli(org.http4s.HttpRoutes$$$Lambda$28199/8722311@47e85b77)

val aggregateService = apiService <+> MyMiddle(service, Header("SomeKey", "SomeValue"))
// aggregateService: cats.data.Kleisli[[β$0$]cats.data.OptionT[cats.effect.IO,β$0$],org.http4s.Request[cats.effect.IO],org.http4s.Response[cats.effect.IO]] = Kleisli(cats.data.KleisliSemigroupK$$Lambda$28317/881998640@c73dd9c)

val apiRequest = Request[IO](Method.GET, Uri.uri("/api"))
// apiRequest: org.http4s.Request[cats.effect.IO] = Request(method=GET, uri=/api, headers=Headers())

aggregateService.orNotFound(goodRequest).unsafeRunSync
// res6: org.http4s.Response[cats.effect.IO] = Response(status=200, headers=Headers(Content-Length: 0, SomeKey: SomeValue))

aggregateService.orNotFound(apiRequest).unsafeRunSync
// res7: org.http4s.Response[cats.effect.IO] = Response(status=200, headers=Headers(Content-Length: 0))

Note that goodRequest ran through the MyMiddle middleware and the Result had our header added to it. But, apiRequest did not go through the middleware and did not have the header added to it’s Result.

Included Middleware

Http4s includes some middleware Out of the Box in the org.http4s.server.middleware package. These include:

• Authentication
• Cross Origin Resource Sharing (CORS)
• Response Compression (GZip)
• Service Timeout
• Jsonp
• Virtual Host
• Metrics

And a few others.

Metrics Middleware

Apart from the middleware mentioned in the previous section. There is, as well, Out of the Box middleware for Dropwizard and Prometheus metrics

Dropwizard Metrics Middleware

To make use of this metrics middleware the following dependencies are needed:

libraryDependencies ++= Seq(
  "org.http4s" %% "http4s-server" % http4sVersion,
  "org.http4s" %% "http4s-dropwizard-metrics" % http4sVersion
)

We can create a middleware that registers metrics prefixed with a provided prefix like this.

import org.http4s.server.middleware.Metrics
import org.http4s.metrics.dropwizard.Dropwizard
import com.codahale.metrics.SharedMetricRegistries

implicit val clock = Clock.create[IO]
// clock: cats.effect.Clock[cats.effect.IO] = cats.effect.Clock$$anon$1@14d767a0

val registry = SharedMetricRegistries.getOrCreate("default")
// registry: com.codahale.metrics.MetricRegistry = com.codahale.metrics.MetricRegistry@4395dc1

val meteredRoutes = Metrics[IO](Dropwizard(registry, "server"))(apiService)
// meteredRoutes: org.http4s.HttpRoutes[cats.effect.IO] = Kleisli(org.http4s.server.middleware.Metrics$$$Lambda$28326/1606017003@3a526828)

Prometheus Metrics Middleware

To make use of this metrics middleware the following dependencies are needed:

libraryDependencies ++= Seq(
  "org.http4s" %% "http4s-server" % http4sVersion,
  "org.http4s" %% "http4s-prometheus-metrics" % http4sVersion
)

We can create a middleware that registers metrics prefixed with a provided prefix like this.

import org.http4s.server.middleware.Metrics
import org.http4s.metrics.prometheus.Prometheus
import io.prometheus.client.CollectorRegistry

implicit val clock = Clock.create[IO]
// clock: cats.effect.Clock[cats.effect.IO] = cats.effect.Clock$$anon$1@21cb4ba2

val registry = new CollectorRegistry()
// registry: io.prometheus.client.CollectorRegistry = io.prometheus.client.CollectorRegistry@4bc00eb6

val meteredRoutes = Prometheus[IO](registry, "server").map(
  Metrics[IO](_)(apiService)
)
// meteredRoutes: cats.effect.IO[org.http4s.HttpRoutes[cats.effect.IO]] = <function1>