WebSockets

Any path takes a WebSocket. The first message is the handshake's reflection, as JSON, and every message after it is echoed back as it came, text or binary. Use it to see what a client sends when it connects, and to check that a proxy passes WebSockets through.

At a Glance

• Looking Glass running (see Getting Started).
• A WebSocket client: websocat, wscat, or a browser.

Connect

websocat 'ws://localhost:8080/live?room=1'

{
  "method": "GET",
  "uri": "/live?room=1",
  "headers": {
    "Connection": ["Upgrade"],
    "Sec-Websocket-Key": ["dGhlIHNhbXBsZSBub25jZQ=="],
    "Upgrade": ["websocket"],
    ...
  },
  ...
}
hello
hello

The reflection is always JSON, since a socket has no HTML view. From a page:

const ws = new WebSocket('ws://localhost:8080/live')
ws.onmessage = (e) => console.log(e.data)
ws.onopen = () => ws.send('hello')

Cookies

Browsers attach cookies to a WebSocket handshake from any page, and CORS doesn't apply to it. So when the page's Origin isn't Looking Glass's own host, the reflection leaves out Cookie, unless --cors-credentials is on (see Cross-Origin Requests). The connection itself is accepted from any origin.

Limits

• Message size: a message larger than --max-body closes the socket with 1009.
• Lifetime: a socket stays open at most --max-ws-duration (1m by default), then closes with 1001.
• Shutdown: every open socket is closed with 1001.

Status and Delay

glass-status with anything but 200 refuses the upgrade with that status, and the usual reflection as the body, so a client can test a failed connect. glass-delay waits before accepting. The browser can't set headers on a WebSocket, so use the query params:

new WebSocket('ws://localhost:8080/live?glass-status=503')

Next Steps

• Activity Log: the open and close lines.
• Status and Delay: every option they take.