bitzorcas
中 EN

Reference

Quota building block

Usage quota management — PlatformBilling module with subscription-based entitlements, usage recording, quota checking, and over-quota enforcement policies.

Last updated

BitzOrcas implements quota management through the PlatformBilling module. It provides subscription-based entitlement tracking, usage recording, and configurable over-quota enforcement.

Architecture

┌─────────────────────────────────────────────┐
│              PlatformBilling                │
│                                             │
│  Plan → Subscription → Entitlements       │
│                             │               │
│                             ▼               │
│                    Usage Records            │
│                             │               │
│                             ▼               │
│                    Quota Check              │
│                   (allow / deny / warn)     │
└─────────────────────────────────────────────┘

Core abstractions

QuotaService

public class QuotaService
{
    public QuotaCheckResult CheckQuota(
        TenantId tenantId,
        string entitlementKey,
        long requestedDelta);
}

EntitlementResolver

Resolves a tenant’s effective entitlements from their active subscription + catalog:

Tenant → Active Subscription → Plan → Catalog Offerings → Entitlements

OverQuotaBehavior

Configurable behavior when a tenant exceeds their quota:

PolicyDescription
DenyBlock the operation (HTTP 429 or 403)
WarnAllow with a warning header/notification
AllowNo enforcement (for internal/privileged tenants)

Key entities

EntityPurpose
PlatformBillingPlanEntityBilling plan definition (free, pro, enterprise)
PlatformBillingSubscriptionEntityTenant’s active subscription
PlatformBillingInvoiceEntityBilling invoices
PlatformBillingUsageRecordEntityUsage tracking records

Quota check flow

  1. Entitlement lookup: Resolve tenant’s subscription → plan → catalog offerings
  2. Usage aggregation: Sum recorded usage for the current billing period
  3. Quota comparison: Compare used vs. allowed
  4. Enforcement: Apply over-quota policy (deny/warn/allow)

Usage recording

Modules record usage through PlatformBillingService.RecordUsageAsync():

await billingService.RecordUsageAsync(
    tenantId,
    entitlementKey: "storage.files",
    delta: 1);

Configuration

{
  "PlatformBilling": {
    "DefaultOverQuotaBehavior": "Deny",
    "BillingCycleDays": 30
  }
}

See also