Skip to content

Add nullability support for server parameter delegation #5486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bjhham merged 4 commits into from
May 12, 2026
+54 −25
Merged

Add nullability support for server parameter delegation #5486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bbd490b
Add nullability support for server parameter delegation
nomisRev Mar 20, 2026
ad1f23d
Cleanup `utils/Parameters.kt` by pushing the nullability support to `…
nomisRev Apr 1, 2026
2973653
Fix compilation error
bjhham May 12, 2026
65a6d88
Update ABI
bjhham May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions ktor-server/ktor-server-core/api/ktor-server-core.klib.api
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1890,12 +1890,12 @@ final fun <#A: io.ktor.util.pipeline/Pipeline<*, io.ktor.server.application/Pipe
final fun <#A: io.ktor.util.pipeline/Pipeline<*, io.ktor.server.application/PipelineCall>, #B: kotlin/Any> (#A).io.ktor.server.application/pluginOrNull(io.ktor.server.application/Plugin<*, *, #B>): #B? // io.ktor.server.application/pluginOrNull|pluginOrNull@0:0(io.ktor.server.application.Plugin<*,*,0:1>){0§<io.ktor.util.pipeline.Pipeline<*,io.ktor.server.application.PipelineCall>>;1§<kotlin.Any>}[0]
final fun <#A: io.ktor.util.pipeline/Pipeline<*, io.ktor.server.application/PipelineCall>, #B: kotlin/Any> (#A).io.ktor.server.application/uninstallPlugin(io.ktor.util/AttributeKey<#B>) // io.ktor.server.application/uninstallPlugin|uninstallPlugin@0:0(io.ktor.util.AttributeKey<0:1>){0§<io.ktor.util.pipeline.Pipeline<*,io.ktor.server.application.PipelineCall>>;1§<kotlin.Any>}[0]
final fun <#A: io.ktor.util.pipeline/Pipeline<*, io.ktor.server.application/PipelineCall>> (#A).io.ktor.server.application/uninstallAllPlugins() // io.ktor.server.application/uninstallAllPlugins|uninstallAllPlugins@0:0(){0§<io.ktor.util.pipeline.Pipeline<*,io.ktor.server.application.PipelineCall>>}[0]
final fun <#A: kotlin/Any> (io.ktor.http/Parameters).io.ktor.server.util/getOrFailImpl(kotlin/String, io.ktor.util.reflect/TypeInfo): #A // io.ktor.server.util/getOrFailImpl|getOrFailImpl@io.ktor.http.Parameters(kotlin.String;io.ktor.util.reflect.TypeInfo){0§<kotlin.Any>}[0]
final fun <#A: kotlin/Any> (io.ktor.server.routing/RoutingNode).io.ktor.server.application/findPluginInRoute(io.ktor.server.application/Plugin<*, *, #A>): #A? // io.ktor.server.application/findPluginInRoute|findPluginInRoute@io.ktor.server.routing.RoutingNode(io.ktor.server.application.Plugin<*,*,0:0>){0§<kotlin.Any>}[0]
final fun <#A: kotlin/Any> io.ktor.server.application/createApplicationPlugin(kotlin/String, kotlin/Function0<#A>, kotlin/Function1<io.ktor.server.application/PluginBuilder<#A>, kotlin/Unit>): io.ktor.server.application/ApplicationPlugin<#A> // io.ktor.server.application/createApplicationPlugin|createApplicationPlugin(kotlin.String;kotlin.Function0<0:0>;kotlin.Function1<io.ktor.server.application.PluginBuilder<0:0>,kotlin.Unit>){0§<kotlin.Any>}[0]
final fun <#A: kotlin/Any> io.ktor.server.application/createApplicationPlugin(kotlin/String, kotlin/String, kotlin/Function1<io.ktor.server.config/ApplicationConfig, #A>, kotlin/Function1<io.ktor.server.application/PluginBuilder<#A>, kotlin/Unit>): io.ktor.server.application/ApplicationPlugin<#A> // io.ktor.server.application/createApplicationPlugin|createApplicationPlugin(kotlin.String;kotlin.String;kotlin.Function1<io.ktor.server.config.ApplicationConfig,0:0>;kotlin.Function1<io.ktor.server.application.PluginBuilder<0:0>,kotlin.Unit>){0§<kotlin.Any>}[0]
final fun <#A: kotlin/Any> io.ktor.server.application/createRouteScopedPlugin(kotlin/String, kotlin/Function0<#A>, kotlin/Function1<io.ktor.server.application/RouteScopedPluginBuilder<#A>, kotlin/Unit>): io.ktor.server.application/RouteScopedPlugin<#A> // io.ktor.server.application/createRouteScopedPlugin|createRouteScopedPlugin(kotlin.String;kotlin.Function0<0:0>;kotlin.Function1<io.ktor.server.application.RouteScopedPluginBuilder<0:0>,kotlin.Unit>){0§<kotlin.Any>}[0]
final fun <#A: kotlin/Any> io.ktor.server.application/createRouteScopedPlugin(kotlin/String, kotlin/String, kotlin/Function1<io.ktor.server.config/ApplicationConfig, #A>, kotlin/Function1<io.ktor.server.application/RouteScopedPluginBuilder<#A>, kotlin/Unit>): io.ktor.server.application/RouteScopedPlugin<#A> // io.ktor.server.application/createRouteScopedPlugin|createRouteScopedPlugin(kotlin.String;kotlin.String;kotlin.Function1<io.ktor.server.config.ApplicationConfig,0:0>;kotlin.Function1<io.ktor.server.application.RouteScopedPluginBuilder<0:0>,kotlin.Unit>){0§<kotlin.Any>}[0]
final fun <#A: kotlin/Any?> (io.ktor.http/Parameters).io.ktor.server.util/getOrFailImpl(kotlin/String, io.ktor.util.reflect/TypeInfo): #A // io.ktor.server.util/getOrFailImpl|getOrFailImpl@io.ktor.http.Parameters(kotlin.String;io.ktor.util.reflect.TypeInfo){0§<kotlin.Any?>}[0]
final fun io.ktor.server.application/createApplicationPlugin(kotlin/String, kotlin/Function1<io.ktor.server.application/PluginBuilder<kotlin/Unit>, kotlin/Unit>): io.ktor.server.application/ApplicationPlugin<kotlin/Unit> // io.ktor.server.application/createApplicationPlugin|createApplicationPlugin(kotlin.String;kotlin.Function1<io.ktor.server.application.PluginBuilder<kotlin.Unit>,kotlin.Unit>){}[0]
final fun io.ktor.server.application/createRouteScopedPlugin(kotlin/String, kotlin/Function1<io.ktor.server.application/RouteScopedPluginBuilder<kotlin/Unit>, kotlin/Unit>): io.ktor.server.application/RouteScopedPlugin<kotlin/Unit> // io.ktor.server.application/createRouteScopedPlugin|createRouteScopedPlugin(kotlin.String;kotlin.Function1<io.ktor.server.application.RouteScopedPluginBuilder<kotlin.Unit>,kotlin.Unit>){}[0]
final fun io.ktor.server.application/serverConfig(io.ktor.server.application/ApplicationEnvironment = ..., kotlin/Function1<io.ktor.server.application/ServerConfigBuilder, kotlin/Unit> = ...): io.ktor.server.application/ServerConfig // io.ktor.server.application/serverConfig|serverConfig(io.ktor.server.application.ApplicationEnvironment;kotlin.Function1<io.ktor.server.application.ServerConfigBuilder,kotlin.Unit>){}[0]
Expand All @@ -1909,8 +1909,6 @@ final fun io.ktor.server.util/url(kotlin/Function1<io.ktor.http/URLBuilder, kotl
final inline fun (io.ktor.http/Parameters).io.ktor.server.util/getOrFail(kotlin/String): kotlin/String // io.ktor.server.util/getOrFail|getOrFail@io.ktor.http.Parameters(kotlin.String){}[0]
final inline fun (io.ktor.server.application/ApplicationCall).io.ktor.server.util/url(kotlin/Function1<io.ktor.http/URLBuilder, kotlin/Unit> = ...): kotlin/String // io.ktor.server.util/url|url@io.ktor.server.application.ApplicationCall(kotlin.Function1<io.ktor.http.URLBuilder,kotlin.Unit>){}[0]
final inline fun (io.ktor.server.engine/ApplicationEngine.Configuration).io.ktor.server.engine/connector(kotlin/Function1<io.ktor.server.engine/EngineConnectorBuilder, kotlin/Unit>) // io.ktor.server.engine/connector|connector@io.ktor.server.engine.ApplicationEngine.Configuration(kotlin.Function1<io.ktor.server.engine.EngineConnectorBuilder,kotlin.Unit>){}[0]
final inline fun <#A: reified kotlin/Any> (io.ktor.http/Parameters).io.ktor.server.util/getOrFail(kotlin/String): #A // io.ktor.server.util/getOrFail|getOrFail@io.ktor.http.Parameters(kotlin.String){0§<kotlin.Any>}[0]
final inline fun <#A: reified kotlin/Any> (io.ktor.http/Parameters).io.ktor.server.util/getValue(kotlin/Any?, kotlin.reflect/KProperty<*>): #A // io.ktor.server.util/getValue|getValue@io.ktor.http.Parameters(kotlin.Any?;kotlin.reflect.KProperty<*>){0§<kotlin.Any>}[0]
final inline fun <#A: reified kotlin/Any> (io.ktor.server.routing/Route).io.ktor.server.routing/patch(crossinline kotlin.coroutines/SuspendFunction2<io.ktor.server.routing/RoutingContext, #A, kotlin/Unit>): io.ktor.server.routing/Route // io.ktor.server.routing/patch|patch@io.ktor.server.routing.Route(kotlin.coroutines.SuspendFunction2<io.ktor.server.routing.RoutingContext,0:0,kotlin.Unit>){0§<kotlin.Any>}[0]
final inline fun <#A: reified kotlin/Any> (io.ktor.server.routing/Route).io.ktor.server.routing/patch(kotlin.text/Regex, crossinline kotlin.coroutines/SuspendFunction2<io.ktor.server.routing/RoutingContext, #A, kotlin/Unit>): io.ktor.server.routing/Route // io.ktor.server.routing/patch|patch@io.ktor.server.routing.Route(kotlin.text.Regex;kotlin.coroutines.SuspendFunction2<io.ktor.server.routing.RoutingContext,0:0,kotlin.Unit>){0§<kotlin.Any>}[0]
final inline fun <#A: reified kotlin/Any> (io.ktor.server.routing/Route).io.ktor.server.routing/patch(kotlin/String, crossinline kotlin.coroutines/SuspendFunction2<io.ktor.server.routing/RoutingContext, #A, kotlin/Unit>): io.ktor.server.routing/Route // io.ktor.server.routing/patch|patch@io.ktor.server.routing.Route(kotlin.String;kotlin.coroutines.SuspendFunction2<io.ktor.server.routing.RoutingContext,0:0,kotlin.Unit>){0§<kotlin.Any>}[0]
Expand All @@ -1923,6 +1921,8 @@ final inline fun <#A: reified kotlin/Any> (io.ktor.server.routing/Route).io.ktor
final inline fun <#A: reified kotlin/Any> (io.ktor.server.routing/Route).io.ktor.server.routing/query(crossinline kotlin.coroutines/SuspendFunction2<io.ktor.server.routing/RoutingContext, #A, kotlin/Unit>): io.ktor.server.routing/Route // io.ktor.server.routing/query|query@io.ktor.server.routing.Route(kotlin.coroutines.SuspendFunction2<io.ktor.server.routing.RoutingContext,0:0,kotlin.Unit>){0§<kotlin.Any>}[0]
final inline fun <#A: reified kotlin/Any> (io.ktor.server.routing/Route).io.ktor.server.routing/query(kotlin.text/Regex, crossinline kotlin.coroutines/SuspendFunction2<io.ktor.server.routing/RoutingContext, #A, kotlin/Unit>): io.ktor.server.routing/Route // io.ktor.server.routing/query|query@io.ktor.server.routing.Route(kotlin.text.Regex;kotlin.coroutines.SuspendFunction2<io.ktor.server.routing.RoutingContext,0:0,kotlin.Unit>){0§<kotlin.Any>}[0]
final inline fun <#A: reified kotlin/Any> (io.ktor.server.routing/Route).io.ktor.server.routing/query(kotlin/String, crossinline kotlin.coroutines/SuspendFunction2<io.ktor.server.routing/RoutingContext, #A, kotlin/Unit>): io.ktor.server.routing/Route // io.ktor.server.routing/query|query@io.ktor.server.routing.Route(kotlin.String;kotlin.coroutines.SuspendFunction2<io.ktor.server.routing.RoutingContext,0:0,kotlin.Unit>){0§<kotlin.Any>}[0]
final inline fun <#A: reified kotlin/Any?> (io.ktor.http/Parameters).io.ktor.server.util/getOrFail(kotlin/String): #A // io.ktor.server.util/getOrFail|getOrFail@io.ktor.http.Parameters(kotlin.String){0§<kotlin.Any?>}[0]
final inline fun <#A: reified kotlin/Any?> (io.ktor.http/Parameters).io.ktor.server.util/getValue(kotlin/Any?, kotlin.reflect/KProperty<*>): #A // io.ktor.server.util/getValue|getValue@io.ktor.http.Parameters(kotlin.Any?;kotlin.reflect.KProperty<*>){0§<kotlin.Any?>}[0]
final inline fun <#A: reified kotlin/Any?> (io.ktor.server.application/Application).io.ktor.server.config/property(kotlin/String): #A // io.ktor.server.config/property|property@io.ktor.server.application.Application(kotlin.String){0§<kotlin.Any?>}[0]
final inline fun <#A: reified kotlin/Any?> (io.ktor.server.application/Application).io.ktor.server.config/propertyOrNull(kotlin/String): #A? // io.ktor.server.config/propertyOrNull|propertyOrNull@io.ktor.server.application.Application(kotlin.String){0§<kotlin.Any?>}[0]
final inline fun <#A: reified kotlin/Any?> (io.ktor.server.config/ApplicationConfig).io.ktor.server.config/getAs(): #A // io.ktor.server.config/getAs|getAs@io.ktor.server.config.ApplicationConfig(){0§<kotlin.Any?>}[0]
Expand Down
45 changes: 23 additions & 22 deletions ktor-server/ktor-server-core/common/src/io/ktor/server/util/Parameters.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,26 +13,25 @@ import kotlin.reflect.*
/**
* Operator function that allows to delegate variables by call parameters.
* It does conversion to type [R] using [DefaultConversionService]
* If [R] is nullable and no values are associated with the delegated property name, returns `null`.
*
* Example
*
* ```
* get("/") {
* val page: Int by call.request.queryParameters
* val query: String by call.request.queryParameters
* get("/{path}") {
* val path: Int by call.pathParameters
* val query: String? by call.queryParameters
* // ...
* }
* ```
*
* @throws MissingRequestParameterException if no values associated with name and [R] is not nullable
* @throws ParameterConversionException when conversion from String to [R] fails
*
* [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.server.util.getValue)
*
* @throws MissingRequestParameterException if no values associated with name
* @throws ParameterConversionException when conversion from String to [R] fails
*/
public inline operator fun <reified R : Any> Parameters.getValue(thisRef: Any?, property: KProperty<*>): R {
return getOrFail<R>(property.name)
}
public inline operator fun <reified R> Parameters.getValue(thisRef: Any?, property: KProperty<*>): R =
getOrFail<R>(property.name)

/**
* Get parameters value associated with this [name] or fail with [MissingRequestParameterException]
Expand All @@ -42,9 +41,8 @@ public inline operator fun <reified R : Any> Parameters.getValue(thisRef: Any?,
* @throws MissingRequestParameterException if no values associated with this [name]
*/
@Suppress("NOTHING_TO_INLINE")
public inline fun Parameters.getOrFail(name: String): String {
return get(name) ?: throw MissingRequestParameterException(name)
}
public inline fun Parameters.getOrFail(name: String): String =
get(name) ?: throw MissingRequestParameterException(name)

/**
* Get parameter value associated with this [name] converting to type [R] using [DefaultConversionService]
Expand All @@ -55,17 +53,20 @@ public inline fun Parameters.getOrFail(name: String): String {
* @throws MissingRequestParameterException if no values associated with this [name]
* @throws ParameterConversionException when conversion from String to [R] fails
Comment on lines 53 to 54
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Update generic getOrFail KDoc to include nullable-missing behavior.

getOrFail<R> now returns null for missing values when R is nullable, but this KDoc still says missing always throws. Please align docs with the new contract.

As per coding guidelines: "Keep KDoc documentation correct when behavior/signatures change".

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ktor-server/ktor-server-core/common/src/io/ktor/server/util/Parameters.kt`
around lines 53 - 54, Update the KDoc for getOrFail<R> to reflect its new
nullable-missing behavior: state that when R is non-nullable a missing parameter
throws MissingRequestParameterException, but when R is a nullable type the
function returns null for missing values; also keep the existing note that
ParameterConversionException is thrown when conversion from String to R fails.
Modify the documentation on the getOrFail<R> declaration to mention the
conditional behavior based on R's nullability and include both exception and
null-return cases for clarity.

*/
public inline fun <reified R : Any> Parameters.getOrFail(name: String): R {
return getOrFailImpl(name, typeInfo<R>())
}
public inline fun <reified R> Parameters.getOrFail(name: String): R =
getOrFailImpl(name, typeInfo<R>())

@PublishedApi
internal fun <R : Any> Parameters.getOrFailImpl(name: String, typeInfo: TypeInfo): R {
val values = getAll(name) ?: throw MissingRequestParameterException(name)
return try {
@Suppress("UNCHECKED_CAST")
DefaultConversionService.fromValues(values, typeInfo) as R
} catch (cause: Exception) {
throw ParameterConversionException(name, typeInfo.type.simpleName ?: typeInfo.type.toString(), cause)
internal fun <R> Parameters.getOrFailImpl(name: String, typeInfo: TypeInfo): R {
return if (typeInfo.kotlinType?.isMarkedNullable == true && get(name) == null) {
null as R
} else {
val values = getAll(name) ?: throw MissingRequestParameterException(name)
try {
@Suppress("UNCHECKED_CAST")
DefaultConversionService.fromValues(values, typeInfo) as R
} catch (cause: Exception) {
throw ParameterConversionException(name, typeInfo.type.simpleName ?: typeInfo.type.toString(), cause)
}
}
}
28 changes: 28 additions & 0 deletions ktor-server/ktor-server-core/common/test/io/ktor/server/http/ParametersTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
package io.ktor.server.http

import io.ktor.http.*
import io.ktor.server.plugins.*
import io.ktor.server.util.*
import kotlin.test.*

Expand Down Expand Up @@ -51,6 +52,33 @@ class ParametersTest {
assertEquals(listOf(3L, 4L), multiple)
}

@Test
fun testNullableValues() {
val another: Int? by parameters
val missing: String? by parameters

assertEquals(2, another)
assertEquals(null, missing)
}

@Test
fun testNullableValueConversionFailure() {
val parameters = parametersOf("value" to listOf("a"))

assertFailsWith<ParameterConversionException> {
val value: Int? by parameters
value
}
}

@Test
fun testMissingNonNullValue() {
assertFailsWith<MissingRequestParameterException> {
val missing: String by parameters
missing
}
}

@Test
fun parametersBuilderTest() {
val params = parameters {
Expand Down
Loading