genhttp-kt

Coming from GenHTTP

Mon, 01 Jan 0001 00:00:00 +0000

If you know GenHTTP, you already know genhttp-kt. The API is the same - the same builders, modules, handlers and concerns - written the way a Kotlin developer expects. This page shows how C# translates, so you can use the samples you find for GenHTTP, and the GenHTTP documentation itself, with genhttp-kt.

The samples on this page have a C# and a Kotlin tab. Choose one and every sample of the page switches with it.

Internal

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-full Package on Maven Central genhttp-core Package on Maven Central

This is the default HTTP implementation of genhttp-kt, the port of GenHTTP’s internal engine. It is written in Kotlin and relies only on the JDK, kotlinx.coroutines and the SLF4J API, which keeps the dependencies of your application and the environment it needs to a minimum. This makes it a good choice for embedding a web service into another application (e.g. a desktop application) or hosting a small service as a Docker container. Both genhttp-core and genhttp-full contain it.

Request API

Mon, 01 Jan 0001 00:00:00 +0000

Request API

To handle incoming HTTP requests, genhttp-kt uses the Request abstraction, which - besides granting access to infrastructure components such as the Server, EndPoint or ClientConnection - is intended to represent the data on the wire as it was received by the connected client.

The core entry points to handle requests are handlers and concerns. The server host is passed a handler instance (known as root handler) which is then responsible for handling all incoming requests. If needed, it can use other handlers to delegate work (see layouting as a starting point).

Routing

Mon, 01 Jan 0001 00:00:00 +0000

When the server receives a request from the client, it passes it to the root handler specified by your application. Depending on the requested path, this handler may invoke additional handlers to actually produce a response. The tree of handlers available in your application is called handler chain. As requests are passed from one handler to another, they need to track, which segments of the requested path have already been considered and which still need to be evaluated, effectively decoupling them from each other. This capability is provided by the routing feature of the framework.

Webservices

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-webservices Package on Maven Central

The webservice module provides an easy way to implement RESTful services that can be consumed by clients as needed.

Deviations

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-kt keeps the API and the behavior of GenHTTP. Where the JVM, Kotlin or a library requires a different solution, the port says so - this page lists every such place, grouped by the area you will meet it in. The complete log is DEVIATIONS.md in the repository.

The one you are most likely to trip over: Kotlin does not allow annotations or default values on lambda parameters. A functional handler that needs @FromBody or an optional parameter is written as a function reference (post(::create)), see Coming from GenHTTP.

Functional Handlers

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-functional Package on Maven Central

With this module, requests can be handled in a functional manner, reducing the boilerplate code to be written by a web application developer.

Method Definitions

Mon, 01 Jan 0001 00:00:00 +0000

All API frameworks share a common base provided by the Reflection and Conversion modules which define some of the capabilities that can be used when defining an API method signature.

Injection

This section describes how parameters of your functions are initialized and which kind of types can be used.

Primitives

By default, a parameter type can be used within a method definition if it is either String, Boolean, an enum, a number (such as Int, Long, Double or BigDecimal), a UUID, or one of the date and time types Instant, OffsetDateTime, LocalDateTime, LocalDate, LocalTime and kotlin.time.Duration.

Netty

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-full-netty Package on Maven Central genhttp-core-netty Package on Maven Central

The native transports of Netty (epoll and io_uring) are included for Linux on x64 and arm64. On other platforms, such as Windows and macOS, the engine runs on Java NIO, which behaves the same but does not reach the same throughput.

Controllers

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-controllers Package on Maven Central

This framework allows to create APIs by defining and implementing controller classes. In contrast to Spring MVC, you cannot use this framework to dynamically render HTML pages in an MVC style project, so this is just another flavor of defining a web API.

Execution Modes

Mon, 01 Jan 0001 00:00:00 +0000

