topology_hiding: keep the dialog-less state in a shared store (fixes long Contact / SUBSCRIBE)

[Lt-Flash]

Problem

When topology hiding runs without a dialog, the whole encoded state (route set, original Contact, flags, bind address) rides in the Contact URI parameter — making it long. Some UAs (e.g. Cisco CP-88xx) truncate it, after which topology_hiding_match() can't decode it and every sequential request of that call is lost. This is unavoidable for non-INVITE dialogs like SUBSCRIBE: dlg_create_dialog() is INVITE-only, so a SUBSCRIBE can never get a dialog to hold its state server-side, and the payload is dominated by the route set.

What this adds

An opt-in mode for the dialog-less path: when th_state_url points at a cachedb backend, the state is stored there under a short key and only the key travels in the Contact:

stateless:  ;thinfo=VG9JbzAdIFsyPz0MNS9yRmdPY31kQWFVd0djUGtSVF9CbzYQIFtiYWNBYEFzWmFbZmZiWQ--   (72 chars)
stateful:   ;thinfo=_9ea80d5443fe5c5a                                                           (17 chars)

The Contact stays short regardless of topology size, making SUBSCRIBE (and long route sets) workable on constrained endpoints. When th_state_url is unset, the encoding path is byte-for-byte unchanged. A call that does get a dialog never reaches this mode — the dialog holds its state and puts only the dialog id in the Contact, so force_dialog=1 is the better answer for calls; this mode serves what a dialog cannot.

The full detail — the marker-safety proof, the notifier-granted-expires handling, the measured TTLs, and the per-backend matrix — is in the module docs (admin.xml / README). This is the summary.

Design

• In-Contact path unchanged. A state that still rides in a Contact is XOR-obfuscated + word-encoded as before; a stored state skips both (pointless off the wire) and is kept as plain length-prefixed text. Decode tells them apart by a marker on the key; the restore logic is shared, not duplicated.
• The state is immutable (route set / contact / socket are fixed at call creation), so a plain KV store with a TTL is the right fit — no update or conflict path.
• One key per dialog leg, not per request. The key is derived (not random) from the leg it belongs to — the call-id + that party's own tag, keyed with the contact-encoding password — so every re-encode overwrites the same key. A live dialog holds exactly two states (one per leg) however often it refreshes; the password keeps the key unguessable from the clear-text call-id/tags. A message that cannot be keyed — no call-id, or no tag, as with the reply of an out-of-dialog transaction (a 200 OK to an OPTIONS keepalive carries a Contact but no To tag) — is simply not stored: its state stays inline in the Contact, and it has no sequential traffic to be matched against anyway.
• Coalesced writes. Since the state is immutable, a re-store only bumps the TTL. Each node keeps a small shm record of the expiry it last wrote per key and skips the backend write while the state still has enough life left — collapsing a busy dialog's identical writes into occasional refreshes. A write that would shorten a state (teardown) is never skipped.
• Availability. A sequential request may land on any node, so the backend must be shared (e.g. cachedb_redis); cachedb_local is fine for a single instance. The storage sits behind a small th_store.h interface (backend enum), so a clusterer-replication backend can be added later without touching the encode/decode sites.

State lifetime

A state is stored every time a Contact is encoded, but the deterministic key overwrites in place (no pile-up), and each write takes its TTL from the message, not a flat value:

Message	State lifetime
SUBSCRIBE / NOTIFY	subscription expires + 30 s (NOTIFY's granted Subscription-State wins, else Contact ;expires, else Expires)
expires 0 / Subscription-State: terminated	matched state dropped now; the outgoing Contact gets th_state_ttl_short (routes the final NOTIFY)
OPTIONS / MESSAGE / INFO / PUBLISH	th_state_ttl_short (default 60) — transaction-only, no target refresh
INVITE / UPDATE with session timers	Session-Expires + 30 s (the Expires ring timeout is deliberately not used)
INVITE / UPDATE without session timers	not stored — stays inline in the Contact (a call bounded by nothing must not be able to expire)
any message that cannot be keyed (no call-id/tag, e.g. an OPTIONS 200 OK with no To tag)	not stored — stays inline in the Contact
anything else	th_state_ttl (default 3600)

A message that carries its dialog's lifetime also refreshes the state it was sent to, in place — so a long-lived subscription that only ever re-SUBSCRIBEs doesn't lose the state it keeps using. An in-dialog OPTIONS does not refresh (its short TTL would otherwise cut a call to a minute). All of this is measured end-to-end against Redis; the full TTL / refresh / notifier-granted tables and the _-marker safety proof are in the docs.

Security

The stored state is in the clear — not encrypted, and (unlike the in-Contact copy) not obfuscated — so anyone who can read the backend sees the topology this hides (real Contact, route set, receiving socket). This is intentional: off the wire the obfuscation/encoding serve no purpose, and plain text is inspectable. The store is expected to be a trusted, internal backend reachable only by the OpenSIPS nodes that share it — deploy it on a private / DMZ network, bind it to the internal interface, enable the backend's own auth, and do not point th_state_url at anything reachable beyond that trust boundary.

Backend compatibility

Any cachedb backend that honours the expires argument of set() (and provides remove()) works — verified against cachedb_redis and cachedb_local, and applies to memcached / cassandra / couchbase / dynamodb / sql. cachedb_mongodb silently ignores the TTL (states would never expire), so it is rejected at startup by a URL-scheme check (the cachedb interface has no "supports expiration" capability — a general gap left out of this PR).

Configuration

loadmodule "cachedb_redis.so"
loadmodule "topology_hiding.so"
modparam("topology_hiding", "th_state_url", "redis://127.0.0.1:6379/0")  # shared, TTL-expiring backend
modparam("topology_hiding", "th_state_ttl", 3600)        # calls with no bound + fallback
modparam("topology_hiding", "th_state_ttl_short", 60)    # OPTIONS/MESSAGE/INFO/PUBLISH

route {
    if (has_totag()) {
        if (!topology_hiding_match())
            xlog("L_WARN", "no topology hiding state for $ru\n");
    } else {
        record_route();
        topology_hiding();   # works for SUBSCRIBE, no dialog needed
    }
}

cachedb_local:// (single instance) and a password-protected redis://:pass@host/db cluster are also supported.

Testing

Against cachedb_redis (and cachedb_local, confirming backend-agnostic):

• A dialog-less SUBSCRIBE gets its state stored; the Contact param shrinks 72 → 17 chars (a 16-hex key plus its _ marker); a sequential request carrying only the key is matched, decoded, and the R-URI restored to the original endpoint.
• Stateless mode unchanged — same 72-char Contact, nothing written.
• Per-message TTLs measured correct (subscription expires, session timers, short-TTL for OPTIONS, teardown removal, notifier-granted correction); the mongodb:// guard refuses startup.

Roadmap (not in this PR)

• Clusterer replication backend — keep states in shm and replicate to peers (mirroring dlg_replication.c), for deployments that don't want an external store in the signalling path; the immutable state makes it simpler (create / read / expire only).
• A CACHEDB_CAP_EXPIRES capability so TTL-ignoring backends are rejected through the interface rather than by a URL-scheme match (touches the core plus every backend).

Notes

• New files th_store.c / th_store.h; docs + regenerated README included. th_state_url declares a cachedb_url dependency so the backend module loads first.

[Lt-Flash]

Hi, whenever you have a moment, could I kindly ask for a review of this PR? I'd really appreciate it.

I'll hold off on any further commits until the review is complete, so the branch stays stable for you to look at.

Thanks very much for your time!