Files

Files

A session produces files two ways: the site downloads them, or you make one with screenshot or print. session://files lists both as one list.

There are two kinds of file in it, and the difference is how long they live.

	Belongs to	Survives the browser	Deleted by
download	the browser	no	the Grid, with the browser
kept	the session	yes	an operator, in the admin UI

A screenshot or a print is kept from the start. Those bytes are this server's, so they are written straight to the session's files rather than handed to the browser as a download — which Chrome refuses on plain-http pages and on pages with no origin.

Why keeping is a copy

The Grid's file API is list, read-one, delete-all. There is no write and no per-file delete. Every rule here falls out of that:

• keep_file copies the file to the server, because the original cannot be moved or removed. The download stays where it is.
• Only a kept file can be deleted individually, because only a kept file is ours.
• Clearing the downloads is therefore safe: kept files are somewhere else by definition. That is the whole reason the admin UI can offer that button.
• Clearing removes the Grid's whole store — including the original of a file you kept. The kept copy is untouched, so nothing you kept is lost.

Keeping the same name again replaces it, so keep_file is safe to repeat. A screenshot or print never replaces one: a second page.pdf is kept as page (1).pdf.

Getting the name

keep_file takes the name exactly as session://files lists it. Chrome deduplicates downloads, so a second report.pdf arrives as report (1).pdf and you cannot derive it — ask for the listing. screenshot and print return the name they used.

A kept file can be attached to a page in a later session with upload_file(path=...), which is the main reason to keep one.

Links

Every entry carries a signed URL that opens in a browser for a while, so a screenshot can be shown to someone rather than described. The signature covers that one path and an expiry; rotating the server's token revokes every link at once. Set PUBLIC_BASE_URL for absolute links — see Deployment.

Kept files need somewhere to live. Set FLOW_DATA_DIR, the same directory that turns on Flows; without it print is refused and a screenshot comes back with file_error. Nothing reaps them: a kept file stays until an operator deletes it, so that directory only grows — screenshots included.

---

Actions · Flows · Administration