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.