microdot.session — sessioni con cookie firmati

Un archivio chiave/valore per-utente basato su un jwt contenuto in un singolo cookie session. Il JWT è firmato con un segreto noto solo all’applicazione, quindi il client può leggere il cookie ma non può manomettere il payload senza che il server lo rilevi.

class Session

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

app

L’istanza microdot.Microdot su cui installare. Opzionale; chiamare initialize() più tardi se non fornita.

secret_key

Chiave simmetrica usata per firmare il JWT della sessione. Richiesta prima che una sessione venga letta o scritta – accedere a get() senza una di esse solleva ValueError. Conservarla al di fuori del controllo del codice sorgente; su una camera è tipicamente un file sul filesystem FAT.

cookie_options

Dict di opzioni inoltrate a microdot.Response.set_cookie() ogni volta che il cookie di sessione viene scritto. I valori predefiniti impostano path='/' e http_only=True. Aggiungere secure=True per deployment solo HTTPS.

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

Si collega a app se la costruzione è stata posticipata. secret_key / cookie_options sovrascrivono i valori del costruttore se forniti.

get(request) → SessionDict

Restituisce il dizionario della sessione per request. Il dizionario viene decodificato in modo lazy dal cookie session al primo accesso e memorizzato nella cache su request.g._session per il resto della richiesta. I cookie manomessi / non firmabili restituiscono un dict vuoto.

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

Codifica payload come JWT con il segreto della sessione. Usato internamente; esposto per i chiamanti che vogliono coniare token compatibili.

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

Verifica e decodifica un valore di sessione in forma di stringa JWT. Restituisce {} in caso di qualsiasi fallimento della verifica.

secret_key: bytes | str | None

Il segreto di firma usato per firmare e verificare il JWT della sessione. Impostabile dopo la costruzione. None finché non viene impostato; leggere la sessione senza di esso solleva ValueError.

cookie_options: dict

Il dict di opzioni applicate al cookie di sessione quando viene scritto, inoltrate a microdot.Response.set_cookie(). I valori predefiniti impostano path='/' e http_only=True dopo l’esecuzione di initialize().

class SessionDict

class microdot.session.SessionDict(request, session_dict)

L’oggetto simile a dict restituito da Session.get(). Sottoclasse dict, quindi tutte le mutazioni standard funzionano; due metodi aggiuntivi confermano le modifiche di nuovo nella risposta.

save()

Riscrive la sessione (eventualmente mutata) nella risposta come nuovo cookie session. Senza questa chiamata, le modifiche in loco vengono perse al termine della richiesta.

delete()

Rimuove la sessione emettendo un header di cancellazione del cookie sulla risposta.

Decoratori a livello di modulo

microdot.session.with_session(f)

Decoratore che passa il dizionario della sessione all’handler della route come secondo argomento:

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']}

Il decoratore non salva automaticamente – chiamare SessionDict.save() quando la sessione è stata modificata.

Il payload della sessione stesso è un normale dict Python serializzato come JSON all’interno del JWT. Tenerlo piccolo: ogni richiesta e ogni risposta trasporta l’intero cookie, e i JWT non sono progettati per memorizzare oggetti di grandi dimensioni. Per uno stato per-utente più grande di qualche centinaio di byte, memorizzare i dati lato server indicizzandoli con un piccolo identificatore di sessione.