Update fixes for hwchen#214.

1. If both secret-service and linux-native are available, prefer secret-service.
2. Document why both secret-service and keyutils are available on linux.
3. Add CI test for both feature linux-native and feature sync-secret-service.

.github/workflows/ci.yaml

@@ -3,11 +3,11 @@ name: CI
 on: [ workflow_dispatch, push, pull_request ]
 
 jobs:
-  ci_native:
+  ci_non_nix:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        os: [ macos-latest, windows-latest ]
 
     steps:
       - name: Fetch head
@@ -35,17 +35,19 @@ jobs:
         run: cargo clippy -- -D warnings
 
       - name: Build and Test
-        run: cargo test --features=apple-native,windows-native,linux-native --verbose
+        run: cargo test --features=apple-native,windows-native --verbose
 
       - name: Build the CLI release
-        run: cargo build --release --features=apple-native,windows-native,linux-native --example keyring-cli
+        run: cargo build --release --features=apple-native,windows-native --example keyring-cli
 
-  ci_secret_service:
+  ci_nix:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         features:
+          - "linux-native"
           - "sync-secret-service"
+          - "linux-native,sync-secret-service"
           - "sync-secret-service,crypto-rust"
           - "sync-secret-service,crypto-openssl"
           - "async-secret-service,tokio,crypto-rust"

src/lib.rs

@@ -103,6 +103,14 @@ You cannot specify both the `sync-secret-service` and `async-secret-service` fea
 this will produce a compile error. You must pick one or the other if you want to use
 the secret service for credential storage.
 
+The Linux platform is the only one for which this crate supplies multiple keystores:
+secret-service and keyutils. The secret-service is the more widely used store, because
+it provides persistence of credentials beyond reboot (which keyutils does not). However,
+because secret-service relies on system UI for unlocking credentials, it often isn't
+available on headless Linux installations, so keyutils is provided for those situations.
+If you enable both the secret-service store and the keyutils store, the secret-service
+store will be used as the default.
+
 ## Client-provided Credential Stores
 
 In addition to the platform stores implemented by this crate, clients
@@ -178,11 +186,12 @@ pub mod mock;
 compile_error!("This crate cannot use the secret-service both synchronously and asynchronously");
 
 //
-// Pick the *nix keystore
+// pick the *nix keystore
 //
 
 #[cfg(all(target_os = "linux", feature = "linux-native"))]
 pub mod keyutils;
+// use keyutils as default if secret-service is not available
 #[cfg(all(
     target_os = "linux",
     feature = "linux-native",
@@ -195,33 +204,29 @@ pub use keyutils as default;
     any(feature = "sync-secret-service", feature = "async-secret-service")
 ))]
 pub mod secret_service;
+// use secret-service as default if it's available
 #[cfg(all(
     any(target_os = "linux", target_os = "freebsd", target_os = "openbsd"),
     any(feature = "sync-secret-service", feature = "async-secret-service"),
-    not(feature = "linux-native")
 ))]
 pub use secret_service as default;
 
-#[cfg(all(
-    target_os = "linux",
-    any(
+// fallback to mock if neither keyutils nor secret service is available
+#[cfg(any(
+    all(
+        target_os = "linux",
         not(any(
             feature = "linux-native",
             feature = "sync-secret-service",
             feature = "async-secret-service"
-        )),
-        all(
-            feature = "linux-native",
-            any(feature = "sync-secret-service", feature = "async-secret-service"),
-        )
+        ))
+    ),
+    all(
+        any(target_os = "freebsd", target_os = "openbsd"),
+        not(any(feature = "sync-secret-service", feature = "async-secret-service"))
     )
 ))]
 pub use mock as default;
-#[cfg(all(
-    any(target_os = "freebsd", target_os = "openbsd"),
-    not(any(feature = "sync-secret-service", feature = "async-secret-service"))
-))]
-pub use mock as default;
 
 //
 // pick the Apple keystore