Skip to content

[Docs] Document WebSocket route pattern grammar #492

Description

@Coldwings

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

  1. Users configuring WebSocket endpoints with path parameters.
  2. Users migrating HTTP route patterns to WebSocket routes.
  3. 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

  • I have searched existing issues to avoid duplicates
  • I have clearly described the problem and proposed solution
  • I have considered alternative approaches
  • I have provided usage examples
  • I have considered backward compatibility

Priority

  • Low: Just an idea, no rush

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions