---

---

---

http4k is a lightweight but fully-featured HTTP toolkit written in pure Kotlin that enables the serving and consuming of HTTP services in a functional and consistent way. http4k applications are just Kotlin functions. For example, here's a simple echo server:

 val app: HttpHandler = { request: Request -> Response(OK).body(request.body) }
 val server = app.asServer(SunHttp(8000)).start()

http4k consists of a lightweight core library, http4k-core, providing a base HTTP implementation and Server/Client implementations based on the JDK classes. Further servers, clients, serverless, templating, websockets capabilities are then implemented in add-on modules. http4k apps can be simply mounted into a running Server, Serverless platform, or compiled to GraalVM and run as a super-lightweight binary.

The principles of http4k are:

• Application as a Function: Based on the Twitter paper "Your Server as a Function", all HTTP services can be composed of 2 types of simple function:
  • HttpHandler: (Request) -> Response - provides a remote call for processing a Request.
  • Filter: (HttpHandler) -> HttpHandler - adds Request/Response pre/post processing. These filters are composed to make stacks of reusable behaviour that can then be applied to an HttpHandler.
• Immutability: All entities in the library are immutable unless their function explicitly disallows this.
• Symmetric: The HttpHandler interface is identical for both HTTP services and clients. This allows for simple offline testability of applications, as well as plugging together of services without HTTP container being required.
• Dependency-lite: Apart the from Kotlin StdLib, http4k-core module has ZERO dependencies and weighs in at ~1mb. Add-on modules only have dependencies required for specific implementation.
• Testability Built by TDD enthusiasts, so supports super-easy mechanisms for both in-memory and port-based testing of:
  • individual endpoints
  • applications
  • websockets/sse
  • full suites of microservices
• Portable Apps are completely portable across deployment platform in either a Server-based, Serverless or Native binaries.

Quickstart

Bored with reading already and just want to get coding? For the impatient, visit the http4k toolbox to generate a complete project from the wide variety of http4k modules.

Alternatively, read the quickstart or take a look at the examples repo, which showcases a variety of http4k use-cases and features.

Module feature overview

