WebSocket Validator

Validate individual WebSocket messages against a user-specified schema before proxying them.

The message schema can be configured by type (text or binary) and sender (client or upstream).

This plugin supports validation against JSON schema draft4.

Note: This plugin does not support conditional expressions.

When an incoming message is invalid according to the schema, a close frame is sent to the sender (status: 1007) and the peer before closing the connection.

For example, here’s what it looks like when validating that client text frames:

• Are valid JSON
• Are a JSON object ({})
• Have a name attribute (of any type)

 
sequenceDiagram
autonumber
    activate Client
    activate Kong
    Client->>Kong: text(`{ "name": "Alex" }`)
    activate Upstream
    Kong->>Upstream: text(`{ "name": "Alex" }`)
    Client->>Kong: text(`{ "name": "Kiran" }`)
    Kong->>Upstream: text(`{ "name": "Kiran" }`)
    Client->>Kong: text(`{ "missing_name": true }`)
    Kong->>Client: close(status=1007)
    Kong->>Upstream: close()
    deactivate Upstream
    deactivate Kong
    deactivate Client
  

The clients with the names Alex and Kiran pass validation, but when missing_name appears, it’s considered invalid and the plugin sends a close frame.

At least one of the following complete message validation configuration pairs must be defined:

• config.client.text.type and config.client.text.schema
• config.client.binary.type and config.client.binary.schema
• config.upstream.text.type and config.upstream.text.schema
• config.upstream.binary.type and config.upstream.binary.schema

See Validating client text frames for an example.