fun main(args: Array) {
Server(handler).listen(3000)
}
```

### Router mounting

`Router#mount(subrouter)` will merge a child router into the current router.

Useful for breaking your application into individual routers that you then mount into a top-level router.

```kotlin
val subrouter = Router {
get("/foo", fun(): Handler = { Response() })
}

val router = Router {
mount(subrouter)
}
```

```text
curl http://localhost:3000/foo # 200 Ok
```

Or mount routers at a prefix:

```kotlin
val subrouter = Router {
get("/foo", fun(): Handler = { Response() })
}

val router = Router {
mount("/subrouter", subrouter)
}
```

```text
curl http://localhost:3000/foo # 404 Not Found
curl http://localhost:3000/subrouter/foo # 200 Ok
```

Or mount routers in a group:

```kotlin
val subrouter = Router {
get("/foo", fun(): Handler = { Response() })
}

val router = Router {
group("/group") {
mount("/subrouter", subrouter)
}
}
```

**Note:** The mount prefix must be static. It does not support dynamic patterns like "/users/".

## Cookies

### Request Cookies

`Request#cookies` is a `MutableMap` which maps cookie names
to cookie values received in the request.

### Response Cookies

`Response#cookies` is a `MutableMap` which maps cookie names
to cookie objects that will get sent to the client.

Here's a handler that increments a counter cookie on every request that
will expire in three days:

``` kotlin
import com.danneu.kog.Response
import com.danneu.kog.Handler
import com.danneu.kog.Server
import com.danneu.kog.cookies.Cookie
import java.time.OffsetDateTime

fun Request.parseCounter(): Int = try {
cookies.getOrDefault("counter", "0").toInt()
} catch(e: NumberFormatException) {
0
}

fun Response.setCounter(count: Int): Response = apply {
cookies["counter"] = Cookie(count.toString(), duration = Cookie.Ttl.Expires(OffsetDateTime.now().plusDays(3)))
}

val handler: Handler = { request ->
val count = request.parseCounter() + 1
Response().text("count: $count").setCounter(count)
}

fun main(args: Array) {
Server(handler).listen(9000)
}
```

Demo:

```
$ http --session=kog-example --body localhost:9000
count: 1
$ http --session=kog-example --body localhost:9000
count: 2
$ http --session=kog-example --body localhost:9000
count: 3
```

## Included Middleware

The `com.danneu.kog.batteries` package includes some useful middleware.

### Development Logger

The logger middleware prints basic info about the request and response
to stdout.

``` kotlin
import com.danneu.kog.batteries.logger

Server(logger(handler)).listen()
```


### Static File Serving

The serveStatic middleware checks the `request.path` against a directory
that you want to serve static files from.

``` kotlin
import com.danneu.kog.batteries.serveStatic

val middleware = serveStatic("public", maxAge = Duration.ofDays(365))
val handler = { Response().text(":)") }

Server(middleware(handler)).listen()
```

If we have a `public` folder in our project root with a file
`message.txt`, then the responses will look like this:

$ http localhost:3000/foo
HTTP/1.1 404 Not Found

$ http localhost:3000/message.txt
HTTP/1.1 200 OK
Content-Length: 38
Content-Type: text/plain

This is a message from the file system

$ http localhost:3000/../passwords.txt
HTTP/1.1 400 Bad Request

### Conditional-Get Caching

This middleware adds `Last-Modified` or `ETag` headers to each downstream
response which the browser will echo back on subsequent requests.

If the response's `Last-Modified`/`ETag` matches the request,
then this middleware instead responds with `304 Not Modified` which tells the
browser to use its cache.

#### ETag

`notModified(etag = true)` will generate an ETag header for each
downstream response.

``` kotlin
val router = Router(notModified(etag = true)) {
get("/", fun(): Handler = {
Response().text("Hello, world!)
})
}
```

First request gives us an ETag.

