Tham chiếu API

Mã hóa WebSocket

Đăng ký GraphQL dùng khung nhị phân đã mã hóa.

Máy khách
wss://<host>:<port>/graphql?cid=706c6169-3b80-8f42-9a61-4e312e54d001
Máy chủ

Gửi Init

initFrame

Máy chủ xác minh Init và đọc clientNonce.

Chống phát lại

Kết nối WebSocket…/graphql?cid=<clientId>
↓
Init / Ack mới cho mỗi kết nốibinding = SHA256(fields(initFrame, ackFrame))
↓
Bộ đếm độc lập cho mỗi chiềuclient → server: seq 1, 2, 3…server → client: seq 1, 2, 3…
↓
Xác thực và giải mãseq = lastReceived + 1
✓ ↓Chấp nhậnlastReceived ← seq
✕ ↓Từ chốiclose

Kết nối lại: binding mới, đặt lại bộ đếm

Di chuột hoặc chạm một trường
1 / 5

Các tuyến WebSocket khác

Máy khách
wss://<host>:<port>/screen?cid=<clientId>
Máy chủ

Init · clientNonce

Init

Máy chủ xác minh Init và đọc clientNonce.

XChaCha20-Poly1305 · Di chuột hoặc chạm một trường
1 / 5

Thao tác

websocket

1. Kết nối

Gửi Init sau khi socket mở. cid xác định máy khách.

typescript
const cid = '706c6169-3b80-8f42-9a61-4e312e54d001' // Your existing session's client ID
const socket = new WebSocket(
  'wss://<device-host>:<https-port>/graphql?cid=' + encodeURIComponent(cid)
)
socket.binaryType = 'arraybuffer'
let binding: Uint8Array
let lastSent = 0n
let lastReceived = 0n
protocol

2. Init máy khách

Gửi trong 10 giây. clientNonce: 32 byte ngẫu nhiên dạng 64 ký tự hex. nonce AEAD: 24 byte ngẫu nhiên cho mỗi khung.

typescript
// Run immediately on socket.open.
const init = {
  clientNonce: Array.from(randomBytes(32), n => n.toString(16).padStart(2, '0')).join(''),
}
const aad = fields([utf8.encode('WS_INIT'), utf8.encode('/graphql'), utf8.encode(cid)])
const initFrame = seal(key, utf8.encode(JSON.stringify(init)), aad)
socket.send(initFrame) // Retain these exact bytes for Ack.
protocol

3. Ack máy chủ

Xác minh Ack và tính binding, rồi gửi ngay xác nhận rỗng đã mã hóa tại sequence máy khách 1.

typescript
socket.addEventListener('message', event => {
  const ackFrame = new Uint8Array(event.data)
  if (ackFrame.length < 40) throw new Error('Invalid Ack')
  const aad = fields([utf8.encode('WS_ACK'), utf8.encode('/graphql'), utf8.encode(cid), sha256(initFrame)])
  const ack: { serverNonce: string } = JSON.parse(decoder.decode(open(key, ackFrame, aad)))
  if (!/^[0-9a-f]{64}$/.test(ack.serverNonce)) throw new Error('Invalid serverNonce')
  binding = sha256(fields([initFrame, ackFrame]))
  lastSent = lastReceived = 0n
  const counter = uint64be(1n)
  const confirmationAad = fields([utf8.encode('WS_FRAME'), utf8.encode('/graphql'), utf8.encode(cid), binding, utf8.encode('client'), counter])
  const encrypted = seal(key, new Uint8Array(), confirmationAad)
  lastSent = 1n
  socket.send(concatBytes(counter, encrypted))
}, { once: true })
protocol

4. Gửi thông điệp đã mã hóa

Dùng direction client và nonce mới. Xác nhận rỗng dùng sequence 1; nghiệp vụ bắt đầu tại sequence 2 và tăng nghiêm ngặt.

typescript
const message = {
  type: 'subscribe', id: 'prefs',
  payload: { query: 'subscription { prefsChanged }' },
}
const next = lastSent + 1n
const counter = uint64be(next) // Reject overflow; never wrap.
const aad = fields([utf8.encode('WS_FRAME'), utf8.encode('/graphql'), utf8.encode(cid), binding, utf8.encode('client'), counter])
const encrypted = seal(key, utf8.encode(JSON.stringify(message)), aad)
lastSent = next // Advance only after successful encryption.
socket.send(concatBytes(counter, encrypted))
protocol

5. Nhận thông điệp đã mã hóa

Yêu cầu lastReceived + 1 (đầu tiên: 1) và direction server. Chỉ tăng sau khi giải mã đã xác thực.

typescript
// For each binary message after Ack, in arrival order:
const frame = new Uint8Array(event.data)
if (frame.length < 48) throw new Error('Invalid frame')
const sequence = new DataView(frame.buffer).getBigUint64(0, false)
if (sequence !== lastReceived + 1n) throw new Error('Invalid sequence')
const aad = fields([utf8.encode('WS_FRAME'), utf8.encode('/graphql'), utf8.encode(cid), binding, utf8.encode('server'), frame.subarray(0, 8)])
const plaintext = open(key, frame.subarray(8), aad) // Throws on invalid tag.
lastReceived = sequence // Advance only after authentication.
const message = JSON.parse(decoder.decode(plaintext))
protocol

6. Loại thông điệp

Các thông điệp JSON của ứng dụng, kể cả ping/pong, được mã hóa. Khung điều khiển Ping/Pong gốc của WebSocket không được bọc trong lớp mã hóa này, nhưng TLS có thể bảo vệ chúng. subscriptionReady báo rằng đăng ký đã sẵn sàng.

typescript
const subscribe = {
  type: 'subscribe', id: 'prefs',
  payload: { query: 'subscription { prefsChanged }' },
}
const ready = {
  type: 'next', id: 'prefs',
  payload: { data: null, extensions: { subscriptionReady: true } },
}
const event = {
  type: 'next', id: 'prefs',
  payload: { data: { prefsChanged: true } },
}
const complete = { type: 'complete', id: 'prefs' }
const ping = { type: 'ping', payload: null }
const pong = { type: 'pong', payload: null }
const error = { type: 'error', id: 'prefs', payload: [{ message: '...' }] }
protocol

7. Giới hạn và lỗi

Đóng khi lỗi xác thực hoặc số thứ tự. Kết nối lại bằng lần bắt tay mới.

text
Server Init wait:     timeout(10 seconds, socket.next()), after upgrade and session-key lookup
Server confirmation:  timeout(10 seconds, socket.next()), after Ack send completes
Confirmation:         send encrypted empty payload immediately after Ack, client sequence 1
Business messages:    client starts at sequence 2; server starts at sequence 1
Init replay:          may receive a fresh Ack; old bound frames fail
Replay state:         connection counters, no timestamp or global cache
Message sequence:     last + 1, independently in each direction
Sequence overflow:    u64 max once; next frame fails, never wrap to 0
Frame size:           <= 1,048,576 bytes
Timeout/auth failure: close 1008, reason "invalid_subscription"
Reconnect:            fresh Init / Ack, new binding, last counters reset to 0; no legacy fallback