brantburnett · jeffrymorris · Nov 9, 2020 · Jan 30, 2021 · Feb 6, 2021 · Feb 17, 2021
diff --git a/Couchbase.Extensions.sln b/Couchbase.Extensions.sln
@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 16
-VisualStudioVersion = 16.0.30503.244
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31912.275
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{EC47DFB9-AB39-41F8-BD7C-7B25BBCDEBD1}"
 EndProject
@@ -42,6 +42,20 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.Locks.
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.Locks.Example", "example\Couchbase.Extensions.Locks.Example\Couchbase.Extensions.Locks.Example.csproj", "{5E042A12-E803-494C-B90C-6DF048AF73BD}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.MultiOp", "src\Couchbase.Extensions.MultiOp\Couchbase.Extensions.MultiOp.csproj", "{BB5FD506-3E66-4496-AC5D-ADF460A56093}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.MultiOp.IntegrationTests", "tests\Couchbase.Extensions.MultiOp.IntegrationTests\Couchbase.Extensions.MultiOp.IntegrationTests.csproj", "{4AF29051-106E-42BE-A8D1-152013BAD668}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.MultiOp.UnitTests", "tests\Couchbase.Extensions.MultiOp.UnitTests\Couchbase.Extensions.MultiOp.UnitTests.csproj", "{2DB91771-38EF-491F-9B89-2666801D013B}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.Compression.Snappier", "src\Couchbase.Extensions.Compression.Snappier\Couchbase.Extensions.Compression.Snappier.csproj", "{06FA9ED5-00FA-4969-A983-B73B3C5A91CB}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.Compression.Snappier.IntegrationTests", "tests\Couchbase.Extensions.Compression.Snappier.IntegrationTests\Couchbase.Extensions.Compression.Snappier.IntegrationTests.csproj", "{5AA07C99-EC7E-442D-A3EE-B8A373E0C278}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.Session.Example", "..\temp\Couchbase.Extensions\example\Couchbase.Extensions.Session.Example\Couchbase.Extensions.Session.Example.csproj", "{2002815D-BB04-4EE7-A671-D2A8A4E0A498}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Couchbase.Extensions.Caching.Example", "example\Couchbase.Extensions.Caching.Example\Couchbase.Extensions.Caching.Example.csproj", "{02FC8C26-DD40-4944-B897-B30598F8BC58}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -96,6 +110,34 @@ Global
 		{5E042A12-E803-494C-B90C-6DF048AF73BD}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{5E042A12-E803-494C-B90C-6DF048AF73BD}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{5E042A12-E803-494C-B90C-6DF048AF73BD}.Release|Any CPU.Build.0 = Release|Any CPU
