Async Redis, DynamoDB, Cache, Session, Auth Repo & Auth Providers

Just a quick announcement to document some upcoming changes for anyone using the v5.9.3 pre-release NuGet packages on MyGet.

A large part of this release was focused on adding Async APIs to many of ServiceStack’s providers most of which now have both Sync & Async APIs starting with ICacheClientAsync which all ServiceStack Caching Providers now support in addition to ICacheClient.

Which you can access from inside your ServiceStack Services (and other MVC/Razor base classes) with the CacheAsync property, e.g:

public Task<object> Any(MyRequest request)
{
    var item = await CacheAsync.GetAsync<Item>("key");
    //....
}

Outside of ServiceStack you can the AppHost.GetCacheClientAsync() API to access the ICacheClientAsync provider:

var cache = HostContext.AppHost.GetCacheClientAsync();
var item = await cache.GetAsync<Item>("key");

Nothing different is needed to register ICacheClientAsync which utilizes the existing ICacheClient dependency since all built-in caching providers implements both. In addition you can even use the ICacheClientAsync APIs even when using your own ICacheClient providers as it will return an Async ICacheClientAsync wrapper over Sync ICacheClient APIs.

In order to implement true async caching providers all underlying clients also needed to implement Async APIs.

Redis Async

The biggest client library implemented in this release by sheer API surface area is ServiceStack.Redis. All Redis Client Managers also implement both IRedisClientsManager and IRedisClientsManagerAsync so you can use your existing Redis configuration to access Redis in your Services with GetRedisAsync(), e.g:

public async Task<object> Any(AsyncRedis request)
{
    await using var redis = await GetRedisAsync();
    await redis.IncrementAsync(nameof(AsyncRedis), request.Value);
    
    return new AsyncRedisResponse {
        Value = await redis.GetAsync<long>(nameof(AsyncRedis))
    };
}

Or should you wish you can use both Sync/Async APIs in the same project, e.g:

public async object Any(SyncRedis request)
{
    Redis.Increment(nameof(SyncRedis), request.Value);
    
    return new SyncRedisResponse {
        Value = Redis.Get<long>(nameof(SyncRedis))
    };
}

The async support in ServiceStack.Redis differs from other async APIs in that it aimed for maximum efficiency so uses ValueTask & other modern Async APIs so it requires a minimum v4.7.2+ .NET Framework or .NET Standard 2.0 (i.e. .NET Core) project. All other Async APIs return the more interoperable Task responses for their async APIs.

If you’re using ServiceStack.Redis in your own (i.e. non ServiceStack) projects you could just register IRedisClientsManagerAsync to force usage of async APIs as it only lets you resolve async only IRedisClientAsync and ICacheClientAsync clients, e.g:

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IRedisClientsManagerAsync>(c => new RedisManagerPool());
}

//... 

public class MyDep
{
    private IRedisClientsManagerAsync manager;
    public MyDep(IRedisClientsManagerAsync manager) => this.manager = manager;

    public async Task<long> Incr(string key, uint value)
    {
        await using var redis = await manager.GetClientAsync();
        return await redis.IncrementAsync(key, value);
    }
}

PocoDynamo Async

Just like ServiceStack.Redis the ServiceStack.Aws PocoDynamo Dynamo DB client now also supports both sync & async APIs where the IPocoDynamo interface inherits IPocoDynamoAsync interface so you can use the same client to make sync & async API calls whilst continue to use the
same PocoDynamo registration.

Azure Table Storage Async

Likewise AzureTableCacheClient also implements ICacheClientAsync which

container.Register<ICacheClient>(new AzureTableCacheClient(cacheConnStr));

Async Auth Repositories

All built-in ServiceStack Auth Repositories now also implement IUserAuthRepositoryAsync
which you can use inside ServiceStack Services with the AuthRepositoryAsync property, e.g:

public async Task<object> Post(GetUserAuth request)
{
    var userAuth = await AuthRepositoryAsync.GetUserAuthByUserNameAsync(request.UserName);
    if (userAuth == null)
        throw HttpError.NotFound(request.UserName);
    return userAuth;
}

Outside of ServiceStack you can access it from the AppHost.GetAuthRepositoryAsync() API, e.g:

var authRepo = HostContext.AppHost.GetAuthRepositoryAsync();
await using (authRepo as IAsyncDisposable)
{
    //...
}

Like the caching providers the async Auth Repositories makes use of the existing IAuthRepository registration so no additional configuration is needed. Also your Services can use the IAuthRepositoryAsync APIs above even for your own sync IAuthRepository providers as it will return a IAuthRepositoryAsync wrapper API in its place.

Async Auth Providers

To make usage of the new async API functionality all of ServiceStack’s built-in Auth Providers were rewritten to use the new Async APIs. If you’re only using the existing Auth Providers this will be a transparent detail, however your own Custom Auth Providers will need to change as all existing Sync I/O base class APIs have been refactored into Async APIs.

Breaking Changes

Async Auth Providers

The recommendation would be change your existing Auth Providers to use the new Async APIs which all follow the same async method convention, i.e:

  • Has an *Async suffix
  • Takes an optional CancellationToken as its last parameter
  • Returns a Task

Here’s an example of all these changes to convert a sync into an async method:

