1  # Protocol Notes
 2  
 3  ## Frame principles
 4  
 5  The protocol must be:
 6  
 7  - versioned
 8  - explicit
 9  - replay-aware
10  - debuggable
11  - transport-neutral
12  - tolerant of reconnects
13  - strict about client-originated events
14  
15  ## Frame classes
16  
17  ### Handshake
18  
19  Client and server negotiate protocol version and capabilities.
20  
21  ### Event
22  
23  Client sends a user event to the server. The server must validate target, event name, and payload.
24  
25  ### Diff
26  
27  Server sends a patch or render update to the client.
28  
29  ### Ack
30  
31  Client acknowledges the latest applied patch.
32  
33  ### Error
34  
35  Either side reports a protocol-level error. Application-level errors should normally render through the component model instead of leaking raw errors to the protocol.
36  
37  ## Versioning
38  
39  Protocol version is separate from package version.
40  
41  Rules:
42  
43  - Backward-compatible additions can remain in the same major protocol version.
44  - Removing or changing a frame field requires a new protocol major version.
45  - Clients must reject unsupported major versions.
46  - Servers may support multiple protocol major versions through adapters.
47  
48  ## Security
49  
50  The protocol must assume that every client frame is hostile.
51  
52  Minimum requirements:
53  
54  - CSRF/session binding
55  - origin checks where transport supports it
56  - event target validation
57  - payload size limits
58  - patch reference validation
59  - rate limiting hooks
60  - reconnect throttling