mirror of
https://github.com/soarqin/DSP_Mods.git
synced 2026-11-19 17:05:20 +08:00
fix(livestreamassist): migrate WebSocket API to Kestrel
Replace Fleck with pinned in-process Kestrel packages and explicit runtime packaging. Fix connection lifetimes, deadlines, admission accounting, and reflection validation. Add production transport regressions and update the migration guidance with remaining Unity/LAN acceptance gates.
This commit is contained in:
1 parent
94254b8c28
commit
e95c832e03
20 files changed
+3098
-480
No files matched your search
@@ -1,8 +1,8 @@
|
||||
# LiveStreamAssist WebSocket API
|
||||
|
||||
Status: implemented contract for API `1.0.0`. Enable the listener with BepInEx setting `WebSocketApi.Enabled`. Real-game and LAN acceptance still need a DSP run; see the [design and implementation plan](WebSocketDesign.md).
|
||||
Status: API `1.0.0` compatibility contract. The in-tree transport is in-process ASP.NET Core 2.3 Kestrel; Unity/LAN acceptance is still pending. Enable the listener with BepInEx setting `WebSocketApi.Enabled`; see the [design and transport migration plan](WebSocketDesign.md).
|
||||
|
||||
Audience: developers of live-stream overlays, OBS integrations, and other clients. Server architecture and implementation tasks are documented separately in the [design and implementation plan](WebSocketDesign.md).
|
||||
Audience: developers of live-stream overlays, OBS integrations, and other clients. Server architecture and implementation tasks are documented separately in the [design and transport migration plan](WebSocketDesign.md).
|
||||
|
||||
## Connection
|
||||
|
||||
@@ -12,7 +12,7 @@ ws://<host>:18080/api/v1
|
||||
|
||||
The service supports local and LAN clients without authentication. No token, login request, or application-level handshake is required. The client sends requests after the WebSocket connection opens. Other URL paths are rejected and must not execute API requests.
|
||||
|
||||
The planned BepInEx configuration section is `WebSocketApi`:
|
||||
The BepInEx configuration section is `WebSocketApi`:
|
||||
|
||||
| Setting | Type | Default | Meaning |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -31,6 +31,18 @@ Suggested client sequence:
|
||||
|
||||
There are no subscriptions or unsolicited application messages. Normal WebSocket control frames, including ping/pong and close frames, are transport operations rather than application notifications.
|
||||
|
||||
## WebSocket interoperability
|
||||
|
||||
The required transport profile is [RFC 6455](https://www.rfc-editor.org/rfc/rfc6455) over HTTP/1.1 Upgrade, using WebSocket version `13`. It is intended to interoperate with current browsers, OBS browser sources, and standard WebSocket clients. The migration does not change the JSON-RPC contract or require a new client SDK.
|
||||
|
||||
- Client frames must be masked; server frames must not be masked. Invalid framing, reserved opcodes, and unnegotiated RSV bits are protocol errors (`1002`).
|
||||
- Fragmentation must preserve message boundaries and UTF-8 decoder state. Interleaved control frames do not restart or relax the complete-message byte limit.
|
||||
- Ping/pong and close handshakes follow RFC 6455. A pong responding to a ping carries the same payload. Invalid text or close-reason UTF-8 produces `1007`.
|
||||
- `permessage-deflate` and other extensions are not negotiated in v1. An extension offer can be declined while accepting an ordinary uncompressed WebSocket connection. HTTP/2 and HTTP/3 WebSocket transports are not advertised by this profile.
|
||||
- Invalid paths, invalid opening handshakes, and connection-capacity rejection may be rejected at the HTTP layer before upgrade. A client must not assume every unsuccessful connection produces a WebSocket close frame.
|
||||
|
||||
These are acceptance requirements for the transport. Passing desktop checks does not imply full conformance or Unity/LAN acceptance; see the linked implementation status.
|
||||
|
||||
## Message format
|
||||
|
||||
The API uses a restricted JSON-RPC 2.0 request/response format. It does not implement the full JSON-RPC feature set: batches and notification requests are deliberately rejected.
|
||||
@@ -123,7 +135,7 @@ These are the initial v1 defaults. `system.info.limits` is the authoritative sou
|
||||
| `maxRequestsPerFrame` | 8 | Maximum game-data requests started in one Unity frame. |
|
||||
| `mainThreadBudgetMs` | 2 | Soft main-thread scheduling budget per Unity frame. |
|
||||
|
||||
Outstanding requests include queued reads, executing reads, and responses waiting to be sent. System methods also consume outstanding-request capacity, but do not consume the game-data execution budget. A saturated server returns `SERVER_BUSY` when it can deliver an error without growing the send queue; otherwise it closes the connection with `1013`.
|
||||
Outstanding requests include queued reads, executing reads, and responses waiting to be sent, including an active send. System methods also consume outstanding-request capacity, but do not consume the game-data execution budget. A saturated server returns `SERVER_BUSY` when it can deliver an error within the bounded send queue; otherwise it attempts to close the connection with `1013`. A stalled or broken transport is aborted if a close frame cannot be delivered within the send deadline.
|
||||
|
||||
The main-thread budget does not preempt a running read. Deadlines are independent of game ticks and pause state. A timed-out request cannot later produce a success response. If a response cannot be delivered to a stalled client within the bounded send deadline, the connection closes instead of retaining output indefinitely.
|
||||
|
||||
@@ -486,10 +498,13 @@ Transport closure codes relevant to clients:
|
||||
| Code | Meaning |
|
||||
| --- | --- |
|
||||
| `1001` | Server is stopping. |
|
||||
| `1002` | WebSocket framing or protocol violation. |
|
||||
| `1003` | Binary application message is unsupported. |
|
||||
| `1007` | Invalid UTF-8 payload. |
|
||||
| `1008` | Protocol violation such as reuse of an outstanding ID. |
|
||||
| `1009` | Incoming message is too large. |
|
||||
| `1013` | Overload or inability to drain a bounded send queue. |
|
||||
|
||||
Reserved status values such as `1005`, `1006`, and `1015` are not sent in close frames. A client may locally report `1006` when a transport is lost or aborted without a completed close handshake.
|
||||
|
||||
Do not retry invalid paths unchanged in a tight loop. Game-state errors can be retried after discovery; overload and timeouts require client-side backoff. Reconnection creates a new request-ID namespace but does not restore any requests from the old connection.
|
||||
Reference in new issue
Block a user