docs: document all config options, includes a unit test for verification

Author: drahnr

docs/Configuration.md

@@ -0,0 +1,98 @@
+# Available Configuration Options
+
+## file
+
+```toml
+[dist]
+# where to find the scheduler
+scheduler_url = "http://1.2.3.4:10600"
+# a set of prepackaged toolchains
+toolchains = []
+# the maximum size of the toolchain cache in bytes
+toolchain_cache_size = 5368709120
+cache_dir = "/home/user/.cache/sccache-dist-client"
+
+[dist.auth]
+type = "token"
+token = "secrettoken"
+
+
+#[cache.azure]
+# does not work as it appears
+
+[cache.disk]
+dir = "/tmp/.cache/sccache"
+size = 7516192768 # 7 GiBytes
+
+[cache.gcs]
+# optional url
+url = "..."
+rw_mode = "READ_ONLY"
+# rw_mode = "READ_WRITE"
+cred_path = "/psst/secret/cred"
+bucket = "bucket"
+
+[cache.memcached]
+url = "..."
+
+[cache.redis]
+url = "redis://user:[email protected]:6379/1"
+
+[cache.s3]
+bucket = "name"
+endpoint = "s3-us-east-1.amazonaws.com"
+use_ssl = true
+```
+
+## env
+
+Whatever is set by a file based configuration, it is overruled by the env
+configuration variables
+
+### misc
+
+* `SCCACHE_ALLOW_CORE_DUMPS` to enable core dumps by the server
+* `SCCACHE_CONF` configuration file path
+* `SCCACHE_CACHED_CONF`
+* `SCCACHE_IDLE_TIMEOUT` how long the local daemon process waits for more client requests before exiting
+* `SCCACHE_STARTUP_NOTIFY` specify a path to a socket which will be used for server completion notification
+* `SCCACHE_MAX_FRAME_LENGTH` how much data can be transfered between client and server
+* `SCCACHE_NO_DAEMON` set to `1` to disable putting the server to the background
+
+### cache configs
+
+#### disk
+
+* `SCCACHE_DIR` local on disk artifact cache directory
+* `SCCACHE_CACHE_SIZE` maximum size of the local on disk cache i.e. `10G`
+
+#### s3 compatible
+
+* `SCCACHE_BUCKET` s3 bucket to be used
+* `SCCACHE_ENDPOINT` s3 endpoint
+* `SCCACHE_REGION` s3 region
+* `SCCACHE_S3_USE_SSL` s3 endpoint requires TLS, set this to `true`
+
+The endpoint used then becomes `${SCCACHE_BUCKET}.s3-{SCCACHE_REGION}.amazonaws.com`.
+If `SCCACHE_REGION` is undefined, it will default to `us-east-1`.
+
+#### redis
+
+* `SCCACHE_REDIS` full redis url, including auth and access token/passwd
+
+The full url appears then as `redis://user:[email protected]:6379/1`.
+
+#### memcached
+
+* `SCCACHE_MEMCACHED` memcached url
+
+#### gcs
+
+* `SCCACHE_GCS_BUCKET`
+* `SCCACHE_GCS_CREDENTIALS_URL`
+* `SCCACHE_GCS_KEY_PATH`
+* `SCCACHE_GCS_RW_MODE`
+
+#### azure
+
+* `SCCACHE_AZURE_CONNECTION_STRING`

src/config.rs

@@ -215,7 +215,7 @@ pub enum CacheType {
     S3(S3CacheConfig),
 }
 
-#[derive(Debug, Default, Serialize, Deserialize)]
+#[derive(Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(deny_unknown_fields)]
 pub struct CacheConfigs {
     pub azure: Option<AzureCacheConfig>,
@@ -404,7 +404,7 @@ impl Default for DistConfig {
 }
 
 // TODO: fields only pub for tests
-#[derive(Debug, Default, Serialize, Deserialize)]
+#[derive(Debug, Default, Serialize, Deserialize, Eq, PartialEq)]
 #[serde(default)]
 #[serde(deny_unknown_fields)]
 pub struct FileConfig {
@@ -938,3 +938,92 @@ fn test_gcs_oauth_url() {
         None => unreachable!(),
     };
 }
+
+
+
+#[test]
+fn full_toml_parse() {
+    const CONFIG_STR: &str = r#"
+[dist]
+# where to find the scheduler
+scheduler_url = "http://1.2.3.4:10600"
+# a set of prepackaged toolchains
+toolchains = []
+# the maximum size of the toolchain cache in bytes
+toolchain_cache_size = 5368709120
+cache_dir = "/home/user/.cache/sccache-dist-client"
+
+[dist.auth]
+type = "token"
+token = "secrettoken"
+
+
+#[cache.azure]
+# does not work as it appears
+
+[cache.disk]
+dir = "/tmp/.cache/sccache"
+size = 7516192768 # 7 GiBytes
+
+[cache.gcs]
+# optional url
+url = "..."
+rw_mode = "READ_ONLY"
+# rw_mode = "READ_WRITE"
+cred_path = "/psst/secret/cred"
+bucket = "bucket"
+
+[cache.memcached]
+url = "..."
+
+[cache.redis]
+url = "redis://user:[email protected]:6379/1"
+
+[cache.s3]
+bucket = "name"
+endpoint = "s3-us-east-1.amazonaws.com"
+use_ssl = true
+"#;
+
+    let file_config: FileConfig = toml::from_str(CONFIG_STR).expect("Is valid toml.");
+    assert_eq!(file_config,
+        FileConfig {
+            cache: CacheConfigs {
+                azure: None, // TODO not sure how to represent a unit struct in TOML Some(AzureCacheConfig),
+                disk: Some(DiskCacheConfig {
+                    dir: PathBuf::from("/tmp/.cache/sccache"),
+                    size: 7 * 1024 * 1024 * 1024,
+                }),
+                gcs: Some(GCSCacheConfig {
+                    url: Some("...".to_owned()),
+                    bucket: "bucket".to_owned(),
+                    cred_path: Some(PathBuf::from("/psst/secret/cred")),
+                    rw_mode: GCSCacheRWMode::ReadOnly,
+
+                }),
+                redis: Some(RedisCacheConfig {
+                    url: "redis://user:[email protected]:6379/1".to_owned(),
+                }),
+                memcached: Some(MemcachedCacheConfig {
+                    url: "...".to_owned(),
+                }),
+                s3: Some(S3CacheConfig {
+                    bucket: "name".to_owned(),
+                    endpoint: "s3-us-east-1.amazonaws.com".to_owned(),
+                    use_ssl: true,
+                }),
+            },
+            dist: DistConfig {
+                auth: DistAuth::Token { token: "secrettoken".to_owned() } ,
+                #[cfg(any(feature = "dist-client", feature = "dist-server"))]
+                scheduler_url: Some(parse_http_url("http://1.2.3.4:10600").map(|url| { HTTPUrl::from_url(url)}).expect("Scheduler url must be valid url str")),
+                #[cfg(not(any(feature = "dist-client", feature = "dist-server")))]
+                scheduler_url: Some("http://1.2.3.4:10600".to_owned()),
+                cache_dir: PathBuf::from("/home/user/.cache/sccache-dist-client"),
+                toolchains: vec![],
+                toolchain_cache_size: 5368709120,
+                rewrite_includes_only: false,
+            },
+        }
+    )
+}