Yilialinn commented on code in PR #11853: URL: https://github.com/apache/apisix/pull/11853#discussion_r1980868052
########## docs/en/latest/plugins/request-validation.md: ########## @@ -58,255 +65,464 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Validate Request Header + +The following example demonstrates how to validate request headers against a defined JSON schema, which requires two specific headers and the header value to conform to specified requirements. + +Create a Route with `request-validation` Plugin as follows: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/5 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "request-validation-route", "uri": "/get", "plugins": { - "request-validation": { - "body_schema": { - "type": "object", - "required": ["required_payload"], - "properties": { - "required_payload": {"type": "string"}, - "boolean_payload": {"type": "boolean"} - }, - "rejected_msg": "customize reject message" + "request-validation": { + "header_schema": { + "type": "object", + "required": ["User-Agent", "Host"], + "properties": { + "User-Agent": { + "type": "string", + "pattern": "^curl\/" + }, + "Host": { + "type": "string", + "enum": ["httpbin.org", "httpbin"] } + } } + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:8080": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' ``` -The examples below shows how you can configure this Plugin for different validation scenarios: +#### Verify with Request Conforming to the Schema -### Enum validation +Send a request with header `Host: httpbin`, which complies with the schema: + +```shell +curl -i "http://127.0.0.1:9080/get"; -H "Host: httpbin" +``` + +You should receive an `HTTP/1.1 200 OK` response similar to the following: ```json { - "body_schema": { - "type": "object", - "required": ["required_payload"], - "properties": { - "enum_payload": { - "type": "string", - "enum": ["enum_string_1", "enum_string_2"], - "default": "enum_string_1" - } - } - } + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin", + "User-Agent": "curl/7.74.0", + "X-Amzn-Trace-Id": "Root=1-6509ae35-63d1e0fd3934e3f221a95dd8", + "X-Forwarded-Host": "httpbin" + }, + "origin": "127.0.0.1, 183.17.233.107", + "url": "http://httpbin/get"; } ``` -### Boolean validation +#### Verify with Request Not Conforming to the Schema -```json -{ - "body_schema": { - "type": "object", - "required": ["bool_payload"], - "properties": { - "bool_payload": { - "type": "boolean", - "default": true +Send a request without any header: + +```shell +curl -i "http://127.0.0.1:9080/get"; +``` + +You should receive an `HTTP/1.1 400 Bad Request` response, showing that the request fails to pass validation: + +```text +property "Host" validation failed: matches none of the enum value +``` + +Send a request with the required headers but with non-conformant header value: + +```shell +curl -i "http://127.0.0.1:9080/get"; -H "Host: httpbin" -H "User-Agent: cli-mock" +``` + +You should receive an `HTTP/1.1 400 Bad Request` response showing the `User-Agent` header value does not match the expected pattern: + +```text +property "User-Agent" validation failed: failed to match pattern "^curl/" with "cli-mock" +``` + +### Customize Rejection Message and Status Code + +The following example demonstrates how to customize response status and message when the validation fails. + +Configure the Route with `request-validation` as follows: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "request-validation-route", + "uri": "/get", + "plugins": { + "request-validation": { + "header_schema": { + "type": "object", + "required": ["Host"], + "properties": { + "Host": { + "type": "string", + "enum": ["httpbin.org", "httpbin"] } - } + } + }, + "rejected_code": 403, + "rejected_msg": "Request header validation failed." + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -} + }' ``` -### Number or Integer validation +Send a request with a misconfigured `Host` in the header: -```json -{ - "body_schema": { - "type": "object", - "required": ["integer_payload"], - "properties": { - "integer_payload": { +```shell +curl -i "http://127.0.0.1:9080/get"; -H "Host: httpbin2" +``` + +You should receive an `HTTP/1.1 403 Forbidden` response with the custom message: + +```text +Request header validation failed. +``` + +### Validate Request Body + +The following example demonstrates how to validate request body against a defined JSON schema. + +The `request-validation` Plugin supports validation of two types of media types: + +* `application/json` +* `application/x-www-form-urlencoded` + +#### Validate JSON Request Body + +Create a Route with `request-validation` Plugin as follows: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "request-validation-route", + "uri": "/post", + "plugins": { + "request-validation": { + "header_schema": { + "type": "object", + "required": ["Content-Type"], + "properties": { + "Content-Type": { + "type": "string", + "pattern": "^application\/json$" + } + } + }, + "body_schema": { + "type": "object", + "required": ["required_payload"], + "properties": { + "required_payload": {"type": "string"}, + "boolean_payload": {"type": "boolean"}, + "array_payload": { + "type": "array", + "minItems": 1, + "items": { "type": "integer", - "minimum": 1, - "maximum": 65535 + "minimum": 200, + "maximum": 599 + }, + "uniqueItems": true, + "default": [200] } + } } + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -} + }' ``` -### String validation +Send a request with JSON body that conforms to the schema to verify: + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -H "Content-Type: application/json" \ + -d '{"required_payload":"hello", "array_payload":[301]}' +``` + +You should receive an `HTTP/1.1 200 OK` response similar to the following: ```json { - "body_schema": { - "type": "object", - "required": ["string_payload"], - "properties": { - "string_payload": { - "type": "string", - "minLength": 1, - "maxLength": 32 + "args": {}, + "data": "{\"array_payload\":[301],\"required_payload\":\"hello\"}", + "files": {}, + "form": {}, + "headers": { + ... + }, + "json": { + "array_payload": [ + 301 + ], + "required_payload": "hello" + }, + "origin": "127.0.0.1, 183.17.233.107", + "url": "http://127.0.0.1/post"; +} +``` + +If you send a request without specifying `Content-Type: application/json`: + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -d '{"required_payload":"hello,world"}' +``` + +You should receive an `HTTP/1.1 400 Bad Request` response similar to the following: + +```text +property "Content-Type" validation failed: failed to match pattern "^application/json$" with "application/x-www-form-urlencoded" +``` + +Similarly, if you send a request without the required JSON field `required_payload`: + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +You should receive an `HTTP/1.1 400 Bad Request` response: + +```text +property "required_payload" is required +``` + +#### Validate URL-Encoded Form Body + +Create a Route with `request-validation` Plugin as follows: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "request-validation-route", + "uri": "/post", + "plugins": { + "request-validation": { + "header_schema": { + "type": "object", + "required": ["Content-Type"], + "properties": { + "Content-Type": { + "type": "string", + "pattern": "^application\/x-www-form-urlencoded$" + } + } + }, + "body_schema": { + "type": "object", + "required": ["required_payload","enum_payload"], + "properties": { + "required_payload": {"type": "string"}, + "enum_payload": { + "type": "string", + "enum": ["enum_string_1", "enum_string_2"], + "default": "enum_string_1" } + } } + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -} + }' ``` -### Regular expression validation +Send a request with URL-encoded form data to verify: + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "required_payload=hello&enum_payload=enum_string_1" +``` + +You should receive an `HTTP/1.1 400 Bad Request` response similar to the following: ```json { - "body_schema": { - "type": "object", - "required": ["regex_payload"], - "properties": { - "regex_payload": { - "type": "string", - "minLength": 1, - "maxLength": 32, - "pattern": "[[^[a-zA-Z0-9_]+$]]" - } - } - } + "args": {}, + "data": "", + "files": {}, + "form": { + "enum_payload": "enum_string_1", + "required_payload": "hello" + }, + "headers": { + ... + }, + "json": null, + "origin": "127.0.0.1, 183.17.233.107", + "url": "http://127.0.0.1/post"; } ``` -### Array validation +Send a request without the URL-encoded field `enum_payload`: + +```shell +curl -i "http://127.0.0.1:9080/post"; -X POST \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "required_payload=hello" +``` + +You should receive an `HTTP/1.1 400 Bad Request` of the following: + +```text +property "enum_payload" is required +``` + +## Appendix: JSON Schema + +The following section provides boilerplate JSON schema for you to adjust, combine, and use with this plugin. For a complete reference, see [JSON schema specification](https://json-schema.org/specification). Review Comment: ```suggestion The following section provides boilerplate JSON schema for you to adjust, combine, and use with this Plugin. For a complete reference, see [JSON schema specification](https://json-schema.org/specification). ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
