Document the IPv4-in-IPv6 tail helper contract so callers cannot treat it as a general search routine and skip the validations its parent function depends on.

# Antipattern: undocumented IPv4-in-IPv6 tail helper

Classification: Antipattern (with corrected pattern guidance)

Context: `runtime/mmanon.c` IPv6 anonymization helpers

Why it matters: The helper is logically an internal slice of a larger routine. Without explicit preconditions, callers may treat it as a general search helper and skip the validations the parent routine depends on, leading to undefined behavior on malformed literals.

Steps (improved pattern):

1. Document that the caller must pass a substring beginning at the first IPv6 hex group and a dot position that is guaranteed to belong to the embedded IPv4 tail.

2. State that the substring must contain a `:` before the dot so the helper can return the IPv4 start offset.

3. Assert in unreachable fallbacks instead of returning `-1` to catch precondition violations early while keeping a compiler-placating return.

Before (antipattern):

    static size_t findV4Start(const uchar *const __restrict__ buf, size_t dotPos) {
        while (dotPos > 0) {
            if (buf[dotPos] == ':') {
                return dotPos + 1;
            }
            dotPos--;
        }
        return -1;  // should not happen
    }

After (pattern with explicit contract):

    /**
     * Locate the start offset of the IPv4 tail inside an embedded IPv4-in-IPv6
     * literal. The caller must pass the substring that begins at the first hex
     * group of the IPv6 address and a dot position that is guaranteed to belong
     * to the IPv4 tail; this routine is not a general-purpose search helper.
     * The substring must contain a ':' before the provided dot index.
     */
    static size_t findV4Start(const uchar *const __restrict__ buf, size_t dotPos) {
        while (dotPos > 0) {
            if (buf[dotPos] == ':') {
                return dotPos + 1;
            }
            dotPos--;
        }
        assert(!"embedded IPv4 must have a ':' before its first '.'");
        return 0;  // placate compilers when assertions are disabled
    }

References:

- `runtime/mmanon.c` embedded IPv4 parsing helper (to be updated with this contract).

- Pattern: document contracts for externalized helpers for the general pattern of documenting narrow helper contracts and defensive fallbacks.

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.