LVD.ServiceStack.RoutedCacheClient 1.1.0

ServiceStack Routed Cache Client

What

The ServiceStack Routed Cache Client is an ICacheClient implementation (ICacheClientExtended to be more exact) that acts as a facade to a collection of multiple other cache clients. It has minimum overhead and does not store cache values itself, but only routes various cache operations (read, write, flush, remove etc.) to a specific registered client, based on an associated rule (for instance, whether the key starts with a given string).

Why

The main issue for me was (and possibly many others) that I could not register a different cache client for session storage (say, OrmLiteCacheClient), whilst continuing to make use of the standard MemoryCacheClient .

How to use

1. Add namespace reference

using LVD.ServiceStackRoutedCacheClient.

2. Create your routed cache client instance

In this example, the default MemoryCacheClient provided by ServiceStack is used as a fallback client, which means it will used to handle keys that are not matched by any of the registered rules.

IRoutedCacheClient routedCacheClient = new DefaultRoutedCacheClient(new MemoryCacheClient());

3. Register your other cache clients

For example, registering a ServiceStack OrmLite cache client for ServiceStack sessions:

OrmLiteCacheClient<CacheEntry> ormLiteCacheClient =
    new OrmLiteCacheClient<CacheEntry>();

routedCacheClient.PushClientWithRule(new KeyStartsWithStringCacheClientRule(ormLiteCacheClient,
    StringComparison.InvariantCultureIgnoreCase,
    "urn:iauthsession:",
    "sess:"));

Or simpler, using PushServiceStackSessionCacheClient(), which automatically registers your provided cache client with a KeyStartsWithStringCacheClientRule and the above prefixes: urn:iauthsession: and sess:.

OrmLiteCacheClient<CacheEntry> ormLiteCacheClient =
    new OrmLiteCacheClient<CacheEntry>();

routedCacheClient.PushServiceStackSessionCacheClient(ormLiteCacheClient);

4. Built-in routing behaviour

4.1. Built-in conditions

• KeyStartsWithStringCacheClientRuleCondition - matches keys that start with a given sub-string;
• KeyEndsWithStringCacheClientRuleCondition - matches keys that end with a given sub-string;
• KeyMatchesRegexpCacheClientRuleCondition - matches keys based on a regular expression;
• ServiceStackSessionKeyCacheClientRuleCondition - matches keys used to store ServiceStack session data;
• AlwaysTrueCacheClientRuleCondition - matches any key;
• AlwaysFalseCacheClientRuleCondition - doesn't match anything;
• MatchAnyRuleCondition - allows composing conditions using OR boolean operator (i.e. returns true if at least one condition evaluates to true);
• MatchAllRuleCondition - allows composing conditions using AND boolean operator (i.e. returns true if all conditions evaluate to true).

4.2. Built-in rules

• GenericConditionBasedCacheClientRule - matches keys that satisfy a given condition;
• KeyStartsWithStringCacheClientRule - matches keys that start with a given sub-string (uses KeyStartsWithStringCacheClientRuleCondition);
• KeyEndsWithStringCacheClientRule - matches keys that end with a given sub-string (uses KeyEndsWithStringCacheClientRuleCondition);
• KeyMatchesRegexpCacheClientRule - matches keys based on a regular expression (uses KeyMatchesRegexpCacheClientRuleCondition);
• ServiceStackSessionKeyCacheClientRule - matches keys used to store ServiceStack session data (uses ServiceStackSessionKeyCacheClientRuleCondition);
• AlwaysTrueCacheClientRule - matches any key (uses AlwaysTrueCacheClientRuleCondition);
• AlwaysFalseCacheClientRule - doesn't match anything (uses AlwaysFalseCacheClientRuleCondition).

5. Extending the routing behaviour

5.1. Creating custom conditions

Creating your own conditions is as easy as implementing IRoutedCacheClientRuleCondition with the single method bool Matches ( string key ). This is also the recommended way of exteding the library's routing behaviour.

As an example, here is the implementation of the built-in KeyStartsWithStringCacheClientRuleCondition condition:

public class KeyStartsWithStringCacheClientRuleCondition : IRoutedCacheClientRuleCondition
{
	private List<string> mTokens = new List<string>();

	private StringComparison mStringComparisonMode;

	public KeyStartsWithStringCacheClientRuleCondition ( StringComparison stringComparisonMode,
		params string[] tokens )
	{
		if ( tokens == null || tokens.Length == 0 )
			throw new ArgumentNullException( nameof( tokens ) );

		mTokens.AddRange( tokens );
		mStringComparisonMode = stringComparisonMode;
	}

	public bool Matches ( string key )
	{
		if ( string.IsNullOrWhiteSpace( key ) )
			throw new ArgumentNullException( nameof( key ) );

		foreach ( string token in mTokens )
			if ( key.StartsWith( token, mStringComparisonMode ) )
				return true;

		return false;
	}

	public StringComparison StringComparisonMode 
		=> mStringComparisonMode;
}

5.2. Creating custom rules

Creating your own rules is as easy as - extending the GenericConditionBasedCacheClientRule class and providing a condition to this base class (this is a useful shortcut to always instantiating GenericConditionBasedCacheClientRule with the same condition). - or extending the BaseCacheClientRule class and providing an implementation for the bool Matches ( string key ) method (should you wish to bypass using a condition altogether).

Example #1 - the implementation of the built-in KeyStartsWithStringCacheClientRule rule:

public class KeyStartsWithStringCacheClientRule : GenericConditionBasedCacheClientRule
{
	public KeyStartsWithStringCacheClientRule ( ICacheClient cacheClient,
		KeyStartsWithStringCacheClientRuleCondition condition )
		: base( cacheClient, condition )
	{
		return;
	}

	public KeyStartsWithStringCacheClientRule ( ICacheClient cacheClient,
		StringComparison stringComparisonMode,
		params string[] tokens )
		: this( cacheClient, new KeyStartsWithStringCacheClientRuleCondition( stringComparisonMode, tokens ) )
	{
		return;
	}
}

Example #2 - the implementation of the built-in GenericConditionBasedCacheClientRule rule:

public class GenericConditionBasedCacheClientRule : BaseCacheClientRule
{
	private IRoutedCacheClientRuleCondition mCondition;

	public GenericConditionBasedCacheClientRule ( ICacheClient cacheClient, IRoutedCacheClientRuleCondition condition )
		: base( cacheClient )
	{
		mCondition = condition
			?? throw new ArgumentNullException( nameof( condition ) );
	}

	public override bool Matches ( string key )
	{
		if ( string.IsNullOrWhiteSpace( key ) )
			throw new ArgumentNullException( nameof( key ) );

		return mCondition.Matches( key );
	}

	private IRoutedCacheClientRuleCondition Condition 
		=> mCondition;
}

6. Dispose behaviour

The dispose behaviour of the DefaultRoutedCacheClient, after version 1.1.0 is as follows:

• to automatically dispose all the registered cache clients by default (this can now be configured);
• to throw throw ObjectDisposedException when invoking methods on diposed instances.

To change how DefaultRoutedCacheClient handles various registered cache clients you may:

• use DefaultRoutedCacheClient ( ICacheClient fallbackClient, bool autoDispose ) constructor to set whether or not the fallback cache client should be disposed along with the DefaultRoutedCacheClient it is registered with;
• use IRoutedCacheClientRule.AutoDispose property to set whether the cache client associated with a rule should be disposed along with the DefaultRoutedCacheClient it is registered with.