Module redis_schema 

The Redis key schema (spec section 08, interop): every key pattern, every value format, and the ban-key migration, byte-compatible with the Go and Python family ports.

A Rust deployment pointed at the same Redis as a Python guard-core or a Go port MUST interoperate byte-for-byte: shared bans, shared counters, shared caches. This module is the pure half - the key builders and the value codecs; the wire half lives in the facade’s redis_store (the redis feature), which drives these shapes over a real connection.

Key namespace

Every key is prefix + namespace + ":" + key (plain concatenation, no normalization; the namespace itself may carry : and so may the inner key). The default prefix is guard_core:. sha256hex(x) is the lowercase hex SHA-256 of the UTF-8 encoding (identity_hash).

Pattern	Type	Builder
{P}rate_limit:rate:{ip}	zset	crate::distributed::rate_window_key
{P}rate_limit:rate:{ip}:{sha256hex(path)}	zset	crate::distributed::rate_window_key_endpoint
{P}banned_ips:{ip}	string	crate::distributed::ban_key
{P}banned_networks:{cidr}	string	ban_network_key
{P}behavior_usage:behavior:usage:{sha256hex(endpoint)}:{sha256hex(ip)}	zset	behavior_usage_key
{P}behavior_returns:behavior:return:{sha256hex(endpoint)}:{sha256hex(ip)}:{sha256hex(pattern)}	zset	behavior_return_key
{P}security_headers:csp_config / hsts_config / custom_headers	string (JSON)	security_headers_config_key
{P}patterns:custom	string	patterns_custom_key
{P}ipinfo:database	string	ipinfo_database_key
{P}cloud_ranges_v2:{provider}	string	cloud_ranges_key
{P}cloud_ip_v2:{provider}	string (JSON)	cloud_ip_key
{P}dynamic_rules:last_known	string	dynamic_rules_last_known_key

The behavior keys’ double segment (behavior_usage:behavior:usage:) is a verbatim reference oddity: namespace plus an in-key literal prefix. Do not clean it up.

Value formats

• banned_ips / banned_networks: the ban expiry as the Go FormatFloat(expiry, 'f', -1, 64) decimal string (format_expiry), read back with a plain float parse and now <= expiry (the reference _check_redis_exact).
• behavior zsets: member = 32 lowercase hex chars (random_member), score = the float epoch; pruning is the exclusive ZREMRANGEBYSCORE key "-inf" "({window_start" bound (exclusive_prune_bound).
• patterns:custom: the custom patterns joined with , (encode_patterns_custom); restored by splitting on , (decode_patterns_custom).
• cloud_ranges_v2: comma-joined, lexically sorted "<network>" / "<network>|<region>" entries (encode_cloud_ranges / decode_cloud_ranges); <network> is the canonical masked CIDR string (canonical_network_string), an unparseable prefix decodes as a corrupt-cache error, not a skip.
• cloud_ip_v2: a JSON array of CIDR strings, sorted lexically (encode_cloud_ip_v2 / decode_cloud_ip_v2); a non-list or undecodable payload is a cache miss.
• ipinfo:database: the full MaxMindDB file bytes carried as the latin-1 string of their byte values (latin1_to_wire / wire_to_latin1).
• security_headers:*: json.dumps of the config object (encode_json_object).
• dynamic_rules:last_known: the snapshot payload stored verbatim, no TTL.

Legacy ban-key migration

migrate_legacy_ban_keys is the versioning bridge for IP canonicalization changes (the reference _ipban_migration.py, via the Go port’s migrateLegacyBanKeys): SCAN the {P}banned_ips:* keys, canonicalize each raw IP segment, skip keys already canonical, move the longer expiry to the canonical key (SET ... PX old_pttl) when the canonical key’s remaining TTL is shorter, and delete the legacy key. Failures never fail startup: callers log and continue.

Example

use guard_core_engine::redis_schema::*;

// The key grammar, byte-identical to the Python and Go ports.
assert_eq!(
    ban_network_key("guard_core:", "10.9.9.9/8").expect("valid cidr"),
    "guard_core:banned_networks:10.0.0.0/8"
);
assert_eq!(
    patterns_custom_key("guard_core:"),
    "guard_core:patterns:custom"
);

// The ban expiry value: the Go FormatFloat('f', -1) decimal string.
assert_eq!(format_expiry(1060.0), "1060");

// The cloud ranges round-trip, sorted and comma-joined.
let payload = encode_cloud_ranges(&[
    (String::from("203.0.113.0/24"), Some("us-east")),
    (String::from("198.51.100.0/24"), None),
]);
assert_eq!(payload, "198.51.100.0/24,203.0.113.0/24|us-east");

Structs

CloudRangeDecodeError

A corrupt cloud_ranges_v2 payload.

Constants

CLOUD_IP_NAMESPACE

The cloud IP store protocol namespace (cloud_ip_v2:{provider}).

