CLI: User-specific configuration paths

[amdprophet]

We need to decide on where we store user-specific configuration, data, and cache for applications such as sensu-cli.

I believe that we've figured out what the paths will be on Windows & Linux (I'd still love feedback) but I'm conflicted on which direction we should take for macOS.

I'm hoping to get some opinions from everyone so that we can get a sense of what people prefer.

Just as a note, all of these defaults should/will be able to be overridden with various environment variables.

[amdprophet]

Linux/BSD

$XDG_CONFIG_HOME/sensu/sensu-cli

• Where user-specific configurations should be written (analogous to /etc).
• Should default to $HOME/.config.

$XDG_CACHE_HOME/sensu/sensu-cli

• Where user-specific non-essential (cached) data should be written (analogous to /var/cache).
• Should default to $HOME/.cache.

$XDG_DATA_HOME/sensu/sensu-cli

• Where user-specific data files should be written (analogous to /usr/share).
• Should default to $HOME/.local/share.

$XDG_RUNTIME_DIR/sensu/sensu-cli

• Used for non-essential, user-specific data files such as sockets, named pipes, etc.
• Not required to have a default value; warnings should be issued if not set or equivalents provided.
• Must be owned by the user with an access mode of 0700.
• Filesystem fully featured by standards of OS.
• Must be on the local filesystem.
• May be subject to periodic cleanup.
• Modified every 6 hours or set sticky bit if persistence is desired.
• Can only exist for the duration of the user's login.
• Should not store large files as it may be mounted as a tmpfs.

NOTE As $XDG_RUNTIME_DIR does not have a default, it seems that people will sometimes use patterns similar to /tmp/servicename-$USER but systemd-based distros require the directories to exist in /run/user/$USER/service.

Read more: https://wiki.archlinux.org/index.php/XDG_Base_Directory_support

Why?

• The XDG standard, for the most part, is what seems to be universally accepted.
• Used by most applications (GNOME, KDE, & XFCE as a start).

If you're happy with this proposal vote with a :+1: otherwise vote with a :-1:

[amdprophet]

Windows

%APPDATA%\sensu\sensu-cli

• Usually C:\Users\<User>\AppData\Roaming\sensu\sensu-cli
• Used for configuration files.
• Roaming-friendly.

%LOCALAPPDATA%\sensu\sensu-cli

• Usually C:\Users\<User>\AppData\Local\sensu\sensu-cli
• Used for intermediate data and downloaded files.
• Not part of roaming profiles.

%LOCALAPPDATA%\sensu\sensu-cli\cache

• Usually C:\Users\<User>\AppData\Local\sensu\sensu-cli\cache
• Used for cached (ephemeral) data and should be safe to delete.
• Not part of roaming profiles.

Why?

• This is where Microsoft intends for developers to store files.
• Roaming profile friendly.
  • Configs stay accessible on any PC you log into within an Active Directory domain.
• Not bound to a drive letter.
• We ought to send some love to our Windows sysadmin friends! :heart:

If you're happy with this proposal vote with a :+1: otherwise vote with a :-1:

[amdprophet]

macOS

Please suggest additional pros & cons if you feel I've left something out.

1. Use the same paths as Linux (XDG)

A few pros

• This is the method that numerous CLI apps use (such as direnv, gcloud, htop, and keybase).
• More consistency across UNIX-like operating systems
  • Less documentation.
  • (however, our documentation solution should make any variances easy to add)

A few cons

• Not the "proper" paths as deemed by Apple.
• Not compatible with the Apple App Store.
  • (not currently a concern, but might cause an issue down the road.)
