laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-10-05 19:18:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(gateway): describe the virtual-IP pool state machine as the code runs it

Browse Source 
A DNS query for a draining mapping now returns it to Allocated with a
fresh TTL, so the design document gains that transition. The rest of
the section is brought in line with the pool's tick at the same time:
an allocated mapping that times out drains before it is freed rather
than being freed directly, traffic that resumes during the grace period
returns a draining mapping to Active, and a mapping only drains once it
has no sessions, since sessions refresh it at every tick.
This commit is contained in:
Johnathan Corgan
2026-09-28 14:35:50 +00:00
parent d388c709c3
commit 94a16ae19b
1 changed files with 23 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/fips-gateway.md
+23 -13
View File
@@ -231,34 +231,44 @@ The pool tracks state per address:
```text
Allocated ──→ Active ──→ Draining ──→ Free
│ ▲
└──────────────────────────────────┘
(TTL expired, no sessions)
│ ▲
└───────────────────────┘
(TTL expired, no sessions)
Draining ──→ Active traffic resumes before the grace period ends
Draining ──→ Allocated a DNS query for the name
```
| State | Meaning |
| ----- | ------- |
| Allocated | DNS query created the mapping; no NAT sessions yet. |
| Allocated | DNS query created or renewed the mapping; no NAT sessions yet. |
| Active | Conntrack reports at least one session for this virtual IP. |
| Draining | TTL has expired; sessions may still be in progress, or grace period is running after sessions ended. |
| Draining | TTL has expired with no sessions; the grace period is running. |
| Free | Reclaimed and available for new allocations. |
Transitions:
- **Allocated → Active**: conntrack sessions count goes above zero.
- **Allocated → Free**: TTL expires before any session is ever
- **Allocated → Draining**: TTL expires before any session is
observed.
- **Active → Draining**: TTL expires (sessions may or may not still
be present).
- **Draining → Free**: session count is zero and the grace period
has elapsed since draining began.
- **Active → Draining**: TTL expires after the last session ends.
Sessions refresh the mapping at every tick, so a mapping in use
does not drain.
- **Draining → Active**: conntrack reports a session again before
the grace period ends. The next drain starts a fresh grace period.
- **Draining → Allocated**: a DNS query for the name, with or
without an address in the answer. The client may now hold a fresh
TTL, so reclamation is cancelled: the mapping gets the full TTL
and, if it stays idle, a fresh grace period.
- **Draining → Free**: the grace period has elapsed since draining
began with no session seen.
Timing:
- **TTL** (`gateway.dns.ttl`, default 60 s) is both the DNS TTL
returned to the client and the mapping's idle lifetime. Repeated
DNS queries for the same destination refresh the
`last_referenced` timestamp.
returned to the client and the mapping's idle lifetime. A DNS
query for a mapped name refreshes the mapping's idle clock, and
so do conntrack sessions at each tick.
- **Grace period** (`gateway.pool_grace_period`, default 60 s) is
the dwell time after the last session ends before the address is
recycled. It prevents immediate reuse from confusing hosts with