Skip to main content

Multi-Tenancy Packages

Comprehensive reference for the Muonroi multi-tenancy system. The platform provides a layered architecture for managing multiple tenants, each with isolated data and per-site schema variants.

System Architecture​

The multi-tenancy system is organized into three conceptual layers:

  1. Abstractions Layer — Core interfaces and models (NuGet.org)
  2. Core Layer — Context, resolution, and validation logic (NuGet.org)
  3. Advanced Layer — Site profiles, infrastructure, and gRPC integration (NuGet.org)
  4. Quota & Licensing — Usage tracking and feature gating (NuGet.org)
┌─────────────────────────────────────────────────────────────────┐
│  Application Layer (Your Code)                                  │
│  - Services, Repositories, Controllers, Handlers                │
└─────────────┬───────────────────────────────────────────────────┘
              │
┌─────────────┴──────────────────────────────────────────────────┐
│  Muonroi.Tenancy.SiteProfile.Web                               │
│  - Per-site DbContext (AddSiteDbContext<T>)                    │
│  - Dapper infrastructure (AddSiteDapperInfrastructure)         │
│  - Repositories (MSiteRepository<TContext, T>)                 │
│  - Services (MSiteService<TContext, TEntity>)                  │
│  - Pipeline hooks, validation, telemetry                       │
└─────────────┬──────────────────────────────────────────────────┘
              │
┌─────────────┴──────────────────────────────────────────────────┐
│  Muonroi.Tenancy.SiteProfile                                   │
│  - ISiteProfile (site definitions)                             │
│  - ISiteProfileResolver (per-request resolution)               │
│  - AddMultiSiteProfiles / AddSiteProfile (DI registration)     │
│  - Site scope override (testing, background jobs)              │
└─────────────┬──────────────────────────────────────────────────┘
              │
┌─────────────┴──────────────────────────────────────────────────┐
│  Muonroi.Tenancy.SiteProfile.Grpc                              │
│  - gRPC-specific dispatchers (site-aware client factories)     │
│  - Interceptors (site code propagation)                        │
│  - Service facades                                             │
└─────────────┬──────────────────────────────────────────────────┘
              │
┌─────────────┴──────────────────────────────────────────────────┐
│  Muonroi.Tenancy + Muonroi.Tenancy.Core                        │
│  - TenantContext (AsyncLocal<string> ambient accessor)         │
│  - TenantResolutionMiddleware (HTTP tenant extraction)         │
│  - Tenant validation & security                                │
│  - Connection string resolution                                │
│  - Redis caching                                               │
└─────────────┬──────────────────────────────────────────────────┘
              │
┌─────────────┴──────────────────────────────────────────────────┐
│  Muonroi.Tenancy.Abstractions                                  │
│  - ITenantContext (interface)                                  │
│  - ITenantIdResolver, ITenantConnectionStringFactory           │
│  - ITenantScoped (marker), ITenantLicenseFeatureGate           │
│  - MultiTenantOptions configuration                            │
└─────────────┬──────────────────────────────────────────────────┘
              │
┌─────────────┴──────────────────────────────────────────────────┐
│  Muonroi.Quota.Abstractions                                    │
│  - ITenantQuotaTracker, ITenantQuotaStore                      │
│  - TenantQuota (limits), TenantQuotaPresets (tiers)            │
│  - QuotaUsage, QuotaType enums                                 │
└─────────────────────────────────────────────────────────────────┘

Muonroi.Tenancy.Abstractions​

NuGet: Muonroi.Tenancy.Abstractions | Tier: OSS | Distribution: NuGet.org

Purpose​

Core tenant context and configuration interfaces — all other layers depend on these abstractions.

Key Types​

TypeKindPurpose
ITenantContextInterfaceGet/set current TenantId string
ITenantIdResolverInterfaceExtract tenant ID from HttpContext (claims, headers, path, subdomain)
ITenantConnectionStringFactoryInterfaceResolve database connection string by tenant ID
ITenantScopedInterfaceMarker for tenant-scoped entities (enables EF global query filters)
ITenantLicenseFeatureGateInterfaceFeature enablement by license tier
MultiTenantOptionsConfigFeature flags: Enabled, RequireTenantClaim, StrictMode
TenantConnectionStringsOptionsConfigMap of tenant IDs to connection strings

DI Registration​

Typically registered automatically by AddTenancy() or AddSiteDbInfrastructure():

services.AddScoped<ITenantContext>(sp => new TenantContext());
services.AddScoped<ITenantIdResolver, DefaultTenantIdResolver>();
services.AddScoped<ITenantConnectionStringFactory, DefaultTenantConnectionStringFactory>();

