Package io.ktor.server.sessions

Types

Link copied to clipboard
interface Cache<in K : Any, V : Any>
Link copied to clipboard
class CacheStorage(delegate: SessionStorage, idleTimeout: Long) : SessionStorage
Link copied to clipboard
class CookieConfiguration

Cookie configuration being used to send sessions

Link copied to clipboard
class CookieIdSessionBuilder<S : Any> : CookieSessionBuilder<S>

Cookie session configuration builder

Link copied to clipboard
open class CookieSessionBuilder<S : Any>

Cookie session configuration builder

Link copied to clipboard
interface CurrentSession

Represents a container for all session instances

Link copied to clipboard
class HeaderIdSessionBuilder<S : Any> : HeaderSessionBuilder<S>

Header session configuration builder

Link copied to clipboard
open class HeaderSessionBuilder<S : Any>

Header session configuration builder

Link copied to clipboard
class SessionNotYetConfiguredException : IllegalStateException

This exception is 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.

Link copied to clipboard
class SessionProvider<S : Any>(name: String, type: KClass<S>, transport: SessionTransport, tracker: SessionTracker<S>)

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

Link copied to clipboard
class Sessions

A plugin that provides a mechanism to persist data between different HTTP requests.

Link copied to clipboard
interface SessionSerializer<T>

Serializes session from and to String

Link copied to clipboard
class SessionSerializerReflection<T : Any> : SessionSerializer<T>

Default reflection-based session serializer that does it via reflection. Serialized format is textual and optimized for size as it is could be transferred via HTTP headers or cookies

Link copied to clipboard
interface SessionStorage

Represents a way to write, read and invalidate session bits.

Link copied to clipboard
class SessionStorageMemory : SessionStorage

SessionStorage that stores session contents into memory.

Link copied to clipboard
interface SessionTracker<S : Any>

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

