Use Cases: Sessions, Caches, Feature State, Rate Limits, Idempotency, and Coordination

Learning outcomes

AtlasMart now has several tempting “small-state” problems: web sessions, a checkout feature flag, API rate limits, payment idempotency, and a background worker lease. They all fit in key-value records, but they do not have identical correctness requirements. This lesson builds a per-use-case contract before choosing a primitive.

1. Sessions: expiration is product behavior

A session record typically needs a strong random identifier, user/tenant identity, authorization context, creation/last-activity time, and expiry. Decide whether session loss is tolerable, whether logout/revocation must be immediate, whether TTL slides on activity, and whether failover can expose an old authorization snapshot. Sensitive session values require encryption in transit, least-privilege access, and careful logging.

2. Feature state: simple reads, but changes may require governance

A boolean feature flag looks trivial, yet high-impact flags need versioning, actor/time audit, staged rollout dimensions, rollback, and sometimes strongly ordered writes. A local cached copy may be intentionally stale for seconds while a payment-kill switch may require tighter propagation. “Store it in a key-value database” does not answer the governance or freshness requirement.

3. Rate limits: atomic accounting at the chosen scope

A token bucket has capacity, current tokens, refill rate, and last-update time. The consume/refill transition must be atomic at the rate-limit scope. If traffic for one user is routed to independent counters on multiple nodes without coordination/merge semantics, each node can admit up to the full limit. Decide whether the limit is exact, approximate, regional, or global and how failover/retry affects the count.

4. Idempotency: same request identity, same effect/result

An idempotency record maps a stable request identifier to processing state/result for a defined retention window. A duplicate request should discover the original outcome instead of repeating the side effect. The key must be scoped to the caller/operation, inputs may need a fingerprint to reject accidental reuse with different payloads, and the record must live long enough to cover plausible retries.

A “set if absent” claim is only the beginning. Crash after the side effect but before recording success creates ambiguity unless the side effect and idempotency decision share an atomic boundary or reconciliation protocol.

5. Coordination: a lease without fencing can corrupt state

A distributed lease says an owner may act until expiry/renewal conditions fail. A paused owner can resume after its lease expired while a new owner has already acquired the resource. If the downstream storage accepts both, two owners act. A fencing token is a monotonically increasing generation number attached to operations; the resource rejects tokens older than the highest it has accepted. This turns stale ownership into a verifiable downstream rejection rather than trusting the old process to behave.

6. AtlasMart lab: five use cases, five contracts

The lab uses a logical TTL session, versioned feature state, token bucket, idempotency registry, and a coordination example. The unsafe lease path performs a duplicate shipment; the fenced resource accepts generation 42 and rejects stale generation 41.

from dataclasses import dataclass

class LogicalTTL:
    def __init__(self): self.now=0; self.items={}
    def tick(self,n=1): self.now += n
    def put(self,key,value,ttl): self.items[key]=(value,self.now+ttl)
    def get(self,key):
        item=self.items.get(key)
        if not item or self.now >= item[1]: return None
        return item[0]

class TokenBucket:
    def __init__(self, capacity, refill_per_tick):
        self.capacity=capacity; self.tokens=capacity; self.refill=refill_per_tick; self.last=0
    def allow(self, now, cost=1):
        elapsed=max(0,now-self.last)
        self.tokens=min(self.capacity,self.tokens+elapsed*self.refill); self.last=now
        if self.tokens < cost: return False
        self.tokens -= cost; return True

class IdempotencyRegistry:
    def __init__(self): self.results={}; self.charge_count=0
    def charge(self, request_id, amount):
        if request_id in self.results:
            return "replay", self.results[request_id]
        self.charge_count += 1
        result={"charge_id":f"ch-{self.charge_count:03d}","amount":amount}
        self.results[request_id]=result
        return "created", result

@dataclass
class Lease:
    owner: str
    token: int