``` bash
$ http localhost:9000
HTTP/1.1 200 OK
Content-Length: 13
Content-Type: text/plain
ETag: "d-bNNVbesNpUvKBgtMOUeYOQ"

Hello, world!
```

When we echo back the ETag, the server lets us know that
the response hasn't changed:

``` bash
$ http localhost:9000 If-None-Match:'"d-bNNVbesNpUvKBgtMOUeYOQ"'
HTTP/1.1 304 Not Modified
```

#### Last-Modified

`notModified(etag = false)` will only add a `Last-Modified` header
to downstream responses if `response.body is ResponseBody.File` since
kog can read the mtime from the File's metadata.

If the response body is not a `ResponseBody.File` type, then no header
will be added.

This is only useful for serving static assets from the filesystem since
ETags are unnecessary to generate when you have a file's modification time.

``` kotlin
val router = Router {
// TODO: kog doesn't yet support mounting middleware on a prefix
use("/assets", notModified(etag = false), serveStatic("public", maxAge = Duration.ofHours(4)))
get("/") { Response().text("homepage")
}
```

### Multipart File Uploads

To handle file uploads, use the `com.danneu.kog.batteries.multipart` middleware.

This middleware parses file uploads out of `"multipart/form-data"` requests
and populates `request.uploads : MutableMap` for your
handler to access which is a mapping of field names to `File` representations.

``` kotlin
package com.danneu.kog.batteries.multipart

class SavedUpload(val file: java.io.File, val filename: String, val contentType: String, val length: Long)
```

In this early implementation, by the time your handler is executed, the
file uploads have already been piped into temporary files in the file-system
which will get automatically deleted.

``` kotlin
import com.danneu.kog.Router
import com.danneu.kog.batteries.multipart
import com.danneu.kog.batteries.multipart.Whitelist

val router = Router {
get("/", fun(): Handler = {
Response().html("""


File1:
File2 (Ignored):
Upload

""")
})
post("/upload", multipart(Whitelist.only(setOf("file1"))), fun(): Handler = { req ->
val upload = req.uploads["file1"]
Response().text("You uploaded ${upload?.length ?: "--"} bytes")
})
}

fun main(args: Array) {
Server(router.handler()).listen(3000)
}
```

Pass a whitelist into `multipart()` to only process field names that
you expect.

``` kotlin
import com.danneu.kog.batteries.multipart
import com.danneu.kog.batteries.multipart.Whitelist

multipart(whitelist = Whitelist.all)
multipart(whitelist = Whitelist.only(setOf("field1", "field2")))
```

### Basic Auth

Just pass a `(name, password) -> Boolean` predicate to the
`basicAuth()` middleware.

Your handler won't get called unless the user satisfies it.

``` kotlin
import com.danneu.kog.batteries.basicAuth

fun String.sha256(): ByteArray {
return java.security.MessageDigest.getInstance("SHA-256").digest(this.toByteArray())
}

val secretHash = "a man a plan a canal panama".sha256()

fun isAuthenticated(name: String, pass: String): Boolean {
return java.util.Arrays.equals(pass.sha256(), secretHash)
}

val router = Router {
get("/", basicAuth(::isAuthenticated)) {
Response().text("You are authenticated!")
}
}
```

### Compression / Gzip

The `compress` middleware reads and manages the appropriate headers to determine if it should
send a gzip-encoded response to the client.

Options:

- `compress(threshold: ByteLength)`
(Default = 1024 bytes)
Only compress the response if it is at least this large.
- `compress(predicate = (String?) -> Boolean)`
(Default = Looks up mime in file)
Only compress the response if its Content-Type header passes `predicate(type)`.

Some examples:

