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 org.http4s._
import org.http4s.dsl._

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

def myMiddle(service: HttpService, header: Header): HttpService = Service.lift { req =>
  service(req).map {
    case Status.Successful(resp) =>
      resp.putHeaders(header)
    case resp =>
      resp
  }
}
// myMiddle: (service: org.http4s.HttpService, header: org.http4s.Header)org.http4s.HttpService

All we do here is pass the request to the service, which returns a Task[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 returns a Task[Response], we need to call unsafeRun on the result of the function to extract the Response.

val service = HttpService {
  case GET -> Root / "bad" =>
    BadRequest()
  case _ =>
    Ok()
}
// service: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31082/935580971@7616d06d)

val goodRequest = Request(Method.GET, uri("/"))
// goodRequest: org.http4s.Request = Request(method=GET, uri=/, headers=Headers())

val badRequest = Request(Method.GET, uri("/bad"))
// badRequest: org.http4s.Request = Request(method=GET, uri=/bad, headers=Headers())

service(goodRequest).unsafeRun
// res0: org.http4s.MaybeResponse = Response(status=200, headers=Headers(Content-Length: 0))

service(badRequest).unsafeRun
// res1: org.http4s.MaybeResponse = 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.HttpService = Kleisli($$Lambda$31180/1488345803@530bbb59)

wrappedService(goodRequest).unsafeRun
// res2: org.http4s.MaybeResponse = Response(status=200, headers=Headers(Content-Length: 0, SomeKey: SomeValue))

wrappedService(badRequest).unsafeRun
// res3: org.http4s.MaybeResponse = 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.

import fs2.interop.cats._
// import fs2.interop.cats._

object MyMiddle {
  def addHeader(mResp: MaybeResponse, header: Header) =
    mResp match {
      case Status.Successful(resp) => resp.putHeaders(header)
      case resp => resp
    }

  def apply(service: HttpService, header: Header) =
    service.map(addHeader(_, header))
}
// defined object MyMiddle

val newService = MyMiddle(service, Header("SomeKey", "SomeValue"))
// newService: cats.data.Kleisli[fs2.Task,org.http4s.Request,org.http4s.MaybeResponse] = Kleisli(cats.data.Kleisli$$Lambda$31192/452013919@601b9d09)

newService(goodRequest).unsafeRun
// res4: org.http4s.MaybeResponse = Response(status=200, headers=Headers(Content-Length: 0, SomeKey: SomeValue))

newService(badRequest).unsafeRun
// res5: org.http4s.MaybeResponse = 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[T] = Middleware[AuthedRequest[T], Response, Request, Response]

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 = HttpService {
  case GET -> Root / "api" =>
    Ok()
}
// apiService: org.http4s.HttpService = Kleisli(org.http4s.package$HttpService$$$Lambda$31082/935580971@5e20b045)

import cats.implicits._
// import cats.implicits._

val aggregateService = apiService |+| MyMiddle(service, Header("SomeKey", "SomeValue"))
// aggregateService: cats.data.Kleisli[fs2.Task,org.http4s.Request,org.http4s.MaybeResponse] = Kleisli(cats.data.KleisliSemigroup$$Lambda$31198/311167322@2d301460)

val apiRequest = Request(Method.GET, uri("/api"))
// apiRequest: org.http4s.Request = Request(method=GET, uri=/api, headers=Headers())

aggregateService(goodRequest).unsafeRun
// res6: org.http4s.MaybeResponse = Response(status=200, headers=Headers(Content-Length: 0, SomeKey: SomeValue))

aggregateService(apiRequest).unsafeRun
// res7: org.http4s.MaybeResponse = 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:

And a few others.