Skip to content
Dr K edited this page Nov 14, 2026 · 2 revisions

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.

Use cases

  • 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 browser and 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.

Neighbours

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.

The endpoints

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.

Creating a session and binding to one

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.

Probing a session

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.

Status and the node listing

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.

Timeouts

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).

What a failed call looks like

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).

Downloads

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).

The idle reaper

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).

What the server assumes about the Grid

GRID-21. The server needs these of the Grid, and checks none of them at start:

  • GET /status answers the JSON shape of GRID-12, and POST /graphql answers the session count.
  • A node honours se:downloadsEnabled, webSocketUrl and, when a browser is recorded, se:recordVideo and se:videoName.
  • The hub proxies /session/{id}/se/bidi and, 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_file when 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.

Recording and file transfer

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.

Clone this wiki locally