microdot.session --- جلسات ملفات تعريف الارتباط الموقَّعة

مخزن مفاتيح/قيم لكل مستخدم مدعوم بـ jwt داخل ملف تعريف ارتباط session واحد. يُوقَّع رمز JWT بسر معروف للتطبيق وحده، فيستطيع العميل قراءة ملف تعريف الارتباط لكن لا يستطيع العبث بالحمولة دون أن يكتشف الخادم ذلك.

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() كلما كُتب ملف تعريف ارتباط الجلسة. تضبط القيم الافتراضية 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. يُفك ترميز القاموس بشكل كسول عند أول وصول من ملف تعريف ارتباط session ويُخزَّن مؤقتًا في request.g._session لبقية الطلب. تُرجع ملفات تعريف الارتباط التي عُبث بها / غير القابلة للتوقيع قاموسًا فارغًا.

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

قاموس الخيارات المطبقة على ملف تعريف ارتباط الجلسة عند كتابته، المُمرَّرة إلى microdot.Response.set_cookie(). تضبط القيم الافتراضية path='/' و http_only=True بعد تنفيذ initialize().

class SessionDict

class microdot.session.SessionDict(request, session_dict)

الكائن الشبيه بالقاموس المُرجَع من Session.get(). يرث من dict، فتعمل جميع التعديلات القياسية؛ وتلتزم طريقتان إضافيتان بإرجاع التغييرات إلى الاستجابة.

save()

يكتب الجلسة (ربما بعد تعديلها) عائدةً إلى الاستجابة كملف تعريف ارتباط session جديد. بدون هذا الاستدعاء، تُفقَد التعديلات في المكان عند انتهاء الطلب.

delete()

يزيل الجلسة بإصدار ترويسة حذف ملف تعريف ارتباط على الاستجابة.

مزينات على مستوى الوحدة

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. أبقِها صغيرة: يحمل كل طلب وكل استجابة ملف تعريف الارتباط الكامل، ورموز JWT ليست مصممة لتخزين كائنات كبيرة. لأجل حالة لكل مستخدم أكبر من بضع مئات من البايتات، خزِّن البيانات على جانب الخادم مفهرسةً بمعرِّف جلسة صغير.