Validate individual WebSocket messages against to a user-specified schema before proxying them.
Message schema can be configured by type (text or binary) and sender (client or upstream).
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.
Configuration Reference
This plugin is compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
/config
endpoint
Example plugin configuration
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter | Description |
---|---|
name
required Type: string |
The name of the plugin, in this case websocket-validator . |
service.name or service.id
Type: string |
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
Type: string |
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
enabled
Type: boolean Default value: true |
Whether this plugin will be applied. |
config.client.text.schema
semi-optional Type: string |
Schema used to validate client-originated text frames. The semantics of
this field depend on the validation type set by |
config.client.text.type
semi-optional Type: string |
The corresponding validation library for |
config.client.binary.schema
semi-optional Type: string |
Schema used to validate client-originated binary frames. The semantics of
this field depend on the validation type set by |
config.client.binary.type
semi-optional Type: string |
The corresponding validation library for |
config.upstream.text.schema
semi-optional Type: string |
Schema used to validate upstream-originated text frames. The semantics of
this field depend on the validation type set by |
config.upstream.text.type
semi-optional Type: string |
The corresponding validation library for |
config.upstream.binary.schema
semi-optional Type: string |
Schema used to validate upstream-originated binary frames. The semantics of
this field depend on the validation type set by |
config.upstream.binary.type
semi-optional Type: string |
The corresponding validation library for |
At least one of the following complete message validation configurations must be defined:
config.client.text.type
andconfig.client.text.schema
config.client.binary.type
andconfig.client.binary.schema
config.upstream.text.type
andconfig.upstream.text.schema
config.upstream.binary.type
andconfig.upstream.binary.schema
Usage
Note: Currently, the only supported validation type is JSON schema draft4, so all examples will use this.
Validate client text frames
This example validates that client text frames:
- Are valid JSON
- Are a JSON object (
{}
) - Have a
name
attribute (of any type)
Here’s an example sequence for this configuration:
.------. .----. .--------.
|Client| |Kong| |Upstream|
'------' '----' '--------'
| | |
| text(`{ "name": "Alex" }`) | |
|>----------------------------------->| |
| | |
| | text(`{ "name": "Alex" }`) |
| |>------------------------------->|
| | |
| text(`{ "name": "Kiran" }`) | |
|>----------------------------------->| |
| | |
| | text(`{ "name": "Kiran" }`) |
| |>------------------------------->|
| | |
| text(`{ "missing_name": true }`) | |
|>----------------------------------->| |
| | |
| close(status=1007) | |
|<-----------------------------------<| |
| | |
| | close() |
| |>------------------------------->|
.------. .----. .--------.
|Client| |Kong| |Upstream|
'------' '----' '--------'