microdot.session — sessões em cookies assinados

Um armazenamento de chave/valor por usuário, apoiado por um jwt em um único cookie session. O JWT é assinado com um segredo conhecido apenas pela aplicação, de modo que o cliente pode ler o cookie, mas não pode adulterar o payload sem que o servidor detecte.

class Session

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

app

A instância de microdot.Microdot na qual instalar. Opcional; chame initialize() posteriormente se não for fornecida.

secret_key

Chave simétrica usada para assinar o JWT da sessão. Necessária antes que qualquer sessão seja lida ou escrita – acessar get() sem uma levanta ValueError. Armazene-a fora do controle de versão; em uma câmera isso normalmente é um arquivo no sistema de arquivos FAT.

cookie_options

Dict de opções encaminhadas a microdot.Response.set_cookie() sempre que o cookie de sessão é escrito. Os padrões definem path='/' e http_only=True. Adicione secure=True para implantações somente HTTPS.

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

Anexa a app se a construção tiver sido adiada. secret_key / cookie_options substituem os valores do construtor se fornecidos.

get(request) → SessionDict

Retorna o dicionário de sessão para request. O dicionário é decodificado de forma preguiçosa a partir do cookie session no primeiro acesso e armazenado em cache em request.g._session pelo restante da requisição. Cookies adulterados / não assináveis retornam um dict vazio.

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

Codifica payload como um JWT com o segredo da sessão. Usado internamente; exposto para chamadores que desejam emitir tokens compatíveis.

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

Verifica e decodifica um valor de sessão em forma de string JWT. Retorna {} em qualquer falha de verificação.

secret_key: bytes | str | None

O segredo de assinatura usado para assinar e verificar o JWT da sessão. Configurável após a construção. None até ser definido; ler a sessão sem ele levanta ValueError.

cookie_options: dict

O dict de opções aplicadas ao cookie de sessão quando ele é escrito, encaminhadas a microdot.Response.set_cookie(). Os padrões definem path='/' e http_only=True após a execução de initialize().

class SessionDict

class microdot.session.SessionDict(request, session_dict)

O objeto semelhante a dict retornado por Session.get(). Subclasse de dict, então todas as mutações padrão funcionam; dois métodos extras confirmam as alterações de volta na resposta.

save()

Escreve a sessão (possivelmente modificada) de volta na resposta como um novo cookie session. Sem esta chamada, as edições no local são perdidas quando a requisição termina.

delete()

Remove a sessão emitindo um cabeçalho de exclusão de cookie na resposta.

Decoradores de nível de módulo

microdot.session.with_session(f)

Decorador que passa o dicionário de sessão ao manipulador de rota como um segundo argumento:

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

O decorador não salva automaticamente – chame SessionDict.save() quando a sessão tiver sido modificada.

O próprio payload da sessão é um dict comum do Python serializado como JSON dentro do JWT. Mantenha-o pequeno: cada requisição e cada resposta carregam o cookie completo, e os JWTs não foram projetados para armazenar objetos grandes. Para estado por usuário maior que algumas centenas de bytes, armazene os dados no lado do servidor, indexados por um pequeno identificador de sessão.