CrispyWaffle.CouchDB

CrispyWaffle.CouchDB provides a cache repository that stores documents in Apache CouchDB, using the CouchDB.NET driver. Use it when cached data should survive restarts and be readable from any process that can reach the CouchDB server, and when the cached values are documents rather than plain strings or numbers.

How it works

Connecting

CouchDBConnector creates a CouchDB.NET CouchClient from an IConnection. The client URL is "{Host}:{Port}", so Host must include the scheme, for example http://localhost. The client always uses basic authentication with Credentials.Username and Credentials.Password.

You can also pass a CouchClient that you have configured yourself.

Documents and databases

Only types derived from CouchDBCacheDocument can be stored.

• CouchDBCacheDocument.Key is the CouchDB document ID, so one key holds at most one document. SubKey is an ordinary document field that the sub-key overloads use as an extra filter.
• The repository picks a database from the document type: the type name in lowercase followed by s. For example, CouchDBCacheDocument maps to couchdbcachedocuments and a Car subclass maps to cars. If that database isn't in the server's database list, it's created. If it's already there, the repository opens it with CouchClient.GetDatabase<T>().

There are two groups of methods:

• The ICacheRepository methods (SetAsync, GetAsync, TryGetAsync, RemoveAsync, TTLAsync, Clear) always use the database of the base CouchDBCacheDocument type.
• SetAsync<T> returns without storing anything when T doesn't derive from CouchDBCacheDocument, and GetAsync<T> returns default.
• Values are read back as CouchDBCacheDocument and then cast to T.
• The *Specific* methods (SetSpecificAsync<T>, GetSpecificAsync<T>, RemoveSpecificAsync<T>, Clear<T>, GetDocCount<T>) use the database of T. Use them for your own document subclasses.

Expiration

SetSpecificAsync(value, key, ttl) stores ttl in TTL and DateTime.UtcNow + ttl in ExpiresAt. CouchDB doesn't expire documents itself. Expiration is checked when a document is read:

• If ExpiresAt is set and in the past, the read deletes the document and returns default.
• The sub-key SetAsync and SetSpecificAsync overloads don't set a TTL.
• TTLAsync returns the stored TTL value, which is the original lifetime, not the time remaining.

Errors

ShouldPropagateExceptions defaults to false.

When it's false:

• Most failures are passed to LogConsumer.Handle and the method returns normally.
• The Remove* methods and TTLAsync also log through LogConsumer.Error.
• GetSpecificAsync throws InvalidOperationException after logging a suppressed error.

In both modes:

• A document that doesn't exist is returned as null, not as an error.
• OperationCanceledException is logged as a warning and rethrown by most methods. The exception is TryGetAsync<T>(key), which returns (false, default) on cancellation.

Dispose() disposes the CouchDBConnector, which disposes the CouchClient.

Getting started

Start CouchDB locally. The repository's docker-compose.yml runs couchdb:latest on port 5984 with the user Admin and the password myP@ssw0rd.

using CrispyWaffle.Cache;
using CrispyWaffle.Composition;
using CrispyWaffle.Configuration;
using CrispyWaffle.CouchDB.Cache;
using CrispyWaffle.CouchDB.Utils.Communications;

var connection = new Connection
{
    Host = "http://localhost", // include the scheme
    Port = 5984,
    Credentials = { Username = "Admin", Password = "myP@ssw0rd" },
};

ServiceLocator.Register(() => new CouchDBConnector(connection), Lifetime.Singleton);
ServiceLocator.Register(
    () => new CouchDBCacheRepository(ServiceLocator.Resolve<CouchDBConnector>()),
    Lifetime.Singleton
);

CacheManager.AddRepository<CouchDBCacheRepository>();

// Use the repository directly for typed documents.
var repository = ServiceLocator.Resolve<CouchDBCacheRepository>();

var doc = new CouchDBCacheDocument();
await repository.SetAsync(doc, Guid.NewGuid().ToString());

var stored = await repository.GetAsync<CouchDBCacheDocument>(doc.Key);

Reference

CouchDBCacheRepository

public class CouchDBCacheRepository : ICacheRepository, IDisposable is a cache repository that stores CouchDBCacheDocument instances in CouchDB.

CouchDBConnector

public class CouchDBConnector : IDisposable holds the CouchDB.NET client. It has the [ConnectionName("CouchDB")] attribute.

CouchDBCacheDocument

public class CouchDBCacheDocument : CouchDocument is the base class for everything stored by CouchDBCacheRepository. Derive from it to add your own fields. Id and Rev come from CouchDB.NET's CouchDocument.

Examples

Store a custom document type in its own database

Documents of type Car go to the cars database.

using CrispyWaffle.CouchDB.Cache;

public class Car : CouchDBCacheDocument
{
    public Car(string maker) => Maker = maker;

    public string Maker { get; set; }
}

var car = new Car("MakerOne");
await repository.SetSpecificAsync(car, Guid.NewGuid().ToString());

var fromDb = await repository.GetSpecificAsync<Car>(car.Key);

await repository.RemoveSpecificAsync<Car>(car.Key);

Store a document that expires

var key = Guid.NewGuid().ToString();
await repository.SetAsync(new CouchDBCacheDocument(), key, TimeSpan.FromSeconds(5));

await Task.Delay(6000);

var expired = await repository.GetAsync<CouchDBCacheDocument>(key); // null; the document was deleted

Clear a database and count documents

await repository.Clear();
var remaining = await repository.GetDocCount<CouchDBCacheDocument>(); // 0

See also

• Caching
• CrispyWaffle.Configuration
• CrispyWaffle.Redis