Usage Example​

// Get current tenant from context
public class MyService
{
    private readonly ITenantContext _tenantContext;

    public MyService(ITenantContext tenantContext)
    {
        _tenantContext = tenantContext;
    }

    public async Task DoWorkAsync()
    {
        string? tenantId = _tenantContext.TenantId;  // Resolves from AsyncLocal<>
        // Use tenantId to filter data, resolve connections, etc.
    }
}

Muonroi.Tenancy.Core​

NuGet: Muonroi.Tenancy.Core | Tier: OSS | Distribution: NuGet.org

Purpose​

Core implementation of tenant context, resolution, and connection string factories. Provides the AsyncLocal<T> ambient storage pattern.

Key Types​

TypeKindPurpose
TenantContextClassStatic CurrentTenantId property backed by AsyncLocal<string?>. Failsafe cross-tenant access via AllowCrossTenantAccess
DefaultTenantIdResolverClassMulti-strategy tenant resolution: claims → headers → path segments → subdomains
DefaultTenantConnectionStringFactoryClassMap-based connection string lookup from configuration
MappingTenantConnectionStringFactoryClassCustom mapping function for connection resolution
TenantSecurityValidatorClassStatic validation: context vs claim vs header matching (fail-closed)
TenantSchemaSelectorClassEF Core schema selection per tenant
TenantQuotaTrackerClassQuota enforcement (if using in-memory store)
ContextMirrorScopeClassMirrors execution context to log scopes

AsyncLocal Pattern​

Tenant context is stored in thread-local (async-safe) storage:

public class TenantContext : ITenantContext
{
    private static readonly AsyncLocal<string?> Current = new();

    public string? TenantId
    {
        get => Current.Value;
        set => Current.Value = value;
    }

    public static string? CurrentTenantId
    {
        get => Current.Value;
        set => Current.Value = value;
    }
}

Key property: TenantContext.AllowCrossTenantAccess (default: false)

When true, EF Core global query filters for ITenantScoped entities are bypassed. Use only for admin/system operations.

DI Registration​

services.AddTenancy(configuration);  // Registers all core services

Or manually:

services.AddScoped<ITenantContext, TenantContext>();
services.AddScoped<ITenantIdResolver, DefaultTenantIdResolver>();
services.AddScoped<ITenantConnectionStringFactory, DefaultTenantConnectionStringFactory>();

Usage Example​

// Access tenant anywhere without parameter passing
public class OrderProcessor
{
    public async Task ProcessAsync()
    {
        var tenantId = TenantContext.CurrentTenantId;  // AsyncLocal access
        // Process order for current tenant
    }
}

// Validate tenant cross-checks
TenantSecurityValidator.TryValidate(
    contextTenantId: context.User.FindFirst("tenant_id")?.Value,
    claimTenantId: jwt.Subject,
    headerTenantId: request.Headers["X-Tenant-Id"],
    requireTenantClaim: true,
    out string errorCode);

if (!valid)
{
    return Unauthorized(errorCode);  // MissingTenantContext, TenantMismatch, etc.
}

Muonroi.Tenancy​

NuGet: Muonroi.Tenancy | Tier: OSS | Distribution: NuGet.org

Purpose​

Provides HTTP middleware and Redis caching for tenant context resolution.

Key Types​

TypeKindPurpose
TenantResolutionMiddlewareMiddlewareExtracts tenant from HTTP request, validates, and sets TenantContext.CurrentTenantId
RedisTenantCacheClassCaches tenant metadata in Redis for fast lookup
TenantResolutionTelemetryClassOpenTelemetry metrics for tenant resolution

DI Registration​

// In Program.cs
var app = builder.Build();
app.UseMiddleware<TenantResolutionMiddleware>();

Or automatically via templates:

public static void AddTenancy(this WebApplicationBuilder builder)
{
    builder.Services.AddTenancy(builder.Configuration);
}

Tenant Resolution Flow​

  1. Check x-tenant-id header
  2. Parse {tenantId} from route values
  3. Extract from URL path (/api/tenant/{id}/...)
  4. Parse from subdomain (tenant-1.myapp.com)
  5. Fallback to JWT claim (iss or sub)
  6. Validate resolved tenant matches JWT claim
  7. Set TenantContext.CurrentTenantId

Muonroi.Tenancy.SiteProfile​

NuGet: Muonroi.Tenancy.SiteProfile | Tier: OSS | Distribution: NuGet.org

Purpose​

Multi-site variant support — allows one codebase to serve multiple deployment variants, each with different database schemas, business rules, and column mappings.

