README
¶
MustBe
mustbe.* functions process an argument of any type and convert it to the required type.
- Any validation steps must be done here. Any range checking, keyword restrictions, etc. should be done here.
- Any IDNA (PunyCode) conversions must be done here. Only ASCII is stored in fields that hold hostnames.
- Any hostnames must be extended to their FQDN, including a trailing dot (if required).
- If a field is case insensitive, we convert it to lowercase (hostnames) or uppercase (base64 or similar) so that future comparisons can simply use
==.
In short, by the time any data makes it to into the struct, it must be valid. No later validation is done. (That's not entirely true. pkg/normalize/validate still does some validation/normalization but once all DNS record types have a Make*() function, we'll be removing validation steps from pkg/normalize/validate. That is, in the future, pkg/normalize/validate will do per-zone validation only, all per-record validations will be done in the Make*() functions.
Documentation
¶
Index ¶
- func Bool(a any) bool
- func BoolString(a any) string
- func Float32(arg any) float32
- func Float64(arg any) float64
- func IPv4(a any) (netip.Addr, error)
- func IPv6(a any) (netip.Addr, error)
- func Int64(arg any) int64
- func MakeErrorSingleDotViolation(s string) error
- func OpenPGPKey(a any) string
- func RawString(a any) string
- func SoaMailbox(arg any) string
- func TargetHost(origin string, isEnabled nrc.Flags, arg any) (string, error)
- func TargetHostSRV(origin string, isEnabled nrc.Flags, arg any) (string, error)
- func ToLowerRawString(a any) string
- func ToUpperRawString(a any) string
- func Txts(args ...any) []string
- func Uint8(arg any) uint8
- func Uint16(arg any) uint16
- func Uint32(arg any) uint32
- func Uint64(arg any) uint64
- func ValidArgs(args []any)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BoolString ¶
BoolString converts to a string that is either `true` or `false`.
func OpenPGPKey ¶
func SoaMailbox ¶
SoaMailbox format a SOA Mailbox string, such as tal.example.com (The "@" in the email address is written as an "." because nothing in DNS is simple). This function also... * Turns normal email addresses (tal@example.com) into SOA Mailbox strings (tal.example.com). * Turns Unicode into PunyCode (just in the hostname part) * Runs ToLower. * Does NOT add an origin if this is a shortname. We can't know if it is a shortname because it is dotless.)
func TargetHost ¶
TargetHost returns a FQDN (or @) suitable as a target for CNAME and other records. What is a target? * A "target" is a hostname used in fields of a DNS record. For example, in "foo IN MX 10 bar.example.com.", "bar" is the target. * A target is stored as a FQDN+"." with all Unicode converted to ASCII (PunyCode). * It is never stored as "@" or a shortname. * If you require a shortname, use dc.TargetAsShort(target) or dc.TargetAsShortOrAt(target).
* origin must be a FQDN without a trailing dot. Violations cause a panic so that this is caught before code is shipped. * if origin is "", a special mode is activated that disables most action.
- This is for legacy situations where the origin is unknown.
- This will eventually be an error.
- In this mode, Either the original string is returned, or if that string is "", "UNKNOWNORIGIN." is returned. This is the only situation where this function might return "@".
* Normal operation:
- arg may be a string or it will be converted to a string using fmt.Printf("%v").
- Unicode is converted to PunyCode.
- The result always ends with a "."
- The reason for not storing the short or "@" version is that "preview" output becomes ambiguous. Explicit is better than implicit.
- Wildcards ("@") are rejected since they are not valid in targets. That's why this is called TargetHost and not Host.
* origin == ".":
- This is a special flag for TargetIsFqdnNoDot mode.
* Examples: (assume $origin = "domain.com")
- `@` -> $origin
- `foo.$origin.` -> `foo.$origin.`
- `$origin.` -> `$origin.`
- `other.com.` -> `other.com.`
- `short` -> `short.$origin`
func TargetHostSRV ¶
TargetHostSRV is like TargetHost with the exception that "." and "" have special meaning and are left alone.
func ToLowerRawString ¶ added in v5.3.0
ToLowerRawString downcases a field so that comparisons do not need to be case-aware.
func ToUpperRawString ¶
ToUpperRawString upcases a field so that comparisons do not need to be case-aware.
func ValidArgs ¶
func ValidArgs(args []any)
ValidArgs panics if args looks like a variadic call that lost its spread operator somewhere up the call chain.
Many Make*() functions are declared `func(..., args ...any)` and forward to another variadic function. The forwarding call must use `f(..., args...)`. If the `...` is omitted, the called function sees args == []any{ []any{...} } i.e. a single element whose value is itself the original []any. The individual values are then never validated as strings/ints/etc., and the bug surfaces far from its cause.
ValidArgs catches exactly that shape: len(args) == 1 AND args[0] is a []any. We panic rather than return an error because the only way to produce this shape is a programmer mistake at a call site; tests will surface it loudly.
Types ¶
This section is empty.
Source Files