Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions docs/updates.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions fastapi_backend/app/api/v1/routes/updates.py
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
25 changes: 25 additions & 0 deletions fastapi_backend/app/domain/notify.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down Expand Up @@ -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")
Expand Down
2 changes: 1 addition & 1 deletion fastapi_backend/app/domain/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
4 changes: 3 additions & 1 deletion fastapi_backend/app/domain/store.py
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
55 changes: 44 additions & 11 deletions fastapi_backend/app/domain/updates.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
19 changes: 18 additions & 1 deletion fastapi_backend/app/email.py
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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")
13 changes: 13 additions & 0 deletions fastapi_backend/app/email_templates/release.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<html>
<body>
<p>Lens {{ tag }} is out. This server runs {{ current }}.</p>

{% if notes_url %}<p><a href="{{ notes_url }}">What's new in {{ tag }}</a></p>{% endif %}

<p><a href="{{ link }}">Back up and install it</a> from Settings › Updates and backups.</p>

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

<p>Lens</p>
</body>
</html>
2 changes: 1 addition & 1 deletion fastapi_backend/app/schemas/notifications.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
46 changes: 46 additions & 0 deletions fastapi_backend/tests/api/test_updates.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 == []
14 changes: 10 additions & 4 deletions nextjs-frontend/app/openapi-client/types.gen.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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
*/
Expand Down
12 changes: 8 additions & 4 deletions nextjs-frontend/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -31151,7 +31151,8 @@
"job.failed",
"job.cancelled",
"batch.finished",
"recording.added"
"recording.added",
"lens.release"
],
"title": "Type"
},
Expand Down Expand Up @@ -39582,7 +39583,8 @@
"job.failed",
"job.cancelled",
"batch.finished",
"recording.added"
"recording.added",
"lens.release"
]
},
"type": "array",
Expand Down Expand Up @@ -39730,7 +39732,8 @@
"job.failed",
"job.cancelled",
"batch.finished",
"recording.added"
"recording.added",
"lens.release"
]
},
"type": "array"
Expand Down Expand Up @@ -39859,7 +39862,8 @@
"job.failed",
"job.cancelled",
"batch.finished",
"recording.added"
"recording.added",
"lens.release"
]
},
"type": "array"
Expand Down
Loading