Link copied to clipboard
class SessionTrackerById<S : Any>(type: KClass<S>, serializer: SessionSerializer<S>, storage: SessionStorage, 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.

Link copied to clipboard
class SessionTrackerByValue<S : Any>(type: KClass<S>, 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.

Link copied to clipboard
interface SessionTransport

SessionTransport receive, send or clear a session from/to an ApplicationCall.

Link copied to clipboard
class SessionTransportCookie(name: String, configuration: CookieConfiguration, transformers: List<SessionTransportTransformer>) : SessionTransport

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

Link copied to clipboard
class SessionTransportHeader(name: String, transformers: List<SessionTransportTransformer>) : SessionTransport

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

Link copied to clipboard
interface SessionTransportTransformer

Represents a session cookie transformation. Useful for such things like signing and encryption

Link copied to clipboard
class SessionTransportTransformerEncrypt(encryptionKeySpec: SecretKeySpec, signKeySpec: SecretKeySpec, ivGenerator: (size: Int) -> ByteArray, encryptAlgorithm: String, signAlgorithm: String) : SessionTransportTransformer

Session transformer that encrypts/decrypts the input.

Session transformer that appends an algorithm MAC (Message Authentication Code) hash of the input. Where the input is either a session contents or a previous transformation. It uses a specified keySpec when generating the Mac hash.

Link copied to clipboard
class TooLateSessionSetException : IllegalStateException

This exception is thrown when HTTP response has already been sent but an attempt to modify session is made

Functions

Link copied to clipboard
inline fun <T : Any> autoSerializerOf(): SessionSerializerReflection<T>

Creates the default SessionSerializer for type T

fun <T : Any> autoSerializerOf(type: KClass<T>): SessionSerializerReflection<T>

Creates the default SessionSerializer for class type

Link copied to clipboard
inline fun <T> CurrentSession.clear()

Clear session instance with type T

Link copied to clipboard
inline fun <S : Any> Sessions.Configuration.cookie(name: String)
fun <S : Any> Sessions.Configuration.cookie(name: String, sessionType: KClass<S>)

Configure sessions to serialize to/from HTTP cookie

inline fun <S : Any> Sessions.Configuration.cookie(name: String, storage: SessionStorage)
fun <S : Any> Sessions.Configuration.cookie(name: String, sessionType: KClass<S>, storage: SessionStorage)
inline fun <S : Any> Sessions.Configuration.cookie(name: String, sessionType: KClass<S>, storage: SessionStorage, block: CookieIdSessionBuilder<S>.() -> Unit)

Configure sessions to get it from cookie using session storage

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

Configures a session using a cookie with the specified name using it as for the actual session content optionally transformed by specified transforms in block. The cookie configuration can be set inside block using the cookie property exposed by CookieIdSessionBuilder.

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

Configures a session using a cookie with the specified name using it as a session id. The actual content of the session is stored at server side using the specified storage. The cookie configuration can be set inside block using the cookie property exposed by CookieIdSessionBuilder.

inline fun <S : Any> Sessions.Configuration.cookie(name: String, sessionType: KClass<S>, block: CookieSessionBuilder<S>.() -> Unit)

Configure sessions to serialize to/from HTTP cookie configuring it by block

Link copied to clipboard
inline fun <T : Any> defaultSessionSerializer(): SessionSerializer<T>

Creates the default SessionSerializer for type T

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

Creates the default SessionSerializer by typeInfo

Link copied to clipboard
fun directorySessionStorage(rootDir: File, cached: Boolean = true): SessionStorage

Creates a session storage that serializes them into regular files under the specified rootDir

Link copied to clipboard
fun generateSessionId(): String

Generates a secure random session ID

Link copied to clipboard
inline fun <T> CurrentSession.get(): T?

Get session instance with type T

Link copied to clipboard
inline fun <T> CurrentSession.getOrSet(name: String = findName(T::class), generator: () -> T): T

Get or generate a new session instance using generator with type T (or name if specified)

Link copied to clipboard
inline fun <S : Any> Sessions.Configuration.header(name: String)
fun <S : Any> Sessions.Configuration.header(name: String, sessionType: KClass<S>)

Configure sessions to serialize to/from HTTP header

inline fun <S : Any> Sessions.Configuration.header(name: String, storage: SessionStorage)
fun <S : Any> Sessions.Configuration.header(name: String, sessionType: KClass<S>, storage: SessionStorage)

Configure sessions to get it from HTTP header using session storage

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

Configures a session using a header with the specified name using it for the actual session content optionally transformed by specified transforms in block.

inline fun <S : Any> Sessions.Configuration.header(name: String, storage: SessionStorage, block: HeaderIdSessionBuilder<S>.() -> Unit)
inline fun <S : Any> Sessions.Configuration.header(name: String, sessionType: KClass<S>, storage: SessionStorage, block: HeaderIdSessionBuilder<S>.() -> Unit)

Configures a session using a header with the specified name using it as a session id. The actual content of the session is stored at server side using the specified storage.

inline fun <S : Any> Sessions.Configuration.header(name: String, sessionType: KClass<S>, block: HeaderSessionBuilder<S>.() -> Unit)

Configures a session using a header with the specified name using it for the actual session content and apply block function to configure serializataion and optional transformations

Link copied to clipboard
inline fun <SessionType : Any> ApplicationCall.sessionId(): 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.

Link copied to clipboard
inline fun <T> CurrentSession.set(value: T?)

Set session instance with type T

Link copied to clipboard
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.

Link copied to clipboard
fun List<SessionTransportTransformer>.transformWrite(value: String): String

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

Properties

Link copied to clipboard
const val DEFAULT_SESSION_MAX_AGE: Long
Link copied to clipboard
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.

Link copied to clipboard
val ApplicationCall.sessionId: String?

Returns a sessionId for 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.

Link copied to clipboard
val ApplicationCall.sessions: CurrentSession

Get current session or fail if no session plugin installed