0005-DNS change proposal: Cache names longer with confidence

proposals/0005-dns.md

@@ -65,6 +65,8 @@ The first option is to set a DNS TXT record at the domain which maps to a "key"-
 datkey={key}
 ```
 
+The minimum TTL is `1800` (30 minutes). TTL durations of weeks and months are encurraged to reduce the dependency on DNS unless you expect to change your Dat key. Start out with a short TTL and increase it over time.
+
 ## .well-known/dat
 [usage-wellknown-dat]: #usage-wellknown-dat
 
@@ -75,24 +77,24 @@ dat://{key}
 TTL={time in seconds}
 ```
 
-`TTL` is optional and will default to `3600` (one hour). If set to `0`, the entry is not cached.
+`TTL` is optional and will default to `1800` (30 minutes). This is also the minimum TTL. TTL durations of weeks and months are encurraged to reduce the dependency on your HTTPS Server unless you expect to change your Dat key. Start out with a short TTL and increase it over time.
 
 
 # Resolution process
 [resolution-process]: #resolution-process
 
 Resolution of a Dat at `dat://{name}` should follow this process:
 
- - Client checks its names cache. If a non-expired entry is found, return with the entry.
- - Client issues a DNS TXT request for `name`. This request should be issued via a secure transport (see ["DNS-over-HTTPS"](#dns-over-https)).
+- Client issues a DNS TXT request for `name`. This request should be issued via a secure transport (see ["DNS-over-HTTPS"](#dns-over-https)).
  - Client iterates all TXT records given (skip if none). If a record's value matches the TXT record schema (see below):
-   - If the record includes a non-zero TTL, store the record value in the names cache.
+   - Cache the record as described below.
    - Return the record value.
  - Client issues an HTTPS GET request to `https://{name}/.well-known/dat`.
    - If the server responds with a `404 Not Found` status, client stores a `null` entry in the names cache with a TTL of 3600 and returns a failed lookup.
    - If the server responds with anything other than a `200 OK` status, return a failed lookup.
    - If the server responds with a malformed file (see below), return a failed lookup.
-   - If the server responds with a well-formed file, store the record value in the names cache (default TTL to `3600` if not provided) and return the record value.
+   - If the server responds with a well-formed file, cache the record as described below, and return the record value.
+
 
 The DNS TXT record must match this schema:
 
@@ -110,6 +112,32 @@ The `/.well-known/dat` file must match this schema:
 Note that DNS-record responses may not follow a pre-defined order. Therefore the results of a lookup may be undefined if multiple TXT records exist.
 
 
+Name cache lookup process:
+
+Name cache entries have four qualifiers: origin (domain name : port), Dat key, first seen timestamp, and expiration timestamp. Timestamps are in seconds since the Unix epoch.
+
+- Client must check if the origin is in the cache.
+  - If the origin is not in the cache, client must perform resolution for the origin using the method described above.
+    - If the domain doesn't resolve, the cache lookup returns a failed lookup.
+    - If the domain resolves: cache the origin and Dat key; set the current time as first seen timestap, and set the expiration timestamp to exactly 30 minutes.
+  - If the origin is in the cache, the client must check the expiration timestamp.
+    - If it's now or in the future, return the cached Dat key.
+      - Clients may opportunistically asyncronously renew cached entries that are ten minutes or less from expiring.
+    - If it's in the past, the client must resolve the origin using the method described above.
+      - If the resolution fails due to a server error (HTTP status code 5XX) or a connection time out, or the server is unreachable, and the expiration time is less than one week ago, return the cached Dat key.
+      - If the resoluton fails for any other reason or the expiration time is more than one week ago, then the name record should be deleted from the cache and return a failed lookup.
+      - If the resolution succeeded then the client must compare the previously cached Dat key to the newly resolved Dat key.
+        - If the two keys differ, then the cached key is replaced: set the current time to the first seen timestamp, and set the expiration timestamp to exactly 30 minutes.
+         - If the two keys are identical, renew the cache expiration timestamp using the following algorithm:
+
+           `currentTime + max(30min, min(TTL, min(6months, (currentTime - firstSeen) * 2)))`
+           - Compare these two numbers and choose the smaller. First number: Subtract the first seen timestamp from the current time and multiply by two; add the resulting number to the current timestamp. Second number: add the resolved TTL to the current time.
+             - Adjust the number to be at least 30 minutes in the future and no more than 6 months.
+             - Set the resulting number as the new expiration timestamp.
+         - Return the resolved Dat key.
+- Client should remove expired entries 30 days after expiration.
+- Client may discard the first seen timestamp by setting it to 0 after six months.
+
 # Security and Privacy
 [security-and-privacy]: #security-and-privacy
 
@@ -163,6 +191,7 @@ Whereas traditional DNS leaks name lookups to everyone on the network, DNS-over-
 # Changelog
 [changelog]: #changelog
 
+- 2019-02-18: Increase resolution caching time linearly as cofidence in resolved result increases.
 - 2018-04-27: First complete draft submitted for review
 - 2018-05-07: Add "Security and Privacy" section and rewrite DNS TXT record schema.
 - 2018-05-16: Merged as Draft after WG approval.