|
| 1 | +""" |
| 2 | +In-process read-through cache for global, low-cardinality singleton config. |
| 3 | +
|
| 4 | +A single per-thread **L1** tier resolves a getter L1 → DB: a hit wins; a ``None`` |
| 5 | +result means "not cached, compute it" and is never stored (unless the getter opts |
| 6 | +in with ``cache_none=True``, for getters where ``None`` is a legitimate answer). |
| 7 | +This is deliberately simple — it is only for global, user-INDEPENDENT, |
| 8 | +signal-invalidated singletons (feature flags, system settings, and the like), |
| 9 | +never per-user or per-object data. |
| 10 | +
|
| 11 | +There is intentionally **no shared/cross-process (L2) tier**: freshness is provided |
| 12 | +by resetting L1 at every request and task boundary (middleware + the Celery task |
| 13 | +base), so each request/task reads the singleton from the DB at most once and never |
| 14 | +serves a value cached during a prior request/task (e.g. a since-changed |
| 15 | +``System_Settings``). This keeps the design free of a Redis dependency, pickled |
| 16 | +model graphs, and cross-process invalidation — at the cost of one DB read per |
| 17 | +singleton per request/task. (The default ``django.core.cache`` backend may still be |
| 18 | +Redis for other uses; this module no longer reads or writes it.) |
| 19 | +
|
| 20 | +Values are stored as plain dicts/scalars (see ``model_to_cache_dict`` / |
| 21 | +``cache_dict_to_model``), never pickled model instances. |
| 22 | +
|
| 23 | +Configuration (Django setting, wired from env in ``settings.dist.py``): |
| 24 | +
|
| 25 | +* ``SETTINGS_CACHE_L1_TTL`` — per-thread in-process freshness budget in seconds |
| 26 | + (``-1`` disables the cache, making the decorator a pass-through). Keep it short. |
| 27 | + L1 is reset at each request/task boundary, so it is effectively request/task |
| 28 | + scoped. |
| 29 | +""" |
| 30 | + |
| 31 | +import threading |
| 32 | +import time |
| 33 | +from functools import wraps |
| 34 | + |
| 35 | +from django.conf import settings |
| 36 | + |
| 37 | + |
| 38 | +class _L1Store: |
| 39 | + |
| 40 | + """ |
| 41 | + Per-thread in-process store, TTL-stamped. ``get`` returns the value or ``None`` |
| 42 | + (absent, expired, or L1 disabled via ``SETTINGS_CACHE_L1_TTL`` < 0). |
| 43 | +
|
| 44 | + Per-thread (not shared across threads) so it needs no locking, and is reset at |
| 45 | + each request/task boundary (see ``reset``) — making it effectively request/task |
| 46 | + scoped on a reused worker/uwsgi thread. |
| 47 | + """ |
| 48 | + |
| 49 | + def __init__(self): |
| 50 | + self._local = threading.local() |
| 51 | + |
| 52 | + def _bucket(self): |
| 53 | + bucket = getattr(self._local, "b", None) |
| 54 | + if bucket is None: |
| 55 | + bucket = self._local.b = {} |
| 56 | + return bucket |
| 57 | + |
| 58 | + def get(self, key): |
| 59 | + if getattr(settings, "SETTINGS_CACHE_L1_TTL", 30) < 0: |
| 60 | + return None |
| 61 | + entry = self._bucket().get(key) |
| 62 | + if entry is None: |
| 63 | + return None |
| 64 | + value, expiry = entry |
| 65 | + if time.monotonic() >= expiry: |
| 66 | + self._bucket().pop(key, None) |
| 67 | + return None |
| 68 | + return value |
| 69 | + |
| 70 | + def set(self, key, value): |
| 71 | + ttl = getattr(settings, "SETTINGS_CACHE_L1_TTL", 30) |
| 72 | + if ttl < 0: |
| 73 | + return |
| 74 | + self._bucket()[key] = (value, time.monotonic() + ttl) |
| 75 | + |
| 76 | + def invalidate(self, key): |
| 77 | + # Only this thread; other threads/processes self-heal within the L1 TTL |
| 78 | + # (and reset at their next request/task boundary). |
| 79 | + self._bucket().pop(key, None) |
| 80 | + |
| 81 | + def reset(self): |
| 82 | + # Clear THIS thread's L1 bucket. Called at request/task boundaries so a |
| 83 | + # reused worker/uwsgi thread never serves a value cached during a prior |
| 84 | + # request or task (e.g. a since-changed System_Settings). |
| 85 | + self._bucket().clear() |
| 86 | + |
| 87 | + def clear(self): |
| 88 | + # Test helper: drop this thread's entries. |
| 89 | + self._local = threading.local() |
| 90 | + |
| 91 | + |
| 92 | +_L1_STORE = _L1Store() |
| 93 | + |
| 94 | +# Sentinel stored in L1 to represent a cached ``None`` result, so a legitimately |
| 95 | +# ``None`` value (e.g. "no default configured") is distinguishable from "absent". |
| 96 | +# Only used by getters that opt in via ``cache_none=True``. |
| 97 | +_CACHED_NONE = object() |
| 98 | + |
| 99 | + |
| 100 | +def dojo_settings_cache(*, key: str, cache_none: bool = False): |
| 101 | + """ |
| 102 | + Read-through in-process (L1) cache for a fixed-key singleton getter. |
| 103 | +
|
| 104 | + Resolves L1 → wrapped function. Becomes a pass-through when L1 is disabled |
| 105 | + (``SETTINGS_CACHE_L1_TTL=-1``). Freshness across processes comes from resetting |
| 106 | + L1 each request/task (see ``reset_l1_cache``), not a shared tier. |
| 107 | +
|
| 108 | + By default a ``None`` result is treated as "no value" and is not cached (so the |
| 109 | + next call retries) — right for singletons that always exist and where ``None`` |
| 110 | + means "not yet computed / transient error". |
| 111 | +
|
| 112 | + Pass ``cache_none=True`` for getters where ``None`` is a legitimate steady-state |
| 113 | + answer (e.g. "no default row configured"). It caches the ``None`` too, so a |
| 114 | + missing row costs one DB read per request/task instead of one per call site. |
| 115 | + Safe only when the getter is signal-invalidated on the row's create/save (so the |
| 116 | + cached ``None`` is dropped the moment a value appears). |
| 117 | + """ |
| 118 | + |
| 119 | + def decorator(fn): |
| 120 | + @wraps(fn) |
| 121 | + def wrapper(*args, **kwargs): |
| 122 | + value = _L1_STORE.get(key) # ---- L1 ---- |
| 123 | + if value is _CACHED_NONE: # cached "no value" (cache_none=True) |
| 124 | + return None |
| 125 | + if value is not None: |
| 126 | + return value |
| 127 | + |
| 128 | + value = fn(*args, **kwargs) # ---- miss: compute ---- |
| 129 | + if value is not None: |
| 130 | + _L1_STORE.set(key, value) |
| 131 | + elif cache_none: |
| 132 | + _L1_STORE.set(key, _CACHED_NONE) |
| 133 | + return value |
| 134 | + |
| 135 | + return wrapper |
| 136 | + |
| 137 | + return decorator |
| 138 | + |
| 139 | + |
| 140 | +def invalidate_dojo_settings_cache(key: str) -> None: |
| 141 | + """ |
| 142 | + Drop a cached singleton from L1 (this thread). |
| 143 | +
|
| 144 | + With no shared tier, other threads/processes self-heal at their next |
| 145 | + request/task boundary (L1 reset), so there is nothing cross-process to drop. |
| 146 | + """ |
| 147 | + _L1_STORE.invalidate(key) |
| 148 | + |
| 149 | + |
| 150 | +def reset_l1_cache() -> None: |
| 151 | + """ |
| 152 | + Reset the current thread's L1 tier. |
| 153 | +
|
| 154 | + Call at request/task boundaries (reused worker/uwsgi threads) so the |
| 155 | + in-process L1 is effectively request/task-scoped and never serves a value |
| 156 | + cached during a prior request or task. |
| 157 | + """ |
| 158 | + _L1_STORE.reset() |
| 159 | + |
| 160 | + |
| 161 | +def model_to_cache_dict(instance) -> dict: |
| 162 | + """ |
| 163 | + Flatten a model instance to a plain dict of concrete field values. |
| 164 | +
|
| 165 | + Keyed by ``attname`` (so a relation ``foo`` becomes ``foo_id``) and includes |
| 166 | + the primary key. M2M and reverse relations are skipped. Storing this instead |
| 167 | + of the model instance keeps the cache free of pickled model graphs; rebuild a |
| 168 | + live instance with ``cache_dict_to_model``. |
| 169 | + """ |
| 170 | + return {f.attname: f.value_from_object(instance) for f in instance._meta.concrete_fields} |
| 171 | + |
| 172 | + |
| 173 | +# Attribute set on instances rebuilt for read-only cache use (``read_only=True``). |
| 174 | +# A guarded model's ``save()`` checks it and refuses to persist a cache-derived |
| 175 | +# snapshot (see ``System_Settings.save``). Instance-level, so it never leaks to a |
| 176 | +# freshly-fetched (``no_cache=True``) instance, which is a distinct object. |
| 177 | +READ_ONLY_CACHE_MARKER = "_dd_read_only_cache_snapshot" |
| 178 | + |
| 179 | + |
| 180 | +class ReadOnlyCachedInstanceError(RuntimeError): |
| 181 | + |
| 182 | + """ |
| 183 | + Raised when code tries to save a model instance rebuilt from the read-through |
| 184 | + cache. Such an instance is a point-in-time snapshot; persisting it can clobber |
| 185 | + concurrent changes with stale field values. Fetch a fresh DB instance |
| 186 | + (e.g. ``System_Settings.objects.get(no_cache=True)``) before saving. |
| 187 | + """ |
| 188 | + |
| 189 | + |
| 190 | +def cache_dict_to_model(model_cls, data: dict, *, read_only: bool = False): |
| 191 | + """ |
| 192 | + Rebuild an in-memory model instance from a ``model_to_cache_dict`` dict. |
| 193 | +
|
| 194 | + For read-only use; callers that persist changes must fetch a fresh DB instance |
| 195 | + rather than saving a cache-derived one. Pass ``read_only=True`` to tag the |
| 196 | + instance with ``READ_ONLY_CACHE_MARKER`` so a guarded model's ``save()`` fails |
| 197 | + loudly instead of silently writing a stale snapshot. |
| 198 | + """ |
| 199 | + instance = model_cls(**data) |
| 200 | + if read_only: |
| 201 | + setattr(instance, READ_ONLY_CACHE_MARKER, True) |
| 202 | + return instance |
0 commit comments