CLOUD_RANGES_NAMESPACE

The cloud ranges cache namespace (cloud_ranges_v2:{provider}).

CLOUD_RANGES_TTL_DEFAULT_SECONDS

The cloud ranges cache TTL default (the reference ttl param).

CSP_CONFIG_KEY

The CSP config key segment (security_headers:csp_config).

CUSTOM_HEADERS_KEY

The custom-headers key segment (security_headers:custom_headers).

DEFAULT_REDIS_PREFIX

The default key prefix (SecurityConfig.redis_prefix).

DYNAMIC_RULES_NAMESPACE

The dynamic-rules namespace and last-known key (dynamic_rules:last_known, no TTL).

HSTS_CONFIG_KEY

The HSTS config key segment (security_headers:hsts_config).

IPINFO_DATABASE_KEY

The ipinfo database key segment.

IPINFO_DATABASE_TTL_DEFAULT_SECONDS

The GeoIP database cache TTL default (the reference constructor max_age).

IPINFO_NAMESPACE

The GeoIP database cache namespace and key (ipinfo:database).

LAST_KNOWN_RULES_KEY

The last-known-rules key segment.

PATTERNS_CUSTOM_KEY

The custom-patterns key segment.

PATTERNS_NAMESPACE

The custom-pattern registry namespace and key (patterns:custom).

SECURITY_HEADERS_NAMESPACE

The security-headers config namespace.

SECURITY_HEADERS_TTL_SECONDS

The security-headers config TTL in seconds (the reference _cache_configuration).

Traits

RedisAdminStore

The admin surface the legacy ban-key migration needs (the reference RedisAdmin, the sync seam pattern of crate::distributed).

Functions

ban_network_key

The {prefix}banned_networks:{cidr} key: a CIDR ban, stored under the canonical network string (host bits cleared, the reference str(ipaddress.ip_network(cidr, strict=False))).

behavior_return_key

The behavior return-patterns zset key.

behavior_usage_key

The {prefix}behavior_usage:behavior:usage:{sha256(endpoint)}:{sha256(ip)} zset key: the reference behavior usage rules.

canonical_network_string

The canonical network string of a bare IP or CIDR entry.

canonicalize_ip_string

The string-level IP canonicalization the migration runs on each scanned key segment (_canonicalize_ip / the Go CanonicalizeIP).

cloud_ip_key

The {prefix}cloud_ip_v2:{provider} key: the cloud IP store protocol.

cloud_ranges_key

The {prefix}cloud_ranges_v2:{provider} key: the cloud-range cache.

decode_cloud_ip_v2

Decode the cloud_ip_v2 payload: Some(ranges) for a JSON array of strings, None for anything else.

decode_cloud_ranges

Decode the cloud_ranges_v2 payload into (networks, regions).

decode_json_object

Decode a JSON object payload into its string pairs (the custom_headers load arm). None when the payload is not an object of strings.

decode_patterns_custom

Split the registry payload back into patterns (the reference cached_patterns.split(",")).

dynamic_rules_last_known_key

The {prefix}dynamic_rules:last_known key: the last-known dynamic rules snapshot (persisted, no TTL).

encode_cloud_ip_v2

The cloud_ip_v2 payload: json.dumps(sorted(ranges)).

encode_cloud_ranges

The cloud_ranges_v2 payload: comma-joined, lexically sorted entries.

encode_json_object

A JSON object payload (json.dumps of a name -> value mapping), the security_headers:* config value shape. The pairs are written in the given order (Python dict insertion order).

encode_patterns_custom

The custom-pattern registry payload: the patterns joined with , (the reference ",".join(custom_patterns)).

exclusive_prune_bound

The behavior window’s prune bound: "(x", the exclusive lower bound.

format_expiry

The ban expiry string, the Go port’s FormatFloat(expiry, 'f', -1, 64) decimal form.

full_key

{prefix}{namespace}:{key}: the reference namespaced helper’s plain concatenation.

ipinfo_database_key

The {prefix}ipinfo:database key: the GeoIP DB cache.

latin1_to_wire

The ipinfo:database wire encoding: the MaxMindDB file bytes read as the latin-1 string of their byte values.

migrate_legacy_ban_keys

The legacy ban-key migration (the reference _ipban_migration.py, via the Go port’s migrateLegacyBanKeys).

migrate_one_ban_key

One key’s migration pass. Ok(false) when the key was already canonical (untouched), Ok(true) when it was migrated or dropped.

patterns_custom_key

The {prefix}patterns:custom key: the custom-pattern registry.

random_member

A fresh zset member: 32 lowercase hex chars, 16 random bytes hex-encoded.

security_headers_config_key

The {prefix}security_headers:{segment} config key for one of CSP_CONFIG_KEY, HSTS_CONFIG_KEY, CUSTOM_HEADERS_KEY.

wire_to_latin1

Recover the binary GeoIP database from the cached string.