Key Concepts​

  • Site: A deployment variant (e.g., "TCI", "Alpha", "Bravo"). Defines structure and behavior.
  • Tenant: An organization/customer using the application. Can exist on one or multiple sites.
  • Relationship: One site → multiple tenants (data isolation). One codebase → multiple sites (schema divergence).

Key Types​

TypeKindPurpose
ISiteProfileInterfaceContract for a site variant. Implement once per site.
GenerateSiteProfileAttributeAttributeMarks class for site profile code generation ([GenerateSiteProfile(SiteIds.BRAVO, typeof(BravoDbContext))])
ISiteProfileResolverInterfacePer-request resolver for current site (scoped lifetime)
SiteProfileResolverClassDefault implementation holding resolved ISiteProfile
SiteProfileScopeClassOverride site resolution in tests/background jobs via AsyncLocal<ISiteProfile>
SiteProfileExtensionsClassAddSiteProfile<T>(), AddMultiSiteProfiles(), AddSiteResolvedService<T>()
SiteProfileRegistrationTrackerClassValidates all sites registered at startup
SiteProfileStartupValidatorHosted ServiceRuns validation + logs results

ISiteProfile Contract​

public interface ISiteProfile
{
    string SiteId { get; }                                    // Unique site identifier
    bool IsEnabled => true;                                   // Enable/disable at runtime
    void RegisterServices(IServiceCollection, IConfiguration); // Per-site DI registration
}

Implement once per site:

[GenerateSiteProfile(SiteIds.BRAVO, typeof(BravoOrderContext))]
public class BravoSiteProfile : ISiteProfile
{
    public string SiteId => SiteIds.BRAVO;

    public void RegisterServices(IServiceCollection services, IConfiguration configuration)
    {
        // Register site-specific DbContext
        services.AddSiteDbContext<BravoOrderContext>();

        // Register site-specific repositories
        services.AddKeyedScoped<IOrderRepository, BravoOrderRepository>(SiteId);

        // Register site-specific services
        services.AddKeyedScoped<IOrderService, BravoOrderService>(SiteId);

        // Register custom column mappings for Dapper
        services.AddKeyedSingleton<ISiteColumnMap, BravoColumnMap>(SiteId);
    }
}

Single-Site Deployment (1 binary = 1 site)​

// Program.cs
services.AddSiteProfile<BravoSiteProfile>(configuration);

Multi-Site Deployment (1 binary = N sites)​

// Program.cs
services.AddMultiSiteProfiles(
    configuration,
    siteCodeAccessor: sp => sp.GetRequiredService<IHttpContextAccessor>()
        .HttpContext?.Request.Headers["X-Site-Code"].FirstOrDefault() ?? "default",
    assemblies: typeof(Program).Assembly);

The siteCodeAccessor delegate determines which site handles each request. Return value is matched against site IDs; missing sites fall back to "default" (unless StrictMode = true).

Per-Request Service Resolution​

Register a scoped factory that automatically resolves site-specific implementations:

// Program.cs
services.AddSiteResolvedService<IOrderService>();  // Scoped factory

// In ISiteProfile.RegisterServices():
services.AddKeyedScoped<IOrderService, TciOrderService>(SiteIds.TCI);
services.AddKeyedScoped<IOrderService, BravoOrderService>(SiteIds.BRAVO);

// In your controller/service:
public class OrderController
{
    public OrderController(IOrderService orderService)
    {
        // orderService is automatically resolved to TciOrderService or BravoOrderService
        // based on the current request's site code
    }
}

Testing & Background Jobs​

Override site resolution:

using (SiteProfileScope.SetCurrent(bravaSiteProfile))
{
    // All ISiteProfileResolver.Current calls return bravaSiteProfile
    var result = await _orderService.ListAsync();
}

Or:

[Test]
public async Task TestBravoOrders()
{
    var bravo = new BravoSiteProfile();
    SiteProfileScope.SetCurrent(bravo);
    try
    {
        var orders = await _orderService.ListAsync();
        Assert.That(orders, Is.Not.Empty);
    }
    finally
    {
        SiteProfileScope.SetCurrent(null);
    }
}

Muonroi.Tenancy.SiteProfile.Web​

NuGet: Muonroi.Tenancy.SiteProfile.Web | Tier: OSS | Distribution: NuGet.org

Purpose​

Web/API infrastructure for per-site data access, configuration, and pipelines.

Key Types​

