Package io.ktor.server.plugins


Link copied to clipboard
class CallId

Retrieves and generates if necessary a call id. A call id (or correlation id) could be retrieved_ from a call via CallId.Configuration.retrieve function. Multiple retrieve functions could be configured that will be invoked one by one until one of them return non-null value. If no value has been provided by retrievers then a generator could be applied to generate a new call id. Generators could be provided via CallId.Configuration.generate function. Similar to retrieve, multiple generators could be configured so they will be invoked one by one. Usually call id is passed via io.ktor.http.HttpHeaders.XRequestId so one could use CallId.Configuration.retrieveFromHeader function to retrieve call id from a header.

Link copied to clipboard
typealias CallIdProvider = (call: ApplicationCall) -> String?

A function that retrieves or generates call id using provided call

Link copied to clipboard
typealias CallIdVerifier = (String) -> Boolean

A function that verifies retrieved or generated call id. Should return true for a valid call id. Also it could throw a RejectedCallIdException to reject an ApplicationCall otherwise an illegal call id will be ignored or replaced with generated one.

Link copied to clipboard
class RejectedCallIdException(illegalCallId: String) : IllegalArgumentException, CopyableThrowable<RejectedCallIdException>

An exception that could be thrown to reject a call due to illegal call id


Link copied to clipboard
fun CallLogging.Configuration.callIdMdc(name: String = "CallId")

Put call id into MDC (diagnostic context value) with name

Link copied to clipboard
fun CallId.Configuration.generate(length: Int = 64, dictionary: String = CALL_ID_DEFAULT_DICTIONARY)

Generates fixed length call ids using the specified dictionary. Please note that this function generates pseudo-random identifiers via regular java.util.Random and should not be considered as cryptographically secure. Also note that you should use the same dictionary for CallIdVerifier otherwise a generated call id could be discarded or may lead to complete call rejection.


Link copied to clipboard

The default call id's generator dictionary

Link copied to clipboard
val ApplicationCall.callId: String?

A call id that is retrieved or generated by CallId plugin or null (this is possible if there is no call id provided and no generators configured or CallId plugin is not installed)