Thrown when a session is asked too early before the Sessions plugin had chance to configure it. For example, in a phase before ApplicationCallPipeline.Plugins or in a plugin installed before Sessions into the same phase.

SessionProvider

class SessionProvider<S : Any>(val name: String, val type: KClass<S>, val transport: SessionTransport, val tracker: SessionTracker<S>)

Specifies a provider for a session with the specific name and type.

SessionsConfig

class SessionsConfig

A configuration for the Sessions plugin.

SessionSerializer

interface SessionSerializer<T>

Serializes a session data from and to String.

SessionStorage

interface SessionStorage

A storage that provides the ability to write, read, and invalidate session data.

SessionStorageMemory

class SessionStorageMemory : SessionStorage

A storage that keeps session data in memory.

SessionTracker

interface SessionTracker<S : Any>

SessionTracker provides the ability to track and extract session from the call context.

SessionTrackerById

class SessionTrackerById<S : Any>(val type: KClass<S>, val serializer: SessionSerializer<S>, val storage: SessionStorage, val sessionIdProvider: () -> String) : SessionTracker<S>

SessionTracker that transfers a Session ID generated by a sessionIdProvider in HTTP Headers/Cookies. It uses a storage and a serializer to store/load serialized/deserialized session content of a specific type.

SessionTrackerByValue

class SessionTrackerByValue<S : Any>(val type: KClass<S>, val serializer: SessionSerializer<S>) : SessionTracker<S>

SessionTracker that stores the contents of the session as part of HTTP Cookies/Headers. It uses a specific serializer to serialize and deserialize objects of type type.

SessionTransport

interface SessionTransport

A session transport used to receive, send, or clear a session from/to an ApplicationCall.

SessionTransportCookie

class SessionTransportCookie(val name: String, val configuration: CookieConfiguration, val transformers: List<SessionTransportTransformer>) : SessionTransport

A session transport that adds the Set-Cookie header and reads the Cookie header for the specified cookie name, and a specific cookie configuration after applying/un-applying the specified transforms defined by transformers.

SessionTransportHeader

class SessionTransportHeader(val name: String, val transformers: List<SessionTransportTransformer>) : SessionTransport

A session transport that sets or gets the specific header name, applying/un-applying the specified transforms defined by transformers.

SessionTransportTransformer

interface SessionTransportTransformer

A transformer used to sign and encrypt session data.

SessionTransportTransformerEncrypt

class SessionTransportTransformerEncrypt(val encryptionKeySpec: SecretKeySpec, val signKeySpec: SecretKeySpec, val ivGenerator: (size: Int) -> ByteArray = { size -> ByteArray(size).apply { SecureRandom().nextBytes(this) } }, val encryptAlgorithm: String = encryptionKeySpec.algorithm, val signAlgorithm: String = signKeySpec.algorithm, backwardCompatibleRead: Boolean = false) : SessionTransportTransformer

A transformer used to sign and encrypt/decrypt session data. This transformer works as follows:

SessionTransportTransformerMessageAuthentication

class SessionTransportTransformerMessageAuthentication(val keySpec: SecretKeySpec, val algorithm: String = "HmacSHA256") : SessionTransportTransformer

A transformer used to sign session data. This transformer appends an algorithm MAC (Message Authentication Code) hash of the session data. It uses a specified keySpec when generating the MAC hash.

TooLateSessionSetException

class TooLateSessionSetException : IllegalStateException

Thrown when an HTTP response has already been sent but an attempt to modify the session is made.

Properties

DEFAULT_SESSION_MAX_AGE

const val DEFAULT_SESSION_MAX_AGE: Long

maxAge

var CookieConfiguration.maxAge: Duration?

Cookie time to live duration or null for session cookies. Session cookies are client-driven. For example, a web browser usually removes session cookies at browser or window close unless the session is restored.

sameSite

val Cookie.sameSite: String?

Extension for easier access of SameSite attribute.

var CookieConfiguration.sameSite: String?

Cookie configuration extension to supply the "SameSite" attribute for preventing cross-site request forgery (CSRF) attacks.

sessionId

val ApplicationCall.sessionId: String?

Returns a sessionId for a single session identified by ID. This will not work if there are multiple sessions by ID were registered or the Sessions plugin is not installed. If you are using multiple sessions, please use sessionId function instead.

Sessions

val Sessions: RouteScopedPlugin<SessionsConfig>

A plugin that provides a mechanism to persist data between different HTTP requests. Typical use cases include storing a logged-in user's ID, the contents of a shopping basket, or keeping user preferences on the client. In Ktor, you can implement sessions by using cookies or custom headers, choose whether to store session data on the server or pass it to the client, sign and encrypt session data and more.

sessions

val ApplicationCall.sessions: CurrentSession

Gets a current session or fails if the Sessions plugin is not installed.

Functions

clear

inline fun <T : Any> CurrentSession.clear()

fun <T : Any> CurrentSession.clear(klass: KClass<T>)

Clears a session instance with the type T.

inline fun <S : Any> SessionsConfig.cookie(name: String)