int Add(int value);

Task<int> AddAsync(int value, CancellationToken token = default);

So if your custom Auth Provider inherits from CredentialsAuthProvider it would now need to implement:

//Async
public class CustomCredentialsAuthProvider : CredentialsAuthProvider
{
    public virtual async Task<bool> TryAuthenticateAsync(IServiceBase authService, 
        string userName, string password, CancellationToken token=default)
    {
        //Add here your custom auth logic (database calls etc)
        //Return true if credentials are valid, otherwise false
    }

    public override async Task<object> AuthenticateAsync(IServiceBase authService, 
        IAuthSession session, Authenticate request, CancellationToken token = default)
    {
        //Fill IAuthSession with data you want to retrieve in the app eg:
        session.FirstName = "some_firstname_from_db";

        //Call base method to Save Session and fire Auth/Session callbacks:
        return await base.AuthenticateAsync(authService, session, tokens, authInfo, token);
    }
}

To simplify migration of existing Auth Providers when upgrading ServiceStack, the popular Auth Providers below used to implement Custom Auth Providers now have a Sync suffix:

  • CredentialsAuthProviderSync
  • BasicAuthProviderSync
  • AuthProviderSync

So the easiest way to migrate would be to just add a *Sync suffix to your base class, e.g:

//Sync
public class CustomCredentialsAuthProvider : CredentialsAuthProviderSync
{
    public override bool TryAuthenticate(IServiceBase authService, 
        string userName, string password)
    {
    }

    public override IHttpResult OnAuthenticated(IServiceBase authService, 
        IAuthSession session, IAuthTokens tokens, 
        Dictionary<string, string> authInfo)
    {
        return base.OnAuthenticated(authService, session, tokens, authInfo);
    }
}

Note that all sync providers use continue to use the sync ICacheClient and IAuthRepository and Session APIs whilst the async providers only use the new async providers. Since there are shims to support when no async APIs are available, you can continue to use either async or sync APIs without issue.

Session Save APIs

Whilst ServiceStack has been changed to use async APIs it will only fire OnSaveSessionAsync() AppHost callback to save the session. So if you previously have overridden OnSaveSession in your AppHost to intercept when sessions are saved you’ll need to change it to override OnSaveSessionAsync instead, e.g:

[Obsolete("Use OnSaveSessionAsync")]
public override void OnSaveSession(IRequest httpReq, IAuthSession session, TimeSpan? expiresIn = null)
{
}

public override Task OnSaveSessionAsync(IRequest httpReq, IAuthSession session, TimeSpan? expiresIn = null, CancellationToken token=default)
{
}

Note that if you have code that calls the sync SaveSession() to save a Users Session you would either need to change it to use SaveSessionAsync() or override both APIs above if you’re intercepting session saves.

That’s the main gotcha’s from the refactor to use async APIs, most of the time the Async APIs are just additive so it shouldn’t effect existing code.

Authenticate & Register Services

If you’re using HostContext.ResolveService<T> to call either the AuthenticateService or RegisterService APIs, e.g. to Authenticate or impersonate a user:

using var authService = HostContext.ResolveService<AuthenticateService>(req);
var response = authService.Post(new Authenticate
{
    provider = Name,
    UserName = userName,
    Password = password
});

The Post() API implementation is now a deprecated “sync over async” implementation which although will continue to work, you’re encouraged to change it to use the async version, e.g:

var response = await authService.PostAsync(new Authenticate { ... });

If you do run into any other issues after upgrading to v5.9.3+ please let me know and I’ll rectify them ASAP.

1 Like

Optional *Async Suffixes

In addition to the expanded support for Async, your Services can now optionally have the *Async suffix which by .NET Standard guidelines (& my preference) is preferred for Async methods to telegraph to client call sites that its response should be awaited.

If both exists (e.g. Post() and PostAsync()) the *Async method will take precedence & be invoked instead.

Allowing both is useful if you have internal services directly invoking other Services using HostContext.ResolveService<T>() where you can upgrade your Service to use an Async implementation without breaking existing clients, e.g. this is used in RegisterService.cs:

[Obsolete("Use PostAsync")]
public object Post(Register request)
{
    try
    {
        var task = PostAsync(request);
        return task.GetResult();
    }
    catch (Exception e)
    {
        throw e.UnwrapIfSingleException();
    }
}

/// <summary>
/// Create new Registration
/// </summary>
public async Task<object> PostAsync(Register request)
{
    //... async impl
}            

To change to use an async implementation whilst retaining backwards compatibility with existing call sites, e.g:

using var service = HostContext.ResolveService<RegisterService>(Request);
var response = service.Post(new Register { ... });

This is important if the response is ignored as the C# compiler wont give you any hints to await the response which can lead to timing issues where the Services is invoked but User Registration hasn’t completed as-is often assumed.

The other option is to rename your method to use *Async suffix so the C# compiler will fail on call sites so you can replace the call-sites to await the async Task response, e.g:

using var service = HostContext.ResolveService<RegisterService>(Request);
var response = await service.PostAsync(new Register { ... });

Support for ValueTask

Not sure if it was explicitly mentioned, but Services can now return the more optimal ValueTask<object> responses.

1 Like