control_url, repeat the handshake, and carry on. The Python SDK does
this for you: when the socket drops, the next call (and any call cut off by the
drop) reopens it, backing off for about 15 seconds, and re-sends with the
call’s idempotency key. It stops on a 403, the session having ended. Scripts
(evaluate) are keyed only when you pass a key, so a keyless script cut off by
a drop runs again. A call cut off by a stalled connection rather than a closed
one fails with a timeout and is not re-sent; the next call redials once the
socket’s keepalive has closed it. Each re-send gets the call’s full timeout.
Classify the close
Reconnect and watch the HTTP status of the upgrade:| Status | Meaning | Do |
|---|---|---|
| 101 | Connected. | Handshake and carry on. |
| 401 | The token is bad or expired. | Get a fresh control_url. |
| 403 | The session is no longer active. | Stop: it has ended. |
Resume with a cursor
By default a new socket starts at the live tail of the stream: replies to commands sent before the drop are lost. To get them, opt in to checkpoints:- Attach with
&resume=1. The session then sends aHalyard.cursornotification after each batch of frames:{ "method": "Halyard.cursor", "params": { "cursor": "..." } }. - Keep the latest cursor. It is opaque: never parse it.
- After a drop, reattach with
&resume=1&cursor=<latest>. Delivery restarts strictly after that checkpoint, so frames after it are delivered again. Match replies byidand ignore ones you’ve already handled.
Halyard.resyncRequired instead: some frames are gone,
so re-read the state you need (Page.getInfo, Target.getTargets).
Idempotency keys
A command that changes the page and was in flight when the socket dropped may or may not have run. Mutating commands take anidempotencyKey: the session
remembers each key’s response, and a repeated key returns the recorded response
(with the new id) without acting again.
Keyboard, Pointer (except move), the Locator actions,
evaluate and dispatchEvent, the navigating Page methods and setContent, and
Target create, close and activate. Reads, waits, hovers and scrolls into view
take no key: they are safe to repeat.