WebSocket 压缩（zstd）

Beta —— 按区域逐步推出。 zstd 正在逐步启用。如果某个网关禁用了 zstd，receiveType: "zstd" 或 "zstd-dict" 的连接会被优雅地降级为 JSON —— 服务器会在 login_ok.receiveType 中告知协商后的模式。请始终信任该回显来选择解码器；切勿假设您请求的模式即为生效模式。

两种模式

两种模式都用 zstd 压缩每个数据帧；控制帧保持 JSON 文本。请根据您愿意承担的客户端工作量来选择：

`receiveType`	`odds` 上的压缩比	客户端工作量	`dict` 帧
`"zstd"`	约 5–6×	一行代码： `zstd.decompress(frame)` → JSON	无
`"zstd-dict"`	约 7–9×	缓存服务器推送的字典，按每帧内嵌的 `dictId` 解码	连接时发送

从 "zstd" 开始。 它完全不需要处理字典 —— 解压并解析即可。当您想要额外约 30–40% 的压缩收益、并能维护一个小型内存字典存储时，再迁移到 "zstd-dict"。

有意不提供压缩版 MessagePack 模式 —— 在任何层面上，压缩 JSON 都优于压缩 MessagePack。

模式 1 —— `zstd`（无字典）

平滑接入路径。每个数据帧都是独立的、无字典的 zstd 帧（dictId = 0）；服务器不会发送 dict 控制帧。您的客户端只需解压并解析。

解码

on text frame   → JSON.parse → control (login_ok, error, …)
on binary frame → JSON.parse(zstd.decompress(frame))   // no dictionary needed
                  route by msg.channel

这就是此模式的全部协议。

模式 2 —— `zstd-dict`（训练字典）

最大压缩比路径。odds、fixtures 和 bookmakers 拥有约 32 KB 的训练字典，可将压缩比提升至约 7–9×。服务器在连接时以控制帧形式下发字典；每个数据帧内嵌了压缩时使用的 dictId，因此解码是自描述的，永远不需要按频道分支。

字典下发（服务器 → 客户端）

在 login_ok 之后（且在任何数据帧之前），对于每个拥有训练字典的已订阅频道，服务器推送一个控制帧：

{
  "type": "dict",
  "channel": "odds",
  "dictVersion": "odds-v1",
  "dictId": 740826216,
  "encoding": "base64",
  "data": "<base64 of the ~32 KB zstd dictionary>"
}

将 data 进行 Base64 解码，得到原始字典字节。
用它构建可复用的 zstd 解码器，并以 dictId 为键存储。

解码由每个数据帧内嵌的 dictId 驱动，而不是由频道驱动。dict 帧上的 channel/dictVersion 字段仅供参考。

字典很小（约 32 KB），并且会在每次连接时重新发送 —— 无需维护客户端版本缓存，登录时也无需发送 dicts 字段。没有训练字典的频道（例如 scores、clocks）不发送 dict 帧；其数据帧携带 dictId = 0，以无字典方式解码。

解码

on text frame   → JSON.parse → control (login_ok, dict, error, …)
on binary frame → id   = zstd.getDictID(frame)        // 0 ⇒ no dict
                  dict = store[id]                     // undefined ⇒ dictless
                  msg  = JSON.parse(zstd.decompress(frame, dict))
                  route by msg.channel

帧规则（两种模式通用）

每个数据帧都是一个 WebSocket Binary 帧，包含一个独立的 zstd 帧（魔数 28 B5 2F FD，内嵌 dictId）。
控制帧（login_ok、dict、error、snapshot_required、resume_complete）保持为 JSON 文本帧，即使在 zstd 连接上也是如此。规则是固定的：

文本帧 → 控制（JSON）。二进制帧 → 数据（zstd）。

login_ok.receiveType 是协商后的模式（"zstd"、"zstd-dict"，或 —— 若网关禁用了 zstd —— "json"）。如果返回 "json"，请按纯 JSON 文本帧解码；不要尝试解压。

🐍 Python 示例

需要 pip install zstandard。

zstd (dictless)
zstd-dict (dictionaries)

import asyncio, json, websockets
import zstandard as zstd

WS_URL, API_KEY = "wss://v5.oddspapi.io/ws", "YOUR_API_KEY"
dctx = zstd.ZstdDecompressor()
MAX_OUT = 64 * 1024 * 1024  # frames carry no content size — pass an upper bound

async def main():
    async with websockets.connect(WS_URL, max_size=4194304) as ws:
        await ws.send(json.dumps({
            "type": "login", "apiKey": API_KEY,
            "channels": ["odds", "fixtures"], "receiveType": "zstd",
        }))
        async for raw in ws:
            if isinstance(raw, str):                       # control (JSON)
                msg = json.loads(raw)
                if msg.get("type") == "login_ok" and msg.get("receiveType") != "zstd":
                    print("zstd disabled here, negotiated:", msg.get("receiveType"))
                continue
            data = json.loads(dctx.decompress(raw, max_output_size=MAX_OUT))
            print("DATA:", data.get("channel"), data.get("entryId"))

asyncio.run(main())

import asyncio, json, base64, websockets
import zstandard as zstd

WS_URL, API_KEY = "wss://v5.oddspapi.io/ws", "YOUR_API_KEY"
decoders: dict[int, zstd.ZstdDecompressor] = {}   # dictId -> decoder
dictless = zstd.ZstdDecompressor()
MAX_OUT = 64 * 1024 * 1024

def decode_frame(frame: bytes) -> dict:
    dict_id = zstd.get_frame_parameters(frame).dict_id  # 0 if no dictionary
    dctx = decoders.get(dict_id, dictless)
    return json.loads(dctx.decompress(frame, max_output_size=MAX_OUT))

async def main():
    async with websockets.connect(WS_URL, max_size=4194304) as ws:
        await ws.send(json.dumps({
            "type": "login", "apiKey": API_KEY,
            "channels": ["odds", "fixtures"], "receiveType": "zstd-dict",
        }))
        async for raw in ws:
            if isinstance(raw, str):                       # control (JSON)
                msg = json.loads(raw)
                t = msg.get("type")
                if t == "login_ok" and msg.get("receiveType") != "zstd-dict":
                    print("downgraded, negotiated:", msg.get("receiveType"))
                elif t == "dict":
                    d = zstd.ZstdCompressionDict(base64.b64decode(msg["data"]))
                    decoders[msg["dictId"]] = zstd.ZstdDecompressor(dict_data=d)
                continue
            data = decode_frame(raw)                        # data (zstd)
            print("DATA:", data.get("channel"), data.get("entryId"))

asyncio.run(main())

另请参阅

认证与过滤器 —— 完整的 login 字段参考
恢复和重放 —— 重新连接并恢复丢失的数据
故障排除 —— zstd 解码问题

​两种模式

​模式 1 —— zstd（无字典）

​登录

​解码

​模式 2 —— zstd-dict（训练字典）

​登录

​字典下发（服务器 → 客户端）

​解码

​帧规则（两种模式通用）

​🐍 Python 示例

​另请参阅

两种模式

模式 1 —— `zstd`（无字典）

登录

解码

模式 2 —— `zstd-dict`（训练字典）

登录

字典下发（服务器 → 客户端）

解码

帧规则（两种模式通用）

🐍 Python 示例

另请参阅