class FencedResource:
    def __init__(self): self.last_token=0; self.value=[]
    def write(self, token, payload):
        if token < self.last_token:
            return False
        self.last_token=token; self.value.append((token,payload)); return True

print("SESSION WITH TTL")
sessions=LogicalTTL(); sessions.put("session:s1", {"user":"u42"}, ttl=3)
print("t0", sessions.get("session:s1")); sessions.tick(4); print("t4", sessions.get("session:s1"))

print("\nFEATURE STATE NEEDS VERSION/AUDIT WHEN CONSEQUENCES MATTER")
feature={"checkout-v2":{"enabled":False,"version":7}}
expected=7
if feature["checkout-v2"]["version"]==expected:
    feature["checkout-v2"]={"enabled":True,"version":8}
print("feature", feature["checkout-v2"])

print("\nTOKEN BUCKET RATE LIMIT")
b=TokenBucket(capacity=3, refill_per_tick=1)
for t in [0,0,0,0,1,1,2]:
    print("t",t,"allow",b.allow(t),"tokens",b.tokens)

print("\nIDEMPOTENCY RECORD")
idem=IdempotencyRegistry()
print(idem.charge("req-777", 50))
print(idem.charge("req-777", 50))
print("physical charges", idem.charge_count)

print("\nCOORDINATION: LOCK WITHOUT FENCING IS UNSAFE")
resource=[]
old_owner="worker-A"; new_owner="worker-B"
# A pauses; lease expires; B acquires and writes; then stale A resumes.
resource.append((new_owner,"ship order"))
resource.append((old_owner,"ship order AGAIN"))
print("without fencing", resource)

print("\nFENCING REJECTS STALE OWNER")
f=FencedResource()
lease_a=Lease("worker-A", 41)
lease_b=Lease("worker-B", 42)
print("B write", f.write(lease_b.token, "ship order"))
print("stale A write", f.write(lease_a.token, "ship order AGAIN"))
print("resource history", f.value)

SESSION WITH TTL
t0 {'user': 'u42'}
t4 None

FEATURE STATE NEEDS VERSION/AUDIT WHEN CONSEQUENCES MATTER
feature {'enabled': True, 'version': 8}

TOKEN BUCKET RATE LIMIT
t 0 allow True tokens 2
t 0 allow True tokens 1
t 0 allow True tokens 0
t 0 allow False tokens 0
t 1 allow True tokens 0
t 1 allow False tokens 0
t 2 allow True tokens 0

IDEMPOTENCY RECORD
('created', {'charge_id': 'ch-001', 'amount': 50})
('replay', {'charge_id': 'ch-001', 'amount': 50})
physical charges 1

COORDINATION: LOCK WITHOUT FENCING IS UNSAFE
without fencing [('worker-B', 'ship order'), ('worker-A', 'ship order AGAIN')]

FENCING REJECTS STALE OWNER
B write True
stale A write False
resource history [(42, 'ship order')]

7. Chapter synthesis and production decision record

Chapter 10 began with the key as an address/routing/atomicity contract, then moved through value representations and server-side operations, ephemeral lifetime semantics, authority/recovery boundaries, and finally common application patterns. The unifying principle is small API does not mean small correctness problem. Key-value systems are powerful when the invariant fits their atomic boundary and the loss/recovery contract is explicit.

Bridge to Chapter 11: The next chapter treats document databases as aggregate-oriented stores, where nested objects and arrays move more related state behind one document boundary but introduce new size, indexing, growth, embedding/reference, and schema-evolution tradeoffs.

Authoritative references

• Redis data types — current implementation examples for sessions/counters/sets/sorted sets/streams
• Redis transactions / WATCH — optimistic conditional-update example
• Redis keyspace / expiration — TTL and key naming example
• Redis sorted sets — current example including rate-limiter use cases
• Redis licenses — current Redis Open Source license options
• Valkey releases — current alternative implementation release reference