``` kotlin
import com.danneu.kog.batteries.compress
import com.danneu.kog.ByteLength

val router = Router() {
// These responses will be compressed if they are JSON of any size
group(compress(threshold = ByteLength.zero, predicate = { it == "application/json" })) {
get("/a", fun(): Handler = { Response().text("foo") }) // <-- Not compressed (not json)
get("/b", fun(): Handler = { Response().html("

bar

## HTML Templating

Templating libraries generally generate an HTML string. Just pass it to `Response().html(html)`.

For example, [tipsy/j2html](https://github.com/tipsy/j2html) is a simple templating library
for generating HTML from your handlers.

compile "com.j2html:j2html:1.0.0"

Here's an example server with a "/" route that renders a file-upload form that posts to a "/upload" route.

``` kotlin
import j2html.TagCreator.*
import j2html.tags.ContainerTag
import com.danneu.kog.Router
import com.danneu.kog.Response
import com.danneu.kog.Server
import com.danneu.kog.batteries.multipart
import com.danneu.kog.batteries.multipart.Whitelist

fun layout(vararg tags: ContainerTag): String = document().render() + html().with(
body().with(*tags)
).render()

val router: Router = Router {
get("/", fun(): Handler = {
Response().html(layout(
form().attr("enctype", "multipart/form-data").withMethod("POST").withAction("/upload").with(
input().withType("file").withName("myFile"),
button().withType("submit").withText("Upload File")
)
))
})
post("/upload", multipart(Whitelist.only(setOf("myFile"))), fun(): Handler = {
Response().text("Uploaded ${req.uploads["myFile"]?.length ?: "--"} bytes")
})
}

fun main(args: Array) {
Server(router.handler()).listen(9000)
}
```

## WebSockets

Check out [examples/websockets.kt][examples-websockets] for a websocket example that demonstrates
a websocket handler that echos back every message, and a websocket handler bound to a dynamic `/ws/` route.

Take note of a few limitations explained in the comments that I'm working on fixing.

### Idle Timeout

By default, Jetty (and thus kog) timeout connections that have idled for 30 seconds.

You can change this when initializing a kog `Server`:

```kotlin
import com.danneu.kog.Server
import java.time.Duration

fun main(args: Array) {
Server(handler, idleTimeout = Duration.ofMinutes(5)).listen(3000)
}
```

However, instead of changing kog's `idleTimeout`, you probably want to have your websocket clients ping the server
to keep the connections alive.

Often reverse proxies like nginx, Heroku's routing layer, and Cloudflare have their own idle timeout.

For example, here are Heroku's docs on the matter:

I believe this is also why websocket libraries like implement their own ping/pong.

Finally, it seems that Jetty's maximum idle timeout is 5 minutes, so passing in durations longer than 5 minutes
seems to just max out at 5 minutes. If someone can correct me here, feel free to create an issue.

[examples-websockets]: https://github.com/danneu/kog/blob/master/src/main/kotlin/com/danneu/kog/examples/websockets.kt

## Caching

### In-Memory Cache

I've been impressed with Ben Manes' [ben-manes/caffeine][caffeine] library.

Easy to pick up and use in any project.

There's also Guava's [Cache](https://github.com/google/guava/wiki/CachesExplained).

[caffeine]: https://github.com/ben-manes/caffeine

## Environment Variables

Kog's `Env` object provides a central way to access any customizations passed into an application.

First it reads from an optional `.env` file, then it reads from system properties, and finally it reads
from system environment variables (highest precedence). Any conflicts will be overwritten in that order.

For instance, if we had `PORT=3000` in an `.env` file and then launched our application with:

PORT=9999 java -jar app.java

Then this is what we'd see in our code:

``` kotlin
import com.danneu.kog.Env

Env.int("PORT") == 9999
```

For example, when deploying an application to Heroku, you want to bind to the port that Heroku gives you
via the `"PORT"` env variable. But you may want to default to port 3000 in development when there is no port
configured:

``` kotlin
import com.danneu.kog.Server
import com.danneu.kog.Env

