From d59d86afb0fede73c480de0dfce3d5bb707718f2 Mon Sep 17 00:00:00 2001 From: Lukas Forst Date: Tue, 9 Aug 2022 15:55:42 +0200 Subject: [PATCH] add more examples to the readmes --- README.md | 113 ++++++++++++++++++++++++- ktor-api-key/README.md | 7 +- ktor-content-security-policy/README.md | 4 +- ktor-openapi-generator/README.md | 3 + ktor-rate-limiting/README.md | 4 +- 5 files changed, 122 insertions(+), 9 deletions(-) create mode 100644 ktor-openapi-generator/README.md diff --git a/README.md b/README.md index 87dccd2..047cbce 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,117 @@ # Ktor Plugins -Collection of Ktor plugins, all plugins have the same version that should correspond with the version of Ktor they're -using. +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/LukasForst/ktor-plugins?style=flat-square) + +Collection of useful Ktor plugins. All plugins are hosted on Maven central and can be added to your project as easy as: + +```kotlin +implementation("dev.forst", "ktor-", "") +``` * [ktor-api-key](ktor-api-key) - * Simple authentication provider for Ktor that verifies presence of the API key in the header. + * simple authentication provider for Ktor that verifies presence of the API key in the header * [ktor-content-security-policy](ktor-content-security-policy) * plugin that allows setting [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers +* [ktor-openapi-generator](https://github.com/LukasForst/ktor-openapi-generator/) + * generates OpenAPI definitions from your server with support for Ktor `>= 2.0.0` + * developed in [separate repository](https://github.com/LukasForst/ktor-openapi-generator/) because it is a fork of + existing project * [ktor-rate-limiting](ktor-rate-limiting) - * plugin that enables rate limiting in Ktor \ No newline at end of file + * plugin that enables rate limiting in Ktor + +## Ktor API Key Authentication Provider + +Simple authentication provider for Ktor that verifies presence of the API key in the header. Useful if you want to +use `X-Api-Key` or similar approaches for request authentication. + +```kotlin +/** + * Minimal Ktor application with API Key authentication. + */ +fun Application.minimalExample() { + // key that will be used to authenticate requests + val expectedApiKey = "this-is-expected-key" + + // principal for the app + data class AppPrincipal(val key: String) : Principal + // now we install authentication feature + install(Authentication) { + // and then api key provider + apiKey { + // set function that is used to verify request + validate { keyFromHeader -> + keyFromHeader + .takeIf { it == expectedApiKey } + ?.let { AppPrincipal(it) } + } + } + } + + routing { + authenticate { + get { + val p = call.principal()!! + call.respondText("Key: ${p.key}") + } + } + } +} +``` + +## Ktor Content Security Policy + +Plugin that allows setting [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers. + +```kotlin +/** + * Minimal Ktor application using Content Security Policy. + */ +fun Application.minimalExample() { + install(ContentSecurityPolicy) { + skipWhen { call -> + call.request.path().startsWith("/some-ignored-route") + } + policy( + "default-src" to "'none'" + ) + } +} +``` + +## Ktor Rate Limiting + +A simple library that enables Rate Limiting in Ktor. + +```kotlin +/** + * Minimal Ktor application with Rate Limiting enabled. + */ +fun Application.minimalExample() { + // install feature + install(RateLimiting) { + registerLimit( + // allow 10 requests + limit = 10, + // each 1 minute + window = Duration.ofMinutes(1) + ) { + // use host as a key to determine who is who + call.request.origin.host + } + // and exclude path which ends with "excluded" + excludeRequestWhen { + call.request.path().endsWith("excluded") + } + } + // now add some routes + routing { + get { + call.respondText("Hello ${call.request.origin.host}") + } + get("excluded") { + call.respondText("Hello ${call.request.origin.host}") + } + } +} +``` \ No newline at end of file diff --git a/ktor-api-key/README.md b/ktor-api-key/README.md index f55f667..f978758 100644 --- a/ktor-api-key/README.md +++ b/ktor-api-key/README.md @@ -1,15 +1,16 @@ # Ktor API Key Authentication Provider +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/LukasForst/ktor-plugins?style=flat-square) + Simple authentication provider for Ktor that verifies presence of the API key in the header. Useful if you want to -use `X-Api-Key` or -similar approaches for request authentication. +use `X-Api-Key` or similar approaches for request authentication. ## Installation Include following in your `build.gradle.kts`: ```kotlin -implementation("dev.forst", "ktor-api-key", "1.1.0") +implementation("dev.forst", "ktor-api-key", "") ``` Versions >= `1.1.0` have implementation for Ktor >= `2.0.0`, use `1.0.0` if you need support for older versions of Ktor. diff --git a/ktor-content-security-policy/README.md b/ktor-content-security-policy/README.md index 7cf8fc3..a941f68 100644 --- a/ktor-content-security-policy/README.md +++ b/ktor-content-security-policy/README.md @@ -1,5 +1,7 @@ # Ktor Content Security Policy Plugin +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/LukasForst/ktor-plugins?style=flat-square) + Plugin that allows setting [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers. ## Installation @@ -7,7 +9,7 @@ Plugin that allows setting [Content-Security-Policy](https://developer.mozilla.o Include following in your `build.gradle.kts`: ```kotlin -implementation("dev.forst", "ktor-content-security-policy", "1.0.0") +implementation("dev.forst", "ktor-content-security-policy", "") ``` ## Usage diff --git a/ktor-openapi-generator/README.md b/ktor-openapi-generator/README.md new file mode 100644 index 0000000..920fd95 --- /dev/null +++ b/ktor-openapi-generator/README.md @@ -0,0 +1,3 @@ +# Ktor OpenAPI Generator + +Hosted on different repository: https://github.com/LukasForst/ktor-openapi-generator/ \ No newline at end of file diff --git a/ktor-rate-limiting/README.md b/ktor-rate-limiting/README.md index 0e0426d..c105d65 100644 --- a/ktor-rate-limiting/README.md +++ b/ktor-rate-limiting/README.md @@ -1,5 +1,7 @@ # Ktor Rate Limiting +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/LukasForst/ktor-plugins?style=flat-square) + A simple library that enables Rate Limiting in Ktor. ## Installation @@ -7,7 +9,7 @@ A simple library that enables Rate Limiting in Ktor. Include following in your `build.gradle.kts`: ```kotlin -implementation("dev.forst", "ktor-rate-limiting", "1.3.3") +implementation("dev.forst", "ktor-rate-limiting", "") ``` Versions >= `1.2.0` have implementation for Ktor >= `2.0.0`, use `1.1.0` if you need support for older versions of Ktor.