Tenant stores
View as MarkdownA tenant store finds a tenant by id (GetTenantAsync) or by the identifier a request carries
(FindByIdentifierAsync), returning null when there is none, and lists every tenant, suspended ones included
(GetAllTenantsAsync). Whether work may run for a tenant is decided separately: see
Suspended and inactive tenants.
public interface ITenantStore<TKey>
{
ValueTask<ITenantDescriptor<TKey>?> GetTenantAsync(TKey tenantId, CancellationToken ct = default);
ValueTask<IReadOnlyList<ITenantDescriptor<TKey>>> GetAllTenantsAsync(CancellationToken ct = default);
// Implemented for you: parses the identifier as a TKey and calls GetTenantAsync.
ValueTask<ITenantDescriptor<TKey>?> FindByIdentifierAsync(string identifier, CancellationToken ct = default);
}The request middleware finds a request's tenant with FindByIdentifierAsync. Implement it when requests name
tenants by something other than their id, such as a subdomain slug or a custom domain with Guid keys: see
Identifiers other than the id. A store that wraps another (to
log, say) must forward FindByIdentifierAsync too: otherwise it gets the default, which never reaches the inner
store's own mapping.
Registration and lifetimes
Register one store; a second throws. UseInMemoryStore registers a singleton. UseStore<T>() and
UseStore(factory) register a scoped store, which can use a scoped DbContext but must not keep state across calls.
Tenantry reads the store through ITenantLookup<TKey>, which resolves it from a new scope for each lookup;
singletons such as hosted services should do the same rather than inject the store. app.UseTenantry() fails at
startup without a store. A non-HTTP host that only calls CreateScope with descriptors it
already holds needs none, but ITenantLookup and RunInScopeAsync throw InvalidOperationException without one.
In-memory store
For tests, demos, and simple single-instance deployments where tenants do not change at runtime:
tenant.UseInMemoryStore(
[
new TenantDescriptor<Guid> { TenantId = acmeId, Name = "Acme" },
new TenantDescriptor<Guid> { TenantId = globexId, Name = "Globex" },
]);This registers InMemoryTenantStore<TKey>, built when you register it. It does not see later
changes to the collection. Two tenants with the same id, or a tenant with an id Tenantry reserves for "no tenant"
(Guid.Empty, 0, an empty string), throw ArgumentException at registration. So do two string ids that differ
only in case, such as acme and ACME: a database whose collation ignores case (the default on SQL Server and MySQL)
takes them for one tenant, and one tenant's query filter would match the other's rows. Ids that differ only in accents
or trailing spaces are not refused; avoid them too. The store finds a tenant by its id exactly as written.
Custom store
For tenants in a database, a cache or a configuration service, implement ITenantStore<TKey>. With string ids, make
sure no two tenants have ids the database's collation takes for one, such as acme and ACME under a collation that
ignores case: a table keyed by the id in the same database guarantees it, while tenants read from configuration or
another service do not. See
String tenant ids and the database's collation.
using Microsoft.EntityFrameworkCore;
using Tenantry;
public sealed class EfCoreTenantStore(AppDbContext db) : ITenantStore<string>
{
// Every tenant that exists, active or not. Tenant is your own entity (any ITenantDescriptor<string>).
public async ValueTask<ITenantDescriptor<string>?> GetTenantAsync(string tenantId, CancellationToken ct = default) =>
await db.Tenants.AsNoTracking().FirstOrDefaultAsync(t => t.TenantId == tenantId, ct);
public async ValueTask<IReadOnlyList<ITenantDescriptor<string>>> GetAllTenantsAsync(CancellationToken ct = default) =>
await db.Tenants.AsNoTracking().ToListAsync<ITenantDescriptor<string>>(ct);
}Register it one of two ways:
// 1. By type, created through dependency injection.
tenant.UseStore<EfCoreTenantStore>();
// 2. By factory, when you need IServiceProvider to construct it.
tenant.UseStore(sp => new EfCoreTenantStore(sp.GetRequiredService<AppDbContext>()));Both are scoped (Registration and lifetimes). To avoid a database round trip on every request, cache the tenants.
Suspended and inactive tenants
Tenantry has no tenant status of its own: a descriptor carries only TenantId and Name. Keep the status on your
own descriptor type, and return every tenant from the store, suspended ones included. Migration tools (Tenantry.Pro's
among them) find tenants through the store, so a hidden tenant misses migrations and breaks when reactivated. Keep its
database until you remove it from the store.
public class Tenant : TenantDescriptor<string>
{
public bool IsActive { get; set; } = true; // yours; Tenantry reads it only through your check
}Tell Tenantry which tenants may have work run for them with ValidateTenantActivity:
tenant.UseStore<EfCoreTenantStore>();
tenant.ValidateTenantActivity(t => t is Tenant { IsActive: true });Check for the active status, as here, rather than the suspended one, so a descriptor of another type is refused
rather than served. For a check that needs services, implement ITenantActivityValidator<TKey> and register it as a
singleton; every registered check must allow the tenant. Tenantry then refuses an inactive tenant:
- An HTTP request gets
403 Forbiddenwhere a tenant is required, and runs without a tenant elsewhere, as for a tenant an access validator refuses.OnRejectedis told the reason isInactive, andInactiveTenantStatusCodechanges the status (see Status codes). RunInScopeAsyncthrowsTenantInactiveException, aTenantNotResolvedException.- Tenantry.Pro's background services, schedulers and message integrations skip it.
CreateScope and ITenantContextSetter.MakeCurrent do not check: they take a tenant you already hold and trust it, for
work such as migrations that must reach suspended tenants. When you loop over tenants for work of your own, ask
ITenantActivity<TKey>:
foreach (var t in await tenants.GetAllTenantsAsync(ct))
{
if (!await activity.IsActiveAsync(t, ct)) continue;
await using var scope = scopes.CreateScope(t);
// ...
}With caching, invalidate a tenant when you suspend it, or it is served until its entry expires.
Bootstrapping with an EF Core-backed store
If your tenants are in the same database as your tenant-owned entities, the Tenant entity must not implement
ITenantEntity<TKey>: with no tenant current, the query filter would hide every row from the store. The
EfCoreWeb sample has a Tenant entity, an EfCoreTenantStore and
seeded data.
Caching
The middleware looks the request's tenant up on every request. To serve requests without asking the store each time, cache the tenants:
builder.Services.AddTenantry<string>(tenant => tenant
.ResolveFromSubdomain(o => o.BaseDomains.Add("example.com"))
.UseStore<EfCoreTenantStore>()
.CacheTenants(o => o.Duration = TimeSpan.FromMinutes(1))); // 5 minutes by defaultCacheTenants keeps each tenant the store finds, in memory, for the duration, by the id or identifier it was
looked up with. It serves Tenantry's own lookups: the request middleware's and ITenantLookup<TKey>'s
(which ITenantScopeFactory.RunInScopeAsync and Tenantry.Pro's jobs and messages use). A lookup that finds no
tenant is not cached, so a tenant you add is found at once, and GetAllTenantsAsync is never cached. Code that
injects ITenantStore<TKey> itself reads the store.
When a tenant changes (it is suspended, renamed or deleted, or its slug changes), invalidate it with
ITenantInvalidator<TKey>, or it is served as it was until its entry expires: ValidateTenantActivity checks
the cached descriptor.
app.MapPost("/admin/tenants/{id}/suspend", async (string id, AppDbContext db, ITenantInvalidator<string> tenants, CancellationToken ct) =>
{
var t = await db.Tenants.SingleOrDefaultAsync(t => t.TenantId == id, ct);
if (t is null) return Results.NotFound();
t.IsActive = false;
await db.SaveChangesAsync(ct);
await tenants.InvalidateAsync(id, ct); // by its id and every identifier it was found by
return Results.NoContent();
});AddTenantry always registers ITenantInvalidator<TKey>, so this code runs with caching off too, when there is no
cached copy to remove. Each instance of the application has its own cache, so InvalidateAsync clears this instance's
copy, and other instances serve theirs until it expires unless you
publish the invalidation to them. The cache reads the time from a registered TimeProvider, so
tests can control expiry.
Everything kept for a tenant
InvalidateAsync also runs every registered ITenantInvalidationHandler<TKey>, with or without CacheTenants.
Tenantry.Caching, IsolateOutputCache() and Tenantry.Options each register one, so one call clears all of them.
Register your own for data you keep per tenant. When your code also injects the class to read from it, register it
once and point the handler registration at that instance, so both use the same data:
using System.Collections.Concurrent;
using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.AddSingleton<PriceListCache>();
builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<ITenantInvalidationHandler<Guid>, PriceListCache>(
sp => sp.GetRequiredService<PriceListCache>()));
public sealed class PriceListCache : ITenantInvalidationHandler<Guid>
{
private readonly ConcurrentDictionary<Guid, decimal[]> _prices = new();
public decimal[] GetOrAdd(Guid tenantId, Func<Guid, decimal[]> load) => _prices.GetOrAdd(tenantId, load);
public ValueTask InvalidateAsync(Guid tenantId, CancellationToken cancellationToken)
{
_prices.TryRemove(tenantId, out _);
return ValueTask.CompletedTask;
}
public ValueTask InvalidateAllAsync(CancellationToken cancellationToken)
{
_prices.Clear();
return ValueTask.CompletedTask;
}
}Each handler runs even when another throws; the exception is thrown once they have all run. Invalidating an id
Tenantry reserves for "no tenant" (Guid.Empty, 0, an empty string) throws, since no tenant has it.
Several instances
Each instance of the application keeps its own copies. To clear them everywhere, publish each invalidation through a
channel the instances share (Redis pub/sub, or a message broker), and apply what each instance receives with
InvalidateLocallyAsync or InvalidateAllLocallyAsync. Those run every handler except the publishing one, so a
received invalidation is not published again.
Register the publisher with BroadcastInvalidations. InvalidateAsync and InvalidateAllAsync run it after the other
handlers, so this instance is cleared first. Tag each message with the instance that sent it, since a subscriber can
receive its own:
using Microsoft.Extensions.Hosting;
builder.Services.AddSingleton<InstanceId>();
builder.Services.AddHostedService<InvalidationSubscriber>();
builder.Services.AddTenantry<string>(tenant => tenant
.UseStore<EfCoreTenantStore>()
.CacheTenants()
.BroadcastInvalidations(sp => new InvalidationPublisher(
sp.GetRequiredService<IInvalidationChannel>(), sp.GetRequiredService<InstanceId>())));
// The channel's interface is yours: wrap Redis pub/sub or your broker's client in it.
public interface IInvalidationChannel
{
Task PublishAsync(InvalidationMessage message, CancellationToken cancellationToken);
Task SubscribeAsync(Func<InvalidationMessage, Task> handler, CancellationToken cancellationToken);
}
// TenantId is null to invalidate every tenant.
public sealed record InvalidationMessage(string? TenantId, Guid Sender);
public sealed class InstanceId
{
public Guid Value { get; } = Guid.NewGuid();
}
public sealed class InvalidationPublisher(IInvalidationChannel channel, InstanceId instance) : ITenantInvalidationHandler<string>
{
public ValueTask InvalidateAsync(string tenantId, CancellationToken cancellationToken) =>
new(channel.PublishAsync(new InvalidationMessage(tenantId, instance.Value), cancellationToken));
public ValueTask InvalidateAllAsync(CancellationToken cancellationToken) =>
new(channel.PublishAsync(new InvalidationMessage(null, instance.Value), cancellationToken));
}
public sealed class InvalidationSubscriber(IInvalidationChannel channel, InstanceId instance, ITenantInvalidator<string> tenants)
: BackgroundService
{
protected override Task ExecuteAsync(CancellationToken stoppingToken) =>
channel.SubscribeAsync(async message =>
{
if (message.Sender == instance.Value) return;
if (message.TenantId is { } tenantId)
await tenants.InvalidateLocallyAsync(tenantId, stoppingToken);
else
await tenants.InvalidateAllLocallyAsync(stoppingToken);
}, stoppingToken);
}When the publisher throws, InvalidateAsync throws its exception after every other handler has run: this instance is
cleared, and the others keep their copies until those expire. Retry the call to reach them; clearing this instance
again does no harm. An instance that misses a message, because it was starting or lost its connection, also keeps its
copies until they expire, so keep cache durations no longer than you can serve a stale tenant for.