fun <S : Any> SessionsConfig.cookie(name: String, typeInfo: TypeInfo)

Configures Sessions to pass the serialized session's data in cookies using the name Set-Cookie attribute.

inline fun <S : Any> SessionsConfig.cookie(name: String, storage: SessionStorage)

fun <S : Any> SessionsConfig.cookie(name: String, typeInfo: TypeInfo, storage: SessionStorage)

Configures Sessions to pass a session identifier in cookies using the name Set-Cookie attribute and store the serialized session's data in the server storage.

inline fun <S : Any> SessionsConfig.cookie(name: String, noinline block: CookieSessionBuilder<S>.() -> Unit)

fun <S : Any> SessionsConfig.cookie(name: String, typeInfo: TypeInfo, block: CookieSessionBuilder<S>.() -> Unit)

Configures Sessions to pass the serialized session's data in cookies using the name Set-Cookie attribute. The block parameter allows you to configure additional cookie settings, for example:

inline fun <S : Any> SessionsConfig.cookie(name: String, storage: SessionStorage, noinline block: CookieIdSessionBuilder<S>.() -> Unit)

fun <S : Any> SessionsConfig.cookie(name: String, typeInfo: TypeInfo, storage: SessionStorage, block: CookieIdSessionBuilder<S>.() -> Unit)

Configures Sessions to pass a session identifier in cookies using the name Set-Cookie attribute and store the serialized session's data in the server storage. The block parameter allows you to configure additional cookie settings, for example:

defaultSessionSerializer

inline fun <T : Any> defaultSessionSerializer(): SessionSerializer<T>

Creates the default SessionSerializer for the type T.

fun <T : Any> defaultSessionSerializer(typeInfo: KType): SessionSerializer<T>

Creates the default SessionSerializer by typeInfo.

directorySessionStorage

fun directorySessionStorage(rootDir: File, cached: Boolean = true): SessionStorage

Creates a storage that serializes a session's data to a file under the rootDir directory.

generateSessionId

fun generateSessionId(): String

Generates a secure random session ID

get

inline fun <T : Any> CurrentSession.get(): T?

fun <T : Any> CurrentSession.get(klass: KClass<T>): T?

Gets a session instance with the type T.

getOrSet

inline fun <T : Any> CurrentSession.getOrSet(name: String = findName(T::class), generator: () -> T): T

Gets or generates a new session instance using generator with the type T (or name if specified)

header

inline fun <S : Any> SessionsConfig.header(name: String)

fun <S : Any> SessionsConfig.header(name: String, typeInfo: TypeInfo)

Configures Sessions to pass the serialized session's data in a name HTTP header.

inline fun <S : Any> SessionsConfig.header(name: String, storage: SessionStorage)

fun <S : Any> SessionsConfig.header(name: String, typeInfo: TypeInfo, storage: SessionStorage)

Configures Sessions to pass a session identifier in a name HTTP header and store the serialized session's data in the server storage.

inline fun <S : Any> SessionsConfig.header(name: String, noinline block: HeaderSessionBuilder<S>.() -> Unit)

fun <S : Any> SessionsConfig.header(name: String, typeInfo: TypeInfo, block: HeaderSessionBuilder<S>.() -> Unit)

Configures Sessions to pass the serialized session's data in a name HTTP header. The block parameter allows you to configure additional settings, for example, sign and encrypt session data.

inline fun <S : Any> SessionsConfig.header(name: String, storage: SessionStorage, noinline block: HeaderIdSessionBuilder<S>.() -> Unit)

fun <S : Any> SessionsConfig.header(name: String, typeInfo: TypeInfo, storage: SessionStorage, block: HeaderIdSessionBuilder<S>.() -> Unit)

Configures Sessions to pass a session identifier in a name HTTP header and store the serialized session's data in the server storage. The block parameter allows you to configure additional settings, for example, sign and encrypt session data.

reflectionSessionSerializer

inline fun <T : Any> reflectionSessionSerializer(): SessionSerializer<T>

fun <T : Any> reflectionSessionSerializer(typeInfo: KType): SessionSerializer<T>

A reflection-based session serializer. Can be used for backward compatibility with previous versions. A serialized format is textual and optimized for size as it could be transferred via HTTP headers or cookies.

sessionId

inline fun <SessionType : Any> ApplicationCall.sessionId(): String?

fun <SessionType : Any> ApplicationCall.sessionId(klass: KClass<SessionType>): String?

Returns the corresponding session ID for the type SessionType or null if no session provided. It will crash if no session provider for type SessionType installed or no Sessions plugin installed.

set

inline fun <T : Any> CurrentSession.set(value: T?)

fun <T : Any> CurrentSession.set(value: T?, klass: KClass<T>)

Sets a session instance with the type T.

transformRead

fun List<SessionTransportTransformer>.transformRead(cookieValue: String?): String?

Un-applies a list of session transformations to a cookieValue representing a transformed session string. If any of the unapplication of transformations fail returning a null, this function also returns null.

transformWrite

fun List<SessionTransportTransformer>.transformWrite(value: String): String

Applies a list of session transformations to a value representing session data.