1817891 - Add in-tree documentation that explains the Cache API disk layout and the "morgue" directory misnomer

Status: NEW

(Core :: Storage: Cache API, enhancement, P3)

Description

[Andrew Sutherland [:asuth] (he/him)]

The Cache API storage using the directory name "morgue" leads to continual (legitimate!) confusion about the contents of the directory. The storage is in fact active; Response body files only exist on disk as long as there is an entry in the Cache database OR there are live refcounts for the Response that had been fetched from the database. At no time does the Cache API implementation intentionally retain files that are not reachable.

Note that crashes do create a situation where response bodies that were only being held alive by refcounts will need to be cleaned up, but this is handled at next initialization. (And in particular, this is something the documentation should cover.)