From 4279bf0018055de68f59dffe9532fab96c80d3ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fl=C3=A1vio=20Cruz?= Date: Mon, 25 Mar 2024 16:35:53 -0400 Subject: [PATCH] docs(vrl): Add documentation for parse_proto and encode_proto (#20139) * docs(vrl): Add documentation for parse_proto and encode_proto (https://github.com/vectordotdev/vrl/pull/739) * Add spellcheck exception Signed-off-by: Jesse Szwedko * Add ignore pattern for base64 Signed-off-by: Jesse Szwedko * Update pattern Signed-off-by: Jesse Szwedko * Fix pattern Signed-off-by: Jesse Szwedko * another try Signed-off-by: Jesse Szwedko * cue formatting Signed-off-by: Jesse Szwedko * update tests Signed-off-by: Jesse Szwedko * Ignore desc files in syntax check Signed-off-by: Jesse Szwedko --------- Signed-off-by: Jesse Szwedko Co-authored-by: Jesse Szwedko --- .github/actions/spelling/patterns.txt | 3 + .../resources/protobuf_descriptor_set.desc | Bin 0 -> 1183 bytes scripts/check-style.sh | 1 + .../remap/functions/encode_proto.cue | 52 ++++++++++++++ .../reference/remap/functions/parse_proto.cue | 65 ++++++++++++++++++ 5 files changed, 121 insertions(+) create mode 100644 lib/vector-vrl/tests/resources/protobuf_descriptor_set.desc create mode 100644 website/cue/reference/remap/functions/encode_proto.cue create mode 100644 website/cue/reference/remap/functions/parse_proto.cue diff --git a/.github/actions/spelling/patterns.txt b/.github/actions/spelling/patterns.txt index 8dd94f985e88c..28109b552e719 100644 --- a/.github/actions/spelling/patterns.txt +++ b/.github/actions/spelling/patterns.txt @@ -225,6 +225,9 @@ user:P@ssw0rd # Ignore base64 encoded values in Prometheus Pushgateway URL paths /.+@base64/.+ +# Ignore base64 encoded values in VRL examples (requires padding to avoid false positives) +"[A-Za-z0-9]*==" + # Ignore punycode \bxn--[-0-9a-z]+ diff --git a/lib/vector-vrl/tests/resources/protobuf_descriptor_set.desc b/lib/vector-vrl/tests/resources/protobuf_descriptor_set.desc new file mode 100644 index 0000000000000000000000000000000000000000..43e7acf6cf7716af7c2a751c2ece9283a5033f47 GIT binary patch literal 1183 zcmaJ<+int36rFQn2KF#890r&|FO;Vyji`Oo_+pbL-fA0S;-j`f^dJ9EkiFDzt}ZWTHf3^34O@W; zL*!mwoxlBX5jv($Ru&45K3~n=hjQ|Y{MYmOI@xT_)AWaVg29q>b791-(-2%bH?GJJjwCl^kPady;(7g9hjb382RHnqshAdE;;h0y{9tx^u!*Fi}O zi|ZAJ-1nQM9I&|~=Qf+Vl1t_xw~Z<^+U9b0or?dYO})%Y*+xTslvQGgZG^g6VeBIe zx)nxx7!50oorDL6r5)&weqPf2L!BKv;Q|N!if8>`RAJb44y$%V9eDh#;yvKgr};lZ z9LY&Gm{cegmH((vDDsONQYaG*4hkjbjgRfQ3Zn;n&U~)C^+COB%?1BpEVC2=Y5{{rq%g!BLa literal 0 HcmV?d00001 diff --git a/scripts/check-style.sh b/scripts/check-style.sh index bf4f18fdf65ad..f905b6f22d34f 100755 --- a/scripts/check-style.sh +++ b/scripts/check-style.sh @@ -33,6 +33,7 @@ for FILE in $(git ls-files); do *ico) continue;; *sig) continue;; *html) continue;; + *desc) continue;; tests/data*) continue;; lib/codecs/tests/data*) continue;; lib/vector-core/tests/data*) continue;; diff --git a/website/cue/reference/remap/functions/encode_proto.cue b/website/cue/reference/remap/functions/encode_proto.cue new file mode 100644 index 0000000000000..253bcf01e9241 --- /dev/null +++ b/website/cue/reference/remap/functions/encode_proto.cue @@ -0,0 +1,52 @@ +package metadata + +remap: functions: encode_proto: { + category: "Codec" + description: """ + Encodes the `value` into a protocol buffer payload. + """ + + arguments: [ + { + name: "value" + description: "The object to convert to a protocol buffer payload." + required: true + type: ["object"] + }, + { + name: "desc_file" + description: """ + The path to the protobuf descriptor set file. Must be a literal string. + + This file is the output of protoc -o ... + """ + required: true + type: ["string"] + }, + { + name: "message_type" + description: """ + The name of the message type to use for serializing. + + Must be a literal string. + """ + required: true + type: ["string"] + }, + ] + internal_failure_reasons: [ + "`desc_file` file does not exist.", + "`message_type` message type does not exist in the descriptor file.", + ] + return: types: ["string"] + + examples: [ + { + title: "Encode to proto" + source: #""" + .payload = encode_base64(encode_proto!({"name": "someone", "phones": [{"number": "123456"}]}, "resources/protobuf_descriptor_set.desc", "test_protobuf.Person")) + """# + return: #"Cgdzb21lb25lIggKBjEyMzQ1Ng=="# + }, + ] +} diff --git a/website/cue/reference/remap/functions/parse_proto.cue b/website/cue/reference/remap/functions/parse_proto.cue new file mode 100644 index 0000000000000..29557895e0df3 --- /dev/null +++ b/website/cue/reference/remap/functions/parse_proto.cue @@ -0,0 +1,65 @@ +package metadata + +remap: functions: parse_proto: { + category: "Parse" + description: """ + Parses the `value` as a protocol buffer payload. + """ + notices: [ + """ + Only proto messages are parsed and returned. + """, + ] + + arguments: [ + { + name: "value" + description: "The protocol buffer payload to parse." + required: true + type: ["string"] + }, + { + name: "desc_file" + description: """ + The path to the protobuf descriptor set file. Must be a literal string. + + This file is the output of protoc -o ... + """ + required: true + type: ["string"] + }, + { + name: "message_type" + description: """ + The name of the message type to use for serializing. + + Must be a literal string. + """ + required: true + type: ["string"] + }, + ] + internal_failure_reasons: [ + "`value` is not a valid proto payload.", + "`desc_file` file does not exist.", + "`message_type` message type does not exist in the descriptor file.", + ] + return: types: ["object"] + + examples: [ + { + title: "Parse proto" + source: #""" + parse_proto!(decode_base64!("Cgdzb21lb25lIggKBjEyMzQ1Ng=="), "resources/protobuf_descriptor_set.desc", "test_protobuf.Person") + """# + return: { + name: "someone" + phones: [ + { + number: "123456" + }, + ] + } + }, + ] +}