docs(vrl): add documentation for punycode encoding functions

.github/actions/spelling/allow.txt

@@ -329,6 +329,7 @@ htmltest
 https
 humungus
 icecream
+idn
 ifeq
 ifneq
 imobile

.github/actions/spelling/patterns.txt

@@ -224,3 +224,6 @@ user:P@ssw0rd
 
 # Ignore base64 encoded values in Prometheus Pushgateway URL paths
 /.+@base64/.+
+
+# Ignore punycode
+\bxn--[-0-9a-z]+

website/cue/reference/remap/functions/decode_punycode.cue

@@ -0,0 +1,36 @@
+package metadata
+
+remap: functions: decode_punycode: {
+	category:    "Codec"
+	description: """
+		Decodes a [punycode](\(urls.punycode)) encoded `value`, like an internationalized domain name ([IDN](\(urls.idn))).
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The string to decode."
+			required:    true
+			type: ["string"]
+		},
+	]
+	internal_failure_reasons: []
+	return: types: ["string"]
+
+	examples: [
+		{
+			title: "Decode a punycode encoded internationalized domain name"
+			source: """
+				decode_punycode("www.xn--caf-dma.com")
+				"""
+			return: "www.café.com"
+		},
+		{
+			title: "Decode an ASCII only string"
+			source: """
+				encode_punycode("www.cafe.com")
+				"""
+			return: "www.cafe.com"
+		},
+	]
+}

website/cue/reference/remap/functions/encode_punycode.cue

@@ -0,0 +1,43 @@
+package metadata
+
+remap: functions: encode_punycode: {
+	category:    "Codec"
+	description: """
+		Encodes a `value` to [punycode](\(urls.punycode)). Useful for internationalized domain names ([IDN](\(urls.idn))).
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The string to encode."
+			required:    true
+			type: ["string"]
+		},
+	]
+	internal_failure_reasons: []
+	return: types: ["string"]
+
+	examples: [
+		{
+			title: "Encode an internationalized domain name"
+			source: """
+				encode_punycode("www.café.com")
+				"""
+			return: "www.xn--caf-dma.com"
+		},
+		{
+			title: "Encode an internationalized domain name with mixed case"
+			source: """
+				encode_punycode("www.CAFé.com")
+				"""
+			return: "www.xn--caf-dma.com"
+		},
+		{
+			title: "Encode an ASCII only string"
+			source: """
+				encode_punycode("www.cafe.com")
+				"""
+			return: "www.cafe.com"
+		},
+	]
+}

website/cue/reference/remap/functions/parse_url.cue

@@ -64,5 +64,37 @@ remap: functions: parse_url: {
 				fragment: null
 			}
 		},
+		{
+			title: "Parse URL with internationalized domain name"
+			source: #"""
+				parse_url!("https://www.café.com")
+				"""#
+			return: {
+				scheme:   "https"
+				username: ""
+				password: ""
+				host:     "www.xn--caf-dma.com"
+				port:     null
+				path:     "/"
+				query: {}
+				fragment: null
+			}
+		},
+		{
+			title: "Parse URL with mixed case internationalized domain name"
+			source: #"""
+				parse_url!("https://www.CAFé.com")
+				"""#
+			return: {
+				scheme:   "https"
+				username: ""
+				password: ""
+				host:     "www.xn--caf-dma.com"
+				port:     null
+				path:     "/"
+				query: {}
+				fragment: null
+			}
+		},
 	]
 }

website/cue/reference/urls.cue

@@ -266,6 +266,7 @@ urls: {
 	iana_time_zones:                            "\(wikipedia)/wiki/List_of_tz_database_time_zones"
 	ieee_754:                                   "\(wikipedia)/wiki/IEEE_754"
 	ietf_rfc_6750:                              "https://tools.ietf.org/html/rfc6750"
+	idn:                                        "\(wikipedia)/wiki/Internationalized_domain_name"
 	initd:                                      "https://bash.cyberciti.biz/guide//etc/init.d"
 	influxdb:                                   "https://www.influxdata.com/products/influxdb-overview/"
 	influxdb_http_api_v1:                       "https://docs.influxdata.com/influxdb/latest/tools/api/#write-http-endpoint"
@@ -422,6 +423,7 @@ urls: {
 	protobuf:                                   "https://developers.google.com/protocol-buffers"
 	pulsar:                                     "https://pulsar.apache.org/"
 	pulsar_protocol:                            "https://pulsar.apache.org/docs/en/develop-binary-protocol/"
+	punycode:                                   "\(wikipedia)/wiki/Punycode"
 	raspbian:                                   "https://www.raspbian.org/"
 	rdkafka:                                    "\(github)/edenhill/librdkafka"
 	regex:                                      "\(wikipedia)/wiki/Regular_expression"