Skip to content
Hexagon is a microservices toolkit written in Kotlin. Its purpose is to ease the building of services (Web applications, APIs or queue consumers) that run inside a cloud platform.
Kotlin HTML Scala JavaScript Dockerfile CSS Shell
Branch: master
Clone or download

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Restore MkDocs Material latest version Feb 21, 2020
buildSrc Improve coverage report generation Feb 1, 2020
gradle Strip signs from dependencies' jars on full JAR packaging Feb 21, 2020
hexagon_benchmark GraalVM native image generation (wip) Feb 21, 2020
hexagon_core GraalVM native image generation (wip) Feb 21, 2020
hexagon_scheduler Remove unneeded Gradle helper inclusion Feb 3, 2020
hexagon_site Add project repository Feb 21, 2020
hexagon_starters Add project repository Feb 21, 2020
hexagon_web Remove unneeded Gradle helper inclusion Feb 3, 2020
http_client_ahc AHC Adapter clean up Feb 18, 2020
http_server_jetty Extract key store passwords outside URIs Feb 16, 2020
http_server_servlet
messaging_rabbitmq Fix SonarQube issues Feb 11, 2020
port_http_client Debug (and hopefully fix) SonarQube analysis Feb 13, 2020
port_http_server Improve examples Feb 21, 2020
port_messaging Test SonarQube settings Feb 1, 2020
port_store Test SonarQube settings Feb 1, 2020
port_templates Fix SonarQube issues Feb 11, 2020
store_mongodb Test SonarQube settings Feb 1, 2020
templates_pebble Fix SonarQube issues Feb 11, 2020
.editorconfig Minor improvements Dec 18, 2019
.gitignore Fix build scripts Feb 1, 2020
.travis.yml Update .travis.yml Feb 17, 2020
README.md Improve examples Feb 21, 2020
build.gradle.kts Delete Lazybones support Feb 11, 2020
code_of_conduct.md Documentation update and clean up Nov 13, 2018
contributing.md Replace Codecov and Codebeat by SonarQube Feb 6, 2020
docker-compose.yml Infrastructure improvements Feb 7, 2020
gradlew Improve site (#175) Mar 24, 2019
gradlew.bat Improve site (#175) Mar 24, 2019
license.md Site updates (#112) Nov 27, 2017
settings.gradle.kts New release version Feb 21, 2020

README.md

Hexagon
Hexagon

The atoms of your platform

Travis CI SonarQube Bintray

Home Site | Quick Start | Developer Guide | HTTP Server


What is Hexagon

Hexagon is a microservices toolkit (not a framework) written in Kotlin. Its purpose is to ease the building of services (Web applications, APIs or queue consumers) that run inside a cloud platform.

It is meant to provide abstraction from underlying technologies (data storage, HTTP server engines, etc.) to be able to change them with minimum impact. It is designed to fit in applications that conforms to the Hexagonal Architecture (also called Clean Architecture or Ports and Adapters Architecture).

The goals of the project are:

  1. Be simple to use: make it easy to develop user services (HTTP or message consumers) quickly. It is focused on making the usual tasks easy.
  2. Make it easy to hack: allow the user to add extensions or change the toolkit itself. The code is meant to be simple for the users to understand it.

Which are NOT project goals:

  1. To be the fastest framework. Write the code fast and optimize only the critical parts. It is not slow anyway.
  2. Support all available technologies and tools: the spirit is to define simple interfaces for the most common features , so users can implement integrations with different tools easily.
  3. To be usable from Java. Hexagon is Kotlin first.

Hexagon Structure

There are three kind of client libraries:

  • The ones that provide a single functionality that does not depend on different implementations.
  • Modules that define a "Port": An interface to a feature that may have different implementations.
  • Adapter modules, which are Port implementations for a given tool.

Ports are independent from each other.

Hexagon Core module provides convenience utilities. The main features it has are:

Simple HTTP service

You can clone a starter project (Gradle Starter or Maven Starter). Or you can create a project from scratch following these steps:

  1. Configure Kotlin in Gradle or Maven.
  2. Setup the JCenter repository (follow the link and click on the Set me up! button).
  3. Add the dependency:
  • In Gradle. Import it inside build.gradle:

    compile ("com.hexagonkt:http_server_jetty:$hexagonVersion")
  • In Maven. Declare the dependency in pom.xml:

    <dependency>
      <groupId>com.hexagonkt</groupId>
      <artifactId>http_server_jetty</artifactId>
      <version>$hexagonVersion</version>
    </dependency>
  1. Write the code in the src/main/kotlin/Hello.kt file:
// hello
package com.hexagonkt.starters

import com.hexagonkt.helpers.logger
import com.hexagonkt.http.httpDate
import com.hexagonkt.http.server.Server
import com.hexagonkt.http.server.ServerPort
import com.hexagonkt.http.server.jetty.JettyServletAdapter
import com.hexagonkt.injection.InjectionManager

val injector = InjectionManager.apply {
    bindObject<ServerPort>(JettyServletAdapter()) // Bind Jetty server to HTTP Server Port
}

/**
 * Service server. Adapter is injected.
 */
val server: Server = Server {
    before { response.setHeader("Date", httpDate()) }

    get("/hello/{name}") { ok("Hello, ${pathParameters["name"]}!", "text/plain") }
}

/**
 * Start the service from the command line.
 */
fun main() {
    logger.info { injector }
    server.start()
}
// hello
  1. Run the service and view the results at: http://localhost:2010/hello/world

You can check the Developer Guide for more details. Or you can clone the Gradle Starter or Maven Starter for a minimal fully working example (including tests).

Books Example

A simple CRUD example showing how to manage book resources. Here you can check the full test.

// books
data class Book(val author: String, val title: String)

private val books: MutableMap<Int, Book> = linkedMapOf(
    100 to Book("Miguel de Cervantes", "Don Quixote"),
    101 to Book("William Shakespeare", "Hamlet"),
    102 to Book("Homer", "The Odyssey")
)

val server: Server = Server(adapter) {
    post("/books") {
        // Require fails if parameter does not exists
        val author = queryParameters.require("author").first()
        val title = queryParameters.require("title").first()
        val id = (books.keys.max() ?: 0) + 1
        books += id to Book(author, title)
        send(201, id)
    }

    get("/books/{id}") {
        val bookId = pathParameters.require("id").toInt()
        val book = books[bookId]
        if (book != null)
            // ok() is a shortcut to send(200)
            ok("Title: ${book.title}, Author: ${book.author}")
        else
            send(404, "Book not found")
    }

    put("/books/{id}") {
        val bookId = pathParameters.require("id").toInt()
        val book = books[bookId]
        if (book != null) {
            books += bookId to book.copy(
                author = queryParameters["author"]?.first() ?: book.author,
                title = queryParameters["title"]?.first() ?: book.title
            )

            ok("Book with id '$bookId' updated")
        }
        else {
            send(404, "Book not found")
        }
    }

    delete("/books/{id}") {
        val bookId = pathParameters.require("id").toInt()
        val book = books[bookId]
        books -= bookId
        if (book != null)
            ok("Book with id '$bookId' deleted")
        else
            send(404, "Book not found")
    }

    // Matches path's requests with *any* HTTP method as a fallback (return 404 instead 405)
    any("/books/{id}") { send(405) }

    get("/books") { ok(books.keys.joinToString(" ", transform = Int::toString)) }
}
// books

Session Example

Example showing how to use sessions. Here you can check the full test.

// session
val server: Server = Server(adapter) {
    path("/session") {
        get("/id") { ok(session.id ?: "null") }
        get("/access") { ok(session.lastAccessedTime?.toString() ?: "null") }
        get("/new") { ok(session.isNew()) }

        path("/inactive") {
            get { ok(session.maxInactiveInterval ?: "null") }

            put("/{time}") {
                session.maxInactiveInterval = pathParameters.require("time").toInt()
            }
        }

        get("/creation") { ok(session.creationTime ?: "null") }
        post("/invalidate") { session.invalidate() }

        path("/{key}") {
            put("/{value}") {
                session.set(pathParameters.require("key"), pathParameters.require("value"))
            }

            get { ok(session.get(pathParameters.require("key")).toString()) }
            delete { session.remove(pathParameters.require("key")) }
        }

        get {
            val attributes = session.attributes
            val attributeTexts = attributes.entries.map { it.key + " : " + it.value }

            response.setHeader("attributes", attributeTexts.joinToString(", "))
            response.setHeader("attribute values", attributes.values.joinToString(", "))
            response.setHeader("attribute names", attributes.keys.joinToString(", "))

            response.setHeader("creation", session.creationTime.toString())
            response.setHeader("id", session.id ?: "")
            response.setHeader("last access", session.lastAccessedTime.toString())

            response.status = 200
        }
    }
}
// session

Cookies Example

Demo server to show the use of cookies. Here you can check the full test.

// cookies
val server: Server = Server(adapter) {
    post("/assertNoCookies") {
        if (request.cookies.isNotEmpty())
            halt(500)
    }

    post("/addCookie") {
        val name = queryParameters["cookieName"]?.first()
        val value = queryParameters["cookieValue"]?.first()
        response.addCookie(HttpCookie(name, value))
    }

    post("/assertHasCookie") {
        val cookieName = queryParameters.require("cookieName").first()
        val cookieValue = request.cookies[cookieName]?.value
        if (queryParameters["cookieValue"]?.first() != cookieValue)
            halt(500)
    }

    post("/removeCookie") {
        response.removeCookie(queryParameters.require("cookieName").first())
    }
}
// cookies

Error Handling Example

Code to show how to handle callback exceptions and HTTP error codes. Here you can check the full test.

// errors
class CustomException : IllegalArgumentException()

val server: Server = Server(adapter) {
    error(UnsupportedOperationException::class) {
        response.setHeader("error", it.message ?: it.javaClass.name)
        send(599, "Unsupported")
    }

    error(IllegalArgumentException::class) {
        response.setHeader("runtimeError", it.message ?: it.javaClass.name)
        send(598, "Runtime")
    }

    // Catching `Exception` handles any unhandled exception before (it has to be the last)
    error(Exception::class) { send(500, "Root handler") }

    // It is possible to execute a handler upon a given status code before returning
    error(588) { send(578, "588 -> 578") }

    get("/exception") { throw UnsupportedOperationException("error message") }
    get("/baseException") { throw CustomException() }
    get("/unhandledException") { error("error message") }

    get("/halt") { halt("halted") }
    get("/588") { halt(588) }
}
// errors

Filters Example

This example shows how to add filters before and after route execution. Here you can check the full test.

// filters
private val users: Map<String, String> = mapOf(
    "Turing" to "London",
    "Dijkstra" to "Rotterdam"
)

private val server: Server = Server(adapter) {
    before { attributes["start"] = nanoTime() }

    before("/protected/*") {
        val authorization = request.headers["Authorization"] ?: halt(401, "Unauthorized")
        val credentials = authorization.first().removePrefix("Basic ")
        val userPassword = String(Base64.getDecoder().decode(credentials)).split(":")

        // Parameters set in call attributes are accessible in other filters and routes
        attributes["username"] = userPassword[0]
        attributes["password"] = userPassword[1]
    }

    // All matching filters are run in order unless call is halted
    before("/protected/*") {
        if(users[attributes["username"]] != attributes["password"])
            halt(403, "Forbidden")
    }

    get("/protected/hi") { ok("Hello ${attributes["username"]}!") }

    // After filters are ran even if request was halted before
    after { response.setHeader("time", nanoTime() - attributes["start"] as Long) }
}
// filters

Files Example

The following code shows how to serve resources and receive files. Here you can check the full test.

// files
private val server: Server = Server(adapter) {
    path("/static") {
        get("/files/*", Resource("assets")) // Serve `assets` resources on `/html/*`
        get("/resources/*", File(directory)) // Serve `test` folder on `/pub/*`
    }

    get("/html/*", Resource("assets")) // Serve `assets` resources on `/html/*`
    get("/pub/*", File(directory)) // Serve `test` folder on `/pub/*`
    get(Resource("public")) // Serve `public` resources folder on `/*`

    post("/multipart") { ok(request.parts.keys.joinToString(":")) }

    post("/file") {
        val part = request.parts.values.first()
        val content = part.inputStream.reader().readText()
        ok(content)
    }

    post("/form") {
        fun serializeMap(map: Map<String, List<String>>): List<String> = listOf(
            map.map { "${it.key}:${it.value.joinToString(",")}}" }.joinToString("\n")
        )

        val queryParams = serializeMap(queryParameters)
        val formParams = serializeMap(formParameters)
        val params = serializeMap(parameters)

        response.headers["queryParams"] = queryParams
        response.headers["formParams"] = formParams
        response.headers["params"] = params
    }
}
// files

CORS Example

The following code shows how to set up CORS for REST APIs used from the browser. You can check the full test.

// cors
val server: Server = Server(adapter) {
    corsPath("/default", CorsSettings())
    corsPath("/example/org", CorsSettings("example.org"))
    corsPath("/no/credentials", CorsSettings(supportCredentials = false))
    corsPath("/only/post", CorsSettings(allowedMethods = setOf(POST)))
    corsPath("/cache", CorsSettings(preFlightMaxAge = 10))
    corsPath("/exposed/headers", CorsSettings(exposedHeaders = setOf("head")))
    corsPath("/allowed/headers", CorsSettings(allowedHeaders = setOf("head")))
}

private fun Router.corsPath(path: String, settings: CorsSettings) {
    path(path) {
        // CORS settings can change for different routes
        cors(settings)

        get("/path") { ok(request.method) }
        post("/path") { ok(request.method) }
        put("/path") { ok(request.method) }
        delete("/path") { ok(request.method) }
        get { ok(request.method) }
        post { ok(request.method) }
        put { ok(request.method) }
        delete { ok(request.method) }
    }
}
// cors

HTTPS Example

The snippet below shows how to set up your server to use HTTPS and HTTP/2. You can check the full test.

// https
// Key store files
val identity = "hexagonkt.p12"
val trust = "trust.p12"

// Default passwords are file name reversed
val keyStorePassword = identity.reversed()
val trustStorePassword = trust.reversed()

// Key stores can be set as URIs to classpath resources (the triple slash is needed)
val keyStore = URI("resource:///ssl/$identity")
val trustStore = URI("resource:///ssl/$trust")

val sslSettings = SslSettings(
    keyStore = keyStore,
    keyStorePassword = keyStorePassword,
    trustStore = trustStore,
    trustStorePassword = trustStorePassword,
    clientAuth = true // Requires a valid certificate from the client (mutual TLS)
)

val serverSettings = ServerSettings(
    bindPort = 0,
    protocol = HTTPS, // You can also use HTTP2
    sslSettings = sslSettings
)

val server = serve(serverSettings, serverAdapter) {
    get("/hello") {
        // We can access the certificate used by the client from the request
        val subjectDn = request.certificate?.subjectDN?.name
        response.setHeader("cert", subjectDn)
        ok("Hello World!")
    }
}

// We'll use the same certificate for the client (in a real scenario it would be different)
val clientSettings = ClientSettings(sslSettings = sslSettings)

// Create a HTTP client and make a HTTPS request
val client = Client(AhcAdapter(), "https://localhost:${server.runtimePort}", clientSettings)
client.get("/hello").apply {
    logger.debug { body }
    // Assure the certificate received (and returned) by the server is correct
    assert(headers.require("cert").first().startsWith("CN=hexagonkt.com"))
    assert(body == "Hello World!")
}
// https

Status

DISCLAIMER: The project is not yet production ready. Use it at your own risk. There are some modules not finished yet (e.g.: storage and HTTP client).

It is used in personal not released projects to develop APIs and Web applications.

Performance is not the primary goal, but it is taken seriously. You can check performance numbers in the TechEmpower Web Framework Benchmarks. You can also run the stress tests, to do so, read the Benchmark readme

Tests, of course, are taken into account. These are some coverage metrics:

Coverage Lines

The code quality is checked by SonarQube:

Maintainability Reliability Security

Contribute

If you like this project and want to support it, the easiest way is to give it a star ✌️.

If you feel like you can do more. You can contribute to the project in different ways:

To know what issues are currently open and be aware of the next features you can check the Project Board at GitHub.

You can ask any question, suggestion or complaint at the project's Slack channel. And be up to date of project's news following @hexagon_kt in Twitter.

Thanks to all project's contributors!

CodeTriage

License

The project is licensed under the MIT License. This license lets you use the source for free or commercial purposes as long as you provide attribution and don’t hold any project member liable.

You can’t perform that action at this time.