TypeKindPurpose
SiteDbInfrastructureOptionsConfigEF Core per-site setup: tenant resolver, connection string resolver, transforms
SiteProfileDbContextExtensionsExtensionsAddSiteDbInfrastructure(), AddSiteDbContext<T>(), AddSiteMigrationRunner(), AddSiteConfiguration()
SiteDapperInfrastructureOptionsConfigDapper per-site setup: write/read connection strings, transforms
SiteProfileDapperExtensionsExtensionsAddSiteDapperInfrastructure(), AddSiteSqlBuilder()
ISiteColumnMapInterfaceCustom column name mappings (e.g., OrderId → ORD_ID in legacy schema)
DefaultSiteColumnMapClassFallback: PascalCase → UPPER_SNAKE_CASE
SiteSqlBuilderClassBuilds SQL with site-specific column maps
MSiteRepository<TContext, T>ClassSite-aware repository base (EF Core write context resolved per-site)
MSiteService<TContext, TEntity>ClassSite-aware service base (write context + read Dapper + repository)
ISiteConfigurationInterfaceRead site-specific config from appsettings.json
SiteProfileStateMiddlewareMiddlewareSets site profile state per request
SiteProfileWebExtensionsExtensionsAddSiteProfileWeb() registers middleware + hot-reload
ISiteProfileChangeHandlerInterfaceHot-reload: react to profile changes
SiteMigrationRunnerHosted ServiceAuto-discovers and runs EF migrations for all sites
EfColumnSyncHostedServiceHosted ServiceSyncs column metadata from EF IModel at startup

Per-Site DbContext (EF Core)​

Problem: Standard AddDbContext<T>() registers both generic DbContextOptions<T> AND non-generic DbContextOptions. Multiple sites cause Autofac "last wins" conflict on the non-generic registration.

Solution: Register only generic options, avoid non-generic conflict:

// Program.cs
services.AddSiteDbInfrastructure(o =>
{
    // Delegate to your tenant/site resolution logic
    o.TenantId = sp => sp.GetRequiredService<IWorkContext>().TenantId;
    o.ConnectionString = sp => sp.GetRequiredService<IWorkContext>().ConnectionString;

    // Optional: decrypt connection string
    o.ConnectionStringTransform = cs => Cryptography.Decrypt(_secretKey, cs);

    // Optional: custom database provider config
    o.ConfigureDbContext = (builder, cs) => builder.UseSqlServer(cs);
});

// Register each site's DbContext
services.AddSiteDbContext<TciOrderContext>();
services.AddSiteDbContext<BravoOrderContext>();

// Auto-migrate on startup
services.AddSiteMigrationRunner(o => o.MaxParallelism = 4);

Inside ISiteProfile.RegisterServices():

public void RegisterServices(IServiceCollection services, IConfiguration configuration)
{
    // BravoOrderContext is scoped — resolved per-request with TenantId-specific connection string
    services.AddSiteDbContext<BravoOrderContext>();
}

Per-Site Dapper (Raw SQL)​

Mirrors EF Core pattern for raw SQL data access:

// Program.cs
services.AddSiteDapperInfrastructure(o =>
{
    o.WriteConnectionString = sp => sp.GetRequiredService<IWorkContext>().ConnectionString;
    o.ReadConnectionString = sp => sp.GetRequiredService<IWorkContext>().ReadOnlyConnectionString;
    o.ConnectionStringTransform = cs => Cryptography.Decrypt(_secretKey, cs);
});

// Register site-specific Dapper implementations
services.AddSiteResolvedService<IDapper>();
services.AddSiteResolvedService<IDapperRead>();

// Optionally: column mapping for SQL builder
services.AddSiteSqlBuilder();

Inside ISiteProfile.RegisterServices():

public void RegisterServices(IServiceCollection services, IConfiguration configuration)
{
    services.AddKeyedScoped<IDapper, BravoDapperImpl>(SiteId);
    services.AddKeyedScoped<IDapperRead, BravoDapperReadImpl>(SiteId);

    // Custom column mapping: BravoDB uses different naming
    services.AddKeyedSingleton<ISiteColumnMap, BravoColumnMap>(SiteId);
}

Site-Aware Repositories​

public class OrderRepository : MSiteRepository<BravoOrderContext, Order>
{
    public OrderRepository(
        BravoOrderContext dbContext,
        ISiteProfileResolver siteResolver,
        IAuthenticateInfoContext authContext,
        ILicenseGuard licenseGuard,
        IMDateTimeService dateTimeService)
        : base(dbContext, siteResolver, authContext, licenseGuard, dateTimeService)
    {
    }

    public async Task<Order?> FindByCodeAsync(string code)
    {
        return await SiteContext.Orders
            .FirstOrDefaultAsync(o => o.Code == code);
    }
}

Key property: SiteContext — type-safe, per-site DbContext.

Site-Aware Services​