fun main(args: Array) {
Server(router.handler()).listen(Env.int("PORT") ?: 3000)
}
```

`Env` provides some conveniences:

- `Env.string(key)`
- `Env.int(key)`
- `Env.float(key)`
- `Env.bool(key)`: True if the value is `"true"` or `"1"`, e.g. `VALUE=true java -jar app.java`

If the parse fails, `null` is returned.

You can get a new, overridden env container with `.fork()`:

```kotlin
Env.int("PORT") //=> 3000
Env.fork(mapOf("PORT" to "8888")).int("PORT") //=> 8888
Env.int("PORT") //=> 3000
```

## Heroku Deploy

This example application will be called "com.danneu.kogtest".

I'm not sure what the minimal boilerplate is, but the following is what worked for me.

In `./build.gradle`:

``` groovy
buildscript {
ext.kotlin_version = "1.1-M03"
ext.shadow_version = "1.2.3"

repositories {
jcenter()
maven { url "http://dl.bintray.com/kotlin/kotlin-eap-1.1" }
}

dependencies {
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
classpath "com.github.jengelman.gradle.plugins:shadow:$shadow_version"
}
}

apply plugin: 'kotlin'
apply plugin: 'com.github.johnrengelman.shadow'
apply plugin: 'application'

mainClassName = 'com.danneu.kogtest.MainKt' // <--------------- CHANGE ME

repositories {
jcenter()
maven { url "http://dl.bintray.com/kotlin/kotlin-eap-1.1" }
maven { url 'https://jitpack.io' }
}

dependencies {
compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
compile 'com.danneu:kog:master-SNAPSHOT'
}

task stage(dependsOn: ['shadowJar', 'clean'])
```

In `./src/main/kotlin/com/danneu/kogtest/main.kt`:

``` kotlin
package com.danneu.kogtest

import com.danneu.kog.Env
import com.danneu.kog.Handler
import com.danneu.kog.Response
import com.danneu.kog.Server

fun main(args: Array) {
val handler: Handler = { Response().text("Hello, world!") }
Server(handler).listen(ENV.int("PORT") ?: 3000)
}
```

**Reminder:** Bind to the PORT env variable that Heroku will set.

In `./Procfile`:

```
web: java -jar build/libs/kogtest-all.jar
```

Create and push to Heroku app:

```
heroku apps:create my-app
commit -am 'Initial commit'
git push heroku master
```

## Example: Tiny Pastebin Server

I got this idea from: .

This simple server will have two endpoints:

- **Upload file**: `curl --data-binary @example.txt http://localhost:3000`.
- Uploads binary stream to a "pastes" directory on the server.
- Server responds with JSON `{ "url": "http://localhost:3000/" }`.
- **Fetch file**: `curl http://localhost:3000/`.
- Server responds with file or 404.

``` kotlin
import com.danneu.kog.Router
import com.danneu.kog.Response
import com.danneu.kog.Handler
import com.danneu.kog.util.CopyLimitExceeded
import com.danneu.kog.util.limitedCopyTo
import java.io.File
import java.util.UUID

val uploadLimit = ByteLength.ofMegabytes(10)

val router = Router {
// Upload file
post("/", fun(): Handler = handler@ { req ->
// Generate random ID for user's upload
val id = UUID.randomUUID()

// Ensure "pastes" directory is created
val destFile = File(File("pastes").apply { mkdir() }, id.toString())

// Move user's upload into "pastes", bailing if their upload size is too large.
try {
req.body.limitedCopyTo(uploadLimit, destFile.outputStream())
} catch(e: CopyLimitExceeded) {
destFile.delete()
return@handler Response.badRequest().text("Cannot upload more than ${uploadLimit.byteLength} bytes")
}

// If stream was empty, delete the file and scold user
if (destFile.length() == 0L) {
destFile.delete()
return@handler Response.badRequest().text("Paste file required")
}

println("A client uploaded ${destFile.length()} bytes to ${destFile.absolutePath}")

// Tell user where they can find their uploaded file
Response().json(JE.obj("url" to JE.str("http://localhost:${req.serverPort}/$id")))
})

// Fetch file
get("/", fun(id: UUID): Handler = handler@ { req ->
val file = File("pastes/$id")
if (!file.exists()) return@handler Response.notFound()
Response().file(file)
})
}

fun main(args: Array) {
Server(router.handler()).listen(3000)
}
```

