base.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523
  1. import logging
  2. import string
  3. from datetime import datetime, timedelta
  4. from asgiref.sync import sync_to_async
  5. from django.conf import settings
  6. from django.core import signing
  7. from django.utils import timezone
  8. from django.utils.crypto import get_random_string
  9. from django.utils.module_loading import import_string
  10. # session_key should not be case sensitive because some backends can store it
  11. # on case insensitive file systems.
  12. VALID_KEY_CHARS = string.ascii_lowercase + string.digits
  13. class CreateError(Exception):
  14. """
  15. Used internally as a consistent exception type to catch from save (see the
  16. docstring for SessionBase.save() for details).
  17. """
  18. pass
  19. class UpdateError(Exception):
  20. """
  21. Occurs if Django tries to update a session that was deleted.
  22. """
  23. pass
  24. class SessionBase:
  25. """
  26. Base class for all Session classes.
  27. """
  28. TEST_COOKIE_NAME = "testcookie"
  29. TEST_COOKIE_VALUE = "worked"
  30. __not_given = object()
  31. def __init__(self, session_key=None):
  32. self._session_key = session_key
  33. self.accessed = False
  34. self.modified = False
  35. self.serializer = import_string(settings.SESSION_SERIALIZER)
  36. def __contains__(self, key):
  37. return key in self._session
  38. def __getitem__(self, key):
  39. return self._session[key]
  40. def __setitem__(self, key, value):
  41. self._session[key] = value
  42. self.modified = True
  43. async def aset(self, key, value):
  44. (await self._aget_session())[key] = value
  45. self.modified = True
  46. def __delitem__(self, key):
  47. del self._session[key]
  48. self.modified = True
  49. @property
  50. def key_salt(self):
  51. return "django.contrib.sessions." + self.__class__.__qualname__
  52. def get(self, key, default=None):
  53. return self._session.get(key, default)
  54. async def aget(self, key, default=None):
  55. return (await self._aget_session()).get(key, default)
  56. def pop(self, key, default=__not_given):
  57. self.modified = self.modified or key in self._session
  58. args = () if default is self.__not_given else (default,)
  59. return self._session.pop(key, *args)
  60. async def apop(self, key, default=__not_given):
  61. self.modified = self.modified or key in (await self._aget_session())
  62. args = () if default is self.__not_given else (default,)
  63. return (await self._aget_session()).pop(key, *args)
  64. def setdefault(self, key, value):
  65. if key in self._session:
  66. return self._session[key]
  67. else:
  68. self[key] = value
  69. return value
  70. async def asetdefault(self, key, value):
  71. session = await self._aget_session()
  72. if key in session:
  73. return session[key]
  74. else:
  75. await self.aset(key, value)
  76. return value
  77. def set_test_cookie(self):
  78. self[self.TEST_COOKIE_NAME] = self.TEST_COOKIE_VALUE
  79. async def aset_test_cookie(self):
  80. await self.aset(self.TEST_COOKIE_NAME, self.TEST_COOKIE_VALUE)
  81. def test_cookie_worked(self):
  82. return self.get(self.TEST_COOKIE_NAME) == self.TEST_COOKIE_VALUE
  83. async def atest_cookie_worked(self):
  84. return (await self.aget(self.TEST_COOKIE_NAME)) == self.TEST_COOKIE_VALUE
  85. def delete_test_cookie(self):
  86. del self[self.TEST_COOKIE_NAME]
  87. async def adelete_test_cookie(self):
  88. del (await self._aget_session())[self.TEST_COOKIE_NAME]
  89. def encode(self, session_dict):
  90. "Return the given session dictionary serialized and encoded as a string."
  91. return signing.dumps(
  92. session_dict,
  93. salt=self.key_salt,
  94. serializer=self.serializer,
  95. compress=True,
  96. )
  97. def decode(self, session_data):
  98. try:
  99. return signing.loads(
  100. session_data, salt=self.key_salt, serializer=self.serializer
  101. )
  102. except signing.BadSignature:
  103. logger = logging.getLogger("django.security.SuspiciousSession")
  104. logger.warning("Session data corrupted")
  105. except Exception:
  106. # ValueError, unpickling exceptions. If any of these happen, just
  107. # return an empty dictionary (an empty session).
  108. pass
  109. return {}
  110. def update(self, dict_):
  111. self._session.update(dict_)
  112. self.modified = True
  113. async def aupdate(self, dict_):
  114. (await self._aget_session()).update(dict_)
  115. self.modified = True
  116. def has_key(self, key):
  117. return key in self._session
  118. async def ahas_key(self, key):
  119. return key in (await self._aget_session())
  120. def keys(self):
  121. return self._session.keys()
  122. async def akeys(self):
  123. return (await self._aget_session()).keys()
  124. def values(self):
  125. return self._session.values()
  126. async def avalues(self):
  127. return (await self._aget_session()).values()
  128. def items(self):
  129. return self._session.items()
  130. async def aitems(self):
  131. return (await self._aget_session()).items()
  132. def clear(self):
  133. # To avoid unnecessary persistent storage accesses, we set up the
  134. # internals directly (loading data wastes time, since we are going to
  135. # set it to an empty dict anyway).
  136. self._session_cache = {}
  137. self.accessed = True
  138. self.modified = True
  139. def is_empty(self):
  140. "Return True when there is no session_key and the session is empty."
  141. try:
  142. return not self._session_key and not self._session_cache
  143. except AttributeError:
  144. return True
  145. def _get_new_session_key(self):
  146. "Return session key that isn't being used."
  147. while True:
  148. session_key = get_random_string(32, VALID_KEY_CHARS)
  149. if not self.exists(session_key):
  150. return session_key
  151. async def _aget_new_session_key(self):
  152. while True:
  153. session_key = get_random_string(32, VALID_KEY_CHARS)
  154. if not await self.aexists(session_key):
  155. return session_key
  156. def _get_or_create_session_key(self):
  157. if self._session_key is None:
  158. self._session_key = self._get_new_session_key()
  159. return self._session_key
  160. async def _aget_or_create_session_key(self):
  161. if self._session_key is None:
  162. self._session_key = await self._aget_new_session_key()
  163. return self._session_key
  164. def _validate_session_key(self, key):
  165. """
  166. Key must be truthy and at least 8 characters long. 8 characters is an
  167. arbitrary lower bound for some minimal key security.
  168. """
  169. return key and len(key) >= 8
  170. def _get_session_key(self):
  171. return self.__session_key
  172. def _set_session_key(self, value):
  173. """
  174. Validate session key on assignment. Invalid values will set to None.
  175. """
  176. if self._validate_session_key(value):
  177. self.__session_key = value
  178. else:
  179. self.__session_key = None
  180. session_key = property(_get_session_key)
  181. _session_key = property(_get_session_key, _set_session_key)
  182. def _get_session(self, no_load=False):
  183. """
  184. Lazily load session from storage (unless "no_load" is True, when only
  185. an empty dict is stored) and store it in the current instance.
  186. """
  187. self.accessed = True
  188. try:
  189. return self._session_cache
  190. except AttributeError:
  191. if self.session_key is None or no_load:
  192. self._session_cache = {}
  193. else:
  194. self._session_cache = self.load()
  195. return self._session_cache
  196. async def _aget_session(self, no_load=False):
  197. self.accessed = True
  198. try:
  199. return self._session_cache
  200. except AttributeError:
  201. if self.session_key is None or no_load:
  202. self._session_cache = {}
  203. else:
  204. self._session_cache = await self.aload()
  205. return self._session_cache
  206. _session = property(_get_session)
  207. def get_session_cookie_age(self):
  208. return settings.SESSION_COOKIE_AGE
  209. def get_expiry_age(self, **kwargs):
  210. """Get the number of seconds until the session expires.
  211. Optionally, this function accepts `modification` and `expiry` keyword
  212. arguments specifying the modification and expiry of the session.
  213. """
  214. try:
  215. modification = kwargs["modification"]
  216. except KeyError:
  217. modification = timezone.now()
  218. # Make the difference between "expiry=None passed in kwargs" and
  219. # "expiry not passed in kwargs", in order to guarantee not to trigger
  220. # self.load() when expiry is provided.
  221. try:
  222. expiry = kwargs["expiry"]
  223. except KeyError:
  224. expiry = self.get("_session_expiry")
  225. if not expiry: # Checks both None and 0 cases
  226. return self.get_session_cookie_age()
  227. if not isinstance(expiry, (datetime, str)):
  228. return expiry
  229. if isinstance(expiry, str):
  230. expiry = datetime.fromisoformat(expiry)
  231. delta = expiry - modification
  232. return delta.days * 86400 + delta.seconds
  233. async def aget_expiry_age(self, **kwargs):
  234. try:
  235. modification = kwargs["modification"]
  236. except KeyError:
  237. modification = timezone.now()
  238. try:
  239. expiry = kwargs["expiry"]
  240. except KeyError:
  241. expiry = await self.aget("_session_expiry")
  242. if not expiry: # Checks both None and 0 cases
  243. return self.get_session_cookie_age()
  244. if not isinstance(expiry, (datetime, str)):
  245. return expiry
  246. if isinstance(expiry, str):
  247. expiry = datetime.fromisoformat(expiry)
  248. delta = expiry - modification
  249. return delta.days * 86400 + delta.seconds
  250. def get_expiry_date(self, **kwargs):
  251. """Get session the expiry date (as a datetime object).
  252. Optionally, this function accepts `modification` and `expiry` keyword
  253. arguments specifying the modification and expiry of the session.
  254. """
  255. try:
  256. modification = kwargs["modification"]
  257. except KeyError:
  258. modification = timezone.now()
  259. # Same comment as in get_expiry_age
  260. try:
  261. expiry = kwargs["expiry"]
  262. except KeyError:
  263. expiry = self.get("_session_expiry")
  264. if isinstance(expiry, datetime):
  265. return expiry
  266. elif isinstance(expiry, str):
  267. return datetime.fromisoformat(expiry)
  268. expiry = expiry or self.get_session_cookie_age()
  269. return modification + timedelta(seconds=expiry)
  270. async def aget_expiry_date(self, **kwargs):
  271. try:
  272. modification = kwargs["modification"]
  273. except KeyError:
  274. modification = timezone.now()
  275. try:
  276. expiry = kwargs["expiry"]
  277. except KeyError:
  278. expiry = await self.aget("_session_expiry")
  279. if isinstance(expiry, datetime):
  280. return expiry
  281. elif isinstance(expiry, str):
  282. return datetime.fromisoformat(expiry)
  283. expiry = expiry or self.get_session_cookie_age()
  284. return modification + timedelta(seconds=expiry)
  285. def set_expiry(self, value):
  286. """
  287. Set a custom expiration for the session. ``value`` can be an integer,
  288. a Python ``datetime`` or ``timedelta`` object or ``None``.
  289. If ``value`` is an integer, the session will expire after that many
  290. seconds of inactivity. If set to ``0`` then the session will expire on
  291. browser close.
  292. If ``value`` is a ``datetime`` or ``timedelta`` object, the session
  293. will expire at that specific future time.
  294. If ``value`` is ``None``, the session uses the global session expiry
  295. policy.
  296. """
  297. if value is None:
  298. # Remove any custom expiration for this session.
  299. try:
  300. del self["_session_expiry"]
  301. except KeyError:
  302. pass
  303. return
  304. if isinstance(value, timedelta):
  305. value = timezone.now() + value
  306. if isinstance(value, datetime):
  307. value = value.isoformat()
  308. self["_session_expiry"] = value
  309. async def aset_expiry(self, value):
  310. if value is None:
  311. # Remove any custom expiration for this session.
  312. try:
  313. await self.apop("_session_expiry")
  314. except KeyError:
  315. pass
  316. return
  317. if isinstance(value, timedelta):
  318. value = timezone.now() + value
  319. if isinstance(value, datetime):
  320. value = value.isoformat()
  321. await self.aset("_session_expiry", value)
  322. def get_expire_at_browser_close(self):
  323. """
  324. Return ``True`` if the session is set to expire when the browser
  325. closes, and ``False`` if there's an expiry date. Use
  326. ``get_expiry_date()`` or ``get_expiry_age()`` to find the actual expiry
  327. date/age, if there is one.
  328. """
  329. if (expiry := self.get("_session_expiry")) is None:
  330. return settings.SESSION_EXPIRE_AT_BROWSER_CLOSE
  331. return expiry == 0
  332. async def aget_expire_at_browser_close(self):
  333. if (expiry := await self.aget("_session_expiry")) is None:
  334. return settings.SESSION_EXPIRE_AT_BROWSER_CLOSE
  335. return expiry == 0
  336. def flush(self):
  337. """
  338. Remove the current session data from the database and regenerate the
  339. key.
  340. """
  341. self.clear()
  342. self.delete()
  343. self._session_key = None
  344. async def aflush(self):
  345. self.clear()
  346. await self.adelete()
  347. self._session_key = None
  348. def cycle_key(self):
  349. """
  350. Create a new session key, while retaining the current session data.
  351. """
  352. data = self._session
  353. key = self.session_key
  354. self.create()
  355. self._session_cache = data
  356. if key:
  357. self.delete(key)
  358. async def acycle_key(self):
  359. """
  360. Create a new session key, while retaining the current session data.
  361. """
  362. data = await self._aget_session()
  363. key = self.session_key
  364. await self.acreate()
  365. self._session_cache = data
  366. if key:
  367. await self.adelete(key)
  368. # Methods that child classes must implement.
  369. def exists(self, session_key):
  370. """
  371. Return True if the given session_key already exists.
  372. """
  373. raise NotImplementedError(
  374. "subclasses of SessionBase must provide an exists() method"
  375. )
  376. async def aexists(self, session_key):
  377. return await sync_to_async(self.exists)(session_key)
  378. def create(self):
  379. """
  380. Create a new session instance. Guaranteed to create a new object with
  381. a unique key and will have saved the result once (with empty data)
  382. before the method returns.
  383. """
  384. raise NotImplementedError(
  385. "subclasses of SessionBase must provide a create() method"
  386. )
  387. async def acreate(self):
  388. return await sync_to_async(self.create)()
  389. def save(self, must_create=False):
  390. """
  391. Save the session data. If 'must_create' is True, create a new session
  392. object (or raise CreateError). Otherwise, only update an existing
  393. object and don't create one (raise UpdateError if needed).
  394. """
  395. raise NotImplementedError(
  396. "subclasses of SessionBase must provide a save() method"
  397. )
  398. async def asave(self, must_create=False):
  399. return await sync_to_async(self.save)(must_create)
  400. def delete(self, session_key=None):
  401. """
  402. Delete the session data under this key. If the key is None, use the
  403. current session key value.
  404. """
  405. raise NotImplementedError(
  406. "subclasses of SessionBase must provide a delete() method"
  407. )
  408. async def adelete(self, session_key=None):
  409. return await sync_to_async(self.delete)(session_key)
  410. def load(self):
  411. """
  412. Load the session data and return a dictionary.
  413. """
  414. raise NotImplementedError(
  415. "subclasses of SessionBase must provide a load() method"
  416. )
  417. async def aload(self):
  418. return await sync_to_async(self.load)()
  419. @classmethod
  420. def clear_expired(cls):
  421. """
  422. Remove expired sessions from the session store.
  423. If this operation isn't possible on a given backend, it should raise
  424. NotImplementedError. If it isn't necessary, because the backend has
  425. a built-in expiration mechanism, it should be a no-op.
  426. """
  427. raise NotImplementedError("This backend does not support clear_expired().")
  428. @classmethod
  429. async def aclear_expired(cls):
  430. return await sync_to_async(cls.clear_expired)()