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
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version

## Unreleased

- **Delete a note with Undo.** Deleting a note no longer asks first: the notice has Undo, which puts it back where it
was. Deleted notes wait in Recently deleted, at the bottom of the Notes page, for 30 days with their files and
history, to put back with one click or delete for good; then they go on their own
([Deleting and putting back](docs/notes.md#deleting-and-putting-back)).
- **Every entity has its own page.** An entity's page is named by its name, as a wiki names pages:
`/wiki/<namespace>/<Name>` (spaces as underscores), so Ada Lovelace in `work` is `/wiki/work/Ada_Lovelace`. It shows
what the entity is, the notes people and the assistant keep on it in the BlockSuite editor, every line that says it,
Expand Down
7 changes: 6 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -629,6 +629,9 @@ deleted.
GET /api/v1/notes
POST /api/v1/notes
GET /api/v1/notes/search
GET /api/v1/notes/deleted
POST /api/v1/notes/deleted/{pid}/restore
DELETE /api/v1/notes/deleted/{pid}
GET /api/v1/notes/{pid}
PATCH /api/v1/notes/{pid}
DELETE /api/v1/notes/{pid}
Expand All @@ -644,7 +647,9 @@ DELETE /api/v1/notes/{pid}/files

Note pages ([Notes](notes.md)), apart from the notes on an asset above. `GET /notes?ns=` is a namespace's page tree
(`all=true` adds the pages of things). `search?q=` finds pages by the words in their title, summary or text, title
matches first, each with the words around the match ([Finding notes](notes.md#finding-notes)). `move` puts a free note inside `parent` before `before`, `history` lists what the
matches first, each with the words around the match ([Finding notes](notes.md#finding-notes)). `DELETE /notes/{pid}`
moves a page to recently deleted for 30 days: `deleted` lists them, `restore` puts one back where it was and
`DELETE /notes/deleted/{pid}` deletes one for good ([Deleting](notes.md#deleting-and-putting-back)). `move` puts a free note inside `parent` before `before`, `history` lists what the
page was before each change, and `restore` puts an earlier version back (what it was becomes a version too). `files`
lists the files and images attached to a page; `blobs` uploads (in chunks) and reads them, and `DELETE …/files?key=`
removes one.
Expand Down
16 changes: 15 additions & 1 deletion docs/notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,8 @@ Images, attachments and other files dropped or pasted into a page are kept where
WebDAV), encrypted with the namespace's key before they leave the machine. The editor names each by the SHA-256 of its
bytes, so the same file is kept once per page, and the server checks the name matches the bytes. Anyone who reads the
page reads its files; editors add them (`PUT /api/v1/notes/{id}/blobs?key=…`, up to `server.max_upload_mb`). Images
and PDFs show in place; anything a browser could run (HTML, SVG) only downloads. Deleting the page deletes its files.
and PDFs show in place; anything a browser could run (HTML, SVG) only downloads. A deleted page keeps its files while it
can be put back; deleting it for good deletes them.
The assistant sees a page's files (names, types, sizes) when it reads it.

## Filing (PARA)
Expand Down Expand Up @@ -121,6 +122,19 @@ refining it, or someone else always starts a new one. **History** on a page list
it; pick one to read it, and editors can restore it. Restoring keeps the page as it was too, so it can be undone.
`GET /api/v1/notes/{id}/history`, `GET .../history/{version}` and `POST .../history/{version}/restore`.

## Deleting and putting back

**Delete** on a page deletes it at once, with no question first: the notice has **Undo**, which puts it back and opens
it. The notes inside it move up a level, and links to it show without a name while it's gone. A deleted page waits in
**Recently deleted**, at the bottom of the Notes page, for 30 days with its files and history: **Put back** returns it
where it was, with the notes that were inside it (those nobody moved since), and **Delete now** (clicked twice) deletes
it for good. After 30 days it goes for good on its own, with its files and history. A thing's page comes back as its
page, or as a free note at the top when the thing is gone or has a new page by now.

`DELETE /api/v1/notes/{pid}` deletes; `GET /api/v1/notes/deleted?ns=` lists recently deleted pages,
`POST /api/v1/notes/deleted/{pid}/restore` puts one back and `DELETE /api/v1/notes/deleted/{pid}` deletes one for good
(editors). The assistant never deletes notes.

## Finding notes

The **Notes** page lists the free notes in view, the latest changed first, each with the notes it sits inside
Expand Down
62 changes: 58 additions & 4 deletions fastapi_backend/app/api/v1/routes/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
from app.domain.store import DB
from app.schemas.common import Ok
from app.schemas.notebook import (
NoteDeleted,
NoteFile,
NoteHistory,
NoteHit,
Expand Down Expand Up @@ -143,6 +144,58 @@ def search_pages(
)


def _trashed(acl: Access, db: DB, pid: int, role: str = "viewer") -> dict[str, Any]:
try:
t = notebook.trashed(db, pid)
except KeyError:
raise HTTPException(404, "not found") from None
acl.need(t["space"], role)
return t


@router.get("/deleted")
def deleted_pages(
user: CurrentUser,
acl: Acl,
db: Db,
ns: str | None = Query(None, description="only this namespace (default: every one you can read)"),
) -> list[NoteDeleted]:
"""Pages deleted in the last 30 days, the latest first: each can be put back until then."""
names = store.space_names(db)
spaces = [acl.namespace(ns)] if ns else (list(names) if user.admin else acl.spaces())
rows = notebook.trash(db, spaces)
who = {a: (db.one("SELECT VALUE email FROM $r", r=store.R("account", a)) or None) for a in {r.get("deleted_by") for r in rows} if a}
return [
NoteDeleted(
id=r["id"],
title=r.get("title") or "Untitled",
about=r.get("about"),
namespace=names.get(r["space"], ""),
deleted_at=r["deleted_at"],
deleted_by=who.get(r.get("deleted_by")),
)
for r in rows
]


@router.post("/deleted/{pid}/restore")
def restore_deleted(pid: int, user: Writer, acl: Acl, db: Db) -> NotePage:
"""Put a deleted page back where it was, with its links, files and history (Undo after Delete). Editors."""
_trashed(acl, db, pid, "editor")
with domain_errors():
p = notebook.undelete(db, pid)
return _out(acl, db, p, user)


@router.delete("/deleted/{pid}")
def purge_deleted(pid: int, user: Writer, acl: Acl, db: Db, cfg: Cfg) -> Ok:
"""Delete a deleted page for good now, with its files and history, rather than after 30 days. Editors."""
_trashed(acl, db, pid, "editor")
with _vault():
notebook.purge(db, pid, cfg)
return Ok()


@router.get("/about/{kind}/{key}")
def page_about(kind: str, key: int, user: CurrentUser, acl: Acl, db: Db) -> NotePage | NotePageDraft:
"""The page of an asset, entity, topic, collection or person: its page, or a draft while nobody has written one."""
Expand Down Expand Up @@ -247,11 +300,12 @@ def move_page(pid: int, body: NotePageMove, user: Writer, acl: Acl, db: Db) -> N


@router.delete("/{pid}")
def delete_page(pid: int, user: Writer, acl: Acl, db: Db, cfg: Cfg) -> Ok:
"""Delete a page; the pages inside it move up a level. Needs editor access."""
def delete_page(pid: int, user: Writer, acl: Acl, db: Db) -> Ok:
"""Delete a page; the pages inside it move up a level. It can be put back from recently deleted for
`TRASH_DAYS` (30) days (`POST /notes/deleted/{pid}/restore`). Needs editor access."""
_page(acl, db, pid, "editor")
with _vault():
notebook.delete(db, pid, cfg)
with domain_errors():
notebook.delete(db, pid, user.id)
return Ok()


Expand Down
122 changes: 108 additions & 14 deletions fastapi_backend/app/domain/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -413,20 +413,113 @@ def move(db, pid, parent=None, before=None):
db.q("UPDATE $r SET parent = $p, position = $pos, updated_at = $t", r=R("note_page", int(pid)), p=parent, pos=position, t=store.now())


def delete(db, pid, cfg=None):
"""Delete a page, with its files (given `cfg`, to reach where they are kept); the pages inside it move up to its
parent. Links to it stay as text."""
p = get(db, pid)
if cfg is not None:
for f in files(db, int(pid)):
delete_file(db, cfg, int(pid), f["key"])
for child in db.values("SELECT VALUE record::id(id) FROM note_page WHERE parent = $p", p=int(pid)):
TRASH_DAYS = 30 # a deleted page can be put back for this long, then it's gone with its files and history


def delete(db, pid, account=None):
"""Delete a page: it goes to the namespace's recently deleted (note_trash, under its own id) for TRASH_DAYS, with
its files and history kept, so it can be put back (undelete). The pages inside it move up to its parent. Links to
it stay as text, and show without a name while it's gone."""
p = db.one("SELECT * OMIT id FROM $r", r=R("note_page", int(pid)))
if not p:
raise KeyError(pid)
children = db.values("SELECT VALUE record::id(id) FROM note_page WHERE parent = $p", p=int(pid))
for child in children:
db.q("UPDATE $r SET parent = $up", r=R("note_page", child), up=p.get("parent"))
db.q("DELETE note_link WHERE page = $p", p=int(pid))
db.q("DELETE note_version WHERE page = $p", p=int(pid))
db.q(
"UPSERT $r CONTENT $d",
r=R("note_trash", int(pid)),
d=store.clean(
{
"space": p["space"],
"title": p.get("title"),
"about": p.get("about"),
"page": p,
"children": children,
"deleted_at": store.now(),
"deleted_by": account,
}
),
)
db.q("DELETE $r", r=R("note_page", int(pid)))


TRASH_FIELDS = "record::id(id) AS id, space, title, about, deleted_at, deleted_by"


def trash(db, spaces, limit=100):
"""The pages deleted from these namespaces that can still be put back, the latest deleted first."""
return db.rows(
f"SELECT {TRASH_FIELDS} FROM note_trash WHERE space IN $s ORDER BY deleted_at DESC LIMIT $n",
s=list(spaces),
n=int(limit),
)


def trashed(db, pid):
"""A deleted page's trash row (its page under `page`), or KeyError."""
t = db.one(f"SELECT {TRASH_FIELDS}, page, children FROM $r", r=R("note_trash", int(pid)))
if not t:
raise KeyError(pid)
return t


def undelete(db, pid):
"""Put a deleted page back where it was, with its links, files and history, and the pages that were inside it
back inside it (those still where they moved to). A thing's page that the thing no longer has (it's gone, moved
away, or has a new page by now) comes back as a free note at the top. Returns the page."""
t = trashed(db, pid)
p, sid = dict(t["page"]), t["space"]
if p.get("about"):
kind, key = _about(p["about"])
try:
kept = owner(db, kind, key) == sid and not db.one(
"SELECT VALUE id FROM note_page WHERE about_key = $k LIMIT 1", k=p.get("about_key")
)
except KeyError:
kept = False
if not kept:
p.update(about=None, about_key=None, parent=None, position=_last_position(db, sid, None))
parent = p.get("parent")
if parent is not None and not db.one("SELECT VALUE id FROM $r WHERE space = $s", r=R("note_page", int(parent)), s=sid):
p.update(parent=None, position=_last_position(db, sid, None))
db.q("CREATE $r CONTENT $d", r=R("note_page", int(pid)), d=store.clean(p))
for child in t.get("children") or []:
c = db.one("SELECT parent, space FROM $r", r=R("note_page", int(child)))
if c and c.get("space") == sid and c.get("parent") == t["page"].get("parent"): # still where it moved up to
db.q("UPDATE $r SET parent = $p", r=R("note_page", int(child)), p=int(pid))
_links(db, int(pid), sid, p.get("body") or "")
db.q("DELETE $r", r=R("note_trash", int(pid)))
return get(db, pid)


def purge(db, pid, cfg=None):
"""Delete a page from recently deleted for good: with its files (given `cfg`, to reach where they are kept) and
its history."""
t = trashed(db, pid)
if cfg is not None:
for f in files(db, int(pid)):
delete_file(db, cfg, int(pid), f["key"], space=t["space"])
db.q("DELETE note_file WHERE page = $p", p=int(pid))
db.q("DELETE note_version WHERE page = $p", p=int(pid))
db.q("DELETE $r", r=R("note_trash", int(pid)))


def purge_due(db, cfg, log=None):
"""The pages deleted more than TRASH_DAYS ago, gone for good. How many."""
before = (dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=TRASH_DAYS)).isoformat(timespec="seconds")
gone = 0
for pid in db.values("SELECT VALUE record::id(id) FROM note_trash WHERE deleted_at < $t LIMIT 50", t=before):
try:
purge(db, pid, cfg)
gone += 1
except Exception as e: # noqa: BLE001 - one page's files shouldn't stop the rest
if log:
log(f"note {pid}: {type(e).__name__}: {e}")
return gone


def links(db, pid):
"""The page's links, in the order its body has them."""
p = get(db, pid)
Expand Down Expand Up @@ -512,12 +605,13 @@ def _space_of(db, pid):
return get(db, pid)["space"]


def delete_file(db, cfg, pid, key):
"""Remove a file from a page and from where it's kept."""
def delete_file(db, cfg, pid, key, space=None):
"""Remove a file from a page and from where it's kept (`space`: the page's namespace, for a deleted page)."""
from . import blobs

row = file_row(db, pid, key)
blobs.delete(db, cfg, row.get("where"), f"notes/{_space_of(db, pid)}/{int(pid)}/{row['id']}")
sid = space if space is not None else _space_of(db, pid)
blobs.delete(db, cfg, row.get("where"), f"notes/{sid}/{int(pid)}/{row['id']}")
db.q("DELETE $r", r=R("note_file", row["id"]))


Expand Down Expand Up @@ -912,5 +1006,5 @@ def file_due(db, cfg, log=None):


def organise_due(db, cfg, log=None):
"""The notes pass the scheduler runs: titles and summaries first, then filing."""
return refine_due(db, cfg, log) + file_due(db, cfg, log)
"""The notes pass the scheduler runs: titles and summaries first, then filing, then emptying old deletions."""
return refine_due(db, cfg, log) + file_due(db, cfg, log) + purge_due(db, cfg, log)
3 changes: 3 additions & 0 deletions fastapi_backend/app/domain/store.py
Original file line number Diff line number Diff line change
Expand Up @@ -1416,6 +1416,9 @@ def close(self):
# what a page was before each change (notebook.snapshot): its history, to look back at and restore
"DEFINE TABLE IF NOT EXISTS note_version SCHEMALESS",
"DEFINE INDEX IF NOT EXISTS note_version_page ON note_version FIELDS page",
# deleted pages, under their own id, until they're put back or TRASH_DAYS pass (notebook.delete)
"DEFINE TABLE IF NOT EXISTS note_trash SCHEMALESS",
"DEFINE INDEX IF NOT EXISTS note_trash_space ON note_trash FIELDS space",
# the files on a note page (images, attachments), kept where Settings → Storage says (notebook.py, blobs.py)
"DEFINE TABLE IF NOT EXISTS note_file SCHEMALESS",
"DEFINE INDEX IF NOT EXISTS note_file_page ON note_file FIELDS page, key",
Expand Down
9 changes: 9 additions & 0 deletions fastapi_backend/app/schemas/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,15 @@ class NoteHit(ResponseModel):
snippet: str | None = Field(None, description="the words around the match in its text, when the text has it")


class NoteDeleted(ResponseModel):
id: int
title: str
about: str | None = Field(None, description='what it was the page of, like "recording:12"; null for a free note')
namespace: str
deleted_at: str
deleted_by: str | None = Field(None, description="who deleted it (their email)")


class NoteSearch(ResponseModel):
total: int = Field(description="how many pages match; `pages` has the first `limit`")
pages: list[NoteHit]
Expand Down
Loading
Loading