Concepts on genhttp-kt

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.

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.

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.

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.

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.

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.