docs(vrl): Add documentation for parse_proto and encode_proto (#20139)

* docs(vrl): Add documentation for parse_proto and encode_proto (vectordotdev/vrl#739) * Add spellcheck exception Signed-off-by: Jesse Szwedko <[email protected]> * Add ignore pattern for base64 Signed-off-by: Jesse Szwedko <[email protected]> * Update pattern Signed-off-by: Jesse Szwedko <[email protected]> * Fix pattern Signed-off-by: Jesse Szwedko <[email protected]> * another try Signed-off-by: Jesse Szwedko <[email protected]> * cue formatting Signed-off-by: Jesse Szwedko <[email protected]> * update tests Signed-off-by: Jesse Szwedko <[email protected]> * Ignore desc files in syntax check Signed-off-by: Jesse Szwedko <[email protected]> --------- Signed-off-by: Jesse Szwedko <[email protected]> Co-authored-by: Jesse Szwedko <[email protected]>
vectordotdev · Mar 25, 2024 · 4279bf0 · 4279bf0
1 parent 4d23e66
commit 4279bf0
Show file tree

Hide file tree

Showing 5 changed files with 121 additions and 0 deletions.
diff --git 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
diff --git 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
@@ -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 <path> ...
+				"""
+			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
@@ -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 <path> ...
+				"""
+			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"
+					},
+				]
+			}
+		},
+	]
+}