+		{BB5FD506-3E66-4496-AC5D-ADF460A56093}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{BB5FD506-3E66-4496-AC5D-ADF460A56093}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{BB5FD506-3E66-4496-AC5D-ADF460A56093}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{BB5FD506-3E66-4496-AC5D-ADF460A56093}.Release|Any CPU.Build.0 = Release|Any CPU
+		{4AF29051-106E-42BE-A8D1-152013BAD668}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{4AF29051-106E-42BE-A8D1-152013BAD668}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{4AF29051-106E-42BE-A8D1-152013BAD668}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{4AF29051-106E-42BE-A8D1-152013BAD668}.Release|Any CPU.Build.0 = Release|Any CPU
+		{2DB91771-38EF-491F-9B89-2666801D013B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{2DB91771-38EF-491F-9B89-2666801D013B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{2DB91771-38EF-491F-9B89-2666801D013B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{2DB91771-38EF-491F-9B89-2666801D013B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{06FA9ED5-00FA-4969-A983-B73B3C5A91CB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{06FA9ED5-00FA-4969-A983-B73B3C5A91CB}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{06FA9ED5-00FA-4969-A983-B73B3C5A91CB}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{06FA9ED5-00FA-4969-A983-B73B3C5A91CB}.Release|Any CPU.Build.0 = Release|Any CPU
+		{5AA07C99-EC7E-442D-A3EE-B8A373E0C278}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5AA07C99-EC7E-442D-A3EE-B8A373E0C278}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5AA07C99-EC7E-442D-A3EE-B8A373E0C278}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5AA07C99-EC7E-442D-A3EE-B8A373E0C278}.Release|Any CPU.Build.0 = Release|Any CPU
+		{2002815D-BB04-4EE7-A671-D2A8A4E0A498}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{2002815D-BB04-4EE7-A671-D2A8A4E0A498}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{2002815D-BB04-4EE7-A671-D2A8A4E0A498}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{2002815D-BB04-4EE7-A671-D2A8A4E0A498}.Release|Any CPU.Build.0 = Release|Any CPU
+		{02FC8C26-DD40-4944-B897-B30598F8BC58}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{02FC8C26-DD40-4944-B897-B30598F8BC58}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{02FC8C26-DD40-4944-B897-B30598F8BC58}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{02FC8C26-DD40-4944-B897-B30598F8BC58}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -113,6 +155,13 @@ Global
 		{AB7D1460-4C72-45FA-8939-38C32C905AE8} = {EC47DFB9-AB39-41F8-BD7C-7B25BBCDEBD1}
 		{2EB84E99-15FC-4A7E-B42D-E45BB0A8D198} = {727F95F9-8FD9-423C-ACC6-B23E0D6CCC4C}
 		{5E042A12-E803-494C-B90C-6DF048AF73BD} = {58E7557B-D434-402A-9B6B-0DBE59E8DF3B}
+		{BB5FD506-3E66-4496-AC5D-ADF460A56093} = {EC47DFB9-AB39-41F8-BD7C-7B25BBCDEBD1}
+		{4AF29051-106E-42BE-A8D1-152013BAD668} = {727F95F9-8FD9-423C-ACC6-B23E0D6CCC4C}
+		{2DB91771-38EF-491F-9B89-2666801D013B} = {727F95F9-8FD9-423C-ACC6-B23E0D6CCC4C}
+		{06FA9ED5-00FA-4969-A983-B73B3C5A91CB} = {EC47DFB9-AB39-41F8-BD7C-7B25BBCDEBD1}
+		{5AA07C99-EC7E-442D-A3EE-B8A373E0C278} = {727F95F9-8FD9-423C-ACC6-B23E0D6CCC4C}
+		{2002815D-BB04-4EE7-A671-D2A8A4E0A498} = {58E7557B-D434-402A-9B6B-0DBE59E8DF3B}
+		{02FC8C26-DD40-4944-B897-B30598F8BC58} = {58E7557B-D434-402A-9B6B-0DBE59E8DF3B}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {BBE581CF-99BB-42AD-A7C8-59FF4B45DB55}

diff --git a/Couchbase.Extensions.sln.DotSettings b/Couchbase.Extensions.sln.DotSettings
@@ -1,3 +1,5 @@
 <wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
 	<s:String x:Key="/Default/FilterSettingsManager/CoverageFilterXml/@EntryValue">&lt;data&gt;&lt;IncludeFilters /&gt;&lt;ExcludeFilters&gt;&lt;Filter ModuleMask="*Tests" ModuleVersionMask="*" ClassMask="*" FunctionMask="*" IsEnabled="True" /&gt;&lt;Filter ModuleMask="Couchbase.Extensions.DependencyInjection" ModuleVersionMask="*" ClassMask="Couchbase.Extensions.DependencyInjection.Internal.ClusterProvider" FunctionMask="CreateCluster" IsEnabled="True" /&gt;&lt;Filter ModuleMask="TestApp" ModuleVersionMask="*" ClassMask="*" FunctionMask="*" IsEnabled="True" /&gt;&lt;Filter ModuleMask="Couchbase.Extensions.DnsDiscovery" ModuleVersionMask="*" ClassMask="Couchbase.Extensions.DnsDiscovery.Internal.LookupClientAdapter" FunctionMask="*" IsEnabled="True" /&gt;&lt;/ExcludeFilters&gt;&lt;/data&gt;</s:String>
-	<s:String x:Key="/Default/FilterSettingsManager/AttributeFilterXml/@EntryValue">&lt;data&gt;&lt;AttributeFilter ClassMask="Couchbase.Extensions.DependencyInjection.Internal.ExcludeFromCodeCoverageAttribute" IsEnabled="True" /&gt;&lt;/data&gt;</s:String></wpf:ResourceDictionary>
+	<s:String x:Key="/Default/FilterSettingsManager/AttributeFilterXml/@EntryValue">&lt;data&gt;&lt;AttributeFilter ClassMask="Couchbase.Extensions.DependencyInjection.Internal.ExcludeFromCodeCoverageAttribute" IsEnabled="True" /&gt;&lt;/data&gt;</s:String>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=parallelization/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Upsert/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>
diff --git a/README.md b/README.md
@@ -9,6 +9,8 @@ While not a officially supported Couchbase project, this repo is actively mainta
 ## Developer Guide ##
 
 - [Couchbase.Extensions.Caching](docs/caching.md): A distributed Cache [Middleware](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/middleware) for [ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/) and [Couchbase](http://couchbase.com) server
+- [Couchbase.Extensions.Compression.Snappier](docs/compression.md): An adapter to enable Snappy compression for key/value operations
+- [Couchbase.Extensions.MultiOp](docs/multi-op.md): Provides extensions for ICouchbaseCollection to perform multiple similar operations in parallel.
 - [Couchbase.Extensions.Session:](docs/session.md) A distributed Session [Middleware](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/middleware) for [ASP.NET Cor](https://docs.microsoft.com/en-us/aspnet/core/)e and [Couchbase](http://couchbase.com) Server
 - [Couchbase.Extensions.Locks](docs/locks.md): A system for managing distributed mutexs backed by Couchbase.
 

diff --git a/docs/caching.md b/docs/caching.md
@@ -24,7 +24,7 @@ public void ConfigureServices(IServiceCollection services)
     services.AddCouchbase(opt =>
     {
         opt.ConnectionString = "couchbase://localhost";
-        opt.Username = "Administrator";
+        opt.UserName = "Administrator";
         opt.Password = "password";
     });
 

diff --git a/docs/compression.md b/docs/compression.md
@@ -0,0 +1,51 @@
+# Couchbase Compression using Snappier
+
+Using compression for key/value operations can improve performance by reducing the amount of data sent and
+received over the network. It is trading CPU cycles for reducing network utilization. In some cloud
+environments it may also reduce network-related costs.
+
+For more details, see <https://docs.couchbase.com/server/current/learn/buckets-memory-and-storage/compression.html>.
+
+The Couchbase .NET SDK 3.x doesn't include built-in support for compression. This is because Couchbase uses
+[Snappy](https://github.com/google/snappy) for its compression algorithm, which historically hasn't had a
+great cross-platform implementation in .NET. Since version 3.1, the Couchbase .NET SDK does support
+extensibility points to add an external implementation of Snappy.
+
+## Couchbase.Extensions.Compression.Snappier
+
+The Couchbase.Extensions.Compression.Snappier is a simple adapter library that wires the Couchbase SDK to
+the [Snappier](https://github.com/brantburnett/Snappier) library. This is a .NET port of the C++ Snappy
+compression algorithm. It uses C# only, without P/Invoke to native code, to maintain full compatibilty with
+all CPU architectures and operating systems. In order to deliver near C++ performance, it uses pointer
+arithmetic and hardware intrinsics.
+
+Due to the high performance requirements of Couchbase key/value operations, it is recommend that this
+adapter only be used with .NET Core 3.1 or .NET 5.0 and later. Earlier versions of the .NET runtime do not
+support the required hardware intrinsics to get all of the performance benefits. It is also recommended
+that the application be run in x64 on an Intel or AMD processor, not ARM. However, older versions of the
+.NET runtime and other architectures like x86 and ARM are supported, they will just have a CPU performance
+penalty.
+
+### Configuring Snappier
+
+To enable Snappier compression, simply call `WithSnappierCompression` on your `ClusterOptions` object
+before connecting your cluster.
+
+```cs
+var options = new ClusterOptions()
+    .WithCredentials("Administrator", "password")
+    .WithSnappierCompression();
+
+var cluster = await Cluster.ConnectAsync("couchbase://localhost", options);
+```
+
+This will negotiate compression with the server during bootstrap and apply compression to any requests
+or responses which support it.
+
+The compression settings may be further configured if advanced tuning is required:
+
+```cs
+options.Compression = true;          // Default is true, setting to false disables even if WithSnappierCompression is called
+options.CompressionMinRatio = 0.90f; // Default is 0.83 == 83%, the compressed result is discarded if this ratio is not acheived
+options.CompressionMinSize = 128;    // Default is 32 bytes, docs smaller than this never try to compress on mutations
+```
diff --git a/docs/multi-op.md b/docs/multi-op.md
@@ -0,0 +1,97 @@
+# Couchbase.Extension.MultiOp
+
+Provides extensions for ICouchbaseCollection to perform multiple similar operations in parallel. For example, getting 100 documents based on their keys or performing a bulk insert of 100,000 documents. It is optimized to maximize throughput by limiting the degree of parallelization and to returning exceptions separately for each operation.
+
+## Getting Documents
+
+```cs
+var collection = bucket.DefaultCollection();
+
+var results = await bucket.Get(new[] { "key-1", "key-2", "key-3"}).ToList();
+
+foreach (var result in results)
+{
+    // result.Exception contains any Couchbase error, such as DocumentNotFoundException
+    // result.Result contains the IGetResult
+
+    var document = result.Result.ContentAs<DocType>();
+}
+```
+
+## Updating Documents
+
+```cs
+var collection = bucket.DefaultCollection();
+
+// Note: any IEnumerable<string, TValue> can be used, allowing
+// operations to be streamed for very large operation sets.
+var documents = new Dictionary<string, DocType> 
+{
+    ["key-1"] = new DocType() { /* ... */ },
+    ["key-2"] = new DocType() { /* ... */ },
+    ["key-3"] = new DocType() { /* ... */ }
+};
+
+var results = await collection.Upsert(documents).ToList();
+
+foreach (var result in results)
+{
+    // result.Exception contains any Couchbase error, such as DocumentNotFoundException
+    // result.Result contains the IMutationResult
+
+    var cas = result.Result.Cas;
+}
+```
+
+## Observables
+
+Note that all operations return an `IObservable<MultiOpResult>` or an `IObservable<MultiOpResult<T>>`. These observables may be subscribed to receive the results as the operations complete, rather than waiting to receive the results in bulk at the end.
+
+```cs
+var subscription = bucket.Get(keys).Subscribe(
+    result => {
+        // Action is triggered for each result
+    },
+    (Exception ex) => {
+        // Action is triggered for any Framework exception
+    }
+)
+
+// At some point later, you may dispose of the subscription to cancel the operations
+subscription.Dispose();
+```
+
+> :info: While it is possible to simply `await` the returned observable, this will only return the last operation result once all operations are completed. Use `.ToList()` to convert to an observable that returns the list of all results.
+
+> :warning: Operations are not begun until the returned observable is subscribed. It is
+> important to trigger a subscription so that the operations execute. This may include
+> awaiting the observable, calling `.ToTask()`, or calling  `.ToAsyncEnumerable()` and then enumerating.
+
+### Helpful Patterns
+
+These patterns may be helpful for working with the returned observables.
+
+```cs
+// To simply ensure that all operations succeed, without keeping the results
+await bucket.Upsert(documents).EnsureSuccessfulAsync();
+
+// To get a list of results
+var results = await bucket.Upsert(documents).ToList();
+
+// To provide a CancellationToken which stops operations
+var results = await bucket.Upsert(documents).ToList().ToTask(cancellationToken);
+
+// To convert the observable to an IAsyncEnumerable<T>
+await foreach (var result in bucket.Upsert(documents).ToAsyncEnumerable().WithCancellation(cancellationToken))
+{
+    // Do something here with each result
+}
+```
+
+## Exceptions
+
+Exceptions are handling using two different models.
+
+Exceptions which inherit from `CouchbaseException` are returned on the result object for each operation. They do not interfere with the completion of any other operations. Consumers must validate each `MultiOpResult` object to see if each operation succeeded or failed.
+
+All other exceptions, such as low-level framework exceptions, will be returned as an error on the observable. This cancels all further operations. For cases where the observable is being awaited, this will cause the exception to bubble up to your method. You may catch these exceptions using a `try..catch` block.
diff --git a/example/Couchbase.Extensions.Caching.Example/Controllers/WeatherForecastController.cs b/example/Couchbase.Extensions.Caching.Example/Controllers/WeatherForecastController.cs
@@ -0,0 +1,49 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Caching.Distributed;
+
+namespace Couchbase.Extensions.Caching.Example.Controllers
+{
+    [ApiController]
+    [Route("[controller]")]
+    public class WeatherForecastController : ControllerBase
+    {
+        private IDistributedCache _cache;
+
+        public WeatherForecastController(IDistributedCache cache, ILogger<WeatherForecastController> logger)
+        {
+            _cache = cache;
+            _logger = logger;
+        }
+
+        private static readonly string[] Summaries = new[]
+            {
+            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
+        };
+
+        private readonly ILogger<WeatherForecastController> _logger;
+
+        [HttpGet(Name = "GetWeatherForecast")]
+        public async Task<IEnumerable<WeatherForecast>> Get()
+        {
+            var weatherForcast = await _cache.GetAsync<IEnumerable<WeatherForecast>>("weatherForecast");
+
+            if(weatherForcast == null)
+            {
+                _logger.LogInformation("Cache miss!");
+                weatherForcast = Enumerable.Range(1, 5).Select(index => new WeatherForecast
+                {
+                    Date = DateTime.Now.AddDays(index),
+                    TemperatureC = Random.Shared.Next(-20, 55),
+                    Summary = Summaries[Random.Shared.Next(Summaries.Length)]
+                }).ToArray();
+
+                await _cache.SetAsync("weatherForecast", weatherForcast,
+                    new DistributedCacheEntryOptions().SetAbsoluteExpiration(TimeSpan.FromSeconds(10)));
+
+                return weatherForcast;
+            }
+            _logger.LogInformation("Cache hit!");
+            return weatherForcast;
+        }
+    }
+}
diff --git a/example/Couchbase.Extensions.Caching.Example/Couchbase.Extensions.Caching.Example.csproj b/example/Couchbase.Extensions.Caching.Example/Couchbase.Extensions.Caching.Example.csproj
@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net6.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Couchbase.Extensions.Caching" Version="3.3.5" />
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
+  </ItemGroup>
+
+</Project>
diff --git a/example/Couchbase.Extensions.Caching.Example/Program.cs b/example/Couchbase.Extensions.Caching.Example/Program.cs
@@ -0,0 +1,43 @@
+using Couchbase.Extensions.Caching;
+using Couchbase.Extensions.DependencyInjection;
+
+namespace Couchbase.Extensions.Caching.Example
+{
+    public class Program
+    {
+        public static void Main(string[] args)
+        {
+            var builder = WebApplication.CreateBuilder(args);
+
+            // Add services to the container.
+
+            builder.Services.AddControllers();
+            // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
+            builder.Services.AddEndpointsApiExplorer();
+            builder.Services.AddSwaggerGen();
+            builder.Services.AddCouchbase(opt =>
+            {
+                opt.ConnectionString = "couchbase://localhost";
+                opt.UserName = "Administrator";
+                opt.Password = "password";
+            });
+
+            builder.Services.AddDistributedCouchbaseCache("default", opt => { });
+
+            var app = builder.Build();
+
+            // Configure the HTTP request pipeline.
+            if (app.Environment.IsDevelopment())
+            {
+                app.UseSwagger();
+                app.UseSwaggerUI();
+            }
+
+            app.UseAuthorization();
+
+            app.MapControllers();
+
+            app.Run();
+        }
+    }
+}