Advanced sessions for Starlette and FastAPI frameworks

Warnings

• breaking Version 2.0.0 introduced significant breaking changes, most notably renaming session 'Backends' to 'Stores' (e.g., `CookieBackend` became `CookieStore`, `RedisBackend` became `RedisStore`). The `Session` class was also removed, and method signatures (like `Store.write`) were altered. Middleware argument names were also changed.
  Fix: Update your code to use `*Store` classes instead of `*Backend` classes, remove direct `Session` class usage, and review method signatures and middleware argument names against the v2.0.0+ documentation.
• breaking Python 3.6 support was dropped in `starsessions` v2.0.0.
  Fix: Ensure your project is running on Python 3.8 or newer to use `starsessions` v2.0.0 and above.
• gotcha By default, `starsessions` does not autoload session data for performance reasons. You must explicitly call `await load_session(request)` in your endpoint or middleware before accessing `request.session`, or use `SessionAutoloadMiddleware`. Failure to do so will result in an empty session or `SessionNotLoaded` errors.
  Fix: Add `await load_session(request)` at the beginning of any view or middleware that needs to interact with the session, or configure `SessionAutoloadMiddleware` in your application's middleware stack.
• gotcha When using `CookieStore`, session data is signed to prevent tampering but is NOT encrypted by default. This means sensitive information stored in the session cookie can be read by the client. For confidentiality, you must provide an `Encryptor` (e.g., `FernetEncryptor`) to the `SessionMiddleware`.
  Fix: Import `FernetEncryptor` from `starsessions.encryptors` and pass an instance to `SessionMiddleware` via the `encryptor` argument, ensuring `starsessions[cryptography]` is installed.
• gotcha When using `RedisStore`, you must explicitly close the Redis connection when the application shuts down. The library does not handle this automatically. The recommended approach is to use a lifespan handler in your ASGI application.
  Fix: Implement an ASGI lifespan handler to properly initialize and `aclose()` your `redis.asyncio.Redis` client when your application starts and stops.
• gotcha The order of middleware in Starlette/FastAPI applications is crucial. If `SessionMiddleware` or `SessionAutoloadMiddleware` is placed incorrectly relative to other middlewares that modify the request or response, unexpected behavior or session issues may arise.
  Fix: Ensure `SessionMiddleware` is placed appropriately in your middleware stack, typically before any middleware or route handlers that need to access or modify the session.
• gotcha Default cookie security settings (`cookie_https_only=True`, `cookie_same_site='strict'`) can cause issues in cross-domain or HTTP development environments. While secure by default, these might prevent cookies from being set or sent by the browser in certain scenarios.
  Fix: For development, you might set `cookie_https_only=False` and `cookie_same_site='lax'`. For cross-domain production deployments, carefully configure `cookie_same_site='none'` along with `cookie_https_only=True` and ensure your frontend handles `withCredentials`.

Install

• pip install starsessions Base installation
• pip install starsessions[redis] With Redis store support
• pip install starsessions[cryptography] With Fernet encryption support

Imports

• SessionMiddleware

  from starsessions import SessionMiddleware

• CookieStore

  from starsessions import CookieStore

• InMemoryStore

  from starsessions import InMemoryStore

• load_session

  from starsessions import load_session

• RedisStore

  from starsessions.stores.redis import RedisStore

  RedisStore is located in a submodule and requires `starsessions[redis]` to be installed.
• FernetEncryptor

  from starsessions.encryptors import FernetEncryptor

  FernetEncryptor is located in a submodule and requires `starsessions[cryptography]` to be installed.

Quickstart

This quickstart demonstrates setting up a basic Starlette application with `starsessions` using the `CookieStore`. It includes `SessionMiddleware` to enable session support and `load_session` to access session data within a view. A `SECRET_KEY` is mandatory for signing session cookies. For local testing, `cookie_https_only` is set to `False` for convenience, but it should be `True` in production for security.

import os
import uvicorn
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import JSONResponse
from starlette.routing import Route
from starsessions import SessionMiddleware, CookieStore, load_session

# It's crucial to use a strong, randomly generated secret key in production.
# For local development, you might use a placeholder, but fetch from env vars.
SECRET_KEY = os.environ.get("SESSION_SECRET_KEY", "a-very-secret-key-that-you-should-change")

session_store = CookieStore(secret_key=SECRET_KEY)

async def homepage(request):
    await load_session(request)
    if "counter" not in request.session:
        request.session["counter"] = 0
    request.session["counter"] += 1
    return JSONResponse({"message": "Session accessed!", "counter": request.session["counter"]})

routes = [
    Route("/", homepage),
]

middleware = [
    Middleware(SessionMiddleware, store=session_store, lifetime=3600 * 24 * 7, cookie_https_only=False)
]

app = Starlette(routes=routes, middleware=middleware)

# To run this example:
# 1. Save as e.g., `app.py`
# 2. `pip install starlette uvicorn starsessions`
# 3. `uvicorn app:app --reload`
# 4. Access at http://127.0.0.1:8000/