release: bump version to 0.52.0

websocket_protocol.md

@@ -422,25 +422,72 @@ Same as `data_frame` with `update_type: "full"`
 
 ## Subscription Management
 
+The current backend accepts `type: "subscribe"` / `type: "unsubscribe"` messages. Older examples that use `type: "subscription"` describe the same intent but should not be used for new clients.
+
 ### Subscribe
 ```json
 {
-    "type": "subscription",
+    "type": "subscribe",
     "timestamp": "2024-01-20T10:30:00.000Z",
     "data": {
-        "action": "subscribe",
         "channels": ["gpu_clusters", "alerts"]
     }
 }
 ```
 
+### Vessel Viewport Subscribe
+
+The `vessels` channel is viewport-scoped. Clients must provide the current bbox, zoom, and limit. The server stores only this lightweight subscription filter and sends updates that match the subscribed bbox.
+
+```json
+{
+    "type": "subscribe",
+    "timestamp": "2026-05-12T10:30:00.000Z",
+    "data": {
+        "channel": "vessels",
+        "bbox": [120.8, 30.7, 122.1, 31.8],
+        "zoom": 12,
+        "limit": 1000
+    }
+}
+```
+
+`limit` is capped at 5000 per subscription, and each WebSocket data frame is capped to 1000 vessel updates. Collector updates are throttled to one flush per second; within a flush window, only the latest update per MMSI is retained.
+
+Vessel data frames use the normal `data_frame` envelope:
+
+```json
+{
+    "type": "data_frame",
+    "channel": "vessels",
+    "timestamp": "2026-05-12T10:30:01.000Z",
+    "payload": {
+        "action": "upsert",
+        "vessels": [
+            {
+                "mmsi": 257123000,
+                "lat": 59.91,
+                "lon": 10.73,
+                "sog": 12.4,
+                "cog": 214,
+                "received_at": "2026-05-12T10:30:00Z"
+            }
+        ],
+        "subscription": {
+            "bbox": [120.8, 30.7, 122.1, 31.8],
+            "zoom": 12,
+            "limit": 1000
+        }
+    }
+}
+```
+
 ### Unsubscribe
 ```json
 {
-    "type": "subscription",
+    "type": "unsubscribe",
     "timestamp": "2024-01-20T10:30:00.000Z",
     "data": {
-        "action": "unsubscribe",
         "channels": ["alerts"]
     }
 }