• Core:
  • Base HTTP handler and immutable HTTP message objects, cookie handling.
  • Commonly used HTTP functionalities provided as reusable Filters (caching, debugging, Zipkin request tracing)
  • Path-based routing, including nestable contexts
  • Typesafe HTTP message construction/deconstruction and Request Contexts using Lenses
  • Servlet implementation to allow plugin to any Servlet container
  • Launch applications in 1LOC with an embedded SunHttp server backend (recommended for development use only)
  • Lightweight JavaHttpClient implementation - perfect for Serverless contexts where binary size is a factor.
  • Path-based WebSockets including typesafe message marshalling using Lenses, which are testable without a running container
  • Path-based Server-Sent Events which are testable without a running container
  • APIs to record and replay HTTP traffic to disk or memory
  • Static file-serving capability with Caching and Hot-Reload
  • Single Page Application support with Caching and Hot-Reload
  • WebJars support in 1LOC`
• Client:
  • 1LOC client adapters
    • Apache sync + async HTTP
    • Java (bundled with http4k-core)
    • Fuel HTTP (supports sync and async HTTP)
    • Jetty HTTP (supports sync and async HTTP)
    • OkHttp HTTP (supports sync and async HTTP)
  • 1LOC WebSocket client, with blocking and non-blocking modes
  • GraphQL client (bundled with GraphQL module)
• Server:
  • 1LOC server backend spin-up for:
    • Apache v4 & v5 (from httpcore)
    • Jetty (including WebSocket support)
    • Ktor CIO & Netty
    • Netty (including WebSocket support)
    • SunHttp (bundled with http4k-core)
    • Undertow (including SSE and WebSocket support)
  • API design allows for simple customization of underying backend.
  • Native Friendly Several of the supported backends can be compiled with GraalVM and Quarkus with zero configuration.
• Serverless:
  • Function-based support for both HTTP and Event-based applications via adapters, using the simple and testable HttpHandler and FnHandler types.
  • AWS Lambda Extend custom adapters to serve HTTP apps from APIGateway or use react to AWS events (without using the heavyweight AWS serialisation).
  • Custom AWS Lambda Runtime Avoid the heavyweight AWS runtime, or simply compile your http4k app to GraalVM and get cold-starts in a few milliseconds!
  • Google Cloud Functions Extend custom adapters to serve HTTP apps from Google Cloud Functions or use react to GCloud events.
  • Apache OpenWhisk Extend custom adapters to serve HTTP apps or react to JSON events in IBM Cloud/OpenWhisk installations.
  • Azure Functions Extend custom adapters to serve HTTP apps from AzureCloud.
  • Alibaba Function Compute Extend custom adapters to serve HTTP apps from Alibaba.
  • Tencent Serverless Cloud Functions Extend custom adapters to serve HTTP apps from SCF.
• Contracts:
  • Define Typesafe HTTP contracts, with required and optional path/query/header/bodies
  • Typesafe path matching
  • Auto-validation of incoming requests == zero boilerplate validation code
  • Self-documenting for all routes - eg. Built in support for live OpenApi v2 and v3 description endpoints including JSON Schema model breakdown.
• Templating:
  • Pluggable templating system support for:
    • Dust
    • Freemarker
    • Handlebars
    • Pebble
    • Thymeleaf
    • Jade4j
  • Caching and Hot-Reload template support
• Message formats:
  • Consistent API provides first class support for marshalling formats to/from HTTP messages for:
    • JSON - with support for:
      • Jackson - includes support for fully automatic marshalling of Data classes
      • Gson - includes support for fully automatic marshalling of Data classes
      • Klaxon - includes support for fully automatic marshalling of Data classes
      • Moshi - includes support for fully automatic marshalling of Data classes
      • KotlinX Serialization - official Kotlin JSON API.
      • Argo - lightweight Java JSON API with zero dependencies.
    • XML - includes support for:
      • Jackson - includes support for fully automatic marshalling of Data classes
      • Xml - includes support for one way automatic marshalling of Data classes
    • YAML - includes support for:
      • Jackson - includes support for fully automatic marshalling of Data classes
      • Moshi - includes support for fully automatic marshalling of Data classes
    • CSV - includes support for:
      • Jackson - CSV format for Jackson
• Resilience4J:
  • Circuits, Retrying, Rate-Limiting, Bulkheading via Resilience4J integration
• Micrometer:
  • Support for plugging http4k apps into Micrometer.
• Cloud Events:
  • Consume and produce CloudEvents using typesafe lenses.
• OpenTelemetry:
  • Instrument http4k apps with OpenTelemetry tooling.
• Multipart:
  • Support for Multipart HTML forms, including Lens extensions for type-safe marshalling of fields.
• GraphQL:
  • Integration with GraphQL Java library to route and serve Graph-based apps. Plus conversion of any HttpHandler to be a GraphQL client.
• AWS:
  • Plug a standard HttpHandler into the AWS v2 SDKs. This massively simplifies testing and allows for sniffing of the exact traffic going to AWS - brilliant for debugging and building fakes.
  • Client filter to allow super-simple interaction with AWS services (via request signing)
• OAuth Security:
  • Implement OAuth Authorisation Code Grant flow with a single Interface
  • Pre-configured OAuth for following providers:
    • Auth0
    • Dropbox
    • Google
    • Soundcloud
• Digest Security:
  • Implement the Digest Authentication flow for clients and servers
  • Supports the null and Auth QoPs
  • Supports Proxy Authentication
• Cloud Native:
  • Tooling to support operating http4k applications in orchestrated cloud environments such as Kubernetes and CloudFoundry. 12-factor configuration, dual-port servers and health checks such as liveness and readiness checking.
• Approval Testing:
  • JUnit 5 extensions for Approval testing of http4k Request and Response messages.
• Chaos:
  • API for declaring and injecting failure modes into http4k applications, allowing modelling and hence answering of "what if" style questions to help understand how code fares under failure conditions such as latency and dying processes.
• Hamkrest:
  • A set of Hamkrest matchers for testing http4k Request and Response messages.
• Kotest:
  • A set of Kotest matchers for testing http4k Request and Response messages.
• Service Virtualisation:
  • Record and replay versioned HTTP contracts to/from Servirtium Markdown format. Includes Servirtium MiTM server and simple JUnit extensions.
• Strikt:
  • A set of Strikt matchers for testing http4k Request and Response messages.
• WebDriver:
  • Ultra-lightweight Selenium WebDriver implementation for http4k application.

Example

This quick example is designed to convey the simplicity & features of http4k . See also the quickstart for the simplest possible starting point and demonstrates how to serve and consume HTTP services with dynamic routing.

To install, add these dependencies to your Gradle file:

dependencies {
    implementation group: "org.http4k", name: "http4k-core", version: "4.27.4.0"
    implementation group: "org.http4k", name: "http4k-server-jetty", version: "4.27.4.0"
    implementation group: "org.http4k", name: "http4k-client-okhttp", version: "4.27.4.0"
}

package guide.howto.readme

import org.http4k.client.OkHttp
import org.http4k.core.Filter
import org.http4k.core.HttpHandler
import org.http4k.core.Method.GET
import org.http4k.core.Request
import org.http4k.core.Response
import org.http4k.core.Status.Companion.OK
import org.http4k.core.then
import org.http4k.filter.CachingFilters
import org.http4k.routing.bind
import org.http4k.routing.path
import org.http4k.routing.routes
import org.http4k.server.Jetty
import org.http4k.server.asServer

fun main() {
    // we can bind HttpHandlers (which are just functions from  Request -> Response) to paths/methods to create a Route,
    // then combine many Routes together to make another HttpHandler
    val app: HttpHandler = routes(
        "/ping" bind GET to { _: Request -> Response(OK).body("pong!") },
        "/greet/{name}" bind GET to { req: Request ->
            val name: String? = req.path("name")
            Response(OK).body("hello ${name ?: "anon!"}")
        }
    )

    // call the handler in-memory without spinning up a server
    val inMemoryResponse: Response = app(Request(GET, "/greet/Bob"))
    println(inMemoryResponse)

// Produces:
//    HTTP/1.1 200 OK
//
//
//    hello Bob

    // this is a Filter - it performs pre/post processing on a request or response
    val timingFilter = Filter {
        next: HttpHandler ->
        {
            request: Request ->
            val start = System.currentTimeMillis()
            val response = next(request)
            val latency = System.currentTimeMillis() - start
            println("Request to ${request.uri} took ${latency}ms")
            response
        }
    }

    // we can "stack" filters to create reusable units, and then apply them to an HttpHandler
    val compositeFilter = CachingFilters.Response.NoCache().then(timingFilter)
    val filteredApp: HttpHandler = compositeFilter.then(app)

    // only 1 LOC to mount an app and start it in a container
    filteredApp.asServer(Jetty(9000)).start()

    // HTTP clients are also HttpHandlers!
    val client: HttpHandler = OkHttp()

    val networkResponse: Response = client(Request(GET, "http://localhost:9000/greet/Bob"))
    println(networkResponse)

// Produces:
//    Request to /api/greet/Bob took 1ms
//    HTTP/1.1 200
//    cache-control: private, must-revalidate
//    content-length: 9
//    date: Thu, 08 Jun 2017 13:01:13 GMT
//    expires: 0
//    server: Jetty(9.3.16.v20170120)
//
//    hello Bob
}

Acknowledgments

• Dan Bodart's utterlyidle
• Ivan Moore for pairing on "BarelyMagical", a 50-line wrapper around utterlyidle to allow "Server as a Function"

Contributors

This project exists thanks to all the people who contribute.

Backers & Sponsors

If you use http4k in your project or enterprise and would like to support ongoing development, please consider becoming a backer or a sponsor. Sponsor logos will show up here with a link to your website.