Debian Codegraph @

django/contrib/sessions/backends/base.py

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