slighted / protocol.py
runitx's picture
docs: expand nekohash specification with binary framing, arcade rpc, and opcodes
3e3dca4 unverified
Raw History Blame Contribute Delete
10.2 kB
"""
WebSocket protocol for nekohash imageboard engine (awoo.cf).
Reverse-engineered from client bundles (app-AGKBSCUS.js, chunk-NRU3NIKF.js,
chunk-XX362ZFD.js, chunk-XMMHRB6S.js, chunk-JTTGKNWN.js, chunk-PVG4O4YS.js)
and network captures on November 16, 2026.
"""
import json
import struct
from enum import IntEnum
from dataclasses import dataclass
from typing import Any, Optional, Union
class MessageType(IntEnum):
"""
WebSocket message types (client-to-server and server-to-client).
Text messages: <2-digit-type><payload>
Binary messages: <8-byte float64 post_id><payload><1-byte type>
"""
# Post state & Keystroke streaming
ERROR = 0
INSERT_POST = 1
APPEND = 2 # Binary: [post_id (8B), utf-8 text, 0x02]
BACKSPACE = 3 # Binary: [post_id (8B), 0x03]
SPLICE = 4 # Binary: [post_id (8B), start (2B), len (2B), utf-8 text, 0x04]
CLOSE_POST = 5
INSERT_IMAGE = 6
SPOILER_IMAGE = 7
APPLY_MODERATION = 8
REMOVE_IMAGE = 9
REPLACE_IMAGE = 10
# Generative AI Streaming: Claude / LLM
CLAUDE_APPEND = 11 # Binary: Claude streamed text
CLAUDE_DONE = 12 # Binary
CLAUDE_ERROR = 13 # Binary
# Generative AI: Imagen (Text-to-Image)
IMAGEN_APPEND = 14 # Binary
IMAGEN_DONE = 15 # Binary
IMAGEN_ERROR = 16 # Binary
# Generative AI: Videogen
VIDEOGEN_APPEND = 17 # Binary
VIDEOGEN_DONE = 18 # Binary
VIDEOGEN_ERROR = 19 # Binary
# Generative AI: Editgen (Image Editing)
EDITGEN_APPEND = 20 # Binary
EDITGEN_DONE = 21 # Binary
EDITGEN_ERROR = 22 # Binary
# Generative AI: Imgtovid (Image-to-Video)
IMGTOVID_APPEND = 23 # Binary
IMGTOVID_DONE = 24 # Binary
IMGTOVID_ERROR = 25 # Binary
# Generative AI: Img2veo (Google Veo Video)
IMG2VEO_APPEND = 26 # Binary
IMG2VEO_DONE = 27 # Binary
IMG2VEO_ERROR = 28 # Binary
# Generative AI: Grok Video (xAI Grok)
GROKVID_APPEND = 29 # Binary
GROKVID_DONE = 30 # Binary
GROKVID_ERROR = 31 # Binary
GROKVID_APPEND_ALT = 32 # Binary
GROKVID_DONE_ALT = 33 # Binary
GROKVID_ERROR_ALT = 34 # Binary
# Embeds
TIKTOK_PENDING = 36 # TikTok embed state
# Session / Crypto / Control
FP_TOKEN_RECEIVE = 43 # Binary
SYNCHRONISE = 44 # Board / Thread state sync
POST_PASSWORD = 45 # Reclaim draft with password
RECEIVE_ID = 46 # Allocation post ID assignment
BATCH_EVENTS = 47 # Batched streaming events
NOOP_PING = 48 # Periodic keepalive ping
PRESENCE = 49 # Active site/thread/NekoTV viewer counts
SERVER_TIME = 50 # Millisecond server timestamp
REDIRECT = 51 # URL redirect command
NOTIFICATION = 52 # Browser notification trigger
CAPTCHA_TRIGGER = 53 # Trigger captcha challenge
NEKO_TV_SYNC = 54 # NekoTV shared watch-party sync
BOARD_CONFIG = 55 # Dynamic board feature flags (NSFW, games, webRTC)
SESSION_CONFIG = 56 # Captcha session and token updates
SESSION_KEY = 57 # 16-byte session key rotation (Binary)
SYNC_COUNT = 58 # Synced client counter
POLL_UPDATE = 59 # In-thread poll definition
POLL_VOTE = 60 # Poll vote cast/counts
THREAD_CREATED = 62 # New thread created broadcast
WEBRTC_SIGNAL = 63 # WebRTC peer discovery, SDP, and ICE signaling
# Generative AI: Venice Video (Venice AI)
VENICEVID_APPEND = 64 # Binary
VENICEVID_DONE = 65 # Binary
VENICEVID_ERROR = 66 # Binary
# Generative AI: Atlas Video (ByteDance Atlas)
ATLASVID_APPEND = 67 # Binary
ATLASVID_DONE = 68 # Binary
ATLASVID_ERROR = 69 # Binary
# Audio & 3D Assets
AUDIO_ALERT = 70 # Ding / audio notification
THREED_APPEND = 71 # Binary: Three.js 3D GLTF asset streaming
THREED_DONE = 72 # Binary
THREED_ERROR = 73 # Binary
# Reports, Reactions, Appeals, Edits
REPORT_EVENT = 74 # Meguca report event
REACTIONS = 75 # Post emoji reaction events
FP_TOKEN_DELIVERY = 76 # Post-handshake fingerprint token delivery
APPEAL_EVENT = 77 # Meguca appeal event
CLOSED_EDIT = 78 # Post editing after submission
# The Arcade & Extended Pipelines
ARCADE_EVENT = 80 # In-thread multiplayer games & clock updates
CLAUDE_THINKING = 81 # Binary: Claude / LLM internal reasoning stream
BYTEPLUSVID_APPEND = 82 # Binary: ByteDance BytePlus video streaming
BYTEPLUSVID_DONE = 83 # Binary
BYTEPLUSVID_ERROR = 84 # Binary
X_EMBED = 85 # Twitter / X embed card
@dataclass
class NekohashSyncRequest:
"""Nekohash synchronization payload (type 44)."""
board: str
thread: Optional[int] = None
protocolVersion: int = 1
loginData: Optional[dict] = None
seal: str = "noWASM"
fp: str = ""
meta_pass: str = ""
@dataclass
class BinaryStreamChunk:
"""Decoded binary stream chunk (keystroke append, AI streaming, etc.)."""
post_id: float
text: str
msg_type: MessageType
@dataclass
class SpliceEvent:
"""Decoded binary splice event (type 04)."""
post_id: float
start: int
length: int
text: str
@dataclass
class ArcadeAction:
"""Arcade client-to-server action (type 80)."""
t: str
id: Optional[str] = None
m: Optional[dict] = None
e: Optional[int] = None
def encode_message(msg_type: MessageType | int, payload: Any = None) -> str:
"""
Encode a text message for sending over WebSocket.
Format: "<2-digit-type><payload>" (or "<type>" if payload is None).
"""
type_val = msg_type.value if isinstance(msg_type, MessageType) else int(msg_type)
type_str = f"{type_val:02d}"
if payload is None:
return type_str
if isinstance(payload, str):
return type_str + payload
return type_str + json.dumps(payload, separators=(",", ":"))
def decode_binary_message(data: bytes | bytearray) -> tuple[int, Any]:
"""
Decode a binary message frame from WebSocket.
Structure:
- Last byte (len-1): opcode uint8
- Byte 0..7: post ID (double / float64 little-endian)
- Byte 8..len-2: payload
"""
if len(data) == 0:
raise ValueError("Empty binary frame")
opcode = data[-1]
# Type 3: BACKSPACE -> [post_id (8B), 0x03]
if opcode == MessageType.BACKSPACE:
if len(data) < 9:
return opcode, None
post_id = struct.unpack("<d", data[:8])[0]
return opcode, {"post_id": post_id}
# Type 4: SPLICE -> [post_id (8B), start (2B), len (2B), text, 0x04]
if opcode == MessageType.SPLICE:
if len(data) < 13:
return opcode, None
post_id = struct.unpack("<d", data[:8])[0]
start, splice_len = struct.unpack("<HH", data[8:12])
text = data[12:-1].decode("utf-8", errors="replace")
return opcode, SpliceEvent(post_id=post_id, start=start, length=splice_len, text=text)
# Standard Binary Stream: [post_id (8B), text (variable), opcode (1B)]
if len(data) >= 9:
post_id = struct.unpack("<d", data[:8])[0]
text_bytes = data[8:-1]
text = text_bytes.decode("utf-8", errors="replace")
try:
enum_type = MessageType(opcode)
except ValueError:
enum_type = opcode
return opcode, BinaryStreamChunk(post_id=post_id, text=text, msg_type=enum_type)
return opcode, data[:-1]
def decode_message(data: Union[str, bytes, bytearray]) -> tuple[int, Any]:
"""
Decode a message received from WebSocket (supports both text and binary frames).
Returns: (type_code, parsed_payload)
"""
if isinstance(data, (bytes, bytearray)):
return decode_binary_message(data)
if len(data) < 2:
raise ValueError(f"Message too short: {data}")
type_code = int(data[:2])
if len(data) == 2:
return type_code, None
payload_str = data[2:]
# Handle batched events (type 47)
if type_code == MessageType.BATCH_EVENTS:
try:
batch = json.loads(payload_str)
parsed_batch = []
for item in batch:
if isinstance(item, str):
parsed_batch.append(decode_message(item))
return type_code, parsed_batch
except json.JSONDecodeError:
return type_code, payload_str
try:
payload = json.loads(payload_str)
except json.JSONDecodeError:
payload = payload_str
return type_code, payload
def build_synchronise(board: str = "all", thread: Optional[int] = None, fp_token: str = "", meta_pass: str = "") -> str:
"""Build type 44 synchronise message."""
req = NekohashSyncRequest(
board=board,
thread=thread,
fp=fp_token,
meta_pass=meta_pass,
)
return encode_message(MessageType.SYNCHRONISE, req.__dict__)
def build_noop() -> str:
"""Build type 48 NOOP keepalive ping."""
return encode_message(MessageType.NOOP_PING)
def build_arcade_action(action: str, game_id: Optional[str] = None, move_data: Optional[dict] = None) -> str:
"""Build type 80 Arcade action message."""
payload = {"t": action}
if game_id:
payload["id"] = game_id
if move_data:
payload["m"] = move_data
return encode_message(MessageType.ARCADE_EVENT, payload)
def build_nekotv_sync() -> str:
"""Build type 54 NekoTV synchronization request."""
return encode_message(MessageType.NEKO_TV_SYNC, None)