ADded documentation

Author: Erwinvandervalk

README.md

@@ -1,9 +1,190 @@
 # ConfigurationProvider backed by Sql Stream Store  [![Build Status](https://travis-ci.org/Erwinvandervalk/Config.SqlStreamStore.svg?branch=master)](https://travis-ci.org/Erwinvandervalk/Config.SqlStreamStore)
 
-## Example use cases
+This library allows you to store configuration settings (key-value pairs) in a SQl Stream Store stream. 
+
+This allows the following scenario's:
+
+1. All application instances in a webfarm can share the same configuration settings. 
+1. The settings are audited, where the last x (defualt == 10) versions are stored. It's possible to revert back to a previous version of the settings. 
+1. If multiple instances attempt to write the same setting, the writing is idempotent. 
+1. The application can be notified of changes in the settings. 
+1. The settings can be encrypted 'at rest'. (The actual encryption is up to the consumer)
+
+This functionality is somewhat similar to using a key value store like Consul. If you are not yet ready to embrace consul, but do require a centralized key value store, then this might be the library for you, especially if you already use SQL Stream Store. 
 
 ## Getting started
 
+### Dependencies
+
+To get started, add a reference to Config.StreamStore and to your stream store implementation of choice, such as SqlStreamStore.MsSql. 
+
+### Building
+
+To build the solution, execute the build.cmd / build.sh
+
+### Registering SQL Stream store
+Then you register your configuration source like this:
+
+``` c#
+
+    /* 
+    This example adds SQL Stream Store as the provider with the lowest priority. 
+    This means you can override the values in SQL Stream Store with settings defined
+    on the application server. (recommended)
+    
+    */
+
+    // IN this example, the connection string is read from a configuration setting called 'ConnectionString'. This
+    // has to be defined either as a value in the ini file, as a command line setting or as an environment variable. 
+
+    var config = new ConfigurationBuilder()
+                // Get the connection string from the config and build a new SSS implementation
+                .AddStreamStore((c) => new MsSqlStreamStore(new MsSqlStreamStoreSettings(c["connectionString"])));
+
+                .AddIniFile("Settings.ini") 
+                .AddCommandLine(args)
+                .AddEnvironmentVariables()
+
+                .Build();
+
+    config["a_setting_from_sss"];
+
+```
+
+This code assumes that the SQL Stream Store database and schema have been created. If not, it will fail with a SQL Exception
+
+### Writing configuration changes
+
+To write changes, you should create an instance of the **StreamStoreConfigRepository** class. This class allows you to modify the configuration:
+
+Note, the actual writing of configuration settings is idempotent. If you try write the same configuration twice, it will not fail. 
+
+``` c#
+
+var repo = new StreamStoreConfigRepository(store);
+
+// Get the latest version, modify it, then write it back again. 
+var settings = repo.GetLatest(ct);
+
+// The configuration settings object is immutable, but you can create a modified 
+// version and write that back. 
+var modified = settings.WithModifiedSettings(("setting1", "newValue"));
+await _streamStoreConfigRepository.WriteChanges(modified, ct);
+
+// Modify individual settings.
+// Note, in the case of a concurrency error, this will throw a SSS Version Mismatch exception
+await repo.Modify(ct, 
+    ("setting1", "new value"),
+    ("setting2", "newer value"));
+
+// To handle concurrency errors, you can also use the following method. When a concurrency error occurs, 
+// you can retry a number of times. 
+    _streamStoreConfigRepository.Modify(
+
+        // Delegate that allows you to modify the data
+        changeSettings: async (currentSettings, ct) =>
+        {
+            return currentSettings.WithModifiedSettings(("setting1", value));
+        },
+
+        // Error handling logic, including retries. 
+        errorHandler: (exception, retryCount) =>
+        {
+            // do some logging / determine if you want to retry. 
+            return Task.FromResult(true); // returning true, which means retrying. 
+        },
+        ct: CancellationToken.None);
+
+```
+
+### Monitoring for changes in config
+
+It's not difficult to monitor the configuration for changes. 
+
+``` c#
+    var sssConfig = new ConfigurationBuilder()
+
+        // Add the stream store configuration data
+        .AddStreamStore(
+            (c) => new MsSqlStreamStore(new MsSqlStreamStoreSettings(c["connectionString"])),
+            subscribeToChanges: true)
+            .Build();
+
+    // Then use the ChangeToken class to monitor for changes:
+    ChangeToken.OnChange(sssConfig.GetReloadToken, () =>
+    {
+        Console.WriteLine("Settings changed:");
+    });
+
+```
+
+Note, you can also use your own **IChangeMonitor** implementation.
+
+### Capturing SSS instance or bring your own
+
+The Microsoft.Extensions.Config classes don't implement IDisposable, so it's recommended to either inject your own version of sql stream store
+or capture it while it's being built. 
+
+``` c#
+IStreamStore _captured;
+
+var sssConfig = new ConfigurationBuilder()
+    .AddStreamStore(
+        (c) => _captured = new MsSqlStreamStore(new MsSqlStreamStoreSettings(c["connectionString"])))
+        .Build();
+
+// This allows you to dispose it when you need to. This also cancels any subscriptions:
+    _captured.Dispose();
+
+```
+
+### Encrypting data at rest
+
+Use the **IConfigurationSettingsHooks** interface to handle your own encryption. Don't roll your own, use a trusted encryption mechanism. Like (https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.aes?view=netframework-4.7.2)
+
+
+### Handling database not yet available during startup. 
+
+Sometimes the database is not available during startup. Ideally, I'd just like to terminate the process 'gracefully' and have some form of restart logic in the process orchestrator. However, if this is not possible, then you can also implement an error handler:
+
+``` c# 
+
+            var sssConfig = new ConfigurationBuilder()
+
+                // Add the stream store configuration data
+                .AddStreamStore(
+                    // When an error occurs while connecting to the database
+                    (c) => _captured = new MsSqlStreamStore(new MsSqlStreamStoreSettings(c["connectionString"])),
+                    errorHandler: OnConnectError
+
+        private static async Task<bool> OnConnectError(Exception ex, int retryCount)
+        {
+            // delay before retrying???
+            await Task.Delay(2000);
+            
+            // Logging?
+
+            // Retry? returning true like this retries indefinitely. 
+            return true;
+        }
+
+```
+
+### retrieving historic settings and reverting. 
+
+``` c#
+
+// Gets a list of all stored versions. 
+var history = await _streamStoreConfigRepository.GetSettingsHistory(CancellationToken.None);
+
+// Gets a specific version. 
+var version1 = await _streamStoreConfigRepository.GetSpecificVersion(1, CancellationToken.None);
+
+// Reverts config back to a previous version
+await _streamStoreConfigRepository.RevertToVersion(version1, CancellationToken.None);
+
+```
+
 ## Licencing
 
 Licenced under [MIT](https://opensource.org/licenses/MIT).

src/Config.SqlStreamStore.Tests/ConfigRepositoryTests.cs

@@ -1,26 +1,23 @@
 using System;
 using System.Linq;
+using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
+using Newtonsoft.Json;
 using SqlStreamStore;
 using Xunit;
 
 namespace Config.SqlStreamStore.Tests
 {
 
-    // Max number of versions
-    // Can roll back to a version
-    // List versions
-    // Hooks for encryption / decryption
-    // 
-
     public class ConfigRepositoryTests
     {
         private StreamStoreConfigRepository _streamStoreConfigRepository;
 
         public ConfigRepositoryTests()
         {
-            _streamStoreConfigRepository = new StreamStoreConfigRepository(new InMemoryStreamStore());
+            _streamStoreConfigRepository = new StreamStoreConfigRepository(new InMemoryStreamStore(),
+                messageHooks: new Base64Hook());
         }
 
         [Fact]
@@ -32,7 +29,7 @@ public async Task Can_save_new_settings()
 
             var result = await _streamStoreConfigRepository.WriteChanges(settings, CancellationToken.None);
             Assert.Equal(0, result.Version);
-
+            Assert.Equal(new []{"setting1", "setting2"}, result.ModifiedKeys);
             var saved = await _streamStoreConfigRepository.GetLatest(CancellationToken.None);
 
             Assert.Equal(settings, saved);
@@ -63,7 +60,7 @@ public async Task Can_delete_existing_settings()
             Assert.NotEqual(settings, modified);
 
             var saved = await SaveSettings(modified);
-
+            Assert.Equal(new[] { "setting1" }, saved.DeletedKeys);
             Assert.Equal(modified, saved);
             Assert.False(saved.ContainsKey("setting1"));
         }
@@ -88,7 +85,7 @@ Task OnSettingsChanged(IConfigurationSettings configurationSettings, Cancellatio
                 return Task.CompletedTask;
             }
 
-            var subscription = _streamStoreConfigRepository.SubscribeToChanges(settings.Version, OnSettingsChanged,
+            var subscription = _streamStoreConfigRepository.WatchForChanges(settings.Version, OnSettingsChanged,
                 ct: CancellationToken.None);
 
             var modified = await _streamStoreConfigRepository.WriteChanges(settings.WithModifiedSettings(("setting1", "newValue")), CancellationToken.None);
@@ -191,12 +188,56 @@ await _streamStoreConfigRepository.Modify(CancellationToken.None,
             Assert.Equal(expectedMaxCount, history.Count);
         }
 
+        [Fact]
+        public async Task Can_revert_to_previous_version()
+        {
+            // Write 5 modifications. 
+            for (int i = 0; i < 5; i++)
+            {
+                await _streamStoreConfigRepository.Modify(CancellationToken.None,
+                    ("setting", i.ToString()),
+                    ("othersetting", "constant")
+                );
+            }
+
+            var version1 = await _streamStoreConfigRepository.GetSpecificVersion(1, CancellationToken.None);
+
+            await _streamStoreConfigRepository.RevertToVersion(version1, CancellationToken.None);
+
+            var latest = await _streamStoreConfigRepository.GetLatest(CancellationToken.None);
+            Assert.Equal(version1["setting"], latest["setting"]);
+        }
+
         private static ModifiedConfigurationSettings BuildNewSettings()
         {
             var settings = new ModifiedConfigurationSettings(
                 ("setting1", "value1"),
                 ("setting2", "setting2"));
             return settings;
         }
+
+        /// <summary>
+        /// This hook converts the input / output to and from Base64, just to see if the
+        /// hook actually works.
+        ///
+        /// Note, this is NOT encryption, nor should it ever be confused with encryption.
+        /// If you consider using this as a form of encryption, you should reconsider your
+        /// life choices that lead you up to this. 
+        /// </summary>
+        private class Base64Hook : IConfigurationSettingsHooks
+        {
+            public string OnReadMessage(string message)
+            {
+                return Encoding.UTF8.GetString(Convert.FromBase64String(message));
+            }
+
+            public string OnWriteMessage(string message)
+            {
+                return Convert.ToBase64String(Encoding.UTF8.GetBytes(message));
+                
+            }
+
+            public JsonSerializerSettings JsonSerializerSettings => new JsonSerializerSettings();
+        }
     }
 }

src/Config.SqlStreamStore/ConfigChanged.cs

@@ -2,6 +2,9 @@
 
 namespace Config.SqlStreamStore
 {
+    /// <summary>
+    /// Message that's saved in SSS to record configuration has changed. 
+    /// </summary>
     public class ConfigChanged
     {
         public ConfigChanged()
@@ -16,8 +19,19 @@ public ConfigChanged(Dictionary<string, string> allSettings, HashSet<string> mod
             DeletedSettings = deletedSettings;
         }
 
+        /// <summary>
+        /// Memento of all settings. 
+        /// </summary>
         public Dictionary<string, string> AllSettings { get; set; }
+
+        /// <summary>
+        /// Pointers to the settings that have changed in this version
+        /// </summary>
         public HashSet<string> ModifiedSettings { get; set; }
+
+        /// <summary>
+        /// Names of the keys that have been deleted in this version. 
+        /// </summary>
         public HashSet<string> DeletedSettings { get; set; }
     }
 }