Feature Description
Document the WebSocket route pattern grammar exposed by http::websocket::ws_router::websocket().
Problem Statement
The implementation treats WebSocket route patterns as a public router grammar matching the HTTP router:
:name captures one path component.
- A trailing
* matches the rest of the path.
- Other components are matched literally.
This contract is visible in include/elio/http/websocket_server.hpp, and regression coverage now exercises invalid non-terminal wildcard patterns. However, user-facing documentation such as wiki/WebSocket-SSE.md only shows router.websocket("/ws", ...) and does not explain the supported route grammar or the * placement rule. Users therefore have to inspect headers or tests to know which WebSocket patterns are valid.
Proposed Solution
Add a short WebSocket routing section to the user documentation, preferably in wiki/WebSocket-SSE.md, covering:
- Literal WebSocket routes such as
/ws.
- Parameter routes such as
/chat/:room.
- Tail wildcard routes such as
/assets/*.
- The rule that
* is valid only as the final path segment.
- The relationship with HTTP router pattern semantics.
API Design
No API change is required.
Usage Example
ws_router router;
router.websocket("/ws", echo_handler);
router.websocket("/chat/:room", room_handler);
router.websocket("/assets/*", asset_handler);
Alternatives Considered
Leaving the behavior documented only in header comments is possible, but this is a user-facing route grammar and belongs in the WebSocket guide.
Use Cases
- Users configuring WebSocket endpoints with path parameters.
- Users migrating HTTP route patterns to WebSocket routes.
- Users avoiding invalid wildcard placement before runtime registration.
Implementation Considerations
- Complexity: Low.
- Breaking Changes: No.
- Dependencies: None.
- Performance Impact: None.
Compatibility
- C++ Standard: No change.
- Platform: No change.
- Backward Compatibility: Documentation only.
Related Work
Related to the WebSocket wildcard validation fix in #490.
Additional Context
Static documentation audit finding; no build required.
Checklist
Priority
Feature Description
Document the WebSocket route pattern grammar exposed by
http::websocket::ws_router::websocket().Problem Statement
The implementation treats WebSocket route patterns as a public router grammar matching the HTTP router:
:namecaptures one path component.*matches the rest of the path.This contract is visible in
include/elio/http/websocket_server.hpp, and regression coverage now exercises invalid non-terminal wildcard patterns. However, user-facing documentation such aswiki/WebSocket-SSE.mdonly showsrouter.websocket("/ws", ...)and does not explain the supported route grammar or the*placement rule. Users therefore have to inspect headers or tests to know which WebSocket patterns are valid.Proposed Solution
Add a short WebSocket routing section to the user documentation, preferably in
wiki/WebSocket-SSE.md, covering:/ws./chat/:room./assets/*.*is valid only as the final path segment.API Design
No API change is required.
Usage Example
Alternatives Considered
Leaving the behavior documented only in header comments is possible, but this is a user-facing route grammar and belongs in the WebSocket guide.
Use Cases
Implementation Considerations
Compatibility
Related Work
Related to the WebSocket wildcard validation fix in #490.
Additional Context
Static documentation audit finding; no build required.
Checklist
Priority