docs/howto: use net.IP* to validate IP addresses

This adds Commented CUE guides demonstrating how to use the built-in functions net.IP, net.IPv4, and net.IPCIDR as validators. The IPCIDR guide does not include its list-of-bytes input form as this does not currently work as documented (cue-lang/cue#2754). Preview-Path: /docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/ Preview-Path: /docs/howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/ Preview-Path: /docs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/ Signed-off-by: Jonathan Matthews <[email protected]> Change-Id: I23e181d0757487695ceb3a281cb3c8f0c43e9d81 Dispatch-Trailer: {"type":"trybot","CL":1174202,"patchset":5,"ref":"refs/changes/02/1174202/5","targetBranch":"alpha"}
cue-lang · Jan 18, 2024 · 331cb54 · 331cb54
1 parent 3e68077
commit 331cb54
Show file tree

Hide file tree

Showing 12 changed files with 374 additions and 0 deletions.
diff --git a/content/docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/en.md b/content/docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/en.md
@@ -0,0 +1,58 @@
+---
+title: Using the built-in function "net.IP" to validate IP addresses
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function `net.IP` to check that values
+represent valid IPv4 or IPv6 addresses as strings or lists of bytes.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "net"
+
+valid: [_]: net.IP
+valid: {
+	// Both v4* fields represent the same IPv4 address
+	v4String: "198.51.100.14"
+	v4Bytes: [198, 51, 100, 14]
+
+	// All 3 v6* fields represent the same IPv6 address
+	v6StringFull:  "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
+	v6StringShort: "2001:0db8:85a3::8a2e:0370:7334"
+	v6Bytes: [32, 1, 13, 184, 133, 163, 0, 0, 1, 0, 138, 46, 3, 112, 115, 52]
+}
+
+v4TooManyOctets: "198.51.100.14.0" & net.IP
+v4OctetTooLarge: [300, 51, 100, 14] & net.IP
+v6ByteTooLarge: [300, 1, 13, 184, 133, 163, 0, 0, 1, 0, 138, 46, 3, 112, 115, 52]
+v6ByteTooLarge: net.IP
+-- out --
+v4OctetTooLarge: invalid value [300,51,100,14] (does not satisfy net.IP):
+    ./file.cue:18:18
+v4TooManyOctets: invalid value "198.51.100.14.0" (does not satisfy net.IP):
+    ./file.cue:17:18
+v6ByteTooLarge: invalid value [300,1,13,184,133,163,0,0,1,0,138,46,3,112,115,52] (does not satisfy net.IP):
+    ./file.cue:19:17
+    ./file.cue:20:17
+{{{end}}}
+
+## Related content
+
+- The [`net`](https://pkg.go.dev/cuelang.org/go/pkg/net) built-in package
+- [Using the built-in function "net.IPv4" to validate IPv4 addresses]({{< relref
+    "use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses"
+  >}})
+- [Using the built-in function "net.IPCIDR" to validate IP CIDR ranges]({{< relref
+    "use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges"
+  >}})
diff --git a/content/docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/gen_cache.cue b/content/docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-net-ip-to-validate-ip-addresses": {
+					page: {
+						cache: {
+							code: {
+								cc: "NbFGpk0ynObCx4ORLaMJNm+hvyGMcKoQRDpdhyM7t2w="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/content/docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/page.cue b/content/docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-net-ip-to-validate-ip-addresses": {}
diff --git a/...ocs/howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/en.md b/...ocs/howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/en.md
@@ -0,0 +1,50 @@
+---
+title: Using the built-in function "net.IPCIDR" to validate IP CIDR ranges
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function `net.IPCIDR` to check that values
+represent valid IPv4 or IPv6 addresses or subnets in
+[CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation).
+
+{{{with code "en" "cc"}}}
+! exec cue vet 
+cmp stderr out
+-- file.cue --
+package example
+
+import "net"
+
+valid: [_]: net.IPCIDR
+valid: {
+	v4Block:   "198.51.100.0/22"
+	v4Address: "198.51.100.14/24"
+	v6Block:   "2001:db8::/48"
+	v6Address: "::1/128"
+}
+
+v4SubnetMaskTooLarge: "10.0.0.0/50" & net.IPCIDR
+v6MalformedPrefix:    ":::1/128"
+v6MalformedPrefix:    net.IPCIDR
+-- out --
+v4SubnetMaskTooLarge: invalid value "10.0.0.0/50" (does not satisfy net.IPCIDR): error in call to net.IPCIDR: invalid CIDR address: 10.0.0.0/50:
+    ./file.cue:13:23
+v6MalformedPrefix: invalid value ":::1/128" (does not satisfy net.IPCIDR): error in call to net.IPCIDR: invalid CIDR address: :::1/128:
+    ./file.cue:14:23
+    ./file.cue:15:23
+{{{end}}}
+
+## Related content
+
+- The [`net`](https://pkg.go.dev/cuelang.org/go/pkg/net) built-in package
+- [Using the built-in function "net.IP" to validate IP addresses]({{< relref
+    "use-the-built-in-function-net-ip-to-validate-ip-addresses"
+  >}})
+- [Using the built-in function "net.IPv4" to validate IPv4 addresses]({{< relref
+    "use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses"
+  >}})
diff --git a/.../docs/howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/gen_cache.cue b/.../docs/howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges": {
+					page: {
+						cache: {
+							code: {
+								cc: "wf73RGfVuebCWZlo7QARB5aykD5RJ8Jdc0S7Rngftq0="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/content/docs/howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/page.cue b/content/docs/howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges": {}
diff --git a/.../docs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/en.md b/.../docs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/en.md
@@ -0,0 +1,47 @@
+---
+title: Using the built-in function "net.IPv4" to validate IPv4 addresses
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function `net.IPv4` to check that values
+represent valid IPv4 addresses as strings or lists of bytes.
+
+{{{with code "en" "cc"}}}
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "net"
+
+v4ValidString: "198.51.100.14" & net.IPv4
+v4ValidBytes: [198, 51, 100, 14] & net.IPv4
+
+v4TooManyOctets: "198.51.100.14.0" & net.IPv4
+v4OctetTooLarge: [300, 51, 100, 14] & net.IPv4
+v6Notv4: "2001:0db8:85a3::8a2e:0370:7334"
+v6Notv4: net.IPv4
+-- out --
+v4OctetTooLarge: invalid value [300,51,100,14] (does not satisfy net.IPv4):
+    ./file.cue:9:18
+v4TooManyOctets: invalid value "198.51.100.14.0" (does not satisfy net.IPv4):
+    ./file.cue:8:18
+v6Notv4: invalid value "2001:0db8:85a3::8a2e:0370:7334" (does not satisfy net.IPv4):
+    ./file.cue:10:10
+    ./file.cue:11:10
+{{{end}}}
+
+## Related content
+
+- The [`net`](https://pkg.go.dev/cuelang.org/go/pkg/net) built-in package
+- [Using the built-in function "net.IP" to validate IP addresses]({{< relref
+    "use-the-built-in-function-net-ip-to-validate-ip-addresses"
+  >}})
+- [Using the built-in function "net.IPCIDR" to validate IP CIDR ranges]({{< relref
+    "use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges"
+  >}})
diff --git a/...nt/docs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/gen_cache.cue b/...nt/docs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses": {
+					page: {
+						cache: {
+							code: {
+								cc: "P362krAYWyGQvxYovlElqCXDVoPVZn8FARwvn/wwp1o="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/content/docs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/page.cue b/content/docs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses": {}
diff --git a/...n/docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/index.md b/...n/docs/howto/use-the-built-in-function-net-ip-to-validate-ip-addresses/index.md
@@ -0,0 +1,57 @@
+---
+title: Using the built-in function "net.IP" to validate IP addresses
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function `net.IP` to check that values
+represent valid IPv4 or IPv6 addresses as strings or lists of bytes.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "net"
+
+valid: [_]: net.IP
+valid: {
+	// Both v4* fields represent the same IPv4 address
+	v4String: "198.51.100.14"
+	v4Bytes: [198, 51, 100, 14]
+
+	// All 3 v6* fields represent the same IPv6 address
+	v6StringFull:  "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
+	v6StringShort: "2001:0db8:85a3::8a2e:0370:7334"
+	v6Bytes: [32, 1, 13, 184, 133, 163, 0, 0, 1, 0, 138, 46, 3, 112, 115, 52]
+}
+
+v4TooManyOctets: "198.51.100.14.0" & net.IP
+v4OctetTooLarge: [300, 51, 100, 14] & net.IP
+v6ByteTooLarge: [300, 1, 13, 184, 133, 163, 0, 0, 1, 0, 138, 46, 3, 112, 115, 52]
+v6ByteTooLarge: net.IP
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue vet
+v4OctetTooLarge: invalid value [300,51,100,14] (does not satisfy net.IP):
+    ./file.cue:18:18
+v4TooManyOctets: invalid value "198.51.100.14.0" (does not satisfy net.IP):
+    ./file.cue:17:18
+v6ByteTooLarge: invalid value [300,1,13,184,133,163,0,0,1,0,138,46,3,112,115,52] (does not satisfy net.IP):
+    ./file.cue:19:17
+    ./file.cue:20:17
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`net`](https://pkg.go.dev/cuelang.org/go/pkg/net) built-in package
+- [Using the built-in function "net.IPv4" to validate IPv4 addresses]({{< relref
+    "use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses"
+  >}})
+- [Using the built-in function "net.IPCIDR" to validate IP CIDR ranges]({{< relref
+    "use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges"
+  >}})
diff --git a/.../howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/index.md b/.../howto/use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges/index.md
@@ -0,0 +1,51 @@
+---
+title: Using the built-in function "net.IPCIDR" to validate IP CIDR ranges
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function `net.IPCIDR` to check that values
+represent valid IPv4 or IPv6 addresses or subnets in
+[CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation).
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top-left" >}}
+package example
+
+import "net"
+
+valid: [_]: net.IPCIDR
+valid: {
+	v4Block:   "198.51.100.0/22"
+	v4Address: "198.51.100.14/24"
+	v6Block:   "2001:db8::/48"
+	v6Address: "::1/128"
+}
+
+v4SubnetMaskTooLarge: "10.0.0.0/50" & net.IPCIDR
+v6MalformedPrefix:    ":::1/128"
+v6MalformedPrefix:    net.IPCIDR
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="top-right" >}}
+$ cue vet
+v4SubnetMaskTooLarge: invalid value "10.0.0.0/50" (does not satisfy net.IPCIDR): error in call to net.IPCIDR: invalid CIDR address: 10.0.0.0/50:
+    ./file.cue:13:23
+v6MalformedPrefix: invalid value ":::1/128" (does not satisfy net.IPCIDR): error in call to net.IPCIDR: invalid CIDR address: :::1/128:
+    ./file.cue:14:23
+    ./file.cue:15:23
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`net`](https://pkg.go.dev/cuelang.org/go/pkg/net) built-in package
+- [Using the built-in function "net.IP" to validate IP addresses]({{< relref
+    "use-the-built-in-function-net-ip-to-validate-ip-addresses"
+  >}})
+- [Using the built-in function "net.IPv4" to validate IPv4 addresses]({{< relref
+    "use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses"
+  >}})
diff --git a/...cs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/index.md b/...cs/howto/use-the-built-in-function-net-ipv4-to-validate-ipv4-addresses/index.md
@@ -0,0 +1,48 @@
+---
+title: Using the built-in function "net.IPv4" to validate IPv4 addresses
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function `net.IPv4` to check that values
+represent valid IPv4 addresses as strings or lists of bytes.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top-left" >}}
+package example
+
+import "net"
+
+v4ValidString: "198.51.100.14" & net.IPv4
+v4ValidBytes: [198, 51, 100, 14] & net.IPv4
+
+v4TooManyOctets: "198.51.100.14.0" & net.IPv4
+v4OctetTooLarge: [300, 51, 100, 14] & net.IPv4
+v6Notv4: "2001:0db8:85a3::8a2e:0370:7334"
+v6Notv4: net.IPv4
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="top-right" >}}
+$ cue vet
+v4OctetTooLarge: invalid value [300,51,100,14] (does not satisfy net.IPv4):
+    ./file.cue:9:18
+v4TooManyOctets: invalid value "198.51.100.14.0" (does not satisfy net.IPv4):
+    ./file.cue:8:18
+v6Notv4: invalid value "2001:0db8:85a3::8a2e:0370:7334" (does not satisfy net.IPv4):
+    ./file.cue:10:10
+    ./file.cue:11:10
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`net`](https://pkg.go.dev/cuelang.org/go/pkg/net) built-in package
+- [Using the built-in function "net.IP" to validate IP addresses]({{< relref
+    "use-the-built-in-function-net-ip-to-validate-ip-addresses"
+  >}})
+- [Using the built-in function "net.IPCIDR" to validate IP CIDR ranges]({{< relref
+    "use-the-built-in-function-net-ipcidr-to-validate-ip-cidr-ranges"
+  >}})
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		package site

		content: docs: howto: "use-the-built-in-function-net-ip-to-validate-ip-addresses": {}