## Content Negotiation

**TODO:** Improve negotiation docs

Each request has a negotiator that parses the `accept-*` headers, returning a list of
values in order of client preference.

- `request.negotiate.mediaTypes` parses the `accept` header.
- `request.negotiate.languages` parses the `accept-language` header.
- `request.negotiate.encodings` parses the `accept-encoding` header.

Until the docs are fleshed out, here's a demo server that will illuminate this:

```kotlin
fun main(args: Array) {
val handler: Handler = { request ->
println(request.headers.toString())
Response().text("""
languages: ${request.negotiate.languages()}
encodings: ${request.negotiate.encodings()}
mediaTypes: ${request.negotiate.mediaTypes()}
""".trimIndent())
}

Server(handler).listen(3000)
}
```

An example curl request:

```text
curl http://localhost:3000 \
--header 'Accept-Language:de;q=0.7, fr-CH, fr;q=0.9, en;q=0.8, *;q=0.5, de-CH;q=0.2' \
--header 'accept:application/json,TEXT/*' \
--header 'accept-encoding:gzip,DeFLaTE'
```

Corresponding response:

```text
languages: [French[CH], French[*], English[*], German[*], *[*], German[CH]]
encodings: [Encoding(name='gzip', q=1.0), Encoding(name='deflate', q=1.0)]
mediaTypes: [MediaType(type='application', subtype='json', q=1.0), MediaType(type='text', subtype='*', q=1.0)]
```

Notice that values ("TEXT/*", "DeFLaTE") are always downcased for easy comparison.

### Most acceptable language

Given a list of languages that you want to support, the negotiator can return a list that filters and sorts your
available languages down in order of client preference, the first one being the client's highest preference.

```kotlin
import com.danneu.kog.Lang
import com.danneu.kog.Locale

// Request Accept-Language: "en-US, es"
request.negotiate.acceptableLanguages(listOf(
Lang.Spanish(),
Lang.English(Locale.UnitedStates)
)) == listOf(
Lang.English(Locale.UnitedStates),
Lang.Spanish()
)
```

Also, note that we don't have to provide a locale. If the client asks for `en-US`, then of course
`Lang.English()` without a locale should be acceptable if we have no more specific match.

```kotlin
// Request Accept-Language: "en-US, es"
request.negotiate.acceptableLanguages(listOf(
Lang.Spanish(),
Lang.English()
)) == listOf(
Lang.English(),
Lang.Spanish()
)
```

The singular form, `.acceptableLanguage()`, is a helper that returns the first result (the most preferred language
in common with the client).

```kotlin
// Request Accept-Language: "en-US, es"
request.negotiate.acceptableLanguage(listOf(
Lang.Spanish(),
Lang.English()
)) == Lang.English()
```

Here we write an extension function `Request#lang()` that returns the optimal lang between
our available langs and the client's requested langs.

We define an internal `OurLangs` enum so that we can exhaust it with `when` expressions in our routes
or middleware.

```kotlin
enum class OurLangs {
Spanish,
English
}

fun Request.lang(): OurLangs {
val availableLangs = listOf(
Lang.Spanish(),
Lang.English()
)

return when (this.negotiate.acceptableLanguage(availableLangs)) {
Lang.English() -> OurLangs.English
// Default to Spanish
else -> OurLangs.Spanish
}
}

router.get("/", fun(): Handler = { request ->
return when (request.lang()) {
OurLangs.Spanish() ->
Response().text("Les servimos en español")
OurLangs.English() ->
Response().text("We're serving you English")
}
})
```

## License