The service frameworks (webservices, functional handlers and controllers) analyze the signature of each of your functions with kotlin-reflect: where every argument is read from, how the result is sent to the client and which interceptors run before the function. This analysis is done once, while the handler chain is prepared (i.e. when the server starts), and not when a request is handled.

For every request, the framework then reads the arguments in the order of the parameters, invokes the function and maps the result into an HTTP response. How the function is invoked is controlled by the execution mode.

Logging

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-kt logs through SLF4J, the logging facade of the JVM, and allows to create loggers via the Server interface. If there is an SLF4J provider on the classpath (such as Logback, Log4j 2 or slf4j-simple), the server logs through it. Otherwise, the host falls back to a console logger of its own (and SLF4J warns once at startup that it found no provider).

Logging Information

The following code shows to obtain a logger from the server instance in a custom Handler implementation. It is recommended to create the logger once in the preparation phase and store the reference somewhere. You can use this pattern anywhere where you have access to Server (e.g. via request.server).

Versions and Sync

Mon, 01 Jan 0001 00:00:00 +0000

Versions

Versions of genhttp-kt have four components: the version of GenHTTP the port is based on, followed by a counter of releases of the port itself.

Version	Meaning
`11.1.0.0`	The first release based on GenHTTP `11.1.0`
`11.1.0.1`	A release of the port only - a fix in the port, updated libraries
`11.2.0.0`	The first release based on GenHTTP `11.2.0` - the counter resets

Gradle and Maven order these versions correctly, and the tags of the repository are named after them (v11.1.0.0). This documentation describes genhttp-kt 11.1.0.3, based on GenHTTP 11.1.0.

Endpoints and Ports

Mon, 01 Jan 0001 00:00:00 +0000

By default, the server will listen on port 8080 for incoming IPv4 or IPv6 connections on any interface. To simply change the port the server will listen on, you can use the port() directive of the host. Please note, that hosting a server on ports below 1024 will require additional permissions on some operating systems.

 Kotlin
 
 
val app = Layout.create()

val host = Host.create()
 .handler(app)
 .port(80)

To configure the server to listen on specific interfaces only, you can bind() those endpoints explicitly. As soon as an endpoint is bound, the port set via port() is ignored.

Response Content

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-io Package on Maven Central

When sending content in response to a client request, ResponseBuilder has a single entry point for it: content(content: ResponseContent?). Everything about the content itself - its length, type and encoding - is a property of the ResponseContent implementation being passed in, not something configured separately on the builder. length is the number of bytes the content will produce; if it is not known, chunked transfer encoding is applied.

Websockets

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-websockets Package on Maven Central

Websockets allow to create a bidirectional connection between your clients and your server, allowing both sides to push content without the need of sending HTTP requests.

Resources

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-io Package on Maven Central

genhttp-kt provides a thin abstraction layer to control access of binary resources (such as files or blobs). This allows to re-use file-dependent handlers, independent from whether the data comes from the file system, the classpath, a database or somewhere else.

Security

Mon, 01 Jan 0001 00:00:00 +0000

This page summarizes security considerations and configuration options when running genhttp-kt applications.

General Considerations

genhttp-kt is designed to be used as an application server behind a reverse proxy, and therefore does not provide built-in DoS protection (such as IP connection limits or Slowloris prevention). However, its engines are hardened against typical attack vectors such as request smuggling, header injection, or malformed chunk attacks: both parse requests with a port of Glyph11, the hardened parser of GenHTTP, and passes the ported acceptance tests of GenHTTP, which is explicitly tested for these attacks.

Single Page Applications (SPA)

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-single-page-applications Package on Maven Central

This handler provides an easy way to serve a single page application (for example a Vue.js, React, or Angular app) to your clients.

Dependency Injection

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-dependency-injection Package on Maven Central

This optional module allows to use Koin to inject dependencies into handlers, concerns and framework classes as well as their functions.

Static Websites

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-static-websites Package on Maven Central

