From 3d9a93184cb0499d1ade9125fdfb360b4394db4a Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sat, 10 Oct 2026 19:56:44 +0000 Subject: [PATCH] feat(updates): tell admins and notification targets when a new release is out Once per release: an email to every admin (updates.email, on by default) and a lens.release event for the namespaces' notification targets that choose it. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01XturGhybJzfgZvbFxfNB2o --- docs/notifications.md | 1 + docs/updates.md | 9 +++ fastapi_backend/app/api/v1/routes/updates.py | 1 + fastapi_backend/app/domain/notify.py | 25 +++++++++ fastapi_backend/app/domain/settings.py | 2 +- fastapi_backend/app/domain/store.py | 4 +- fastapi_backend/app/domain/updates.py | 55 +++++++++++++++---- fastapi_backend/app/email.py | 19 ++++++- .../app/email_templates/release.html | 13 +++++ fastapi_backend/app/schemas/notifications.py | 2 +- fastapi_backend/tests/api/test_updates.py | 46 ++++++++++++++++ .../app/openapi-client/types.gen.ts | 14 +++-- nextjs-frontend/openapi.json | 12 ++-- 13 files changed, 180 insertions(+), 23 deletions(-) create mode 100644 fastapi_backend/app/email_templates/release.html diff --git a/docs/notifications.md b/docs/notifications.md index cb614d83f..8d41d5164 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -91,6 +91,7 @@ check that the timestamp is recent too, to refuse replays. | `job.cancelled` | a run was cancelled | the same | | `batch.finished` | a batch run finished, or its sample did; each namespace it ran in gets its own counts | `batch`, `label`, `status`, `counts`, `sample` | | `recording.added` | a recording, document, image or web page was added, however it came | `recording`, `title`, `source`, `created_at` | +| `lens.release` | a new Lens release is out, once per release ([Updates](updates.md)) | `tag`, `name`, `current`, `published_at`, `notes_url` | New targets get `job.failed` and `batch.finished`. A batch run's own runs aren't sent one by one: the batch run is, when it finishes. More than five things added to a namespace at once (a watched folder's new files, an import) are one diff --git a/docs/updates.md b/docs/updates.md index 8c7cc937a..56e4d8600 100644 --- a/docs/updates.md +++ b/docs/updates.md @@ -14,6 +14,15 @@ still check by hand (`POST /api/v1/admin/updates/check`). `GET /api/v1/admin/updates` says which version is running, the latest release and its notes, whether it is newer, and how the last upgrade went. +## Being told + +When a check finds a release newer than the one running, Lens says so once per release: + +* **by email** to every admin (`updates.email`, on by default; needs an email server in Settings › Email); +* **to notification targets** (webhooks, Matterbridge, Slack, Discord) whose namespace owners chose the + **A new Lens release is out** event (`lens.release`, [Notifications](notifications.md)); +* in the server log. + ## Upgrading Lens can't replace its own containers (or its microsandbox) from inside them, so a small agent on the machine does it. diff --git a/fastapi_backend/app/api/v1/routes/updates.py b/fastapi_backend/app/api/v1/routes/updates.py index a1932addf..2651af06c 100644 --- a/fastapi_backend/app/api/v1/routes/updates.py +++ b/fastapi_backend/app/api/v1/routes/updates.py @@ -24,6 +24,7 @@ def check_updates(user: AdminWriter, db: Db, cfg: Cfg) -> UpdateStatus: """Ask GitHub for the latest release now.""" try: updates.check(db, cfg) + updates.announce(db, cfg) except updates.UpdateError as e: raise HTTPException(400, str(e)) from None return UpdateStatus.model_validate(updates.view(db, cfg)) diff --git a/fastapi_backend/app/domain/notify.py b/fastapi_backend/app/domain/notify.py index c032d4bec..ed5a679c7 100644 --- a/fastapi_backend/app/domain/notify.py +++ b/fastapi_backend/app/domain/notify.py @@ -48,6 +48,7 @@ "job.cancelled": "A run was cancelled", "batch.finished": "A batch run finished", "recording.added": "Something was added", + "lens.release": "A new Lens release is out", } DEFAULT_EVENTS = ["job.failed", "batch.finished"] KINDS = { @@ -782,6 +783,30 @@ def scan(db, cfg): return n +def release(db, cfg, rel, current): + """Tell the targets that want it that a new Lens release is out (domain/updates.py calls this once per release). + How many deliveries were queued.""" + if not (cfg.get("notifications") or {}).get("enabled", True): + return 0 + live = [t for t in db.rows(f"SELECT {FIELDS} FROM notify_target WHERE enabled = true") if "lens.release" in (t.get("events") or [])] + names = {r["id"]: r["name"] for r in db.rows("SELECT record::id(id) AS id, name FROM space")} + tag, n = rel["tag"], 0 + for space in sorted({t["space"] for t in live}): + key = f"release-{tag}-{space}" + text = f"Lens {tag} is out (this server runs {current})." + data = { + "tag": tag, + "name": rel.get("name"), + "current": current, + "published_at": rel.get("published_at"), + "notes_url": rel.get("url"), + } + e = _event("lens.release", key, space, names.get(space), text, rel.get("url"), data) + if _unclaimed(db, [key]) == {key}: + n += _emit(db, [key], e, [t for t in live if t["space"] == space]) + return n + + def prune(db): """Forget deliveries older than KEEP_DAYS and the claims that only matter while the lookback can see them.""" old = (dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=KEEP_DAYS)).isoformat(timespec="seconds") diff --git a/fastapi_backend/app/domain/settings.py b/fastapi_backend/app/domain/settings.py index 4941151ea..1cf2c0a5e 100644 --- a/fastapi_backend/app/domain/settings.py +++ b/fastapi_backend/app/domain/settings.py @@ -48,7 +48,7 @@ "notifications": None, "telemetry": None, # repo is a startup setting only (what gets installed isn't chosen in the web app) - "updates": ("check", "check_hours", "auto_install"), + "updates": ("check", "check_hours", "auto_install", "email"), "activity": None, "encryption": None, "fedora": None, diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index cbae2c2df..6f52aadec 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -484,7 +484,9 @@ def labels(): }, # new releases (docs/updates.md): check asks GitHub for repo's latest release every check_hours, for the web app's # banner; auto_install installs one as soon as it's seen, through the machine's upgrade agent (install.sh sets it up) - "updates": {"check": True, "check_hours": 24, "auto_install": False, "repo": "adeelahmad/lense"}, + # email: tell admins by email when a new release is seen (once per release; needs Settings › Email). Namespaces' + # notification targets can get it too (the lens.release event). + "updates": {"check": True, "check_hours": 24, "auto_install": False, "email": True, "repo": "adeelahmad/lense"}, # Fedora (docs/fedora.md): a copy of the archive in a Fedora 6 repository, off until url is set (enabled: false pauses # it). password is a # secret; files: send recordings' files too (up to max_file_mb each, 0: any size). diff --git a/fastapi_backend/app/domain/updates.py b/fastapi_backend/app/domain/updates.py index 731b8eae2..777ede171 100644 --- a/fastapi_backend/app/domain/updates.py +++ b/fastapi_backend/app/domain/updates.py @@ -268,24 +268,57 @@ def _hand_over(db, run, backup): # ---------- the background check ---------- +def _once(db, name): + """True for the one process (and the one time) that claims `name`.""" + try: + db.q("CREATE $r CONTENT $d", r=R("app_service", name), d={"at": _ts()}) + return True + except Exception as e: # noqa: BLE001 + if "already exists" in str(e): + return False + raise + + +def announce(db, cfg, log_fn=None): + """Tell people about a newer release, once per release: the namespaces' notification targets that want + lens.release, and the admins by email (updates.email). True when this call told them.""" + rel = _row(db).get("latest") or {} + tag = rel.get("tag") + if not (tag and newer(tag, current()) and _once(db, f"release-notice-{tag}")): + return False + if log_fn: + log_fn(f"Lens {tag} is out (this is {current()})") + from . import notify + + try: + notify.release(db, cfg, rel, current()) + except Exception: # noqa: BLE001 - the email still goes + log.exception("couldn't queue the release notifications") + if cfg["updates"].get("email", True): + admins = db.values("SELECT VALUE email FROM account WHERE admin = true AND disabled != true") + try: + import asyncio + + from app.email import send_release_email + + asyncio.run(send_release_email(cfg, [a for a in admins if a], tag, current(), rel.get("url"))) + except Exception: # noqa: BLE001 - the banner still shows it + log.exception("couldn't email the admins about %s", tag) + return True + + def tick(db, cfg, log_fn=None): - """Check when due; with auto_install, start the upgrade to a new release once.""" + """Check when due and tell people about a new release; with auto_install, start the upgrade to it once.""" if due(db, cfg): - got = check(db, cfg) - tag = (got.get("latest") or {}).get("tag") - if tag and newer(tag, current()) and log_fn: - log_fn(f"Lens {tag} is out (this is {current()})") + check(db, cfg) + announce(db, cfg, log_fn) if not cfg["updates"].get("auto_install"): return tag = ((_row(db).get("latest") or {}).get("tag")) or "" if not (newer(tag, current()) and agent()): return - try: # once per release, across every process - db.q("CREATE $r CONTENT $d", r=R("app_service", f"auto-upgrade-{tag}"), d={"at": _ts()}) - except Exception as e: # noqa: BLE001 - if "already exists" in str(e): - return - raise + if not _once(db, f"auto-upgrade-{tag}"): # once per release, across every process + return try: upgrade(db, cfg, tag, by="auto_install") except UpdateError as e: diff --git a/fastapi_backend/app/email.py b/fastapi_backend/app/email.py index c3cee8dc7..be3eb4d06 100644 --- a/fastapi_backend/app/email.py +++ b/fastapi_backend/app/email.py @@ -1,4 +1,4 @@ -"""Outgoing email (password reset, sign-in links, access requests), sent through the SMTP server in Settings → Email (or MAIL_* in +"""Outgoing email (password reset, sign-in links, access requests, new releases), sent through the SMTP server in Settings → Email (or MAIL_* in .env, which win and show locked). Without one, links are logged instead.""" from __future__ import annotations @@ -122,3 +122,20 @@ async def send_access_request_email( subtype=MessageType.html, ) await _mailer(cfg).send_message(message_, template_name="access_request.html") + + +async def send_release_email(cfg: dict[str, Any], admins: list[str], tag: str, current: str, notes_url: str | None) -> None: + """Tell the admins that a new Lens release is out (docs/updates.md).""" + link = f"{app_url(cfg)}/settings/updates" + if not admins or not mail_enabled(cfg): + return + from fastapi_mail import MessageSchema, MessageType + from pydantic import NameEmail + + message = MessageSchema( + subject=f"Lens {tag} is out", + recipients=[NameEmail(a, a) for a in admins], + template_body={"tag": tag, "current": current, "link": link, "notes_url": notes_url}, + subtype=MessageType.html, + ) + await _mailer(cfg).send_message(message, template_name="release.html") diff --git a/fastapi_backend/app/email_templates/release.html b/fastapi_backend/app/email_templates/release.html new file mode 100644 index 000000000..f4f34ab98 --- /dev/null +++ b/fastapi_backend/app/email_templates/release.html @@ -0,0 +1,13 @@ + + +