• At least a couple of projects that do not use, or improperly use, OS-recommended paths have received criticism from the community about it.
  • Atom (https://github.com/atom/atom/issues/8281)
  • Electron (https://github.com/electron/electron/issues/8124)

2. Use the paths that Apple wants developers to use

As per Apple's Recommendations:

$HOME/Library/Application support/sensu/sensu-cli

• Stores app-created support files.
• Can include data files, configuration files, and templates.
• Can be automatically backed up by Time Machine & iCloud.
  • Large files can be prevented from being backed up by using a system call.
  • Required for large files that can be re-created or downloaded.

$HOME/Library/Caches/sensu/sensu-cli

• Stores cache files.
• Cache data can be used for any data that needs to persist longer than temporary data.
• Not to be used for long-term support files.
• Generally, application should not require cache data to operate properly.
• Note that the system may delete the Caches/ directory to free up disk space, so your app must be able to re-create or download these files as needed.

NOTE In the case of sensu-cli:

• User configuration might be stored in:
  • $HOME/Library/Application Support/sensu/sensu-cli/
• Cache data would be stored in:
  • $HOME/Library/Caches/sensu/sensu-cli/

A few pros

• This is what is recommended in Apple's documentation.
  • They've historically said, "Do not pollute user space"
  • Jeff Atwood wrote a piece on this. (https://blog.codinghorror.com/dont-pollute-user-space/)
• Most multi-platform path helper frameworks & libraries favour the OS defaults.
  • Qt (http://doc.qt.io/qt-5/qstandardpaths.html)
  • Unity (https://docs.unity3d.com/ScriptReference/Application-persistentDataPath.html)
  • A few Python libraries.
  • e.g. https://github.com/ActiveState/appdirs
  • A few Go libraries.
  • e.g. https://github.com/shibukawa/configdir
  • Rust has an RFC for doing this in stdlib. (https://github.com/rust-lang/rfcs/issues/1159)
  • Rust's app_dirs crate. (https://docs.rs/app_dirs/1.1.1/app_dirs/)
• Won't require much in terms of additional documentation variances.

A few cons

• More documentation required.
• More knowledge required to manage a Sensu install across multiple operating systems.

Read more: https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html

Vote with 🎉 for using the XDG standard and :heart: for using macOS standard

[amdprophet]

I voted for the macOS standard as I personally feel that adhering to the various principles in each OS will make us more responsible members of each community. We implemented many of the OS guidelines with the ruby-based Sensu software on macOS, FreeBSD, Solaris, and AIX. Now that we no longer have a dependency on ruby I'm positive that we can do an even better job.

[jamesdphillips]

My argument against it would be that it's:

• where CLI applications are concerned on macOS using ~/Library/Config is unconventional. Kubernetes, AWS, GCE, heroku, git, dropbox, vim, emacs, zsh, tmux, yarn, npm, ruby gems, and more all use the home directory
  • as such it hurts our customer's understanding of where configuration is stored
  • I (personally) prefer that the configuration can be stored in my dotfiles; meaning I can easily take to unix, etc.

[amdprophet]

@calebhailey suggested the following when we last spoke:

1. Try to load from ~/Library/Application Support/sensu first.

2. If no config exists, fallback to the XDG config path.

3. By default, creating a new profile/config will create files in Apple's path.

4. If no config exists in Apple's path but does exist in XDG path, save future configs / changes to the XDG path.

If we only want to deal with one specification we'll need to determine the following:

• Do we want to allow for the possibility of a Mac app that can read the Sensu CLI config?

• Is using a community-created convention more important than playing by Apple's rules?

  • Apple has been increasing enforcement of their file system standards over the years
  • E.g. writing to /usr/bin is no longer possible (even with root) without disabling OS-security features

• It's important to use Apple's path for cache so that time machine and iCloud won't back up unnecessary data but doing so will break away from what we do on Linux.

  • Do we think using part of the XDG spec (for configs) and part of Apple's spec (for cache/tmpfiles) is less confusing than choosing to adhere to Apple's specification?

[amdprophet]

After thinking about this a bit more, I think we should just use the XDG path for configs and Apple path for cache.

If we ever release a Mac GUI app we can just add import functionality for configs / credentials.

[jamesdphillips]