//clika-runtime/io.clika.runtime/HttpServer

HttpServer

[common]
class HttpServer

The runtime's HTTP server: routes by verb and path (exact, or a pattern whose groups become captures), route groups, middleware, static files, the failure and error pages, an access logger, the tuning knobs, and the start and stop (listen blocks; listenAsync / bindToAnyPort serve on a background thread; stop drains). A handler runs on the server's own thread; the runtime attaches it to the JVM for the call. AutoCloseable: close stops the server if it runs and releases it. A borrowed server (isBorrowed) is another object's, handed out for its routes: close drops the handle and releases nothing, and the owner's start, stop and lifetime stay the owner's.

HttpServer.create().use { server ->
    server.get("/hello") { ServerResponse.text("hi") }
    val port = server.bindToAnyPort("127.0.0.1")
    println(Http.getText("http://127.0.0.1:$port/hello"))   // hi
    server.stop()
}

Types

Name	Summary
Companion	[common] object Companion

Properties

Name	Summary
isBorrowed	[common] val isBorrowed: Boolean = false True for a server another object owns; close then releases nothing.
isRunning	[common] val isRunning: Boolean True while the server serves.
port	[common] val port: Int The port served, once bound.

Functions

Name	Summary
addStaticFile	[common] fun addStaticFile(urlPath: String, file: String) Serve one file at one exact urlPath.
bindToAnyPort	[common] fun bindToAnyPort(host: String): Int Serve on host at a port the system picks, on a background thread; the port is answered.
close	[common] open fun close()
delete	[common] fun delete(path: String, handler: Handler): HttpServer A DELETE route.
get	[common] fun get(path: String, handler: Handler): HttpServer A GET route (HEAD falls back to it when no HEAD route exists).
group	[common] fun group(prefix: String): RouteGroup A group of routes under prefix.
listen	[common] fun listen(host: String, port: Int) Serve on host:port, blocking this thread until stop is called from another.
listenAsync	[common] fun listenAsync(host: String, port: Int) Serve on host:port on a background thread; returns once the server accepts.
mount	[common] fun mount(urlPrefix: String, dir: String) Serve the files under dir at urlPrefix.
patch	[common] fun patch(path: String, handler: Handler): HttpServer A PATCH route.
post	[common] fun post(path: String, handler: Handler): HttpServer A POST route.
put	[common] fun put(path: String, handler: Handler): HttpServer A PUT route.
route	[common] fun route(method: Method, path: String, handler: Handler): HttpServer Register handler for method at the exact path. Returns this for chaining.
routePattern	[common] fun routePattern(method: Method, pattern: String, handler: Handler): HttpServer Register handler for method at a path pattern (a regular expression; its groups are the captures).
setBodyDeadline	[common] fun setBodyDeadline(seconds: Int) The ceiling from the end of the headers to the end of the declared body, in seconds (0 disables it).
setDefaultHeader	[common] fun setDefaultHeader(name: String, value: String) A header appended to every response.
setErrorHandler	[common] fun setErrorHandler(handler: ErrorHandler?) The page of an error status such as a 404 (null restores the default page).
setExceptionHandler	[common] fun setExceptionHandler(handler: ExceptionHandler?) The page of a handler that raised (null restores the default 500).
setHeaderDeadline	[common] fun setHeaderDeadline(seconds: Int) The ceiling from a request's first byte to the end of its headers, in seconds (0 disables it).
setKeepAliveTimeout	[common] fun setKeepAliveTimeout(seconds: Int) How long an idle connection stays open between requests, in seconds.
setLogger	[common] fun setLogger(logger: Logger?) The per-request access logger (null removes it).
setMaxConnections	[common] fun setMaxConnections(count: Long) The concurrent-connection ceiling; 0 means unlimited.
setMimeType	[common] fun setMimeType(extension: String, mime: String) Map a file extension (with its dot) to a mime type for the static routes.
setPayloadMaxLength	[common] fun setPayloadMaxLength(bytes: Long) The largest request body accepted, in bytes.
setReadTimeout	[common] fun setReadTimeout(seconds: Int) How long one read waits for the next byte of a request, in seconds.
setTls	[common] fun setTls(certPath: String, keyPath: String) Serve HTTPS with this certificate and private key (PEM file paths).
setWriteTimeout	[common] fun setWriteTimeout(seconds: Int) The per-connection write timeout, in seconds.
stop	[common] fun stop() Stop accepting and drain: in-flight handlers finish and their responses flush.
use	[common] fun use(middleware: Middleware): HttpServer Add a middleware to every route (run in registration order).
waitUntilReady	[common] fun waitUntilReady(timeoutMs: Int = 30000) Block until the server accepts, or fail after timeoutMs.