Skip to content

site data

Dr K edited this page Nov 14, 2026 · 3 revisions

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.

Use cases

  • An agent signs in to two apps, calls save_site_data once, 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-data to see which sites are saved, never a value.

Neighbours

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.

What is stored

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_data that 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.

Saving

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:

  1. the whole cookie jar over BiDi storage.getCookies, httpOnly cookies included;
  2. the page's own origin, localStorage and sessionStorage, by a script in the page;
  3. the localStorage of every other http or https origin 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.

The spare tab

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.

Restoring

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.

History

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.

What an agent reads

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, uri and cookies;
  • storage per origin, with both stores' values;
  • own_cookies, the names Forget removes, and kept_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.

The admin routes

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.

Limits

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.

Clone this wiki locally