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):

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.
State that the substring must contain a : before the dot so the helper can return the IPv4 start offset.
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).
practice-externalized-helper-contracts 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