public class OrderService : MSiteService<BravoOrderContext, Order>
{
    public OrderService(
        BravoOrderContext writeContext,
        IMSiteRepository<BravoOrderContext, Order> repository,
        IDapper readContext,
        ISiteProfileResolver siteResolver)
        : base(writeContext, repository, readContext, siteResolver)
    {
    }

    protected override Order MapCreate(Order entity)
    {
        entity.SiteId = SiteResolver.Current.SiteId;
        return entity;
    }

    public async Task<Order> CreateAsync(Order entity)
    {
        return await base.CreateAsync(entity);  // Calls MapCreate, saves, commits
    }
}

Key properties:

  • WriteContext — EF Core DbContext for write operations
  • ReadContext — Dapper for raw SQL reads
  • SiteResolver — Current site profile
  • Repository — Site-aware CRUD + transaction management

Per-Site Configuration​

Read site-specific settings from appsettings.json:

{
  "Sites": {
    "bravo": {
      "MaxOrders": 1000,
      "EnablePricing": true,
      "ApiUrl": "https://bravo-api.internal"
    },
    "tci": {
      "MaxOrders": 500,
      "EnablePricing": false
    }
  }
}
// Program.cs
services.AddSiteConfiguration();  // Scoped ISiteConfiguration

// In your service:
public class OrderService
{
    private readonly ISiteConfiguration _siteConfig;

    public OrderService(ISiteConfiguration siteConfig)
    {
        _siteConfig = siteConfig;
    }

    public async Task<List<Order>> ListAsync()
    {
        var maxOrders = _siteConfig.GetValue<int>("MaxOrders", 1000);
        // Use site-specific setting
    }
}

Column Mapping (Dapper)​

Map C# property names to database column names per site:

public class BravoColumnMap : ISiteColumnMap
{
    public string GetColumnName(string propertyName)
    {
        return propertyName switch
        {
            nameof(Order.OrderId) => "ORD_ID",
            nameof(Order.CreatedAt) => "CRT_DT",
            _ => propertyName  // Default: use property name as-is
        };
    }
}

Register:

services.AddKeyedSingleton<ISiteColumnMap, BravoColumnMap>(SiteIds.BRAVO);

Used by SiteSqlBuilder:

var sqlBuilder = sp.GetRequiredService<SiteSqlBuilder>();
string sql = sqlBuilder.BuildSelectQuery<Order>("WHERE CreatedAt > @date");
// Generates: SELECT ... FROM Orders WHERE CRT_DT > @date (via Bravo mapping)

Behaviors & Hooks​

Register per-site behaviors for caching, auditing, quota, observability:

services.AddScoped<ISiteStepHook, SiteAuditBehavior>();
services.AddScoped<ISiteStepHook, SiteCachingBehavior>();
services.AddScoped<ISiteStepHook, SiteQuotaBehavior>();
services.AddScoped<ISiteStepHook, SiteObservabilityBehavior>();

Pipeline execution:

// In MSiteService or custom handlers
var pipeline = sp.GetRequiredService<MSitePipeline>();
await pipeline.ExecuteAsync(async () =>
{
    // Your business logic here — behaviors wrap automatically
    return await repository.CreateAsync(entity);
});

Muonroi.Tenancy.SiteProfile.Grpc​

NuGet: Muonroi.Tenancy.SiteProfile.Grpc | Tier: OSS | Distribution: NuGet.org

Purpose​

gRPC-specific dispatchers, interceptors, and service factories for site-aware microservices.

Key Types​

TypeKindPurpose
ISiteGrpcClientFactoryInterfaceFactory for site-specific gRPC clients
SiteGrpcClientFactoryClassDefault implementation with caching
SiteCodeGrpcInterceptorInterceptorPropagates site code in gRPC metadata
SiteCodeHolderClassAmbient site code storage (async-safe)
SiteGrpcDispatchHelperHelperRoutes gRPC calls to correct site handler
GenerateSiteGrpcFacadeAttributeAttributeCode generation for site facades
SiteGrpcServiceAttributeAttributeMarks gRPC service for site dispatch
SiteGrpcExtensionsExtensionsAddSiteGrpc(), AddSiteGrpcClient<T>()

Setup​

// Program.cs
services.AddSiteGrpc(o =>
{
    o.ClientFactory = sp => new SiteGrpcClientFactory(sp);
});

// Register per-site client factories
services.AddSiteGrpcClient<Catalog.CatalogService.CatalogServiceClient>();

Propagating Site Code in gRPC​

The SiteCodeGrpcInterceptor automatically adds site code to outgoing gRPC metadata:

// Outgoing call (from service A to service B)
var channel = GrpcChannel.ForAddress("https://service-b.internal");
var client = new ServiceB.ServiceBClient(
    channel.Intercept(new SiteCodeGrpcInterceptor(siteCodeHolder)));