This handler provides an easy way to serve a static website such as a Hugo application to your clients.

Custom Frameworks

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-reflection Package on Maven Central

The framework layer of genhttp-kt allows application frameworks (such as webservices or controllers) to host a set of operations (put simply a route with a piece of Kotlin code to be executed). This way the application framework itself is only a very thin layer - it analyzes the given scope (such as a controller class) and derives operations from it which are then handled by the generic framework part. This way, all application frameworks share the same feature level and can support things like parameter binding, serialization, suspend functions or execution modes. To give an example, the handler which provides the whole webservice framework consists of about 60 lines of code only - everything else is done by the underlying framework layer.

API Browsing

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-api-browsing Package on Maven Central

This module adds JavaScript based applications to visualize an Open API definition such as Swagger UI, Redoc or Scalar to your app. All resources required by those apps are hosted locally so no internet connection is required.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-authentication Package on Maven Central

The authentication module allows to restrict access to sections provided by handlers to authenticated users only. Independent from the kind of authentication used, the identified user can be read from the request in the following manner:

Client Caching (Policy)

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-client-caching Package on Maven Central

This concern allows to instruct clients to cache responses generated by the server for some duration by adding the Expires HTTP header. The following example will cause the static website to be cached for one week:

Client Caching (Validation)

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-client-caching Package on Maven Central

This concern adds an ETag header to every response generated by the server so that clients send a If-None-Match header to validate their cache. If the content did not change on the server, the handler will generate a 304 Not Modified response, causing the client to re-use the locally cached data. This way, clients revisiting your web application load faster and the load on your server is reduced.

Compression

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-compression Package on Maven Central

The compression concern compresses content sent to the clients, if applicable. By default, gzip, Brotli and Zstandard are supported.

Content

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-io Package on Maven Central

This handler provides the content of a resource such as a file or a text resource to a requesting client. In contrast to a download, the handler does not instruct the client to download and store the file but just serves it.

CORS

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-security Package on Maven Central

Cross-Origin Resource Sharing allows to control which resources browsers are allowed to access and how they are allowed to do so. For example, if you would like to access a webservice from a website hosted on another domain, the browser will send the Origin header along with requests to the webservice and analyze the response to determine, whether the server allows clients to access the resource from this origin.

Decompression

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-compression Package on Maven Central

This concern will analyze incoming requests for compressed content and will automatically decompress the body using a suitable decompression algorithm.

Defaults

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-practices Package on Maven Central

The defaults() function provided by the practices module adds some useful concerns to your web server to enable features such as compression or client side caching. This way, you will have a well configured server instance without the need of adding everything by yourself.

Directory Browsing

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-directory-browsing Package on Maven Central

The directory listing provider serves a simple web UI allowing users to browse directories and files read from a resource tree below the specified path.

Error Handling

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-error-handling Package on Maven Central

If an exception occurs while a request is handled, the server will render the exception into a structured response (JSON, XML, … depending on what the client accepts) via ErrorHandler.default(), which is an alias for ErrorHandler.structured(). To customize the serialization used, pass a SerializationBuilder to structured(...).

Features

Mon, 01 Jan 0001 00:00:00 +0000

Frameworks

genhttp-kt provides several frameworks to develop and host web services (service classes, controllers or functional handlers). Additionally, you can easily host static websites or a single page application. Besides this, the framework comes with a rich set of features:

Automatically generated Open API specifications, with Scalar, Redoc or Swagger UI to browse them
Various authentication methods (API keys, JWT, client certificates or basic authentication)
Support for Websockets and Server Sent Events (SSE)
Automatic response compression (Brotli, Zstandard, gzip) and request decompression
Client caching directives and automatic ETag handling
Range support to fetch byte ranges
Security relevant features, such as CORS policies and an automatic redirection to HTTPS
JSON, XML, YAML, form and Protobuf serialization, dependency injection with Koin

All of them are documented in the documentation.