Lens {{ tag }} is out. This server runs {{ current }}.

+ + {% if notes_url %}

What's new in {{ tag }}

{% endif %} + +

Back up and install it from Settings › Updates and backups.

+ +

You get this because you're an admin of Lens. Turn these emails off in the same place.

+ +

Lens

+ + diff --git a/fastapi_backend/app/schemas/notifications.py b/fastapi_backend/app/schemas/notifications.py index ff9bac4c8..7e1539d59 100644 --- a/fastapi_backend/app/schemas/notifications.py +++ b/fastapi_backend/app/schemas/notifications.py @@ -9,7 +9,7 @@ from app.schemas.common import RequestModel, ResponseModel TargetKind = Literal["webhook", "matterbridge", "slack", "discord"] -EventType = Literal["job.succeeded", "job.failed", "job.cancelled", "batch.finished", "recording.added"] +EventType = Literal["job.succeeded", "job.failed", "job.cancelled", "batch.finished", "recording.added", "lens.release"] class LastSend(ResponseModel): diff --git a/fastapi_backend/tests/api/test_updates.py b/fastapi_backend/tests/api/test_updates.py index 9b7058a37..d6b0d1adf 100644 --- a/fastapi_backend/tests/api/test_updates.py +++ b/fastapi_backend/tests/api/test_updates.py @@ -233,3 +233,49 @@ def fake(db_, label="manual"): monkeypatch.setattr(migrations, "backup", fake) b = client.post("/api/v1/admin/backups", headers=admin(client, db)).json() assert (b["name"], b["label"], b["bytes"]) == ("manual-20261010-120000.surql.gz", "manual", 1) + + +def test_a_new_release_is_announced_once(db, cfg, github, monkeypatch): + from app import email + from app.domain import notify, store + + sent = [] + + async def fake_email(cfg_, admins, tag, current, notes_url): + sent.append((admins, tag, notes_url)) + + monkeypatch.setattr(email, "send_release_email", fake_email) + make_user(db, "root@x.io", "root password 1", admin=True) + make_user(db, "m@x.io", "member password 1") + pods = store.ns_id(db, "pods") + notify.create(db, cfg, pods, "ops", "slack", "https://hooks.example.com/a", events=["lens.release"]) + notify.create(db, cfg, pods, "runs", "slack", "https://hooks.example.com/b", events=["job.failed"]) + github.release = release("v99.0.0") + updates.tick(db, cfg) + assert sent == [(["root@x.io"], "v99.0.0", "https://github.com/adeelahmad/lense/releases/tag/v99.0.0")] + rows = db.rows("SELECT event, payload FROM notify_delivery") + assert [r["event"] for r in rows] == ["lens.release"] + assert json.loads(rows[0]["payload"])["text"] == f"Lens v99.0.0 is out (this server runs {updates.current()})." + # not again, whoever checks next + updates.check(db, cfg) + updates.tick(db, cfg) + assert len(sent) == 1 and len(db.rows("SELECT id FROM notify_delivery")) == 1 + + +def test_no_announcement_for_this_version_or_with_email_off(db, cfg, github, monkeypatch): + from app import email + + sent = [] + + async def fake_email(*a): + sent.append(a) + + monkeypatch.setattr(email, "send_release_email", fake_email) + make_user(db, "root@x.io", "root password 1", admin=True) + github.release = release(f"v{updates.current()}") + updates.tick(db, cfg) + assert sent == [] + cfg["updates"]["email"] = False + github.release = release("v99.0.0") + updates.check(db, cfg) + assert updates.announce(db, cfg) is True and sent == [] diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index fd83bbb05..17a895634 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -3947,7 +3947,7 @@ export type EventInfo = { /** * Type */ - type: "job.succeeded" | "job.failed" | "job.cancelled" | "batch.finished" | "recording.added"; + type: "job.succeeded" | "job.failed" | "job.cancelled" | "batch.finished" | "recording.added" | "lens.release"; /** * Label */ @@ -8836,7 +8836,9 @@ export type NotifyTarget = { /** * Events */ - events: Array<"job.succeeded" | "job.failed" | "job.cancelled" | "batch.finished" | "recording.added">; + events: Array< + "job.succeeded" | "job.failed" | "job.cancelled" | "batch.finished" | "recording.added" | "lens.release" + >; /** * Enabled */ @@ -8911,7 +8913,9 @@ export type NotifyTargetCreate = { * * default: job.failed and batch.finished */ - events?: Array<"job.succeeded" | "job.failed" | "job.cancelled" | "batch.finished" | "recording.added"> | null; + events?: Array< + "job.succeeded" | "job.failed" | "job.cancelled" | "batch.finished" | "recording.added" | "lens.release" + > | null; /** * Enabled */ @@ -8967,7 +8971,9 @@ export type NotifyTargetUpdate = { /** * Events */ - events?: Array<"job.succeeded" | "job.failed" | "job.cancelled" | "batch.finished" | "recording.added"> | null; + events?: Array< + "job.succeeded" | "job.failed" | "job.cancelled" | "batch.finished" | "recording.added" | "lens.release" + > | null; /** * Enabled */ diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index cfe128052..86995a818 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -31151,7 +31151,8 @@ "job.failed", "job.cancelled", "batch.finished", - "recording.added" + "recording.added", + "lens.release" ], "title": "Type" }, @@ -39582,7 +39583,8 @@ "job.failed", "job.cancelled", "batch.finished", - "recording.added" + "recording.added", + "lens.release" ] }, "type": "array", @@ -39730,7 +39732,8 @@ "job.failed", "job.cancelled", "batch.finished", - "recording.added" + "recording.added", + "lens.release" ] }, "type": "array" @@ -39859,7 +39862,8 @@ "job.failed", "job.cancelled", "batch.finished", - "recording.added" + "recording.added", + "lens.release" ] }, "type": "array"