BytedanceRPC commented on a change in pull request #2469: URL: https://github.com/apache/thrift/pull/2469#discussion_r812892752
########## File path: doc/proposal/thrift-parameter-validation-proposal.md ########## @@ -0,0 +1,187 @@ +# Thrift Parameter Validation Proposal + +> Version 1.1 +> +> Dec 15, 2021 +> +> [email protected], [email protected] + +### 1. Abstract +*** +This document presents a proposed set of annotations to the Thrift IDL. The new annotations will supports parameter validation using build-in or third-party validators. The goal of this proposal is to define sematics and behavior of validation annotations, rather than to discuss their implementation. + +### 2. Background +*** +Parameter validation is a common need for web service. In the past, we usually write our validating logics after a RPC message deserialized by thrift. This ways works flexibly enough but restrict poorly: It is dangerous than service A and service B using the same IDL have two different validating rule, which often misdirects developers. Even if we extract our validating codes to a single module, simple and repeated work (ex. `if xx.Field1 > 1 then ...`) is really disturbing. If we can use build tool to generating codes for simple and unchangeable restraint, the web service will be more robust and developers will benefits from lighter work. +Compared to other IDL, the parameter validation gradually gets strong commutity supports like PGV ([protoc-gen-validate](https://github.com/envoyproxy/protoc-gen-validate)), benefiting from pb's strong plugin mechanism (lacking official plugin mechanism is one reason for we submit this proposal). Take a long-term view, auto-generated parameter validation may be a step towards code-less web service. + +### 3. Proposal +*** +This proposal includes three part: Validate Annotation Sematics, Validate Rule and Validate Feedback. The first declare how to write a validate annotation, the middle explain how every annotation should behave, the last introduces a mechanism of validating feedback. + +#### 3.1 Validate Annotation Sematics +This sematics uses same rule of [Thrift IDL](https://thrift.apache.org/docs/idl). The validate option only works on struct fields, thus we must start from Field sematics part. +- Field +```apache +Field ::= FieldID? FieldReq? FieldType Identifier ('=' ConstValue)? ValidateAnnotations? ListSeparator? +``` +- ValidateAnnotations +```apache +ValidateAnnotations ::= '(' ValidateRule+ ListSeparator? ')' +``` +- ValidateRule +```apache +ValidateRule := ('validate' | 'vt') Validator+ = '"' ValidatingValue? '"' +``` +- Validator + + Build-in validating logics. See [Supported Validator](#321-supported-validator) part. +```apache +Validator = '.' Identifier +``` +- ValidatingValue +```apache +ValidatingValue := (ToolFunction '(' )? Arguments ‘)’? Review comment: It actually uses peg grammar, but with the wrong symbol, I made a fix -- 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]
