Repository navigation
workspace files
A workspace keeps files in four sections: Downloads, Screenshots, Recordings and Files. This area covers where each is stored, how a file gets in, how it is listed, read and opened by signed link, how a recording is made and filed, and how a name from outside is made safe.
- An agent takes a screenshot and hands the person its
url, which opens without a token. - An agent downloads an export in the browser, keeps it with
keep_file, and attaches it to another page withupload_file(file=...)without the bytes passing through the model. - An operator records a browser with
open_session(record=true)and watches the video afterwards. - An operator clears a workspace's screenshots, or deletes one kept file, in the admin UI.
FILE-1. The workspace record and its expiry are in
workspaces-and-sessions.md. A signed link's signature, expiry and
refusal are in auth-and-roles.md (AUTH-23 to AUTH-29), and so is the Admin
door that guards the admin routes below. The tool and resource surfaces, the mirror tools and
show are in surfaces.md. The scrub is in
secrets-and-scope.md. record as an open_session option is in
session-settings.md. How the Files tab draws is in
admin-ui.md; this file holds the routes behind it.
FILE-2. A workspace's files are in four sections that are never merged into one list. A file's address names its section, so a name only has to be unique inside its section.
| Section | Belongs to | Where the bytes are | Survives the browser |
|---|---|---|---|
| Downloads | the browser | the Grid's per-session store | no |
| Screenshots | the workspace | <data>/workspaces/<name>/screenshots/ |
yes |
| Recordings | the workspace | <data>/workspaces/<name>/recordings/ |
yes |
| Files | the workspace | <data>/workspaces/<name>/files/ |
yes |
FILE-3. <data> is data.dir. When data.dir is unset, Screenshots, Recordings and Files are off, and
listing, reading and keeping them is refused with keeping files is not enabled on this server: it was started with no DATA_DIR, so there is nowhere to keep them. Downloads still work.
FILE-4. Files holds what a caller put there on purpose: a print, a kept screenshot, a kept recording, a kept download. Screenshots and Recordings hold what the server made until it is kept or cleared.
FILE-5. No folder has an expiry, a size cap or a file-count cap. A file leaves a folder only by Keep
(a move out of Screenshots or Recordings), a clear, or a delete (FILE-42 to FILE-44). A workspace's
record expires after workspace.ttl; its folders do not.
FILE-6. Downloads belong to the Grid. The Grid offers list, read one and delete all, so the server offers those and no per-file delete. A download lives until the browser ends, the Grid reaps it, or Downloads is cleared.
FILE-7. A Grid scratch entry is never listed or served as a download: a name ending .crdownload or
.part, or starting with a dot.
FILE-8. The reserved names inside Files are screenshots, recordings and downloads. A file
arriving in Files under one lands as screenshots (1), recordings (1) or downloads (1).
FILE-9. A file the server makes, and a kept screenshot or recording, never overwrite a name. The next
free name is name (1).ext, then name (2).ext, and so on. A name with no extension becomes
name (1).
FILE-10. A file name in a folder (names.valid_file_name) is 1 to 255 characters, holds no /,
no \, and no control character (\x00 to \x1f), does not start with a dot, and is not blank.
It is not trimmed: " a.pdf " and a.pdf are two files. A name that fails is a 400 naming the rule.
FILE-11. A listing skips a file whose name starts with a dot (a staged copy, the notes folder), a name
that fails FILE-10 (logged), a link, and anything that is not a regular file. A path is refused
when it does not resolve to itself under the data directory, so a link left at
<workspace>/files is never followed.
FILE-12. A name that comes from a caller for a file the server writes is narrowed by safe_name. It
folds \ to /, keeps the last segment, strips surrounding whitespace and leading dots, and
becomes upload when nothing is left. A name with no extension gets one.
FILE-13. For bytes the server made, the extension is forced too: the narrowed name keeps its text and
gets .png, .pdf or .html appended when its suffix is not that type, case-insensitively.
chart.pdf for a screenshot is chart.pdf.png, because the served type comes from the name
(FILE-27).
FILE-14. safe_name takes its extension, when the name has none, from mime_type. The server's own table
wins (JSON, XML, YAML, NDJSON, Markdown, CSV, TSV, plain text and HTML); otherwise the standard
library's guess. A text upload with neither gets .txt.
FILE-15. A browser download lands in the Grid's store for that browser. Nothing on this server
copies it until keep_file does.
FILE-16. screenshot saves its PNG to Screenshots by default (save=true), under
screenshot.png or filename, narrowed by FILE-13. A clash lands as screenshot (1).png. The
result's file is the entry (FILE-24) and the name used is file.name.
FILE-17. screenshot(save=false) stores nothing. When saving fails, the image still comes back and the
result carries file_error in place of file. file_error is the refusal's own text for a
ValueError, and otherwise the capture could not be kept (<ExceptionType>), never a path.
FILE-18. print(format="pdf"|"html") writes straight to Files, under page.pdf or page.html
or filename, narrowed by FILE-13. A PDF is the browser's W3C print, with landscape and
background (off by default). HTML is the page source as the browser holds it now. The result has
file, format and bytes. Any other format is a 400.
FILE-19. A print that cannot be kept fails the call with the print could not be kept (<ExceptionType>), not a path. With no DATA_DIR it fails with the FILE-3 message.
FILE-20. upload_file takes exactly one of text, content (base64) or file (a file's address,
FILE-25). An empty string counts as not given, and zero or more than one is a 400. A content that
is not base64 is a 400 that points at the multipart form of the HTTP route. The page sees the name
from safe_name(filename or the file's own name, mime_type), and reads its type from the
extension.
FILE-21. upload_file writes the bytes to a temporary directory, hands the path to the file input, and
removes the directory afterwards. Selenium ships the file to the Grid node, whose browser cannot
see this filesystem. A directory that cannot be made is a server error naming /tmp and TMPDIR.
A path on this server is never accepted.
FILE-22. See SURF-35 for the caps on an HTTP request body. An MCP call has no cap of its own.
FILE-23. upload_file(file=...) reads from the workspace that owns the call. Inside a flow run it reads
from the workspace running the flow, which a flow in the shared library relies on, and only a flow
run can name another library for file, through the capability row's library_arg. An address
outside Downloads is refused with the FILE-3 message when data.dir is unset.
FILE-24. Every surface describes a file the same way: name, uri, size in bytes, created in epoch
milliseconds, content_type, image, url, and for a screenshot, a recording or a download,
keep_with (the exact keep_file("<uri>") call, the uri JSON-quoted). image is true for PNG,
JPEG, GIF, WebP, AVIF and SVG.
FILE-25. An address is one of:
| Section | Address |
|---|---|
| Files | workspace://files/<name> |
| Screenshots | workspace://files/screenshots/<name> |
| Recordings | workspace://files/recordings/<name> |
| Downloads | session://downloads/<name> |
A name is percent-encoded in an address. workspace://files/downloads... and session://files/...
are refused with a message naming the current spelling.
FILE-26. url is signed (FILE-36) and absolute when public_base_url is set, otherwise
relative to the mount. With auth off it is the plain path.
FILE-27. content_type is guessed from the name (mimetypes), with .webp and .avif
added, and application/octet-stream when it has no guess.
FILE-28. The resources are workspace://files (Files and the two folders with their counts,
not expanded), workspace://files/screenshots, workspace://files/recordings and
session://downloads. Each listing is newest first and carries workspace, folder, uri,
count and files.
FILE-29. Reading workspace://files/<name>, .../screenshots/<name> or
session://downloads/<name> returns the bytes with the file's media type. Reading a Files entry
whose type starts video/ returns the entry as JSON, and so does .../recordings/<name>: a model
cannot watch a video, and a resource would carry it as base64. The url in the entry plays it.
FILE-30. The same operations are HTTP routes on the caller's workspace (named by header or
?workspace=): GET /files, GET /files/screenshots, GET /files/recordings,
GET /browser/downloads and PUT /files/{folder}/{name}/kept.
FILE-31. A listing or a read never opens a browser. Downloads read the workspace's record and, with no
session open, are refused with no session is open in this workspace; a download lives only as long as the browser that took it, without asking the Grid. A Grid failure on a browser the record says
is live is raised, not shown as an empty list.
FILE-32. A listing and a read of a download are scrubbed for the secrets in scope on the origins the call touched, because the site names a download (SEC-58).
FILE-33. keep_file(uri) puts one file in Files and returns kept, from, uri, name,
size and created. What it does depends on the section:
- Files: the file stays; the result is its own entry. A name not in Files is a 400.
- Screenshots: the file is read, claimed in Files under the first free name (FILE-9), then removed from Screenshots. If the removal fails or the screenshot is already gone, the Files copy is removed again and the call fails.
- Recordings: the file is moved, not read into memory. The Files copy is claimed with a hard link (a copy where links cannot cross), then the source is removed. If the source cannot be removed the Files copy is removed and the call fails; a source replaced by a different file in between is left alone.
- Downloads: the bytes are read from the Grid and written to Files under the download's name (renamed by FILE-8), replacing a file of that name already in Files. The download stays on the Grid.
FILE-34. A screenshot or recording that is not there is a 400 saying it may be kept already or cleared, and naming the folder's address.
FILE-35. Keeping is one-way for an agent. There is no tool to delete or clear a file. Deleting
and clearing are admin actions (FILE-42 to FILE-44). The same Keep is offered over HTTP as
PUT /files/{folder}/{name}/kept with folder one of screenshots, recordings or downloads,
and to the admin (FILE-42).
FILE-36. A file is opened without a header through one of four routes, keyed by what owns it:
| Route | Section | Keyed by |
|---|---|---|
/files/{session_id}/{name} |
Downloads | the browser's Grid session id |
/kept/{workspace}/{name} |
Files | the workspace name |
/screenshots/{workspace}/{name} |
Screenshots | the workspace name |
/recordings/{workspace}/{name} |
Recordings | the workspace name |
Each carries exp and sig as AUTH-23 describes, and grants that route's path alone (AUTH-27). The
routes check the signature first, then say a file is not there.
FILE-37. A link works for link_ttl seconds (AUTH-24) and is the only credential the request needs, so
a person can open it in a tab, paste it in a transcript or use it as an <img> source. A refused
link is AUTH-26's 403. Reading the listing again gives a fresh link.
FILE-38. A Files, Screenshots or Recordings route answers 404 when the store is off, the name fails FILE-10, or the file is absent or not a regular file. A Downloads route answers 404 for a Grid scratch name (FILE-7) and when the Grid says the browser or the file is gone. Every other failure, and the wording of each answer, is AUTH-28's.
FILE-39. Files on disk are streamed from the descriptor that was checked, so a file replaced
after the check is not served with the old size. They answer Range, so a player can seek. A
download is read whole from the Grid and served as bytes.
FILE-40. Every served file carries:
-
Content-Disposition: inlinewith an ASCIIfilename(every other character and"and\folded to_) and a percent-encodedfilename*, so any name is fetchable; -
Cache-Control: private, max-age=<seconds left on the link>, or 3600 for an unsigned link; -
X-Content-Type-Options: nosniff; - a
Content-Security-Policyby type.
FILE-41. The policy by type:
- PNG, JPEG, GIF, WebP and AVIF:
default-src 'none'; style-src 'unsafe-inline', not sandboxed; -
video/*andaudio/*:default-src 'none'; media-src 'self'; style-src 'unsafe-inline'; -
application/pdf: no policy, because Chrome's viewer does not load under a sandbox; - everything else, including SVG, HTML and an unknown type:
sandbox, so a site's page opened inline cannot run script beside the admin UI.
FILE-42. GET /admin/workspaces/{key}/files returns the four sections for a workspace key, with the
workspace's header. Downloads are listed only when the record's browser is alive on the Grid;
otherwise Downloads is empty. With no store and no live browser every section is empty rather than
an error, and a key that cannot be a directory name has no files.
POST /admin/workspaces/{key}/files/{folder}/{name}/keep keeps a screenshot, a recording or a
download as FILE-33, and refuses another folder.
FILE-43. DELETE /admin/workspaces/{key}/files/{name} decides by name: downloads clears the
Grid's store when the browser is alive (and succeeds without a call when it is not), screenshots
and recordings delete every file in that folder and return cleared, and any other name deletes
that one file from Files and returns deleted.
FILE-44. Clearing counts and deletes only listed files (FILE-11). The pending notes
(FILE-55) are not files and survive a clear of Recordings, so a recording still on its way lands
after it. Clearing Files is refused: Files is never cleared wholesale; delete one file.
FILE-45. open_session(record=true) films the browser. The server asks the Grid to record
(se:recordVideo: true) and names the video after the workspace (se:videoName, for a person
reading the inbox; nothing matches on it). The Grid's recorder, in the node image, makes a
fragmented MP4 of the node's display and ends it when the Grid session ends. One Grid session is
one recording: a reopen after a reap is a new file.
FILE-46. record is explicit: its setting has no config, header or query source. A bare open_session()
after end_browser does not inherit it, unlike every other remembered setting. A silent reopen
after a reap replays it, unless recording has since been turned off. A raw se:recordVideo or
se:videoName capability is refused in favour of record.
FILE-47. record=true is a 400 when recording.enabled is off (Recording is not set up on this server (recording.enabled is off). See the README's Recording section.), and when the browser
is headless, whether asked now or remembered.
FILE-48. The open_session result carries recording: true|false. When the note (FILE-55)
cannot be written, the browser stays open and the result carries recording_error.
workspace://current reports recording: true while the live browser was opened with record.
FILE-49. Getting the video to the server is the operator's job. The operator makes the Grid's
recordings arrive in one inbox directory (recording.dir, default <data>/recordings) by a shared
volume, an upload to a drive, or a local folder. The server never receives an upload and never
mounts the Grid. The inbox is the operator's: the server files from it and never cleans it.
FILE-50. The settings are:
| Key | Default | Meaning |
|---|---|---|
recording.enabled |
false |
The operator says the Grid's recordings reach the inbox |
recording.dir |
<data>/recordings |
The inbox |
recording.wait |
600, at least 30 |
Seconds after a browser ends to wait for its file |
recording.watch |
auto |
auto, events or poll
|
recording.poll |
1000, at least 200 |
Milliseconds between looks when polling |
recording.settle |
10, at least 0 |
Seconds a finished file sits unchanged before it is filed |
FILE-51. The server does not boot, naming the reason, when recording.enabled is set and:
-
data.diris unset; - the inbox does not exist or is not readable, writable and searchable by the process;
- the inbox is, holds or lies in
<data>/workspaces.
It also does not boot with the old FLOW_DATA_DIR, or when a workspace folder is still at the top
of data.dir instead of under workspaces/. It renames an old sessions/ folder to workspaces/
once; a flat workspace named sessions stays.
FILE-52. watch=auto polls when the inbox's mount is nfs, nfs4, cifs, smb3, smbfs,
9p, ceph, glusterfs or a fuse* type (read from /proc/self/mountinfo), and uses events
otherwise, including where there is no /proc. Events do not see a file a network peer writes.
FILE-53. One collector per process (recordings/collector.py) files recordings. It runs only while a
recording is owed: its task starts with the first expectation and ends when none is owed. It wakes
on an inbox change and on a timer of 30 seconds, or recording.settle when that is shorter. It
owns no browser and takes no session lock.
FILE-54. The browser opening writes a note the moment the Grid makes it, marked discard; the
note is written again without the mark once the workspace holds the browser. A discard note's
video is deleted, not filed, when it arrives, which covers a browser that lost a race to bind or
whose open failed. The monitor reports the session's end to the collector (session.ended, any
cause, a reap included).
FILE-55. A note is workspaces/<name>/recordings/.pending/<gridId>.json holding opened and
ended in epoch milliseconds, browser, and, once done, filed or dropped. The notes are the
queue, so a restart rebuilds it. A note that is not JSON or names no valid Grid id is skipped with a
warning. A Grid id is 8 to 64 letters, digits and -, starting with a letter or digit.
FILE-62. A storage error reading a workspace's notes is a fault of that workspace, not a broken note. Every other workspace is read on, and only an unreadable data directory raises. The collector owes what it read, logs the rest once per streak and reads again each tick. Only bad JSON, a bad id or a non-file is skipped.
FILE-56. A sweep matches an .mp4 in the inbox whose path below it (folders and name) holds
an owed Grid id, however deep. A name ending .partial, .part or .tmp is skipped. A path
that holds more than one owed id matches none.
FILE-57. A recording is complete when its last 16 bytes are an mfro box whose size names an mfra box
inside the file. A complete file is filed once its size and modification time have held for
recording.settle seconds.
FILE-58. A file with no complete ending is filed as it is when its size and time have held for 60 seconds and its browser has ended. A live recording is never idle that long.
FILE-59. Filing moves the file into workspaces/<name>/recordings/ as rec-YYYYMMDD-HHMM.mp4 (UTC, from
the note's opened), under the first free name (FILE-9), in a worker thread. The note is marked,
then deleted; a note whose deletion fails is retried alone and never filed twice. Across
filesystems the move is a copy and an unlink. Filing nudges the admin broadcast.
FILE-60. A recording whose file has not arrived recording.wait seconds after its browser ended
is dropped: the note is deleted and one warning is logged naming the workspace and the time the
browser opened. Nothing is shown. A file that arrives later is not claimed. A discard note that
misses its deadline logs nothing.
FILE-61. The Recordings section lists filed videos only. There is no view of the inbox, the
notes, or a recording in progress. Recordings are video/mp4 and answer Range (FILE-39).
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network