Server

As a basic requirement, the server always needs a handler to be supplied to serve incoming requests. See the Content section to get a list of suitable handlers.

Server instances are usually created using the Host factory. Depending on your use case, you can either use a blocking or non-blocking call.

import org.genhttp.api.content.io.Resource
import org.genhttp.engine.internal.Host
import org.genhttp.modules.io.Content
import org.genhttp.modules.io.fromString
import org.genhttp.modules.practices.defaults

import kotlin.system.exitProcess

suspend fun main() {
    // the content we would like to serve
    val content = Content.from(Resource.fromString("Hello World!"))

    // blocking until the application receives a shutdown signal (e.g. main function of a standalone application)
    val exitCode = Host.create()
        .handler(content)
        .defaults()
        .run()

    exitProcess(exitCode)
}

val content = Content.from(Resource.fromString("Hello World!"))

// non-blocking (e.g. for in-process embedding or test libraries)
val host = Host.create()
    .handler(content)
    .defaults()
    .start()

try {
    // do something with the server instance
} finally {
    // release resources
    host.stop()
}

The server will start to listen for requests as soon as run() or start() is called. Both are suspend functions: run() suspends until the JVM shuts down (e.g. on Ctrl+C or SIGTERM), then stops the server and returns the exit code, while start() returns as soon as the server is listening. When stopped, the server will stop to process messages and release all claimed resources.

By default, the server will listen to all IP addresses on port 8080. These settings can be adjusted as needed. The defaults() call adds typical features such as compression and client caching.

Security

By default, the server will provide an HTTP endpoint on port 8080 with no SSL support enabled. It is recommended to serve all of your web applications by a dedicated reverse proxy such as nginx or the GenHTTP Gateway. Nevertheless, the server allows you to add HTTPS endpoints to your application.

Content