microdot.session — подписанные cookie-сессии

Хранилище ключ/значение для каждого пользователя на основе jwt в едином cookie session. JWT подписывается секретом, известным только приложению, поэтому клиент может прочитать cookie, но не может подделать полезную нагрузку так, чтобы сервер этого не обнаружил.

class Session

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

app

Экземпляр microdot.Microdot, на который выполняется установка. Необязательный; вызовите initialize() позже, если он не задан.

secret_key

Симметричный ключ, используемый для подписи JWT сессии. Требуется до того, как сессия читается или записывается – доступ к get() без него возбуждает ValueError. Храните его вне системы контроля версий; на камере это обычно файл в файловой системе FAT.

cookie_options

Словарь параметров, передаваемых в microdot.Response.set_cookie() при каждой записи cookie сессии. По умолчанию устанавливаются path='/' и http_only=True. Добавьте secure=True для развёртываний только по HTTPS.

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

Подключается к app, если создание было отложено. secret_key / cookie_options переопределяют значения конструктора, если заданы.

get(request) → SessionDict

Возвращает словарь сессии для request. Словарь лениво декодируется из cookie session при первом доступе и кэшируется в request.g._session на остаток запроса. Подделанные / неподписываемые cookie возвращают пустой словарь.

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

Кодирует payload как JWT с секретом сессии. Используется внутренне; предоставляется для вызывающих сторон, которым нужно создавать совместимые токены.

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

Проверяет и декодирует значение сессии в виде JWT-строки. Возвращает {} при любом сбое проверки.

secret_key: bytes | str | None

Секрет подписи, используемый для подписи и проверки JWT сессии. Можно задать после создания. None до установки; чтение сессии без него возбуждает ValueError.

cookie_options: dict

Словарь параметров, применяемых к cookie сессии при его записи, передаваемых в microdot.Response.set_cookie(). По умолчанию устанавливаются path='/' и http_only=True после выполнения initialize().

class SessionDict

class microdot.session.SessionDict(request, session_dict)

Словареподобный объект, возвращаемый Session.get(). Является подклассом dict, поэтому все стандартные изменения работают; два дополнительных метода фиксируют изменения обратно в ответ.

save()

Записывает (возможно изменённую) сессию обратно в ответ как новый cookie session. Без этого вызова правки на месте теряются по завершении запроса.

delete()

Удаляет сессию, отправляя заголовок удаления cookie в ответе.

Декораторы уровня модуля

microdot.session.with_session(f)

Декоратор, передающий словарь сессии обработчику маршрута в качестве второго аргумента:

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

Декоратор не сохраняет автоматически – вызовите SessionDict.save(), когда сессия была изменена.

Сама полезная нагрузка сессии – это обычный словарь Python, сериализованный как JSON внутри JWT. Держите его небольшим: каждый запрос и каждый ответ несут полный cookie, а JWT не предназначены для хранения крупных объектов. Для состояния отдельного пользователя размером больше нескольких сотен байт храните данные на стороне сервера, привязав их к небольшому идентификатору сессии.