microdot.session — ondertekende cookie-sessies

Een sleutel/waarde-opslag per gebruiker, ondersteund door een jwt in één enkele session-cookie. De JWT wordt ondertekend met een geheim dat alleen de applicatie kent, zodat de client de cookie kan lezen maar de payload niet kan manipuleren zonder dat de server dit detecteert.

class Session

class microdot.session.Session(app: Microdot | None = None, secret_key: bytes | str | None = None, cookie_options: dict | None = None)

app

De microdot.Microdot-instantie om op te installeren. Optioneel; roep later initialize() aan indien niet opgegeven.

secret_key

Symmetrische sleutel gebruikt om de sessie-JWT te ondertekenen. Vereist voordat een sessie wordt gelezen of geschreven – get() aanroepen zonder sleutel gooit ValueError op. Bewaar deze buiten versiebeheer; op een camera is dit doorgaans een bestand op het FAT-bestandssysteem.

cookie_options

Dict van opties die worden doorgegeven aan microdot.Response.set_cookie() telkens wanneer de sessiecookie wordt geschreven. Standaard wordt path='/' en http_only=True ingesteld. Voeg secure=True toe voor uitsluitend-HTTPS-implementaties.

initialize(app: Microdot, secret_key=None, cookie_options=None)

Koppel aan app als de constructie was uitgesteld. secret_key / cookie_options overschrijven de constructorwaarden indien opgegeven.

get(request) → SessionDict

Geef het sessiewoordenboek voor request terug. Het woordenboek wordt lui gedecodeerd uit de session-cookie bij de eerste toegang en gecachet op request.g._session voor de rest van het request. Gemanipuleerde / niet-ondertekenbare cookies geven een lege dict terug.

encode(payload: dict, secret_key=None) → str

Codeer payload als een JWT met het geheim van de sessie. Wordt intern gebruikt; blootgesteld voor aanroepers die compatibele tokens willen aanmaken.

decode(session: str, secret_key=None) → dict

Verifieer en decodeer een JWT-string-sessiewaarde. Geeft {} terug bij elke verificatiefout.

secret_key: bytes | str | None

Het ondertekeningsgeheim gebruikt om de sessie-JWT te ondertekenen en te verifiëren. Instelbaar na constructie. None totdat ingesteld; de sessie lezen zonder dit geheim gooit ValueError op.

cookie_options: dict

De dict van opties die op de sessiecookie wordt toegepast wanneer deze wordt geschreven, doorgegeven aan microdot.Response.set_cookie(). Standaard wordt path='/' en http_only=True ingesteld nadat initialize() draait.

class SessionDict

class microdot.session.SessionDict(request, session_dict)

Het dict-achtige object dat door Session.get() wordt teruggegeven. Subklasse van dict, dus alle standaardmutaties werken; twee extra methoden committen de wijzigingen terug in de respons.

save()

Schrijf de (mogelijk gemuteerde) sessie terug in de respons als een nieuwe session-cookie. Zonder deze aanroep gaan in-place bewerkingen verloren wanneer het request eindigt.

delete()

Verwijder de sessie door een cookie-verwijderingsheader op de respons uit te sturen.

Decorators op moduleniveau

microdot.session.with_session(f)

Decorator die het sessiewoordenboek als tweede argument aan de route-handler doorgeeft:

from microdot import Microdot
from microdot.session import Session, with_session

app = Microdot()
Session(app, secret_key=load_secret())

@app.get('/counter')
@with_session
async def counter(request, session):
    session['n'] = session.get('n', 0) + 1
    session.save()
    return {'n': session['n']}

De decorator slaat niet automatisch op – roep SessionDict.save() aan wanneer de sessie is gewijzigd.

De sessie-payload zelf is een gewone Python-dict die als JSON binnen de JWT wordt geserialiseerd. Houd deze klein: elk request en elke respons draagt de volledige cookie, en JWT’s zijn niet ontworpen voor het opslaan van grote objecten. Sla voor gebruikersstatus groter dan een paar honderd bytes de gegevens server-side op met een kleine sessie-identificatie als sleutel.