Kitto.Web.Session

Server-side user session support for KittoX. Defines TKWebSession (the per-user session object, kept thread-local via a threadvar), TKWebSessions (the thread-safe session list with find/create/cleanup), the periodic cleanup thread, and a per-session gnugettext-based localization tool.

TKWebSession class

Represents the server side of a user client session. Holds all objects and data pertaining to the user session.

procedure SetLanguageFromQueriesOrConfig(const AConfig: TKConfig);

Sets the session language from the request query, else from config.

property ReloadingHome: Boolean read FReloadingHome write FReloadingHome;

True when the next request to the application root is a reload the application itself has just asked for — the redirect that follows a login, a language change, or an operation that sends the user back to the home page. Reaching the root normally logs the user out, on purpose: this flag tells it apart from a fresh page load by the browser. Home clears it once it has served the page.

function GetDefaultViewportWidth: Integer;

The default viewport width (in inches-derived pixels) for mobile layout.

constructor Create(const AClientAddress, ASessionId: string;

Creates a session for the given client address, id and timeout (minutes).

property CreationDateTime: TDateTime read FCreationDateTime;

When the session was created (used for timeout/expiry).

property SessionId: string read FSessionId;

The current session's UUID.

property Timeout: Double read FTimeout;

The session timeout in minutes.

property Language: string read FLanguage write SetLanguage;

The active language id; setting it re-applies localization.

property DatabaseName: string read FDatabaseName write FDatabaseName;

Name of the database connection currently active for this session. When empty, the application falls back to Config.DefaultDatabaseName. Set at login time when the user picks an "environment" via the Auth/DatabaseChoices combo. Persisted across sessions: under Auth: JWT via the 'db' claim in kx_token (re-hydrated by AuthorizeRequest at every request); under non-JWT auth via the legacy kx_db cookie (30-day lifetime).

property AuthData: TEFNode read FAuthData;

Gives access to a copy of the auth data that was last passed to Authenticate (and possibly modified by the object during authentication).

property IsAuthenticated: Boolean read FIsAuthenticated write FIsAuthenticated;

Returns True if authentication has successfully taken place.

property ControllerContainer: IKXContainer read FControllerContainer write FControllerContainer;

A reference to the main container of controllers.

property OpenControllers: TList<IKXController> read FOpenControllers;

The controllers currently open in this session.

property HomeController: IKXController read FHomeController write FHomeController;

The home (main) controller instance.

property LoginController: IKXController read FLoginController write FLoginController;

The login controller instance.

property ViewportWidthInInches: Integer read FViewportWidthInInches write FViewportWidthInInches;

Viewport width in inches (mobile scaling hint).

property AutoOpenViewName: string read FAutoOpenViewName write FAutoOpenViewName;

Name of a view to open automatically after login, if any.

property HomeViewNodeName: string read FHomeViewNodeName write FHomeViewNodeName;

Node name of the home view for this session.

property ViewportContent: string read FViewportContent write FViewportContent;

The HTML meta viewport content emitted in the page.

property ViewportWidth: Integer read FViewportWidth write FViewportWidth;

Viewport width in mobile applications.

property ScreenWidth: Integer read FScreenWidth write FScreenWidth;

Screen width in CSS pixels, detected from kx_sw cookie or UA heuristic.

property ScreenHeight: Integer read FScreenHeight write FScreenHeight;

Screen height in CSS pixels, detected from kx_sw cookie or UA heuristic.

property IsMobileBrowser: Boolean read FIsMobileBrowser write FIsMobileBrowser;

True if the client is a mobile browser (phone or tablet).

procedure RemoveController(const AController: IKXController);

If the specified object is found in the list of open controllers, it is removed from the list. Otherwise nothing happens. Used by view hosts to notify the session that a controller was closed.

procedure RegenerateId;

Replaces the session ID with a freshly generated one and clears the IsSessionLost flag. The session object itself is preserved (state already gathered for this request — Language, DatabaseName, client address — survives), only its identity changes. The new ID is sent back as a cookie at AfterHandleRequest time. Called by the login handler before authenticating, both for session-fixation hardening and to recover from stale cookies pointing to an expired/lost server-side session.

property DisplayName: string read GetDisplayName write FDisplayName;

Display name for the session (falls back to SessionId when unset).

property LastRequestInfo: TKWebRequestInfo read FLastRequestInfo;

Snapshot of the last request's data (user agent, client address, time), kept alive after the request object itself is destroyed.

property IsSessionLost: Boolean read FIsSessionLost write FIsSessionLost;

True if this session was created to replace a lost session (client had a cookie but the server no longer knows the session, e.g. after a server restart).

procedure SetDefaultLanguage(const AValue: string);

Sets the default language without triggering a full language refresh.

function HasExpired: Boolean;

True if the session has expired, based on the value of Timeout and the current time.

procedure RegisterStore(const AViewName: string;

Registers a store for a view name. The session becomes owner of the store (it will be freed when unregistered or when the session is destroyed). If a store was already registered for this view, it is freed and replaced.

function FindStore(const AViewName: string): TKViewTableStore;

Returns the store registered for the given view name, or nil if none.

procedure UnregisterStore(const AViewName: string);

Removes and frees the store registered for the given view name. Does nothing if no store is registered for that name.

TKWebSessionLocalizationTool class

This class serves two purposes: redirects localization calls to a per-session instance of dxgettext so we can have per-session language selection, and configures Kitto's localization scheme based on two text domains (the application's default.mo and Kitto's own Kitto.mo). The former is located under the application home directory, the latter under the system home directory.

function AsObject: TObject;

Returns Self as a TObject (IEFInterface support).

function TranslateString(const AString: string;

Translates AString via the Kitto text domain, falling back to the app domain.

procedure TranslateComponent(const AComponent: TComponent);

Translates the captions of AComponent using both text domains.

procedure ForceLanguage(const ALanguageId: string);

Switches the current (per-session) instance to the given language id.

function GetCurrentLanguageId: string;

Returns the language id currently active on the per-session instance.

TKWebSessionInfo record

Thread-safe list of active TKWebSession objects. Owns the sessions it holds and provides atomic find/create, lookup by id or client address, removal and expiry-based cleanup. Fires OnSessionStart/OnSessionEnd.

Read-only snapshot of one session, for monitoring. Exists so that a caller outside the sessions lock never holds a TKWebSession POINTER: the cleanup thread frees expired sessions, so a pointer handed out and read later is a dangling one. That produced access violations in the desktop host's session monitor — on the GUI thread, so neither the request pipeline nor the log ever saw them, they surfaced as Windows exception dialogs. Values are copied under the lock; the id lets a caller ask for an action on that session, again under the lock.

TKWebSessions class

constructor Create(const ATimeout: Double);

Creates the session list with the given per-session timeout (minutes).

function NewSession(const AClientAddress: string;

Creates a new sessions and adds it to the list.

function FindOrCreateSession(const ASessionId, AClientAddress: string;

Atomically finds or creates a session. A request is matched to an existing session ONLY by the session id it presents: if ASessionId matches a live session that session is returned, otherwise a NEW session is created — never one belonging to another client. AClientAddress is recorded on the new session, it is not a matching key. ACreated is set to True when a new session was created.

function GetSessionInfos: TArray<TKWebSessionInfo>;

Returns all sessions as an array for reporting and diagnostic purposes.

Snapshot of every live session, built under the lock. Use this instead of handing out session objects — see TKWebSessionInfo.

function SetSessionDisplayName(const ASessionId, ADisplayName: string): Boolean;

Renames the session with the given id, under the lock. Returns False when that session no longer exists.

procedure RemoveSession(const ASession: TKWebSession);

Deletes and frees the specified session.

procedure ClearSessions;

Removes and frees all sessions.

procedure CleanupExpiredSessions;

Removes and frees the sessions that have expired (per their timeout).

property OnSessionStart: TKWebSessionProc read FOnSessionStart write FOnSessionStart;

Fired when a new session is created.

property OnSessionEnd: TKWebSessionProc read FOnSessionEnd write FOnSessionEnd;

Fired when a session is removed/ended.

TKWebSessionCleanupThread class

Periodically cleans up the list of active sessions by disposing of the stale ones.

constructor Create(const ASessions: TKWebSessions;

Creates the cleanup thread for the given session list, waking every AInterval.