WIP ArNS caching ADR

docs/madr/002-arns-cache-timing.md

@@ -0,0 +1,59 @@
+# ArNS Cache Timing
+
+- Status: proposed
+- Deciders: [David]
+- Date: 2024-12-09
+- Authors: [David]
+
+## Context and Problem Statement
+
+ArNS resolution requires multiple AO process interactions. Caches are used in
+this process to reduce response latency and AO CU load. There is an intrinsic
+trade-off between reducing response latency and AO CU load and the freshness of
+ArNS responses. In order to allow gateway operators to opimtize these
+trade-offs we need to define the levels of caching involved and make them
+configurable. The purpose of this ADR is to show the levels of caching and
+define the relevant timeouts involved.
+
+## Decision Outcome
+
+### Resolution Flow
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart TD
+    Start([Resolution Requested]) --> CDN[CDN]
+    CDN --> CDNStatus{"CDN Cache Status"}
+    CDNStatus -->|Hit| Resolution
+    CDNStatus -->|Miss| NameCache
+
+    subgraph Gateway ["AR.IO Gateway"]
+        NameCache["Name List Cache"]
+
+        NameCache --> ListStatus{"Name List Status"}
+        ListStatus -->|Up-to-date| ANTCache["ANT State Cache"]
+        ListStatus -->|"Stale (name list TTL expired)"| IO["IO AO Process"]
+        ListStatus -->|Not Cached| IO
+
+        ANTCache --> StateStatus{"ANT State Status"}
+        StateStatus -->|"Stale (name TTL expired)"| ANT["ANT AO Process"]
+        StateStatus -->|Not Cached| ANT
+
+        IO -->|"Update Cache <debounced>"| NameCache
+        ANT -->|"Update Cache <debounced and concurrency limited>"| ANTCache
+    end
+
+    StateStatus -->|Up-to-date| Resolution([Resolution Returned])
+
+    style Start fill:#ff69b4,stroke:#333
+    style CDN fill:#4169e1,stroke:#333
+    style NameCache fill:#4169e1,stroke:#333
+    style IO fill:#4169e1,stroke:#333
+    style ANT fill:#4169e1,stroke:#333
+    style ListStatus fill:#ff69b4,stroke:#333
+    style ANTCache fill:#4169e1,stroke:#333
+    style StateStatus fill:#ff69b4,stroke:#333
+    style Resolution fill:#ff69b4,stroke:#333
+    style CDNStatus fill:#ff69b4,stroke:#333
+
+```