microdot.session — sessões por cookie assinado

Um armazenamento de chave/valor por utilizador suportado por um jwt num único cookie session. O JWT é assinado com um segredo conhecido apenas pela aplicação, pelo que o cliente pode ler o cookie mas não pode alterar o payload sem que o servidor o detete.

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 microdot.Microdot onde instalar. Opcional; chame initialize() mais tarde se não for fornecida.

secret_key

Chave simétrica utilizada para assinar o JWT de sessão. Obrigatória antes de qualquer sessão ser lida ou escrita – aceder a get() sem ela lança ValueError. Guarde-a fora do controlo de versões; numa câmara, é normalmente um ficheiro no sistema de ficheiros FAT.

cookie_options

Dict de opções passadas a microdot.Response.set_cookie() sempre que o cookie de sessão é escrito. As predefinições definem path='/' e http_only=True. Adicione secure=True para implementações exclusivamente HTTPS.

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

Associa a app se a construção foi adiada. secret_key / cookie_options substituem os valores do construtor se forem fornecidos.

get(request) → SessionDict

Devolve o dicionário de sessão para request. O dicionário é descodificado de forma lazy a partir do cookie session no primeiro acesso e armazenado em cache em request.g._session pelo resto do pedido. Cookies alterados / impossíveis de assinar devolvem um dict vazio.

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

Codifica payload como JWT com o segredo da sessão. Utilizado internamente; exposto para chamadores que pretendam criar tokens compatíveis.

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

Verifica e descodifica um valor de sessão JWT-string. Devolve {} em qualquer falha de verificação.

secret_key: bytes | str | None

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

cookie_options: dict

O dict de opções aplicado ao cookie de sessão quando é escrito, passado a microdot.Response.set_cookie(). As predefinições definem path='/' e http_only=True após initialize() ser executado.

class SessionDict

class microdot.session.SessionDict(request, session_dict)

O objeto do tipo dict devolvido por Session.get(). É uma subclasse de dict, pelo que todas as mutações padrão funcionam; dois métodos extra confirmam as alterações de volta na resposta.

save()

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

delete()

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

Decoradores ao nível do módulo

microdot.session.with_session(f)

Decorador que passa o dicionário de sessão ao handler de rota como 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 guarda automaticamente – chame SessionDict.save() quando a sessão for modificada.

O payload da sessão em si é um dict Python regular serializado como JSON dentro do JWT. Mantenha-o pequeno: cada pedido e cada resposta transporta o cookie completo, e os JWTs não foram concebidos para armazenar objetos grandes. Para estado por utilizador superior a algumas centenas de bytes, armazene os dados no lado do servidor indexados por um identificador de sessão pequeno.