Repository navigation
grid
Every browser lives on a Selenium Grid, and this server reaches it over a small set of HTTP and WebSocket endpoints. This area is that contract as a rebuild needs it: which endpoint is called and why, how the socket addresses are derived, how the server binds to a browser it did not just create, what each timeout is, what each way the Grid can fail looks like, what the server assumes about the Grid's own settings, and what it leaves to the Grid for recording and files. The workspace's side of the same facts (the record, the reopen, the keep-alive's rules) is in workspaces-and-sessions.md.
- An engineer points a rebuilt server at a Grid and needs the list of endpoints it must answer.
- An operator puts the Grid behind a path prefix or a TLS ingress with credentials in its URL, and the BiDi and VNC sockets still connect.
- An operator sees
no Grid node took this browserand knows which Grid setting and which node class to look at. - An operator sets the node's session timeout and knows how long an idle browser lives and when the keep-alive pings it.
GRID-1. The record, grid_timeout, the reopen after a reap and its causes are in
workspaces-and-sessions.md (WS-15, WS-19 to WS-24), and so are the
keep-alive's window, interval and rules (WS-35 to WS-38). The capabilities an open sends, and
what a refused open says, are in session-settings.md (SET-27 to SET-43).
Downloads, the recording inbox and the collector are in workspace-files.md.
What the sockets carry is in capture.md and
live-view-and-control.md. Each failure's status and wording is in
errors-and-logging.md. grid.url and grid.console_url are in
config.md.
GRID-2. The server calls these endpoints, relative to grid.url, and no others. {id} is the
Grid's session id.
| Endpoint | Used for | Timeout | Retried once on a dropped connection |
|---|---|---|---|
POST /session (Selenium's remote driver) |
Creating a browser (GRID-7) | none of the server's own | no |
GET /session/{id}/url |
The liveness probe and the keep-alive ping (GRID-10, GRID-11) | 30 s probe, 5 s ping | yes |
DELETE /session/{id} |
Ending a browser; a 404 is done | 30 s | yes |
GET /status |
The listing, the idle timeout, readiness and the admin's browser list (GRID-12) | 30 s; 5 s for the idle timeout | yes; no for the idle timeout |
POST /graphql, query { grid { sessionCount } }
|
The browsers count of /ready
|
30 s | yes |
GET /session/{id}/se/files |
Listing a browser's downloads (GRID-18) | 30 s | yes |
POST /session/{id}/se/files, body {"name": <file>}
|
Reading one download | 30 s | yes |
DELETE /session/{id}/se/files |
Clearing a browser's downloads; a 404 is done | 30 s | yes |
WebSocket /session/{id}/se/bidi
|
Capture, site data, the monitor (GRID-5) | 5 s to open, 5 s per reply | no |
WebSocket /session/{id}/se/vnc
|
The live view (GRID-5) | 15 s for both handshakes | no |
Every WebDriver command of an action goes to the Grid through Selenium's remote driver under
/session/{id}/..., and is not listed here.
GRID-3. grid.url defaults to http://localhost:4444. It is trimmed of trailing slashes and
may carry a path prefix and userinfo. Every endpoint above is that URL followed by its path, so a
prefix is kept and the userinfo is sent as the URL has it. No message, log line or page shows the
userinfo: the address is shown without it (CFG-51) and a failure's text is stripped of it.
GRID-4. A request that dies because the pool's connection had already been closed by the Grid (a reset instead of a response) is sent again once, on a fresh connection. A refused, unresolvable or timed-out Grid is not sent again. A response with an error status is an answer, not a failure to send, and is never sent again.
GRID-5. The socket addresses are derived from grid.url and a session id, never read from the
session's webSocketUrl or se:vnc capabilities, which carry the Grid's own internal name.
http becomes ws and https becomes wss; the host, port, userinfo and path prefix are kept.
The BiDi address is <root>/session/{id}/se/bidi and the VNC address is
<root>/session/{id}/se/vnc, where <root> is the derived root without a trailing slash. The BiDi
channel needs the session opened with webSocketUrl: true (SET-28), and the VNC stream a node with
a display.
GRID-6. The server holds two connection pools to the Grid, each of 40 connections: one for the plain endpoints above, which keeps no cookies, and one for the WebDriver commands, shared by every bound driver (GRID-8).
Both set TCP keep-alive on their sockets, where the platform has each option: first probe after 30 s idle, then every 10 s, three missed, and unacknowledged data abandoned after 60 s. A connection to a hub that died with its node is then noticed instead of retransmitted for minutes. A long command is not cut short, because a live hub answers the probes while the browser works.
The sockets to the BiDi and VNC addresses are not pooled. Each is opened for its purpose, pinged every 20 s, and takes frames up to 16 MiB.
GRID-7. open_session creates a browser with Selenium's remote driver against grid.url,
sending exactly the capabilities session_caps.build made (SET-27) and nothing Selenium adds of
its own. The browser class of the options follows the browser asked for. No timeout of the
server's own is set, so the call waits as long as the Grid's new-session queue does (SET-36). The
Grid's session id is the driver's session_id.
GRID-8. The server binds to a running session without creating one: it builds a driver that
skips session negotiation, sets its session_id to the stored id and sends commands under
/session/{id}. Binding sends no request. The driver lives for one call and every driver shares
the one WebDriver connection pool. The options of a bound driver are never sent, so the same call
binds to a Chrome and a Firefox session.
GRID-9. The only source of the id a call binds to is the workspace's record (WS-12). No tool or route takes one (WS-6). The admin's browser list, which reads the Grid rather than the records, shows every running session the Grid reports, including ones this server did not open.
GRID-10. Grid.is_alive is GET /session/{id}/url with a 30 s timeout. A 200 is alive. Any
other answer is alive unless its JSON body has value.error equal to invalid session id: an open
dialog answers 500 unexpected alert open, and that browser is alive. A request that fails to
send or times out reads as alive, because a wrong alive costs the next call a real error and a
wrong gone abandons a browser and its slot. WS-19 uses it.
GRID-11. Grid.ping is the same request with a 5 s timeout, and it raises a failure to send
instead of reading it as alive, so the keep-alive can log it (WS-38). It is a WebDriver command, so
the node counts it as activity and resets the browser's idle timer. It is the only command the
server sends to a browser on a timer.
GRID-12. GET /status answers value.ready (a boolean) and value.nodes. Each node has
sessionTimeout in milliseconds and slots, and a slot with a browser has session.sessionId.
Grid.listing reduces it to the number of nodes and a map of every running session id to its
node's timeout in whole seconds, or None when the node gives none, a non-number or less than a
second. It touches no browser, which matters: a command sent to a session would count as activity
and keep it alive. The admin's browser list reads the same payload for each session's start,
capabilities.browserName, capabilities.browserVersion, capabilities["se:containerName"]
(else the node's id) and capabilities["se:vnc"].
GRID-13. /ready (SURF-34) is value.ready from GET /status and sessionCount from
POST /graphql. A Grid that is reachable and not ready answers 503 degraded.
GRID-14. A plain request waits 30 s unless it names a shorter timeout: the idle timeout asked
at each open and reopen (WS-15) and the keep-alive ping wait 5 s. The idle timeout is shown, never
needed, so it is not retried and its failure never fails an open. The WebDriver commands wait as
Selenium's client does, which the server does not change; the browser-side bounds
(session.page_load_timeout, session.script_timeout) are set per browser (SET-14).
GRID-15. How the Grid's failures surface to a caller:
| What happened | What the server sees | Reported as |
|---|---|---|
| The Grid is unreachable | A refused, unresolvable or timed-out connection | 503 |
| The Grid answers a plain endpoint with an error | 404 |
404 |
| another 4xx | 400 | |
| 5xx | 503 | |
| No node took a new browser |
SessionNotCreated with New session request timed out or Timed out creating session
|
NoNodeTook, 503 (SET-36, SET-37) |
| The Grid's router or queue failed |
SessionNotCreated with one of the five texts of SET-38 |
the plain 503, the Grid's words |
| A node refused a browser | any other SessionNotCreated
|
NodeRefused, 400 or 503 (SET-39, SET-40) |
| The browser was already gone at the call |
invalid session id from the probe |
a reopen (WS-19 to WS-22) |
| The browser vanished during a call |
invalid session id or no such driver |
404 |
| The node stopped answering during a call | the hub's text Unable to execute request for an existing session, or Chrome's session deleted because of page crash or tab crashed
|
NodeLost, 404 |
| A BiDi socket would not open, closed or went silent | a closed or silent socket |
BidiUnavailable or SocketClosed, 503 |
| A BiDi frame was larger than 16 MiB | close code 1009 | 503 (CAP-71 for a body) |
GRID-16. A node lost is judged from the failure's text and not from a probe, because the probe
right after a crash can still answer alive: the hub answers 500, not invalid session id. The
failure is replaced by a fixed sentence, because the hub's own text names the node's address and
the Grid's session id.
GRID-17. A held socket is a channel and not a sign of life. A BiDi socket stays open after its session is deleted or reaped, the hub still answers its pings, and a command sent on it is never answered. A command with no reply is therefore not a reason to call a session gone: only the listing says that (WS-32).
GRID-18. A browser's downloads are the Grid's store, enabled by the se:downloadsEnabled
capability the server always sends (SET-28). The listing answers value.files, each with name and
creationTime. The server hides scratch names (FILE-7) and sorts newest first. A read answers a zip
in value.contents, base64, from which the server takes the entry named like the file, else the
first. The store lives and dies with the session, and a 404 from any of the three endpoints means the
browser or the file is gone (FILE-38).
GRID-19. The Grid ends a browser that has received no command for its node's
sessionTimeout. The server assumes that a WebDriver command (the keep-alive's ping included) and
a BiDi frame are activity, which is why a held BiDi connection is closed at its deadline (WS-33),
and that GET /status and a WebSocket ping answered by the hub are not. The server reads the
timeout at each open and reopen (WS-15) and never sets it. A reaped browser's id stops appearing
in the listing, which announces session.ended with cause gone (WS-27, WS-32), and the next call
that names its workspace reopens one (WS-20).
GRID-20. The keep-alive (WS-35 to WS-38) is the only defence against the reaper. It pings
with Grid.ping (GRID-11), and the server runs no other cleanup (WS-57).
GRID-21. The server needs these of the Grid, and checks none of them at start:
-
GET /statusanswers the JSON shape of GRID-12, andPOST /graphqlanswers the session count. - A node honours
se:downloadsEnabled,webSocketUrland, when a browser is recorded,se:recordVideoandse:videoName. - The hub proxies
/session/{id}/se/bidiand, for the live view,/session/{id}/se/vnc, and a proxy or ingress in front of it forwards WebSockets. - A node's session timeout is long enough to survive a ping interval (GRID-20), at least a few minutes in practice.
- The new-session queue's timeout is the longest an open waits. Nothing in the server shortens it.
- A node with a display serves VNC, with the password in
live.password_filewhen it has one (LIVE-6). - One browser holds one slot, and the server holds at most one browser per workspace, so the Grid's slot count is the cap on concurrent workspaces with a browser.
A Grid that is down at start does not stop the server: nothing contacts it before the first call,
and /ready answers 503 until it answers.
GRID-22. Recording is the Grid's. The server asks for it with se:recordVideo: true, and
names the video with se:videoName (FILE-45). The recorder runs in the node image, and its
settings and where its files go are the operator's. The server never calls a recorder endpoint and
reads the video only from recording.dir (FILE-49).
GRID-23. A file the agent uploads (upload_file) travels through the same remote driver: the
server writes it to a temporary directory and hands the path to the file input, and Selenium sends
the bytes to the node and gives the input the node's path (FILE-21). A page's downloads reach the
server only through GRID-18, and only when keep_file asks for one.
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