File size: 20,675 Bytes
ea2c336 81a8217 ea2c336 8145bee 81a8217 ea2c336 9e15897 ea2c336 9e15897 ea2c336 9e15897 8145bee ea2c336 1ad1eea ea2c336 ef68ae0 ea2c336 81a8217 ea2c336 81a8217 ea2c336 81a8217 ea2c336 81a8217 ea2c336 9e15897 b2aa446 9e15897 ea2c336 81a8217 ea2c336 b2aa446 ea2c336 aa1490a 1ad1eea c3e4cb4 f546440 1ad1eea c3e4cb4 aa1490a 1ad1eea aa1490a b2aa446 aa1490a 1ad1eea aa1490a 8145bee 1ad1eea c3e4cb4 9e15897 b2aa446 9e15897 c3e4cb4 aa1490a 1ad1eea aa1490a c3e4cb4 b2aa446 1ad1eea c3e4cb4 9e15897 ea2c336 9e15897 ea2c336 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 | """core/alerts.py β "tell me when a record ENTERS this view" (wave 20, owner item 25).
THE OWNER'S SHAPE, verbatim: *"a user click a view and click 'Create alert'. This way when a
Record gets into that Filter's criteria, a user gets notified in that module β¦ Read/Unread like an
inbox type of thing so they can confirm whether they have seen the Record that got filtered in."*
An alert remembers a View's matched set and delivers one counted notification per run.
An entrant is a pid that matches now and did not last time. That definition is what
makes the module trustworthy rather than noisy:
* a record already in the view when the alert is created is NOT news. The first evaluation
SEEDS the set silently (`seed=True`); without that, creating an alert on a 400-row view
would announce 400 "new" records, and the user would turn the feature off in one click;
* a record that leaves and comes back IS news again β it re-entered the criteria, which is the
event the owner described;
* a record that merely CHANGES while staying in the view is not an entrant. "Still matching" is
not an event. (An on-change alert is a different feature with a different noise budget; it is
NOT smuggled in here under the same name.)
β **WHY THE MATCHED SET IS STORED AND NOT RECOMPUTED FROM HISTORY.** There is no row-level audit
log to diff against β `store` holds current state, and Odoo is read-only. The remembered set IS
the history, so it is written on every evaluation, in the same transaction that queues the
notifications. Losing that write while keeping the notifications would re-announce the same
records forever.
β **WHAT AN UNANSWERABLE LEAF ACTUALLY DOES HERE β CHECKED, NOT ASSUMED.** `harness.filter_eval`'s
`EvalCtx` is explicit that each of its four members "absent, the condition matches NOTHING rather
than everything" β the engine NARROWS on an unresolved measure/cohort/rank set rather than
widening. So the failure mode is not a false alert; it is a **missed** one, and a missed entrant
is re-detected on the next evaluation because `matched` only ever records what genuinely matched.
That is the safe direction, and it is why `partial` is a caller-supplied flag rather than
something inferred in here: the caller (`routes_alerts`) is the only layer that knows whether it
could BUILD a complete context. When it says so, `evaluate()` records the attempt and changes
nothing β updating `matched` from a narrowed evaluation would drop rows out of the remembered set
and then re-announce every one of them as an "entrant" on the next complete pass. That is the
real hazard: not a phantom alert, but a storm of stale ones.
β **EVERY STAMP CARRIES A UTC OFFSET** (DEBT D-18). A browser can only render a timestamp
relatively if it can subtract it from `now`, and a naive container-local stamp is unsubtractable β
it renders VERBATIM or, worse, silently as the reader's own zone. `_now_iso()` is the one place
that is decided.
"""
import datetime as _dt
import logging as _logging
from urllib.parse import urlencode
import core.store as store
from core import account_rows
#: Alert DEFINITIONS, per tenant: {alert_id: {...}}. Separate from the notifications bucket so a
#: busy inbox never rewrites the definitions (and a definition edit never rewrites the inbox).
ALERTS_KEY = 'alerts'
#: Legacy inbox document, replaced by recipient-scoped notification rows on PostgreSQL.
NOTIFICATIONS_KEY = 'alert_notifications'
#: Keep 200 per recipient when possible, dropping only the oldest read notifications.
MAX_NOTIFICATIONS = account_rows.NOTIFICATION_TARGET
_SINK = None
_LOG = _logging.getLogger(__name__)
def set_sink(fn):
"""Register the optional notification sink without importing an application layer."""
if fn is not None and not callable(fn):
raise ValueError('A notification sink must be callable.')
global _SINK
_SINK = fn
def _publish(owner, item, st):
if _SINK is not None:
try:
_SINK(_st(st), owner, item)
except Exception as exc:
# A failed notice must not roll back its producer or suppress the compatibility row.
_LOG.warning('Assistant notice was not delivered: %s', type(exc).__name__)
def _now_iso():
"""UTC, WITH the offset β `2026-08-05T09:41:07.123456+00:00`. See the module note (D-18)."""
from core import write_execution
return write_execution.utcnow().isoformat()
def _st(st):
return st if st is not None else store
def list_alerts(user=None, st=None, is_admin=False):
"""Alert definitions this user may see: their own. Admins see all (they support them)."""
try:
recs = _st(st).get(ALERTS_KEY) or {}
except Exception:
return []
out = []
for aid, rec in recs.items():
if not isinstance(rec, dict):
continue
if user and not is_admin and str(rec.get('owner') or '') != str(user):
continue
out.append({**rec, 'id': str(aid)})
return sorted(out, key=lambda r: str(r.get('createdAt') or ''))
def create(alert_id, *, view_id, topic, owner, label='', st=None):
"""Register an alert on a view. Returns the record.
The view is stored BY ID, never by a copy of its filter tree. An alert whose criteria were
snapshotted at creation would silently stop matching the view the moment its owner edited it β
and the user's mental model is "alert me on THIS VIEW", not "on this view as it was in
August".
"""
rec = {'id': str(alert_id), 'viewId': str(view_id), 'topic': str(topic),
'owner': str(owner), 'label': str(label or '')[:160],
'createdAt': _now_iso(), 'matched': [], 'seeded': False,
'lastRunAt': None, 'lastError': None}
def _apply(data):
data[str(alert_id)] = rec
return data
_st(st).update(ALERTS_KEY, _apply, flush='sync')
return rec
def drop_topic(topic, st=None):
"""Delete every alert DEFINITION on a topic (wave 21, item 6a / C3 β a deleted database's
alerts die with it; an alert on a view that no longer exists can only ever error).
Notifications already delivered are left in inboxes: they are history, and history is the
one thing a delete must not rewrite."""
t = str(topic or '')
if not t:
return
def _apply(data):
for aid in [k for k, r in (data or {}).items()
if isinstance(r, dict) and str(r.get('topic') or '') == t]:
data.pop(aid, None)
return data
_st(st).update(ALERTS_KEY, _apply, flush='async')
def delete(alert_id, st=None):
def _apply(data):
data.pop(str(alert_id), None)
return data
_st(st).update(ALERTS_KEY, _apply, flush='sync')
return True
def evaluate(alert_id, matching_pids, *, labels=None, partial=False, st=None):
"""Fold a fresh evaluation of one alert's view into its state; queue any NEW entrants.
`matching_pids` is what the view matches NOW β the caller owns running the filter, because
only it knows the topic's rows and the reader's scope. `partial` says the evaluation could not
answer every leaf; see the module note on why that suppresses everything.
Returns `{'new': [...], 'seeded': bool}` or `{'skipped': 'partial'|'missing'}`.
"""
now_set = {str(p) for p in (matching_pids or ())}
outcome = {}
def _apply(data):
rec = data.get(str(alert_id))
if not isinstance(rec, dict):
outcome['skipped'] = 'missing'
return data
if partial:
# Record the ATTEMPT (so "last checked" is honest) but change nothing else. Writing
# `matched` here would bake a widened set in as truth, and the next COMPLETE
# evaluation would then report every genuinely-absent row as an entrant.
rec['lastRunAt'] = _now_iso()
rec['lastError'] = ('the view could not be fully evaluated (a filter leaf was '
'unanswerable); no alert was raised')
outcome['skipped'] = 'partial'
data[str(alert_id)] = rec
return data
prior = {str(p) for p in (rec.get('matched') or ())}
seeding = not rec.get('seeded')
entrants = [] if seeding else sorted(now_set - prior, key=lambda s: (len(s), s))
rec['matched'] = sorted(now_set, key=lambda s: (len(s), s))
rec['seeded'] = True
rec['lastRunAt'] = _now_iso()
rec['lastError'] = None
data[str(alert_id)] = rec
outcome['new'] = entrants
outcome['seeded'] = seeding
outcome['_rec'] = rec
return data
_st(st).update(ALERTS_KEY, _apply, flush='sync')
if outcome.get('skipped'):
return {'skipped': outcome['skipped']}
rec = outcome.pop('_rec', {}) or {}
if outcome.get('new'):
_queue(rec, outcome['new'], labels or {}, st=st)
return outcome
def _queue(rec, pids, labels, st=None):
"""Append one counted delivery per filter run to both internal destinations."""
if not pids:
return
at = _now_iso()
topic = str(rec.get('topic') or '')
database = {'customer': 'customer_data', 'product': 'product_data'}.get(topic, topic)
view = str(rec.get('viewId') or '')
count = len(pids)
item = {'id': f"{rec.get('id')}:{at}",
'alertId': str(rec.get('id')), 'viewId': str(rec.get('viewId')),
'topic': topic, 'rowId': '', 'kind': 'alert', 'count': count,
'label': f"{count} {'record' if count == 1 else 'records'} entered this View",
'target': {'module': 'database', 'id': database, 'tab': view},
'link': '#/data?' + urlencode({'database': database, 'view': view}),
'alertLabel': str(rec.get('label') or ''),
'at': at, 'read': False}
owner = str(rec.get('owner') or '')
# The sink's first-post cutover must finish before the new bell row is appended.
_publish(owner, item, st)
if account_rows.records_backend(_st(st)):
_notification_write(st, lambda: _append_notification_rows([(owner, False, item, {})], st=st), 1)
return
def _apply(data):
inbox = list(data.get(owner) or [])
inbox.append(item)
if len(inbox) > MAX_NOTIFICATIONS:
# Drop READ entries oldest-first; keep every unread one. A cap that dropped unread
# notifications would silently lose exactly the records the user has not confirmed β
# the one thing this module promises not to do.
unread = [n for n in inbox if not n.get('read')]
read = [n for n in inbox if n.get('read')]
keep_read = read[max(0, len(unread) + len(read) - MAX_NOTIFICATIONS):]
inbox = sorted(unread + keep_read, key=lambda n: str(n.get('at') or ''))
data[owner] = inbox
return data
_notification_write(st, lambda: _st(st).update(NOTIFICATIONS_KEY, _apply, flush='async'), 1)
def notify(owner, label, *, topic='automation', key='', row_id='', detail='', actor='', st=None,
replace=False, target=None, inbox=None):
"""β WAVE 23 (C6) β put ONE notification in a named user's inbox, for a producer that is not
a view-alert evaluation.
The automation engine needs the bell to ring when records arrive at a review gate, and that
is not an alert over a view: there is no filter tree, no `matched` set, no entrant diff. It
reached for `_queue` directly during the wave, which would have made a private function a
cross-module contract β so this is the public door instead, and `_queue` stays the internal
half of `evaluate()`.
The inbox shape is UNCHANGED, deliberately: `AlertsPane` reads one list, and a second row
shape would mean a client that must branch on where a notification came from. `alertId`
carries the producer's key so a click-through can route (W23-W5).
ββ W33-T28 (`ASK C-14`) β `actor` IS THE ONLY THING THAT KNOWS WHO. Owner item: *"the Inbox
reads like email"*, and a verifier reading the carried wave-32 surface found the SENDER position
occupied by `kindLabel(n.kind)` β the literals "Alert" / "Automation" / "Shared with you", i.e. a
CATEGORY where mail puts a who β with no sender field anywhere on the wire, in the model or in
the markup. An alert and an automation have no person behind them and are honestly named by
their machine; **a SHARE has a real person, and only the PRODUCER knows their name.** By the time
the read path sees the row that fact is gone, so it has to be carried at write time.
β ADDITIVE, AND THAT IS THE WHOLE DESIGN. No existing caller changes, no stored row changes
shape, and every reader already tolerates the key's absence β so an inbox written before this
line reads exactly as it did. The alternative C rejected is worth recording because it is the
tempting one: recovering the name by REGEXING the body prose (`"<name> shared this with you"`).
A sender parsed out of a sentence breaks the first time the sentence is reworded, and it breaks
SILENTLY, in the header β [[one-question-two-normalizers]] with the second normaliser being
English.
β Blank is a legitimate value and means *"no person did this"*, NOT "unknown". The client falls
back BY KIND rather than to an empty From column, so an automation never borrows a human's name.
`inbox` (S72-T27) is an agent message's C6 payload. It rides to the sink only and never
enters the compatibility row or the returned item.
"""
items = notify_many([{'owner': owner, 'label': label, 'topic': topic, 'key': key,
'row_id': row_id, 'detail': detail, 'actor': actor,
'replace': replace, 'target': target, 'inbox': inbox}], st=st)
return items[0] if items else None
def _notification_write(st, write, count):
"""Count refused notices under their tenant and clear the loss after a successful write."""
from core import audit
target = _st(st)
tenant = getattr(target, 'key', None) or getattr(target, 'tenant_slug', None)
if tenant is None and target is store:
tenant = getattr(store._d(), 'tenant_slug', None) or 'royal-imports'
tenant = tenant or 'unknown'
try:
result = write()
except Exception as exc:
audit.note_loss(tenant, NOTIFICATIONS_KEY, exc, count)
raise
audit.note_ok(tenant, NOTIFICATIONS_KEY)
return result
def notify_many(entries, st=None):
"""Queue a producer's notifications in one write, preserving the existing inbox wire.
Replacement is opt-in and scoped to one owner's (topic, alertId). Ticket assignments keep
the assignment count in the row label and the ticket title in an additive detail cell.
"""
queued = []
for entry in entries:
owner = str(entry.get('owner') or '').strip()
label = entry.get('label')
if not owner or not label:
continue
topic, key = str(entry.get('topic', 'automation')), str(entry.get('key') or '')
row_id, detail = str(entry.get('row_id') or ''), str(entry.get('detail') or '')
at = _now_iso()
replace = bool(entry.get('replace'))
item = {'id': f"{key or topic}:{row_id or 'n'}:{at}",
'alertId': key, 'viewId': '', 'topic': topic, 'rowId': row_id,
'label': str(detail or label), 'alertLabel': str(label), 'at': at,
'read': False, 'actor': str(entry.get('actor') or '')}
if topic == 'ticket' and replace:
# Subject (`alertLabel`) says who assigned it; the preview (`label`) names the ticket.
item['detail'] = detail
if isinstance(entry.get('target'), dict):
item['target'] = dict(entry['target'])
sink_extra = {'inbox': dict(entry['inbox'])} if isinstance(entry.get('inbox'), dict) else {}
queued.append((owner, replace, item, sink_extra))
if not queued:
return []
# Cutover drops old unread rows before this batch writes fresh compatibility rows.
for owner, _replace, item, sink_extra in queued:
_publish(owner, {**item, **sink_extra}, st)
if account_rows.records_backend(_st(st)):
_notification_write(st, lambda: _append_notification_rows(queued, st=st), len(queued))
return [item for _owner, _replace, item, _extra in queued]
def _apply(data):
owners = set()
for owner, replace, item, _extra in queued:
box = list(data.get(owner) or [])
if replace:
box = [n for n in box if (n.get('topic'), n.get('alertId')) !=
(item['topic'], item['alertId'])]
box.append(dict(item))
data[owner] = box
owners.add(owner)
for owner in owners:
box = data[owner]
if len(box) > MAX_NOTIFICATIONS:
unread = [n for n in box if not n.get('read')]
read = [n for n in box if n.get('read')]
keep_read = read[max(0, len(unread) + len(read) - MAX_NOTIFICATIONS):]
box = sorted(unread + keep_read, key=lambda n: str(n.get('at') or ''))
data[owner] = box
return data
_notification_write(st, lambda: _st(st).update(NOTIFICATIONS_KEY, _apply, flush='async'), len(queued))
return [item for _owner, _replace, item, _extra in queued]
def _trim_notifications(items):
return account_rows.retain_notifications(items)
def _append_notification_rows(queued, *, st):
for owner in sorted({entry[0] for entry in queued}):
def append(items, owner=owner):
for recipient, replace, item, _extra in queued:
if recipient != owner:
continue
if replace:
items = [n for n in items if (n.get('topic'), n.get('alertId')) !=
(item['topic'], item['alertId'])]
items.append(dict(item))
return _trim_notifications(items)
account_rows.update_notifications(owner, append, st=_st(st))
def notification_items(user, st=None):
"""Return only the recipient's notices without falling back after a row-store failure."""
st = _st(st)
if account_rows.records_backend(st):
return account_rows.notification_items(str(user), st=st)
reader = getattr(st, 'get_entry', None)
if callable(reader):
return reader(NOTIFICATIONS_KEY, str(user)) or []
return (st.get(NOTIFICATIONS_KEY) or {}).get(str(user)) or []
def mark_read(user, ids, st=None):
"""Mark allowed notification ids read without changing another recipient's inbox."""
ids = set(ids)
def mark(items):
for item in items:
if isinstance(item, dict) and item.get('id') in ids:
item['read'] = True
return _trim_notifications(items)
st = _st(st)
if account_rows.records_backend(st):
return account_rows.update_notifications(str(user), mark, st=st)
def apply(data):
data[str(user)] = mark(data.get(str(user)) or [])
return data
return st.update(NOTIFICATIONS_KEY, apply, flush='sync')
def inbox(user, st=None, limit=100):
"""`{'unread': int, 'items': [...]}` β newest first, for the badge and the pane."""
try:
items = list(notification_items(user, st=st))
except Exception:
return {'unread': 0, 'items': []}
items = [n for n in items if isinstance(n, dict)]
items.sort(key=lambda n: str(n.get('at') or ''), reverse=True)
return {'unread': sum(1 for n in items if not n.get('read')), 'items': items[:max(0, limit)]}
def after_write(topic_key, st=None, runner=None):
"""The write-path HOOK: re-evaluate every alert whose view belongs to `topic_key`.
β CALLED FROM A WRITE PATH, SO IT MUST NOT RAISE AND MUST NOT BLOCK ON A FULL POOL BUILD.
A failed alert evaluation must never fail the edit that triggered it β the user typed into a
cell; whether an alert fires is not their problem. `runner` is injected by the caller
(`routes_alerts` passes one that can resolve the topic's rows for the alert's owner), so this
module never reaches for a pool itself and stays unit-testable with a fake.
"""
if runner is None:
return {'evaluated': 0}
n = 0
for rec in list_alerts(st=st):
if str(rec.get('topic')) != str(topic_key):
continue
try:
runner(rec)
n += 1
except Exception: # noqa: BLE001 β see the docstring
continue
return {'evaluated': n}
|