SessionFileHandler: no TTL or cleanup — session files accumulate indefinitely

[justin-k-bruce]

Problem

When using SessionFileHandler (the default), session files in the sessions/ directory are never cleaned up. The only way to delete a session file is by explicitly calling session.close(), but the framework's ASGI handler (__init__.py:422) never calls it after request processing.

This is especially problematic for WebSocket endpoints: since WebSocket clients don't send cookies, every single WebSocket connection creates a new orphaned session file that is never read or deleted.

In production, this led to 24,800+ orphaned session files accumulating on disk.

Root Cause

In __init__.py lines 419-422:

if os.getenv("TINA4_SESSION", "PY_SESS") in webserver.cookies:
    webserver.session.load(webserver.cookies[...])
else:
    self.cookies["PY_SESS"] = webserver.session.start()  # creates file, never cleaned up

session.start() calls save() which writes a file to disk. After the response is sent, the session is never closed or cleaned up.

Suggested Fix

Add a TTL-based cleanup mechanism to SessionFileHandler:

1. Option A: Add a configurable TINA4_SESSION_TTL (e.g., default 3600s). Run periodic cleanup of files older than the TTL.
2. Option B: Skip session creation entirely for WebSocket upgrade requests (message["type"] == "websocket").
3. Option C: Call session.close() automatically after each non-WebSocket response if the session was auto-created and unused.

Environment

• tina4-python 0.2.170
• WebSocket endpoint using simple_websocket
• Linux (systemd service)

[andrevanzuydam]

Acknowledged — this is tracked for the next maintenance cycle. The session file handler needs TTL-based expiry and a garbage collection sweep (similar to how DatabaseSessionHandler already implements GC). Will align with the session_handlers test coverage added in v3.10.47.

[andrevanzuydam]

Fixed in v3.10.50 — session file handler now has probabilistic GC (1% per request) and TTL-based expiry. Expired sessions are cleaned up automatically. Please update and verify.

[andrevanzuydam]

Investigated in v3.10.68: FileSessionHandler has gc(max_lifetime) which removes expired files (checks _expires timestamp). TTL is stored per session via write(session_id, data, ttl). The Session.gc() method delegates to the handler.

The issue may be that gc() is not called automatically on each request. Consider adding gc() to the request lifecycle (e.g., probabilistic gc like PHP's session.gc_probability).

[andrevanzuydam]

Fixed in 9ad6bfa. Two changes: (1) WebSocket upgrade requests now skip session creation entirely — they don't send cookies and were creating an orphaned file per connection. (2) New anonymous HTTP sessions are lazy — the session file is only written if the route actually stores data, preventing empty orphaned files from accumulating on anonymous page views.

[andrevanzuydam]

Status: Already fixed in v3

Investigated the session implementation — it already has all the safeguards in place:

• Lazy save with dirty flag — save() only writes when data has actually changed
• WebSocket skip — session is not loaded/saved for WebSocket upgrade requests
• Probabilistic GC — gc() runs with 1% probability on each request, cleaning expired sessions
• No redundant writes — the dirty flag prevents unnecessary file I/O

No further action needed.

[andrevanzuydam]

Re-verified against v3.11.8. The session implementation has all the safeguards:

• Lazy save — save() only writes when the dirty flag is set
• WebSocket skip — upgrade requests don't load or save sessions
• Probabilistic GC — gc() runs with 1% probability on each request and sweeps expired files
• Dirty flag prevents redundant writes

The original 24,800-orphaned-files scenario (new session per WebSocket connection) is specifically covered by the WebSocket skip. Leaving this open until we confirm the fix works for the reporter under production load.