var response = await client.DoWorkAsync(new Request { ... });

Receiving side reads the site code from metadata:

[SiteGrpcService(typeof(ServiceB.ServiceBBase))]
public class ServiceBImpl : ServiceB.ServiceBBase
{
    private readonly ISiteProfileResolver _siteResolver;

    public override async Task<Response> DoWork(Request request, ServerCallContext context)
    {
        // Site code extracted from metadata automatically
        var site = _siteResolver.Current;

        // Use site-specific DbContext, services, etc.
        return await base.DoWork(request, context);
    }
}

Muonroi.Tenancy.SiteProfile.SourceGenerators​

NuGet: Muonroi.Tenancy.SiteProfile.SourceGenerators | Tier: OSS | Distribution: NuGet.org

Purpose​

Roslyn code generators for automatic site profile registration, gRPC facades, and validation.

Generated Code​

Annotate your site profile class:

[GenerateSiteProfile(SiteIds.BRAVO, typeof(BravoOrderContext))]
public class BravoSiteProfile : ISiteProfile
{
    public string SiteId => SiteIds.BRAVO;
    public void RegisterServices(IServiceCollection services, IConfiguration config) { }
}

Generators create:

  1. SiteProfileRegistrationGenerator

    • MGeneratedSiteProfilesExtensions.g.cs
    • Contains AddGeneratedSiteProfiles() method for multi-site registration

  2. SiteGrpcFacadeGenerator

    • BravoServiceBFacade.g.cs
    • Auto-wraps gRPC services with site dispatch

  3. SiteProfileScaffoldingGenerator

    • BravoOrderContext.g.cs (if needed)
    • Partial DbContext with site-specific configuration

Analyzers​

The generators also provide Roslyn analyzers:

AnalyzerRuleCheck
SiteIdLiteralAnalyzerSITE001SiteId must be string literal, not variable
AssemblyIsolationHintAnalyzerSITE002Site assemblies should not cross-reference
ContractComplianceAnalyzerSITE003All sites must implement same contracts
ColumnMapDriftAnalyzerSITE004Column mappings must be consistent
InheritanceHintAnalyzerSITE005Inheritance patterns must match
MissingSiteGrpcServiceAttributeAnalyzerSITE006gRPC service missing [SiteGrpcService]
DuplicateProtoMessageAnalyzerSITE007Duplicate proto messages across sites
SiteGrpcServiceRegistryAnalyzerSITE008gRPC service not registered

Muonroi.Quota.Abstractions​

NuGet: Muonroi.Quota.Abstractions | Tier: OSS | Distribution: NuGet.org

Purpose​

Tenant quota tracking and enforcement. Limits resources per tenant (rules, executions, API calls, storage, etc.).

Key Types​

TypeKindPurpose
ITenantQuotaTrackerInterfaceCheck quota availability and increment usage
ITenantQuotaStoreInterfacePersist quota limits and usage
TenantQuotaModelQuota limits for a tenant
TenantQuotaPresetsStaticFree, Starter, Professional, Enterprise presets
QuotaUsageModelCurrent usage statistics
QuotaTypeEnumRules, Executions, DecisionTables, Storage, Messages, Connectors, etc.
InMemoryTenantQuotaStoreClassVolatile in-memory storage (testing)
InMemoryTenantQuotaTrackerClassVolatile in-memory tracker
TenantQuotaServiceCollectionExtensionsExtensionsAddTenantQuota() registration

Quota Types​

public enum QuotaType
{
    RulesPerTenant,
    RuleExecutionsPerDay,
    ConcurrentExecutions,
    DecisionTablesPerTenant,
    JsonWorkflows,
    StorageMB,
    ApiRequestsPerMinute,
    RuleEvaluationsPerSecond,
    WorkflowExecutionsPerHour,
    RuleComplexity,
    WorkflowSizeKB,
    ExecutionTimeMs,
    MessagesPerDay,
    MessagesPerMinute,
    TotalConnectors,
    ConnectorExecutionsPerDay
}

Quota Limits by Tier​

var freeQuota = TenantQuotaPresets.Free;
// MaxRulesPerTenant: 10
// MaxRuleExecutionsPerDay: 1000
// MaxApiRequestsPerMinute: 20

var enterpriseQuota = TenantQuotaPresets.Enterprise;
// MaxRulesPerTenant: int.MaxValue
// MaxRuleExecutionsPerDay: int.MaxValue
// MaxApiRequestsPerMinute: int.MaxValue

DI Registration​

// Use in-memory tracker (dev/testing)
services.AddTenantQuota();

