Handling HTTP Requests

Also, the call itself has some useful convenience properties and methods that rely on the request.

Table of contents:

• Introduction
• • URL, method, scheme, protocol, host, path, httpVersion, remoteHost, clientIp
• GET / Query parameters
• • Raw payload
  • Receive Typed Objects, Content-Type and JSON
  • Custom receive transformers
• Headers

When using the feature, or when intercepting requests, you can accessthe call property inside handlers. That call includes a request property with relevant information about the request:

Request information

As part of the request, you can get access to its internal context:

val call: ApplicationCall = request.call
val pipeline: ApplicationReceivePipeline = request.pipeline

val version: String = request.httpVersion // "HTTP/1.1"
val uri: String = request.uri // Short cut for `origin.uri`
val scheme: String = request.origin.scheme // "http" or "https"
val host: String? = request.host() // The host part without the port 
val port: Int = request.port() // Port of request
val path: String = request.path() // The uri without the query string
val document: String = request.document() // The last component after '/' of the uri
val remoteHost: String = request.origin.remoteHost // The IP address of the client doing the request

Reverse proxy support: origin and local

When behind a reverse-proxy (for example an nginx or a load balancer), the received request is not performed by the end-user, but that reverse proxy.That means that the client IP address of the connection would be the one of the proxy instead of the client.Also the reverse proxy might be serving via HTTPS and requesting to your server via HTTP.Popular reverse proxies send X-Forwarded- headers to be able to access this information.

Note that for this to work when under a reverse-proxy you have to install the XForwardedHeaderSupport feature.

As part of the request object, there are two properties local and origin that allows to get information of the original requestor the local/proxied one.

val local : RequestConnectionPoint = request.local // Local information 
val origin: RequestConnectionPoint = request.origin // Local / Origin if XForwardedHeaderSupport feature is installed.

The local/origin information you can get:

interface RequestConnectionPoint {
    val scheme: String // "http" or "https": The provided protocol (local) or `X-Forwarded-Proto`
    val version: String // "HTTP/1.1"
    val port: Int
    val host: String // The provided host (local) or `X-Forwarded-Host`
    val uri: String
    val method: HttpMethod
    val remoteHost: String // The client IP (the direct ip for `local`, or the redirected one `X-Forwarded-For`)
}

You can also access the raw queryString (param1=value&param2=value):

val queryString: String = request.queryString()

POST, PUT and PATCH

POST, PUT and PATCH requests has an associated request body (the payload).That payload is usually encoded.

All the receive methods consume the whole payload sent by the client so an attempt to receive a request body twicewill lead to RequestAlreadyConsumedException error unless you have DoubleReceive feature installed.

To access the raw bits of the payload, you can use receiveChannel, but it isdirectly part of the call instead of call.request:

val channel: ByteReadChannel = call.receiveChannel()

And it provide some convenience methods for common types:

val channel: ByteReadChannel = call.receiveChannel()
val text: String = call.receiveText()
val inputStream: InputStream = call.receiveStream() // NOTE: InputStream is synchronous and blocks the thread
val multipart: MultiPartData = call.receiveMultipart()

All those receive* methods are aliases of call.receive<T> with the specified type.The types ByteReadChannel, ByteArray, InputStream, MultiPartData, String and Parameters are handled byApplicationReceivePipeline.installDefaultTransformations that is installed by default.

Form Parameters (urlencoded or multipart)

To parse a form urlencoded or with multipart, you can use receiveParameters or receive<Parameters>:

val postParameters: Parameters = call.receiveParameters()

The call also supports receiving generic objects:

install(ContentNegotiation) {
    gson {
        setDateFormat(DateFormat.LONG)
        setPrettyPrinting()

If you configure the ContentNegotiation to use gson,you will need to include the ktor-gson artifact:

compile("io.ktor:ktor-gson:$ktor_version")

Then you can, as an example, do:

data class HelloWorld(val hello: String)
routing {
    post("/route") {
        val helloWorld = call.receive<HelloWorld>()
    }
}

Remember that your classes must be defined top level (outside of any other class or function) to be recognized by Gson.

Multipart, Files and Uploads

Check the section.

You can create custom transformers by callingapplication.receivePipeline.intercept(ApplicationReceivePipeline.Transform) { query ->and then calling proceedWith(ApplicationReceiveRequest(query.type, transformed)) as does the ContentNegotiation feature.

There is a cookies property to access the Cookie headers sent by the client,just as if it was a collection:

val cookies: RequestCookies = request.cookies
val mycookie: String? = request.cookies["mycookie"]

To handle sessions using cookies, have a look to the feature.

Headers

To access the headers the request objects has a headers: Headers property.It implements the StringValues interface where each key can have a list of Strings associated with it.

val contentType: ContentType = request.contentType() // Parsed Content-Tpe 
val contentCharset: Charset? = request.contentCharset() // Content-Type JVM charset
val authorization: String? = request.authorization() // Authorization header
val location: String? = request.location() // Location header
val accept: String? = request.accept() // Accept header
val acceptItems: List<HeaderValue> = request.acceptItems() // Parsed items of Accept header
val acceptEncoding: String? = request.acceptEncoding() // Accept-Encoding header
val acceptEncodingItems: List<HeaderValue> = request.acceptEncodingItems() // Parsed Accept-Encoding items 
val acceptLanguage: String? = request.acceptLanguage() // Accept-Language header
val acceptLanguageItems: List<HeaderValue> = request.acceptLanguageItems() // Parsed Accept-Language items
val acceptCharset: String? = request.acceptCharset() // Accept-Charset header
val acceptCharsetItems: List<HeaderValue> = request.acceptCharsetItems() // Parsed Accept-Charset items
val userAgent: String? = request.userAgent() // User-Agent header
val cacheControl: String? = request.cacheControl() // Cache-Control header
val ranges: RangesSpecifier? = request.ranges() // Parsed Ranges header
val isMultipart: Boolean = request.isMultipart() // Content-Type matches Multipart