docs: reorder & testing

gateway/internal/session/session.go

@@ -14,13 +14,29 @@ var (
 )
 
 // Cache resolves authenticated device-session state from the gateway
-// hot path. The implementation dropped the previous Redis projection: the only
-// implementation is *BackendCache, which calls backend's
-// `/api/v1/internal/sessions/{id}` synchronously per request.
+// hot path. The canonical implementation is *MemoryCache: a
+// process-local LRU + TTL store that falls back to backend's
+// `/api/v1/internal/sessions/{id}` on miss and listens for
+// `session_invalidation` push events from backend so revoked sessions
+// are reflected immediately without a fresh backend lookup.
+//
+// The Mark* methods are called by the push dispatcher. They flip
+// cached entries to revoked status; subsequent Lookups serve the
+// revoked record directly so authenticated traffic on those sessions
+// is rejected at the edge before reaching backend.
 type Cache interface {
 	// Lookup returns the cached record for deviceSessionID. Implementations must
 	// wrap ErrNotFound when the cache does not contain the requested record.
 	Lookup(ctx context.Context, deviceSessionID string) (Record, error)
+
+	// MarkRevoked flips the cached record for deviceSessionID to a
+	// revoked status. Calling on a missing entry is a no-op.
+	MarkRevoked(deviceSessionID string)
+
+	// MarkAllRevokedForUser flips every cached record belonging to
+	// userID to a revoked status. Calling on a user with no cached
+	// sessions is a no-op.
+	MarkAllRevokedForUser(userID string)
 }
 
 // Status identifies the cached lifecycle state of a device session.