// Or register custom persistent store
services.AddScoped<ITenantQuotaStore, PostgresQuotaStore>();
services.AddScoped<ITenantQuotaTracker>(sp =>
    new TenantQuotaTracker(sp.GetRequiredService<ITenantQuotaStore>()));

Usage Example​

public class RuleExecutor
{
    private readonly ITenantQuotaTracker _quota;

    public RuleExecutor(ITenantQuotaTracker quota)
    {
        _quota = quota;
    }

    public async Task<RuleResult> ExecuteAsync(string tenantId, IRule rule, CancellationToken ct)
    {
        // Check if tenant has execution quota remaining
        bool hasQuota = await _quota.CheckQuotaAsync(
            tenantId,
            QuotaType.RuleExecutionsPerDay,
            amount: 1,
            ct: ct);

        if (!hasQuota)
        {
            throw new QuotaExceededException(
                $"Tenant '{tenantId}' exceeded daily rule execution quota");
        }

        // Execute rule
        var result = await rule.ExecuteAsync(...);

        // Increment usage
        await _quota.IncrementUsageAsync(
            tenantId,
            QuotaType.RuleExecutionsPerDay,
            amount: 1,
            ct: ct);

        return result;
    }
}

Quota Integration with Rule Engine​

The rule engine automatically checks quota before execution (if quota tracker is registered):

// In RuleOrchestrator.ExecuteAsync(...)
if (_quotaTracker is not null)
{
    bool hasQuota = await _quotaTracker.CheckQuotaAsync(
        tenantId,
        QuotaType.RuleExecutionsPerDay,
        ct: ct);

    if (!hasQuota)
        return OrchestratorResult.Failure("Quota exceeded");
}

// Execute rules...
await _quotaTracker?.IncrementUsageAsync(tenantId, QuotaType.RuleExecutionsPerDay, ct: ct)!;

Complete Setup Example​

Program.cs (Multi-Site, Multi-Tenant)​

var builder = WebApplication.CreateBuilder(args);

// ===== Core Tenancy (HttpContext extraction + AsyncLocal storage) =====
builder.Services.AddTenancy(builder.Configuration);

// ===== Site Profile Infrastructure =====
builder.Services.AddMultiSiteProfiles(
    builder.Configuration,
    siteCodeAccessor: sp =>
    {
        var httpContext = sp.GetRequiredService<IHttpContextAccessor>()?.HttpContext;
        return httpContext?.Request.Headers["X-Site-Code"].FirstOrDefault() ?? "default";
    },
    assemblies: typeof(Program).Assembly);

// ===== Per-Site DbContext =====
builder.Services.AddSiteDbInfrastructure(o =>
{
    o.TenantId = sp => sp.GetRequiredService<ISystemExecutionContextAccessor>()
        .Get().TenantId;
    o.ConnectionString = sp =>
    {
        var factory = sp.GetRequiredService<ITenantConnectionStringFactory>();
        var tenantId = sp.GetRequiredService<ITenantContext>().TenantId;
        return factory.GetConnectionString(tenantId);
    };
    o.ConnectionStringTransform = cs => Cryptography.Decrypt(_secretKey, cs);
    o.ConfigureDbContext = (b, cs) => b.UseSqlServer(cs);
});

builder.Services.AddSiteDbContext<DefaultOrderContext>();
builder.Services.AddSiteDbContext<BravoOrderContext>();
builder.Services.AddSiteMigrationRunner();

// ===== Per-Site Dapper =====
builder.Services.AddSiteDapperInfrastructure(o =>
{
    o.WriteConnectionString = sp =>
    {
        var factory = sp.GetRequiredService<ITenantConnectionStringFactory>();
        var tenantId = sp.GetRequiredService<ITenantContext>().TenantId;
        return factory.GetConnectionString(tenantId);
    };
    o.ReadConnectionString = sp =>
    {
        // Optional: separate read replica
        return sp.GetRequiredService<IReadOnlyConnectionProvider>()
            .GetReadConnectionString();
    };
});

builder.Services.AddSiteResolvedService<IDapper>();
builder.Services.AddSiteResolvedService<IDapperRead>();
builder.Services.AddSiteSqlBuilder();

// ===== Quota Tracking =====
builder.Services.AddTenantQuota();

// ===== gRPC =====
builder.Services.AddSiteGrpc();

// ===== Site Profiles (source-generated or manual) =====
builder.Services.AddGeneratedSiteProfiles(builder.Configuration);

var app = builder.Build();

// ===== Middleware =====
app.UseMiddleware<TenantResolutionMiddleware>();
app.UseMiddleware<SiteProfileStateMiddleware>();

app.Run();

