Repository navigation
site data
A workspace outlives its browsers, so a browser that replaces one would come back signed out. This area keeps what a browser needs to be signed in again (cookies, localStorage, sessionStorage), puts it back before a new browser's first page, and keeps the history of the pages the workspace has reached, which decides whose storage a save reads. It also covers the spare tab, the hidden tab that stands on any origin so another site's storage can be read and written, and the admin routes that read and clear both.
- An agent signs in to two apps, calls
save_site_dataonce, and every browser the workspace opens after that, including the one that replaces a reaped browser, is signed in to both. - An agent starts as a new user with
open_session(restore_site_data=false). - An admin sees where a workspace has been and what is saved for each site, forgets one site, or clears the snapshot or the history, without touching the live browser.
- An agent reads
workspace://site-datato see which sites are saved, never a value.
SITE-1. The record, its store, its expiry and the reopen itself are in workspaces-and-sessions.md. The scrub of a result or a resource is in secrets-and-scope.md. The BiDi client is in the architecture page of Specification.md. How the Site data and History tabs draw is in admin-ui.md; this file holds the routes behind them.
SITE-2. A workspace's record has two fields for this area: history and site_data. They live
in the workspace store (memory or Redis) and nowhere else, so they are never on this server's disk,
and they expire with the record, workspace.ttl seconds after its last use.
SITE-3. Ending a browser keeps both fields, whether the end is end_browser, the admin's End or
the Grid's reaper. Binding a new browser keeps both, except that a declined restore empties
site_data (SITE-33).
SITE-4. A record read from a store whose history or site_data is malformed does not fail.
- A history entry is dropped unless it has a string origin, a string URL that has an origin, and a numeric time. A record with no history reads as one that has been nowhere.
- A
site_datathat is not an object reads as empty. - Inside a snapshot, a cookie without a string name and domain, and an origins or session entry of the wrong shape, count as nothing in every view.
SITE-5. A snapshot has the keys cookies, origins, session and saved_at. A cookie is
name, value, value_type, domain, path, http_only, secure, same_site and expiry
(null for a session cookie). origins maps an origin, spelt as location.origin spells it, to
{"local": {...}}. session is {"origin", "items"}, or {}. saved_at is epoch seconds.
SITE-6. The snapshot holds the whole cookie jar, localStorage per origin, and the sessionStorage of one tab. IndexedDB, caches and service workers are not saved.
SITE-7. A site is a host. Cookies carry a domain and no scheme or port, so every view groups by host. Storage stays per origin: one host on two ports is two origins, each restored with its own.
SITE-8. A snapshot is at most 1,000,000 bytes of JSON. Past it, the save leaves out the origins visited
longest ago first, then the page's own localStorage, then the page's sessionStorage, and names each
in skipped with the reason left out: the snapshot would pass 1000000 bytes. A jar that passes
the cap alone is a ValueError (a 400), and nothing is saved.
SITE-9. No value is logged. The server holds Selenium's wire loggers at INFO or above whatever
log_level is, because a BiDi frame carries cookie values.
SITE-10. save_site_data(url=None) is a tool and POST /browser/save-site-data, one row of the
capability table, and a flow step. It runs through the recipe like any action, so url navigates
first. It is not read-only, not destructive and idempotent.
SITE-11. A save reads, through site_data.transfer.capture:
- the whole cookie jar over BiDi
storage.getCookies, httpOnly cookies included; - the page's own origin, localStorage and sessionStorage, by a script in the page;
- the localStorage of every other
httporhttpsorigin in the workspace's history, in the spare tab, one origin at a time.
SITE-12. The history a save reads is as the next write would keep it, pruned first, so an origin that has aged out is not read.
SITE-13. A save replaces the snapshot whole. Nothing is merged, so a save after a sign-out is the signed-out state. The one thing carried over is the last storage of an origin the save could not read.
SITE-14. origins lists the page's origin first, then the history newest first, then any
other origin read. An origin whose localStorage is empty is left out. The page's sessionStorage is
kept under its own origin; a page with no origin (about:blank, data:) saves cookies and the
other origins and an empty session.
SITE-15. An origin that cannot be read is named in skipped as {site, reason} and keeps its storage
from the previous snapshot.
- When the spare tab cannot be created, every origin left unread is named with that failure's text.
- An origin whose service worker answered the spare tab is named with the reason
a service worker answered: save while on this site. A save made while on that site reads its storage directly.
SITE-16. The result is the page fields plus saved and uri. saved is {cookies, sites, skipped}: the cookie count, the origins whose storage was read and kept (the page's origin
included when it has sessionStorage), and the origins not read this time. uri is
workspace://site-data. No value is in the result.
SITE-17. The capture travels back from the action under a private key that is removed before the store is asked anything, so a failing store cannot leave it in what the caller gets.
SITE-18. A save is written only by the browser that captured it. When the record names another
browser by then, nothing is stored and skipped says another session took over this workspace before the save landed: nothing was saved. A record that expired before the write is not claimed.
SITE-19. A BiDi channel that does not answer, or a browser that refuses the cookie read, is
BidiUnavailable, a 503, and nothing is saved. Any other failure in the read stays a 500.
SITE-20. In a flow, a save_site_data step first has the run write the pages reached so far into the
history, in order and in one write, so the save reads their storage; the end of the run writes only
what came after. That flush neither hints flows_here nor hands over a held reopen notice.
SITE-21. See CAP-18: while a save runs with capture on, the spare tab is hidden from capture for its whole life.
SITE-22. The spare tab is a background tab opened with browsingContext.create. An intercept on
network.beforeRequestSent, scoped to that tab, matches only the path /__selenium-flow-spare__
on any origin, and every blocked request is answered with a 200 HTML page holding the marker
<meta name="selenium-flow-spare">. The listener starts after the intercept exists.
SITE-23. It yields run(origin, expression), which navigates the tab to that path on origin,
so the site never loads, and evaluates expression there, awaiting a promise, and returns its
JSON value.
SITE-24. The expression runs only when the page carries the marker and location.origin
equals the origin asked for, a test made in the page before the expression. A page without the
marker is a service worker's answer: ServiceWorkerAnswered, and nothing is read or written.
A tab on another origin than asked is a RuntimeError. A script that throws raises its text.
SITE-25. On every way out, the intercept is removed and the tab is closed, each step tried even when an earlier one failed, and a failed removal never raises.
SITE-26. Given a context, the spare tab intercepts that existing tab and leaves it open: the main tab,
for its sessionStorage. Given hidden and no context, the new tab's whole life is spent hidden
from capture.
SITE-27. Each BiDi command waits at most five seconds. There is no total budget across origins, so a systematic failure costs five seconds per origin.
SITE-28. open_session takes restore_site_data, true by default, over MCP and in the HTTP body. The
string "false" counts as false. A snapshot is restored when it holds a cookie, an origin or
sessionStorage items.
SITE-29. A restore completes before the browser goes to its page, in this order: every cookie, each
origin's localStorage through the spare tab, then the saved sessionStorage in the main tab, which
then returns to about:blank. The browser is fully restored when open_session returns.
SITE-30. A cookie that has expired is not set; a cookie with no expiry is. A cookie is sent to
BiDi without its unset fields, and a same_site of none without secure goes as lax, because
Chrome refuses it otherwise. A cookie-only snapshot opens no tab.
SITE-31. A restore is best effort and nothing in it fails an open. Each item that did not come back is a
skipped entry with a reason:
- a stored cookie with no name or domain, or a bad expiry;
- a cookie the browser refused or did not keep, checked by reading the jar back;
- an origin whose storage could not be written, and the sessionStorage;
- a BiDi channel that will not open.
A service worker's answer is reported as in SITE-15.
SITE-32. The open result carries site_data: {restored, skipped, uri} only when restored or
skipped is not empty. restored lists the hosts of the cookies the browser kept and the origins
filled. The report is scrubbed with the rest of the open result.
SITE-33. restore_site_data=false opens a browser with nothing restored and empties the snapshot, in the
same write that binds the new browser, so a failed open erases nothing and an open that loses a
race erases nothing. The history stays.
The result says site_data: {"forgotten": n}, n the number of hosts, only when something
restorable was there to forget. It does so with insecure=true too.
SITE-34. insecure=true restores nothing and deletes nothing. It reports one skipped entry,
an insecure browser gets no saved site data.
SITE-35. fresh=true drops only the remembered page. The snapshot and the history stay.
SITE-36. An open with no url and a restore that ran leaves the browser on about:blank, set
through the classic driver when BiDi did not leave it there, before capture is told the browser is
ready.
SITE-37. A browser that replaces a reaped or lost one is restored from the snapshot the same way, and goes to the top of the history (SITE-46).
SITE-38. The first result from that new browser carries reopened and, when the restore said
something, site_data, once. A failing first call carries the notice as a note on its error, ending
Saved site data was put back for N site(s). when N is not zero. A flow run carries them on the
run, never on a step.
SITE-39. history is a list of {origin, url, at}, one per origin, newest first.
SITE-40. A call that leaves the browser on a page with an origin moves that origin to the top with the URL and the time. A URL that is withheld, and a page with no origin, record nothing, though the call still slides the record's expiry. A browser's open records the page it landed on.
SITE-41. A result from a browser the record does not name records no page.
SITE-42. A flow run records, in one write at its end, each successful step's URL that its report shows and then the run's own URL, in order, except the run's URL when redaction touched it. A failed step records nothing.
SITE-43. Writing prunes. Every entry below the top that is older than workspace.ttl goes, the
top entry never goes, and at most 100 entries stay, the oldest dropped first.
SITE-44. Only the top entry keeps its whole URL. Below it a URL is its origin, path and hash
route, never the route's query. A route containing = is dropped as an anchor is.
SITE-45. Clearing site data does not touch the history, and clearing the history does not touch site data.
SITE-46. The current page is the top entry's URL, or empty. A reopen and an open_session with no url
go there.
SITE-47. workspace://site-data and GET /site-data answer {sites, saved_at, uri}: one entry
per host, {site, uri, cookies, storage}, with counts only (storage holds, per origin,
local_storage and session_storage as counts). With no record the listing is empty. Reading it
never opens a browser.
SITE-48. A host has a row when it has storage, or when a cookie names it. A cookie domain makes
no row of its own when it is a stored host, .host of a stored host, or a dotted parent of one.
Rows are the hosts in the history first, newest first, then the rest alphabetically.
SITE-49. A cookie is listed under its own domain. A parent's leading-dot cookie is listed under
every row it covers, marked shared, and belongs to none of them.
SITE-50. workspace://site-data/{site} and GET /site-data/{site} answer one host in full:
-
site,uriandcookies; -
storageper origin, with both stores' values; -
own_cookies, the names Forget removes, andkept_shared, the{name, domain, path}of the cookies Forget keeps.
A cookie has name, value, domain, path, expiry, http_only, secure, same_site and
shared. An httpOnly cookie's value is ••• on every surface, and no other value is hidden by
this area. A host with nothing saved is a ValueError naming the listing, a 400.
SITE-51. The two reads go through the scrub as every resource does (SEC-58). The history is not on the agent surface.
SITE-52. workspace://current carries site_data: {sites, uri} only when the snapshot holds
at least one host.
These are in http/admin/site_data.py, behind the admin sign-in (AUTH). Each reads or rewrites the
workspace's record and never touches a browser. A route that changes the record is marked to refresh
the admin's workspace list.
SITE-53. GET /admin/workspaces/{key}/history answers {key, sites, clears}. sites has one row per
host the workspace landed on, the current host first, each {site, url, at, saved, secrets}:
- the host's latest URL and time;
-
saved, the{cookies, local, session}counts of the snapshot for it, or null; -
secrets, those allowed there, as{name, description, keys}.
With no record all lists are empty.
SITE-54. A secret joins a history row and never makes one: a host never reached is not listed whatever a secret allows. A secret whose leash was rejected, or that was refused, is allowed nowhere and is not listed.
SITE-55. clears is the origin of every history entry below the top, so a second port of the
current host, which is no row of its own, still says there is something to clear.
SITE-56. DELETE /admin/workspaces/{key}/history keeps only the top entry and answers
{cleared}: the hosts of the history except the first. Site data and the live browser are
untouched.
SITE-57. GET /admin/workspaces/{key}/site-data answers the listing of SITE-47 with the
hosts in the history first, plus key and details, a map from host to the full view of SITE-50.
It holds no secrets.
SITE-58. DELETE /admin/workspaces/{key}/site-data empties the snapshot and answers
{cleared}, the hosts it listed. The history and the live browser are untouched.
SITE-59. DELETE /admin/workspaces/{key}/site-data/{site} forgets one host, lower-cased: its storage,
its sessionStorage when its origin is that host's, and the cookies whose domain is the host or
.host. A parent's cookie stays, and so does saved_at, because a forget is not a save. It
answers {forgotten: {site, cookies, origins, kept_shared}}. A host with nothing to remove is a
404, a host that only a parent's cookie covers included.
SITE-60. Forget and the two clears rewrite the record as it is when the write lands, so a save or an open that lands meanwhile is kept. The live browser keeps what it holds, only the next browser comes back without it, and a save made after saves it again.
SITE-61. Each workspace row of the admin list carries site_data_count (hosts),
site_data_rev (the JSON of [saved_at, hosts]), history_count (hosts) and history_rev (the
JSON of every entry's [origin, url] in order, with no times). A save moves saved_at, a forget or
clear moves the hosts, and the clock alone moves nothing.
SITE-62. sessionStorage is saved for the tab the browser was on and its origin only.
SITE-63. A site passed through inside one call is not in the history and so is not read. A site
last visited longer ago than workspace.ttl, or past the newest 100, loses its storage at the next
save, and its cookies stay.
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