Files

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-files Package on Maven Central

The Files module serves resources to clients, either one at a time with a fixed path or as a whole browsable directory tree. The content type of a file is automatically determined by its extension unless overridden.

Hardening

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-security Package on Maven Central

Besides CORS, the security module provides a few concerns that harden a web application against common transport-level issues. All three are added automatically by defaults() (with preventSniffing off), or can be added together via harden() (which also enables preventSniffing by default). They are extensions of the host in the package org.genhttp.modules.security.

Inspection

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-inspection Package on Maven Central

When developing client applications, you will sometimes have trouble to understand, why you are getting a specific response from a webserver. The inspection concern allows you to add the query param ?inspect to any request and will respond with a detailed summary of how the received request looked like and what response was generated by the server.

Layouting

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-layouting Package on Maven Central

Layouts are a basic mechanism that allows you to assemble your web application from different parts. They define which URLs are made available by the server and what the URL structure of your app will look like.

Legal

Mon, 01 Jan 0001 00:00:00 +0000

Imprint

Andreas Nägeli

Kientzheimer Str. 1, 79238 Ehrenkirchen, Germany

solutions@genhttp.org

If you would like to report a bug or ask a question, please visit our GitHub page.

Data Privacy

This website is intended to provide information about the genhttp-kt project. Personal data and cookies are not required for this, but your IP address is logged by the server for the purpose of technical operation with every request sent by your browser. This information will reside on the server until it is restarted. Besides this, no other personal data will be collected.

Load Balancer

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-load-balancing Package on Maven Central

Allows to distribute incoming requests to multiple nodes, either by using a reverse proxy or by redirecting the client.

Localization

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-i18n Package on Maven Central

The localization concern analyzes incoming requests for language preferences and allows the application logic to serve content based on those.

Open API

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-open-api Package on Maven Central

This concern dynamically generates and serves an Open API v3 specification using swagger-core for all detected API endpoints.

Pages

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-pages Package on Maven Central

The pages module allows the server to generate HTML pages (e.g. error messages or the directory listing) and can be used to render custom pages from a template, using Pebble as a rendering engine. Support for rendering websites in genhttp-kt is minimalistic, so you should not use this for a website project.

Range Support

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-io Package on Maven Central

Partial responses allow clients to fetch a specified portion of a requested resource which can be helpful for download managers to pause and resume downloads. As this functionality is not needed by every web application, range support is disabled by default.

Redirects

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-redirects Package on Maven Central

The redirect provider allows to inform the client that the location of the actual resource is different than the requested URI.

Reverse Proxies

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-reverse-proxy Package on Maven Central

The reverse proxy content provider allows to embed content from another web server into your application.

Server Sent Events (SSE)

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-server-sent-events Package on Maven Central

Server Sent Events (SSE) allow client applications such as browsers to subscribe to a stream of relevant events without the overhead added by the bi-directional connection of websockets. Therefore, they are useful whenever the server would like to notify the client about changes. This article describes how to host an event source in Kotlin using genhttp-kt.

Support

Mon, 01 Jan 0001 00:00:00 +0000

Getting Support

If you have questions or run into issues while building applications with genhttp-kt, the community is here to help. You can reach us through:

GitHub for issues specific to genhttp-kt
GitHub discussions and issue tracking for everything around the framework itself
The community Discord channel of GenHTTP

Both platforms are actively monitored and are great places to get guidance, report problems, or exchange ideas with other users. As genhttp-kt follows GenHTTP, a feature or a change of behavior is proposed for GenHTTP first and reaches genhttp-kt with the next sync.

Virtual Hosts

Mon, 01 Jan 0001 00:00:00 +0000

genhttp-modules-virtual-hosting Package on Maven Central

The virtual host handler can be used to deliver different content depending on the host requested by the client. Note, that the handler can be used anywhere in the handler chain, but usually it is most beneficial as the main handler.