Use OS provided cache home to store cached files

[mojavelinux]

I recently (re)discovered the XDG basedir standard, which specifies a standard location for storing cache files for an application (particularly on Linux). I think Asciidoctor Diagram should follow this standard where possible.

The logic is pretty simple. The application directory should be created inside the directory specified by XDG_CACHE_HOME, which is typically ~/.cache. In our case, the location would be $XDG_CACHE_HOME/asciidoctor/diagram.

In the event this environment variable is not specified, there are generally accepted fallbacks which can be found in the xdg-basedir npm package. See https://github.com/sindresorhus/xdg-basedir/blob/master/index.js

[mojavelinux]

We might also consider allowing the cache to be specified explicitly using an attribute such as asciidoctor-cachedir. This would override the default location.

[mojavelinux]

The benefit of making this change is that cache directories don't get spread all over the place, which primarily comes into place when using Asciidoctor Diagram in a site generator.

[pepijnve]

I generalised this issue to one where we use the OS provided user cache directory, not just the XDG stuff on Linux.

• Linux: $XDG_CACHE_HOME/asciidoctor/diagram; XDG_CACHE_HOME defaults to ~/.cache if not specified. See https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
• macOS: ~/Library/Caches/asciidoctor/diagram. See https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html
• Windows: %LOCALAPPDATA%/asciidoctor/diagram. Hard to find detailed information on this. See https://msdn.microsoft.com/en-us/library/windows/desktop/ms723686(v=vs.85).aspx and https://en.wikipedia.org/wiki/Environment_variable#LOCALAPPDATA

[mojavelinux]

Exactly!

[pepijnve]

Couple of implementation details that need to be figured out:

• Should this only be used if the safe mode allows it? By default we'll be escaping the jail
• What do we use as cache key? At the moment the cache logic assumes it's per document and uses the image name as key. In the case of a shared cache for multiple documents we need some conflict resolution scheme.

[mojavelinux]

Should this only be used if the safe mode allows it? By default we'll be escaping the jail

Since it's a well-defined location that's generally accepted as read/write, I think it's fine in this case. But if we want to be absolutely strict, then we'd have to require the use of unsafe mode. But seeing that no other program imposes that kind of requirement, I think that would be overkill.

What do we use as cache key? At the moment the cache logic assumes it's per document and uses the image name as key.

I think we can continue doing that. We're really just talking about where the base directory is, so the cache doesn't get scattered across the filesystem.