Create standard PaySwarm config file format

msporny commented 11 years ago

A standard config file format should be created for PaySwarm clients so that they can share information between implementations. The configuration file format should be expressed in JSON-LD, which is readable by any JSON library. There is a specific format for entries and all applications that read and write data to the configuration file MUST do so in a standard way.

In Unix-based environments, the configuration file should be stored in the directory specified by $XDG_CONFIGHOME/payswarm1/default or default to ~/.config/payswarm1/default. The $XDG prefix is used by the Freedesktop project.

Additional config files may be specified by name for different PaySwarm configurations. For example, the development configuration can be used by doing the following:

"payswarm -c dev ..."

If $XDG_CONFIG_HOME is set, the file that is read should be $XDG_CONFIG_HOME/.config/payswarm1/dev If $XDG_CONFIG_HOME is not set, the application should look for that file in: ~/.config/payswarm1/dev

The configuration should use the following config file template:

{
  "@context": "https://w3id.org/payswarm/v1",
  "publicKey": {
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----... -----END PUBLIC KEY-----",
    "privateKeyPem": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
    "id": "https://dev.payswarm.com/i/CUSTOMER/keys/NUMBER"
  },
  "owner": "https://dev.payswarm.com/i/CUSTOMER",
  "source": "https://dev.payswarm.com/i/CUSTOMER/accounts/ACCOUNT"
}

When a configuration file is stored to disk by any PaySwarm client, it MUST be done using the template above and pretty-printed with 2-space indentation.

davidlehn commented 11 years ago

I'm not sure I understand what files are being loaded.

What I had been playing with (perhaps over-engineering) for a payswarm-python update was to use ~/.config/payswarm1/payswarm.json as a main config file that defaults to something like:

{
  "@context": ...,
  "configs": {
    "configPath": "~/.config/payswarm1/configs",
    "default": "default"
  },
  "node": { "pluginPath": [...]},
  "python": { "pluginPath": [...]}
}

The idea was to have a top-level config value for your real default config along with other basic tool config values. Maybe those should be elsewhere though. If you pass a simple string that doesn't look like a file (no "/" or ".ext", etc) then try to load ~/.config/payswarm1/configs/{CONFIG_NAME}.json. You could set your config.configs.default to a simple string or a path as needed.

I think config files should use .json extension to allow easy editor type detection.

msporny commented 11 years ago

Yeah, that's basically what I have implemented so far except for the top-level payswarm.json file (I think that's over engineered for now).

The default configuration file is $XDG_CONFIG_HOME/payswarm1/default. $XDG_CONFIG_HOME is the value that the Free Desktop folks specify that you should use for configuration files.

If $XDG_CONFIG_HOME isn't set, it defaults to ~/.config/ and the default configuration file can thus be found at ~/.config/payswarm1/default

If someone specifies a config file that doesn't exist, via something like 'payswarm -c foo', then this config file is attempted to be loaded:

$XDG_CONFIG_HOME/payswarm1/foo or ~/.config/payswarm1/foo

If we are going to use file extensions, we should match it to the correct MIMEType for the file. The application/ld+json MIMEType has a registered IANA file extension of ".jsonld". Unfortunately, no editor is going to detect that now... maybe eventually. I have no strong feelings about using an extension or not. The correct long-term solution would be to either use .jsonld or nothing at all. Not really leaning one way or the other right now. Thoughts?

web-payments / web-payments.org

Create standard PaySwarm config file format #8