The Apinizer WebSocket proxy employs a flexible path mapping system for routing incoming WebSocket connection requests to backend servers. This system provides a wide range of configuration options, from simple routings to complex dynamic paths.

Supported Matching Types

1. Exact Match

The simplest and most direct matching type where the incoming request path must exactly match the defined path.

Format:

  • Relative Path: /fixed/path
  • Routing Template: /backend/path

Properties:

  • Case insensitive
  • Trailing "/" is optional
  • Query parameters are preserved

Examples:

Example 1:
Relative Path: /websocket/chat
Routing Template: /ws/chat
─────────────────────────────
Request: ws://host/websocket/chat        →  ws://backend/ws/chat
Request: ws://host/websocket/chat/       →  ws://backend/ws/chat
Request: ws://host/websocket/chat?id=123 →  ws://backend/ws/chat?id=123

Example 2:
Relative Path: /live/feed
Routing Template: /streaming/feed
─────────────────────────────
Request: ws://host/live/feed      →  ws://backend/streaming/feed
Request: ws://host/LIVE/FEED      →  ws://backend/streaming/feed  (case insensitive)
CODE

2. Wildcard End

Allows the path to be dynamic after a certain fixed prefix. Paths ending with wildcard (/*) fall into this category.

Format:

  • Relative Path: /fixed/part/*
  • Routing Template: /backend/path

Properties:

  • All path segments after wildcard are preserved
  • Supports subdirectories
  • Query parameters are preserved

Examples:


Example 1:
Relative Path: /ws/rooms/*
Routing Template: /chat/rooms
─────────────────────────────
Request: ws://host/ws/rooms/123          →  ws://backend/chat/rooms/123
Request: ws://host/ws/rooms/abc/user/456 →  ws://backend/chat/rooms/abc/user/456
Request: ws://host/ws/rooms/             →  ws://backend/chat/rooms/

Example 2:
Relative Path: /stream/*
Routing Template: /video/live
─────────────────────────────
Request: ws://host/stream/hd        →  ws://backend/video/live/hd
Request: ws://host/stream/sd/mobile →  ws://backend/video/live/sd/mobile
CODE


3. General Wildcard

Allows wildcard (*) usage at any position in the path. This is the most flexible matching type.

Format:

  • Relative Path: /path*/suffix or */path or /middle*/part
  • Routing Template: /backend/* or */backend or /middle*/end

Properties:

  • Wildcard can be placed anywhere in the path
  • Multiple wildcards are supported
  • Matched wildcard content is used in the same order in backend path

Examples:

Example 1:
Relative Path: /ws/*/chat
Routing Template: /backend/*/messaging
─────────────────────────────
Request: ws://host/ws/room1/chat  →  ws://backend/backend/room1/messaging
Request: ws://host/ws/user5/chat  →  ws://backend/backend/user5/messaging

Example 2:
Relative Path: */socket
Routing Template: */ws
─────────────────────────────
Request: ws://host/app1/socket  →  ws://backend/app1/ws
Request: ws://host/chat/socket  →  ws://backend/chat/ws

Example 3:
Relative Path: /stream*type
Routing Template: /video*format
─────────────────────────────
Request: ws://host/stream/hd/type  →  ws://backend/video/hd/format
Request: ws://host/stream123type   →  ws://backend/video123format
CODE

4. Parameterized Path

Defines path segments as named parameters. Each parameter is specified in the format {paramName}.

Format:

  • Relative Path: /path/{param1}/{param2}
  • Routing Template: /backend/path/{param2}/{param1}

Properties:

  • Parameters are defined within curly braces
  • Parameter names must be unique
  • Parameters can be used in different order in backend path
  • Parameter names must be the same in Relative Path and Routing Template
  • Can be combined with fixed path segments
  • Query parameters are preserved


Examples:

Example 1:
Relative Path: /chat/{roomId}/{userId}
Routing Template: /ws/room/{roomId}/user/{userId}
─────────────────────────────
Request: ws://host/chat/123/456       →  ws://backend/ws/room/123/user/456
Request: ws://host/chat/game1/player2 →  ws://backend/ws/room/game1/user/player2

Example 2:
Relative Path: /app/{tenant}/{service}/{instance}
Routing Template: /ws/{tenant}/{instance}/{service}
─────────────────────────────
Request: ws://host/app/company1/chat/inst1 →  ws://backend/ws/company1/inst1/chat
Request: ws://host/app/org2/mail/srv3     →  ws://backend/ws/org2/srv3/mail

Example 3:
Relative Path: /live/{channel}/feed/{quality}
Routing Template: /streaming/{quality}/{channel}
─────────────────────────────
Request: ws://host/live/sports/feed/hd  →  ws://backend/streaming/hd/sports
Request: ws://host/live/news/feed/4k    →  ws://backend/streaming/4k/news
CODE

Matching Priority Order

When multiple path definitions match the same request, the following priority order is used:

  1. Exact Match (highest priority)
  2. Parameterized Path
  3. Wildcard Match (lowest priority)

Example:

Defined Paths:
1. /chat/room1        (Exact Match)
2. /chat/{roomId}     (Parameterized)
3. /chat/*           (Wildcard)

Request: ws://host/chat/room1
→ Definition 1 is selected (Exact Match priority)

Request: ws://host/chat/room2
→ Definition 2 is selected (Parameterized Path, prioritized over Wildcard)

Request: ws://host/chat/room3/user1
→ Definition 3 is selected (Only Wildcard matches)
CODE


Important Notes and Best Practices

  1. Path Termination
    • Trailing "/" is optional
    • System automatically normalizes presence/absence of trailing "/"
  2. Case Sensitivity
    • All path matching is case insensitive
    • /Chat/{RoomId} and /chat/{roomid} are processed identically
  3. Query Parameters
    • Query parameters are always forwarded to backend as-is
    • Query parameters are not considered during path matching
  4. Parameter Naming
    • Parameter names must be unique
    • Use meaningful and descriptive parameter names
    • Use only alphanumeric characters in parameter names
  5. Wildcard Usage
    • Use wildcards sparingly
    • Prefer more specific paths over broad wildcard definitions
    • Consider maintenance and debugging when using wildcards