Site Profile Implementation​

[GenerateSiteProfile(SiteIds.BRAVO, typeof(BravoOrderContext))]
public class BravoSiteProfile : ISiteProfile
{
    public string SiteId => SiteIds.BRAVO;

    public void RegisterServices(IServiceCollection services, IConfiguration configuration)
    {
        // DbContext (already registered globally, but can customize here)
        services.AddSiteDbContext<BravoOrderContext>();

        // Repositories
        services.AddKeyedScoped<IOrderRepository, BravoOrderRepository>(SiteId);

        // Services
        services.AddKeyedScoped<IOrderService, BravoOrderService>(SiteId);

        // Dapper
        services.AddKeyedScoped<IDapper, BravoDapperImpl>(SiteId);
        services.AddKeyedScoped<IDapperRead, BravoDapperReadImpl>(SiteId);

        // Column mappings
        services.AddKeyedSingleton<ISiteColumnMap, BravoColumnMap>(SiteId);

        // gRPC services
        services.AddKeyedScoped<Catalog.CatalogService.CatalogServiceClient,
            BravoCatalogServiceClient>(SiteId);

        // Custom behavior
        services.AddKeyedScoped<ISiteStepHook, BravoAuditBehavior>(SiteId);
    }
}

Service Usage​

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IOrderService _orderService;
    private readonly ITenantContext _tenantContext;
    private readonly ISiteProfileResolver _siteResolver;
    private readonly ITenantQuotaTracker _quotaTracker;

    public OrdersController(
        IOrderService orderService,
        ITenantContext tenantContext,
        ISiteProfileResolver siteResolver,
        ITenantQuotaTracker quotaTracker)
    {
        _orderService = orderService;
        _tenantContext = tenantContext;
        _siteResolver = siteResolver;
        _quotaTracker = quotaTracker;
    }

    [HttpGet]
    public async Task<IActionResult> ListAsync()
    {
        // Tenant context resolved automatically from HTTP request
        var tenantId = _tenantContext.TenantId;

        // Site profile resolved automatically based on X-Site-Code header
        var site = _siteResolver.Current.SiteId;

        // Check quota
        bool hasQuota = await _quotaTracker.CheckQuotaAsync(
            tenantId,
            QuotaType.ApiRequestsPerMinute);

        if (!hasQuota)
            return StatusCode(429, "Rate limit exceeded");

        // Execute — site-specific service is injected
        var orders = await _orderService.ListAsync();

        await _quotaTracker.IncrementUsageAsync(
            tenantId,
            QuotaType.ApiRequestsPerMinute);

        return Ok(orders);
    }
}

Patterns & Best Practices​

Fail-Closed Security​

Always validate tenant context:

// ✓ Good: Explicit validation
if (TenantContext.CurrentTenantId is null)
{
    throw new UnauthorizedException("Tenant context required");
}

// ✗ Bad: Silent default
var tenantId = TenantContext.CurrentTenantId ?? "default-tenant";

Cross-Tenant Operations​

When admin needs cross-tenant access (rare):

using (TenantContext.AllowCrossTenantAccess = true)
{
    // Global query filters temporarily disabled
    var allTenants = await _dbContext.Tenants.ToListAsync();
}

Schema Divergence in Dapper​

Use SiteSqlBuilder to handle column name differences:

var sqlBuilder = sp.GetRequiredService<SiteSqlBuilder>();

// Builds SQL with site-specific column mappings
string sql = sqlBuilder.BuildSelectQuery<Order>(
    "WHERE CreatedAt > @date AND Status = @status");

// Executes: SELECT ... WHERE CRT_DT > @date AND STS = @status (for Bravo site)
var orders = await readContext.QueryAsync<Order>(sql, new { date, status });

Testing with Site Scope​

[Test]
public async Task OrderService_CreateAsync_SetsSiteCode()
{
    var bravo = new BravoSiteProfile();
    using (SiteProfileScope.SetCurrent(bravo))
    {
        var order = new Order { Name = "Test" };
        var created = await _orderService.CreateAsync(order);

        Assert.That(created.SiteCode, Is.EqualTo(SiteIds.BRAVO));
    }
}

Background Jobs (Quota Reset)​

[BackgroundJob("DailyQuotaReset")]
public class DailyQuotaResetJob : IBackgroundJob
{
    private readonly ITenantQuotaTracker _quotaTracker;

    public async Task ExecuteAsync(IJobExecutionContext context)
    {
        // No HTTP context here — set via AsyncLocal
        TenantContext.CurrentTenantId = "SYSTEM";

        await _quotaTracker.ResetDailyQuotasAsync(context.CancellationToken);
    }
}