ما معنى Multi-Tenancy؟
Tenant هو customer/account/workspace مستقل داخل SaaS واحد. كل tenant قد يملك users و documents و projects و usage و settings خاصة به. Multi-tenancy تقلل تكلفة تشغيل نسخة منفصلة لكل عميل، لكنها تخلق مسؤولية أمنية: أي خطأ في query أو cache أو background job قد يكشف بيانات tenant آخر.
ميّز بين tenant و user و organization و workspace؛ قد يكون للعميل عدة workspaces، وقد ينتمي user لأكثر من tenant. لا تفترض أن tenant واحد يساوي user واحد. صمم identity membership واضحة: User ↔ Tenant عبر TenantMembership مع roles/permissions داخل tenant.
مثال عملي: نموذج العضوية الصح من أول يوم
شركة «Contoso Legal» عندها 3 فروع، وكل فرع عايز workspace منفصل، والمحامية «سارة» شغالة في فرعين. لو صممت الـ schema على إن User.TenantId عمود واحد، سارة محتاجة حسابين وإيميلين — وده أول طلب هيجيلك بعد أسبوعين من الإطلاق. الصح:
public sealed class Tenant { public Guid Id { get; init; } public string Slug { get; init; } = ""; public TenantStatus Status { get; set; } public string Plan { get; set; } = "free"; public string Region { get; init; } = "eu"; }
public sealed class AppUser { public Guid Id { get; init; } public string Email { get; init; } = ""; } // global identity, NOT tenant-scoped
public sealed class TenantMembership
{
public Guid TenantId { get; init; }
public Guid UserId { get; init; }
public string Role { get; set; } = "member"; // owner | admin | member | viewer
public DateTimeOffset JoinedAt { get; init; }
public DateTimeOffset? RevokedAt { get; set; } // soft revoke keeps audit history
}
public enum TenantStatus { Provisioning, Active, Suspended, PendingDeletion, Deleted }ليه كده؟ الهوية (مين إنت) عالمية، والصلاحية (تعمل إيه هنا) خاصة بكل tenant. ده نفس الفصل بين authentication و authorization اللي في Auth Pillar، بس بُعد إضافي.
منتج بدأ بـ User.TenantId. بعد سنة، عميل enterprise طلب «حساب واحد لمستشار خارجي يدخل على 4 شركات تابعة». الحل اتعمل كـ hack (حسابات مكررة بنفس الإيميل + suffix) وبوّظ الـ SSO والـ audit. التكلفة: migration للـ identity كلها. الدرس: membership table من أول يوم حتى لو أول نسخة بتسمح بـ tenant واحد لكل user.
Tenancy Models: Shared DB, Schema per Tenant, DB per Tenant
Shared database/shared schema: كل الجداول تحتوي TenantId. أقل تكلفة وأسهل migrations، لكن أي query ناقص filter خطر، و noisy neighbor قد يؤثر على الجميع. Schema per tenant يعزل namespace لكنه يزيد تعقيد migrations/connection management، ولا يوفر دائمًا عزلًا أمنيًا كاملًا وحده. Database per tenant يعطي isolation و backup/restore/region flexibility أقوى لكنه يرفع operational cost وإدارة connections والمigrations.
يمكن استخدام hybrid model: shared tier للعملاء الصغار و dedicated database للعملاء enterprise. القرار يعتمد على regulatory requirements، tenant count، data size، restore granularity، noisy-neighbor tolerance، و operational maturity. وثّق trade-off في ADR ولا تبدأ بأعلى تعقيد دون حاجة.
إزاي تختار فعلًا: جدول قرار برقم
| السؤال | لو الإجابة… | بيميل لـ |
|---|---|---|
| عدد الـ tenants المتوقع | آلاف صغيرة (self-serve) | Shared schema + RLS |
| عقود بتطلب عزل فيزيائي/backup منفصل | أيوه لبعض العملاء | Hybrid: silo لـ enterprise |
| Data residency (EU/KSA/…) | عملاء في مناطق مختلفة | DB/cluster لكل region (cells)، shared جوه الـ region |
| Restore لـ tenant واحد بدون الباقي | مطلب صريح | DB per tenant أو أدوات export/restore per tenant |
| نضج التشغيل | فريق صغير من غير DBA | ابدأ shared؛ كل DB زيادة = migrations و monitoring زيادة |
public sealed record TenantPlacement(Guid TenantId, string Region, string ConnectionName, bool Dedicated);
public sealed class TenantDbContextFactory(ITenantContext tenant, IPlacementStore placements, IConfiguration cfg)
{
public async Task<AppDb> CreateAsync(CancellationToken ct)
{
var p = await placements.GetAsync(tenant.TenantId, ct); // cached, from a control-plane table
var options = new DbContextOptionsBuilder<AppDb>()
.UseNpgsql(cfg.GetConnectionString(p.ConnectionName))
.Options;
return new AppDb(options, tenant); // same model, same migrations everywhere
}
}Failure case: فريق عمل «schema per tenant» لـ 3,000 tenant. كل migration بقت loop على 3,000 schema بتاخد ساعات، وواحدة فشلت في النص فبقى فيه tenants على نسختين من الـ schema. التفاصيل وحلها في SaaS Operations at Scale.
Tenant Resolution and Trusted Context
مصادر tenant resolution قد تكون subdomain أو route أو claim أو API key. أي قيمة من request يجب التحقق منها وربطها بالـ authenticated principal. Header مثل X-Tenant-Id ليس دليل صلاحية؛ هو selector فقط. استخرج membership من trusted identity/database، وتحقق أن user عضو في tenant المطلوب قبل إنشاء TenantContext scoped للطلب.
اجعل resolution مبكرًا في request pipeline، وتعامل مع missing/ambiguous tenant كخطأ واضح. في background jobs لا يوجد HttpContext؛ خزّن tenant ID كجزء من job payload ثم أعد التحقق من وجود tenant وحالته عند التنفيذ. لا تستخدم mutable static tenant state في تطبيق متعدد المستخدمين.
public sealed record TenantContext(Guid TenantId, Guid UserId);
public interface ITenantContextAccessor
{
TenantContext Current { get; }
}
// Resolve tenant selector -> authenticate principal -> verify membership ->
// create scoped TenantContext. Do not trust a raw X-Tenant-Id header by itself.Implementation كامل: من الـ request للـ TenantContext
public sealed class TenantResolutionMiddleware(RequestDelegate next)
{
public async Task InvokeAsync(HttpContext http, IMembershipStore members, TenantContextHolder holder)
{
if (http.User.Identity?.IsAuthenticated != true) { await next(http); return; } // auth endpoints etc.
// 1) selector: subdomain (acme.app.example) or route value; never trusted on its own
var slug = http.Request.Host.Host.Split('.')[0];
// 2) principal from the validated token
var userId = Guid.Parse(http.User.FindFirstValue("sub")!);
// 3) membership from OUR database (cached briefly), not from the request
var m = await members.FindAsync(slug, userId, http.RequestAborted);
if (m is null || m.RevokedAt is not null)
{
http.Response.StatusCode = StatusCodes.Status404NotFound; // 404 not 403: do not confirm the tenant exists
return;
}
if (m.TenantStatus is TenantStatus.Suspended or TenantStatus.PendingDeletion)
{
await Results.Problem(title: "Workspace unavailable", statusCode: 423).ExecuteAsync(http);
return;
}
holder.Current = new TenantContext(m.TenantId, userId, m.Role); // scoped service, set once per request
using (LogContextScope.Push("tenant_id", m.TenantId)) // every log line carries the tenant
await next(http);
}
}Background jobs: الـ job payload بيحمل TenantId و InitiatedBy، والـ worker بيبني TenantContext من جديد بعد ما يتأكد إن الـ tenant لسه Active والـ user لسه عضو (ممكن يكون اتشال بين الـ enqueue والتنفيذ).
endpoint POST /api/reports كان بياخد tenantId في الـ JSON «عشان الـ admin dashboard». مستخدم عادي غيّر الرقم وطلع تقرير tenant تاني. الـ global filter ما حماش لأن الكود استخدم الـ tenantId اللي جاي من الـ body في الـ filter نفسه. القاعدة: الـ tenant بييجي من TenantContext فقط؛ أي tenantId في input = 400.
Tenant Isolation in EF Core
EF Core Global Query Filters تضيف predicate تلقائيًا مثل TenantId == currentTenantId للكيانات tenant-scoped. هذا يقلل احتمال نسيان filter في LINQ، لكنه لا يغطي كل access path: raw SQL، bulk operations، IgnoreQueryFilters، detached entities، admin paths، و incorrectly scoped DbContext قد تتجاوز الحماية.
اجعل TenantId immutable بعد إنشاء entity، واملأه server-side من TenantContext لا من DTO. أضف composite indexes تبدأ بـ TenantId عندما يناسب query pattern، و unique constraints تشمل TenantId حتى لا تتعارض IDs بين العملاء. اختبر cross-tenant reads/writes في integration tests، ولا تعتمد على unit tests فقط.
// Illustrative EF Core configuration
modelBuilder.Entity<Invoice>()
.HasQueryFilter(x => x.TenantId == _tenantContext.TenantId);
modelBuilder.Entity<Invoice>()
.HasIndex(x => new { x.TenantId, x.InvoiceNumber })
.IsUnique();
// Also validate TenantId on writes and review raw SQL / IgnoreQueryFilters paths.الـ DbContext بالكامل + الأماكن اللي الفلتر ما بيغطيهاش
public interface ITenantOwned { Guid TenantId { get; } }
public sealed class AppDb(DbContextOptions<AppDb> options, ITenantContext tenant) : DbContext(options)
{
public DbSet<Invoice> Invoices => Set<Invoice>();
public DbSet<Document> Documents => Set<Document>();
protected override void OnModelCreating(ModelBuilder b)
{
foreach (var et in b.Model.GetEntityTypes().Where(t => typeof(ITenantOwned).IsAssignableFrom(t.ClrType)))
{
// Build `e => e.TenantId == tenant.TenantId` for every tenant-owned entity automatically.
var p = Expression.Parameter(et.ClrType, "e");
var body = Expression.Equal(Expression.Property(p, nameof(ITenantOwned.TenantId)),
Expression.Property(Expression.Constant(this), nameof(CurrentTenantId)));
b.Entity(et.ClrType).HasQueryFilter(Expression.Lambda(body, p));
b.Entity(et.ClrType).HasIndex(nameof(ITenantOwned.TenantId));
}
}
public Guid CurrentTenantId => tenant.TenantId; // evaluated per query, per context instance
public override Task<int> SaveChangesAsync(CancellationToken ct = default)
{
foreach (var e in ChangeTracker.Entries<ITenantOwned>())
{
if (e.State == EntityState.Added)
e.Property(nameof(ITenantOwned.TenantId)).CurrentValue = tenant.TenantId; // server-side, always
else if (e.State == EntityState.Modified && e.Property(nameof(ITenantOwned.TenantId)).IsModified)
throw new InvalidOperationException("TenantId is immutable");
}
return base.SaveChangesAsync(ct);
}
}Access paths خارج الفلتر (كل واحد لازم test): FromSqlRaw/SqlQuery، ExecuteUpdate/ExecuteDelete (بيحترموا الفلتر لكن راجع)، Dapper/ADO.NET reports، IgnoreQueryFilters() في الـ admin، الـ Find على entity متتبعة من context تاني، الـ projections لـ search engines والـ vector store، والـ exports. عشان كده RLS (s5) تحت الـ ORM.
أضف analyzer/architecture test بيمنع IgnoreQueryFilters برّه namespace معيّن (مثلًا Admin.CrossTenant) وكل استخدام له يتسجّل في الـ audit log.
Database Row-Level Security and Defense in Depth
PostgreSQL Row-Level Security (RLS) يسمح بكتابة policies تحدد الصفوف التي يمكن قراءتها أو تعديلها. عند تفعيله، يجب ضبط tenant context داخل transaction/session بطريقة لا تتسرب بين pooled connections. استخدم SET LOCAL داخل transaction عند الإمكان، وتأكد أن application role ليس table owner أو BYPASSRLS دون قصد؛ table owners قد يتجاوزون policies في الإعدادات المعتادة.
RLS طبقة دفاع إضافية وليست بديلًا عن application authorization. اختبر كل operation تحت database role الفعلي، وراجع policies للـ SELECT/INSERT/UPDATE/DELETE، وراجع connection pooling/reset semantics. خطأ في session variable أو role configuration قد يبطل العزل.
-- PostgreSQL conceptual example; adapt role names and transaction handling.
ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON invoices
USING (tenant_id = current_setting('app.tenant_id', true)::uuid)
WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid);
-- Set app.tenant_id transaction-locally from authenticated server context.المثال الكامل اتنفّذ في v2-rls — هنا الأخطاء اللي بتكسره
- الـ app بيتصل كـ owner الجدول: الـ owner بيتخطى الـ policies (إلا لو
FORCE ROW LEVEL SECURITY). الحل: role منفصل للتطبيق، والـ migrations بـ role تاني. SETبدلSET LOCALمع pooling: القيمة بتفضل على الـ connection وترجع للـ pool، والطلب الجاي (tenant تاني) يرثها لو ما اتضبطتش. استخدمset_config(..., true)جوه transaction.current_setting('app.tenant_id', true)رجّع NULL: المقارنةtenant_id = NULLبترجع NULL = مفيش صفوف = fail closed. ده كويس — اتأكد إنك ما كتبتش policy زيOR current_setting(...) IS NULL«عشان الـ jobs».- Policies ناقصة على INSERT/UPDATE:
USINGبيحمي القراءة؛WITH CHECKبيمنع كتابة صف بـ tenant تاني.
ALTER TABLE invoices FORCE ROW LEVEL SECURITY; -- even the owner obeys the policy
CREATE ROLE app_runtime LOGIN NOINHERIT NOBYPASSRLS; -- the API connects as this
CREATE ROLE app_migrator LOGIN; -- owns tables; used only by migrations
-- Admin/reporting across tenants is an explicit, audited role, not a missing filter:
CREATE ROLE app_crosstenant_reader NOLOGIN BYPASSRLS;Row-Level Security في PostgreSQL: عزل بيتنفذ حتى لو الكود نسي
الـ global query filter في EF Core بيحميك طول ما كل query بتعدّي عليه. أول FromSqlRaw، أول report مكتوب بـ Dapper، أول IgnoreQueryFilters() اتنسى — والعزل اتكسر في صمت. الـ Row-Level Security بيحط القاعدة في قاعدة البيانات نفسها: الصف اللي مش بتاع الـ tenant مش موجود من وجهة نظر الـ query، مهما كان اللي كتبها.
SET client_min_messages = warning;
DROP TABLE IF EXISTS invoices; DROP ROLE IF EXISTS app_user;
CREATE ROLE app_user NOLOGIN; -- the role the API connects as: NOT the table owner
CREATE TABLE invoices (
id int GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
tenant_id uuid NOT NULL,
customer text NOT NULL,
amount numeric(10,2) NOT NULL
);
GRANT SELECT, INSERT, UPDATE, DELETE ON invoices TO app_user;
INSERT INTO invoices (tenant_id, customer, amount) VALUES
('11111111-1111-1111-1111-111111111111', 'Nile Traders', 1200),
('11111111-1111-1111-1111-111111111111', 'Delta Foods', 340),
('22222222-2222-2222-2222-222222222222', 'Sahara Tech', 9900);
ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON invoices
USING (tenant_id = current_setting('app.tenant_id', true)::uuid) -- which rows are visible
WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid); -- which rows may be written
SET ROLE app_user;
\echo '--- no tenant set: fail closed (zero rows, not all rows)'
SELECT count(*) AS visible_rows FROM invoices;
\echo '--- tenant 1: a query with NO WHERE clause still sees only its own rows'
BEGIN;
SET LOCAL app.tenant_id = '11111111-1111-1111-1111-111111111111';
SELECT customer, amount FROM invoices ORDER BY id;
\echo '--- tenant 1 tries to update tenant 2''s invoice'
UPDATE invoices SET amount = 0 WHERE customer = 'Sahara Tech';
\echo '--- tenant 1 tries to insert a row for tenant 2 (rejected by WITH CHECK)'
SAVEPOINT s;
\set ON_ERROR_STOP off
INSERT INTO invoices (tenant_id, customer, amount) VALUES ('22222222-2222-2222-2222-222222222222', 'Planted row', 1);
\set ON_ERROR_STOP on
ROLLBACK TO s;
COMMIT;
\echo '--- tenant 2: its invoice is untouched'
BEGIN;
SET LOCAL app.tenant_id = '22222222-2222-2222-2222-222222222222';
SELECT customer, amount FROM invoices;
COMMIT;
RESET ROLE;
\echo '--- the table OWNER bypasses RLS unless FORCE is set'
SELECT count(*) AS owner_sees FROM invoices;
ALTER TABLE invoices FORCE ROW LEVEL SECURITY;
DROP TABLE invoices; DROP ROLE app_user;SET
DROP TABLE
DROP ROLE
CREATE ROLE
CREATE TABLE
GRANT
INSERT 0 3
ALTER TABLE
CREATE POLICY
SET
--- no tenant set: fail closed (zero rows, not all rows)
visible_rows
--------------
0
(1 row)
--- tenant 1: a query with NO WHERE clause still sees only its own rows
BEGIN
SET
customer | amount
--------------+---------
Nile Traders | 1200.00
Delta Foods | 340.00
(2 rows)
--- tenant 1 tries to update tenant 2's invoice
UPDATE 0
--- tenant 1 tries to insert a row for tenant 2 (rejected by WITH CHECK)
SAVEPOINT
psql: line 37: ERROR: new row violates row-level security policy for table "invoices"
ROLLBACK
COMMIT
--- tenant 2: its invoice is untouched
BEGIN
SET
customer | amount
-------------+---------
Sahara Tech | 9900.00
(1 row)
COMMIT
RESET
--- the table OWNER bypasses RLS unless FORCE is set
owner_sees
------------
3
(1 row)
ALTER TABLE
DROP TABLE
DROP ROLEمن غير tenant: صفر صفوف. current_setting('app.tenant_id', true) بترجّع NULL لو الإعداد مش موجود، و tenant_id = NULL عمرها ما تبقى true. يعني نسيان تحديد الـ tenant بيدّي نتيجة فاضية (bug واضح) بدل ما يدّي كل البيانات (كارثة). ده معنى fail closed.
الـ UPDATE رجّع UPDATE 0 مش error: صف الـ tenant التاني مش مرئي أصلًا فمفيش حاجة تتعدّل. والـ INSERT اترفض بسبب WITH CHECK — من غيرها tenant يقدر «يزرع» صفوف عند غيره.
SET LOCAL جوه transaction: الإعداد بيتمسح مع نهاية الـ transaction. ده ضروري مع connection pooling: لو استخدمت SET عادي، الـ connection هيرجع للـ pool وهو لسه شايل tenant الطلب اللي فات — والطلب الجاي ممكن يشتغل بهوية غلط.
الـ owner والـ superuser بيعدّوا الـ RLS. الـ API لازم يتصل بـ role عادي مش صاحب الجداول، والـ migrations بـ role تاني. FORCE ROW LEVEL SECURITY بيطبق الـ policies على الـ owner كمان.
ربطها بـ EF Core
الـ SQL فوق اتنفذ فعلًا على PostgreSQL 16. كود C# اللي تحت لم يتم عمل compile له.
public sealed class TenantTransactionInterceptor(ITenantContext tenant) : DbTransactionInterceptor
{
public override async Task TransactionStartedAsync(
DbConnection connection, TransactionEndEventData eventData, CancellationToken ct = default)
{
await using var cmd = connection.CreateCommand();
cmd.Transaction = eventData.Transaction;
// set_config(name, value, is_local = true) is the parameterisable form of SET LOCAL
cmd.CommandText = "SELECT set_config('app.tenant_id', @tenant, true)";
var p = cmd.CreateParameter(); p.ParameterName = "tenant"; p.Value = tenant.TenantId.ToString();
cmd.Parameters.Add(p);
await cmd.ExecuteNonQueryAsync(ct);
}
}
// Registration: every unit of work runs inside an explicit transaction, so the setting is always present.
builder.Services.AddScoped<TenantTransactionInterceptor>();
builder.Services.AddDbContext<AppDbContext>((sp, o) => o
.UseNpgsql(connectionString) // connects as app_user, not as the table owner
.AddInterceptors(sp.GetRequiredService<TenantTransactionInterceptor>()));Defense in depth: خلّي الـ global query filter موجود (بيدّي queries أوضح وأخطاء بدري في الـ tests) والـ RLS تحته كشبكة أمان. الاتنين بياخدوا الـ tenant من نفس المصدر: الـ token المتحقق منه، مش header ولا query string.
الـ test اللي لازم يكون موجود: integration test بيعمل بيانات لـ tenant A و B، وبينفذ raw SQL من غير WHERE بهوية A، ويتأكد إن صفوف B مش راجعة. لو الـ test ده عدّى من غير RLS يبقى مش بيختبر حاجة.
| نموذج العزل | العزل | التكلفة التشغيلية | مناسب لـ |
|---|---|---|---|
Shared schema + tenant_id + RLS | منطقي، مفروض من قاعدة البيانات | الأقل: migration واحدة، pool واحد | أغلب الـ B2B SaaS — نقطة البداية |
| Schema لكل tenant | أقوى؛ backup/restore لكل tenant ممكن | migrations × عدد الـ tenants | عشرات–مئات tenants بمتطلبات مختلفة |
| Database لكل tenant | الأقوى؛ noisy neighbour معزول | الأعلى: provisioning، connections، تكلفة | enterprise، residency، compliance |
SET بيفضل طول عمر الـ session، والـ session في الـ pooling بتتشارك بين requests. SET LOCAL (أو set_config(..., true)) محصور في الـ transaction وبيتمسح تلقائيًا.فعّلت RLS والـ API لسه بيرجّع بيانات كل الـ tenants. أرجح سبب؟
BYPASSRLS مش بيتطبق عليهم الـ policies افتراضيًا. اتصل بـ role محدود الصلاحيات، واستخدم FORCE ROW LEVEL SECURITY كحماية إضافية.Tenant Permissions, Quotas and Noisy Neighbors
Tenant-level authorization answers “هل هذا المستخدم مسموح له بهذا الفعل على هذا المورد داخل tenant؟”. Quota answers “كم استهلاك هذا tenant مسموح؟”. Rate limit controls request frequency؛ concurrency limit controls simultaneous expensive work؛ usage quota controls cumulative consumption مثل tokens أو storage أو documents.
ضع limits حسب plan مع server-side enforcement. استخدم atomic counters أو usage ledger موثوق، ولا تعتمد على client-side counters. صمم burst allowance و grace policy و overage behavior. راقب noisy neighbor عبر CPU/queue depth/DB connections/model concurrency per tenant، واستخدم fair scheduling أو per-tenant queues عند الحاجة.
public sealed record TenantLimits(int RequestsPerMinute, int MaxConcurrentAiJobs, long MonthlyTokenBudget);
// Enforce at the server boundary using atomic counters / durable usage records.
// Return 429 for rate limit, 403/402-style product state for exhausted plan,
// and expose reset/upgrade guidance without leaking another tenant's usage.Noisy neighbor بالأرقام: FIFO مقابل fair queueing
Tenant كبير رفع 400 مستند مرة واحدة. لو الـ ingestion workers بتسحب من طابور واحد FIFO، كل الـ tenants الصغيرين بيستنوا وراه. Fair queueing (round-robin بين طوابير الـ tenants) بيحمي الصغيرين والكبير بيدفع تمن زيادة بسيط:
import random
from collections import deque
random.seed(9)
# 3 small tenants send a steady trickle; tenant "big" uploads 400 documents at t=10s.
jobs = []
for t in range(0, 120):
for tenant in ("t-small-1", "t-small-2", "t-small-3"):
if random.random() < 0.25: jobs.append((t + random.random(), tenant))
jobs += [(10 + i * 0.01, "t-big") for i in range(400)]
jobs.sort()
WORKERS, JOB_S = 4, 2.0 # 4 workers, each ingestion job takes 2 s
def simulate(policy):
queues = {} ; fifo = deque(); pending = deque(jobs); waits = {}
free_at = [0.0] * WORKERS; rr = deque()
now = 0.0
while pending or fifo or any(queues.values()):
w = min(range(WORKERS), key=lambda i: free_at[i]); now = max(now, free_at[w])
while pending and pending[0][0] <= now: # enqueue arrivals
arr, ten = pending.popleft()
if policy == "fifo": fifo.append((arr, ten))
else:
if ten not in queues: queues[ten] = deque()
if not queues[ten] and ten not in rr: rr.append(ten)
queues[ten].append(arr)
job = None
if policy == "fifo" and fifo: job = fifo.popleft()
elif policy == "fair":
while rr and not queues[rr[0]]: rr.popleft()
if rr:
ten = rr.popleft(); job = (queues[ten].popleft(), ten)
if queues[ten]: rr.append(ten) # round-robin across tenants
if job is None:
now = pending[0][0] if pending else now; free_at[w] = max(free_at[w], now); continue
waits.setdefault(job[1], []).append(now - job[0]); free_at[w] = now + JOB_S
return waits
for pol in ("fifo", "fair"):
w = simulate(pol)
small = sorted(x for k, v in w.items() if k != "t-big" for x in v)
big = sorted(w["t-big"])
print(f"{pol:5s} small tenants: p50 wait {small[len(small)//2]:6.1f}s p95 {small[int(len(small)*.95)]:6.1f}s | big tenant p95 {big[int(len(big)*.95)]:6.1f}s")fifo small tenants: p50 wait 169.3s p95 198.0s | big tenant p95 189.1s
fair small tenants: p50 wait 1.1s p95 1.9s | big tenant p95 237.1sفي الإنتاج: طابور لكل tenant (أو partitioning بالـ tenant في Service Bus/RabbitMQ/Kafka أو جدول jobs في Postgres بـ ORDER BY عادل)، وحد للـ concurrency لكل tenant، والـ plan بيحدد الأولوية (enterprise weight أعلى = weighted fair queueing).
builder.Services.AddRateLimiter(o =>
{
o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
o.AddPolicy("per-tenant", http =>
{
var t = http.RequestServices.GetRequiredService<ITenantContext>();
var limits = http.RequestServices.GetRequiredService<IPlanCatalog>().For(t.TenantId);
return RateLimitPartition.GetTokenBucketLimiter(t.TenantId.ToString(), _ => new TokenBucketRateLimiterOptions
{
TokenLimit = limits.Burst, TokensPerPeriod = limits.RequestsPerMinute,
ReplenishmentPeriod = TimeSpan.FromMinutes(1), QueueLimit = 0, AutoReplenishment = true
});
});
});
// app.MapPost("/api/chat", ...).RequireRateLimiting("per-tenant");
// NOTE: in-memory limiters are per instance; with N instances use a distributed limiter (Redis) or divide limits by N.Subscriptions, Metering and AI Cost Attribution
Subscription plan يحدد entitlements: seats، storage، API calls، document pages، و AI tokens. لا تخلط plan name مع enforcement logic؛ استخدم entitlement model قابل للتطور. Metering يسجل usage events immutable مع tenant، feature، quantity، unit، timestamp، provider/model، و correlation ID. Billing aggregation يقرأ ledger ولا يعتمد على counters قابلة للتعديل فقط.
في AI، سجّل input/output tokens و embedding/reranking/OCR costs، retries، cache hits، و model route. احسب internal cost و billable usage بشكل منفصل لأن provider price و commercial pricing ليسا الشيء نفسه. أضف reconciliation مع provider invoices، idempotent usage ingestion، و dispute audit.
public sealed record UsageEvent(
Guid TenantId, string Feature, string Unit,
decimal Quantity, string ModelId, string CorrelationId,
DateTimeOffset OccurredAt);
// Store immutable events; aggregate by billing period and entitlement version.
// Deduplicate provider callbacks/events with a stable event ID.Ledger عملي + الربط بالفوترة
CREATE TABLE usage_events (
event_id text PRIMARY KEY, -- idempotency: same event twice = one row
tenant_id uuid NOT NULL,
feature text NOT NULL, -- 'ai.chat', 'ai.embed', 'storage.gb_day', 'seats'
unit text NOT NULL, -- 'input_token', 'output_token', 'page', 'seat_day'
quantity numeric(20,6) NOT NULL CHECK (quantity >= 0),
cost_usd numeric(20,8), -- OUR provider cost (internal), from a versioned price table
model_id text,
price_version text,
occurred_at timestamptz NOT NULL,
ingested_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ON usage_events (tenant_id, occurred_at);
-- Billable usage for a period is a query over immutable facts, never a mutable counter:
SELECT feature, unit, sum(quantity) AS qty, sum(cost_usd) AS our_cost
FROM usage_events
WHERE tenant_id = $1 AND occurred_at >= $2 AND occurred_at < $3
GROUP BY feature, unit;ليه immutable events؟ لما العميل يعترض على فاتورة، لازم تقدر تقول «الـ 2.1 مليون token دول جم من 3,412 request، ودي الـ traces». الـ counter اللي بيتعدل ما بيجاوبش. وتفاصيل الخطط والـ entitlements والـ webhooks في Billing & Subscriptions.
الـ usage event اتبعت من الـ API بعد الرد، والـ client عمل retry بعد timeout ← نفس الاستهلاك اتسجل مرتين. الحل: event_id مشتق من (request id + نوع الاستهلاك) و PRIMARY KEY عليه + ON CONFLICT DO NOTHING.
Enterprise SSO, Tenant Lifecycle and Data Operations
Enterprise SSO غالبًا عبر OIDC أو SAML حسب customer IdP. اربط external subject بالـ tenant membership، وراجع domain verification و JIT provisioning و SCIM lifecycle إن احتجت. لا تسمح لأي email domain بمجرد مطابقته أن ينشئ membership تلقائيًا دون verified ownership/policy. دعم MFA/session policy و audit export قد يكون مطلوبًا.
Tenant lifecycle يشمل provisioning، plan change، suspension، export، deletion، restore، و region migration. deletion يجب أن يغطي primary DB و search/vector indexes و object storage و caches و derived AI artifacts وفق retention/legal holds. backup deletion لها semantics مختلفة وقد تحتاج expiry policy. وثّق tenant offboarding runbook واختبره.
Tenant lifecycle كـ state machine
- Provisioning idempotent: لو الخطوة 3 من 5 فشلت (إنشاء bucket مثلًا)، إعادة التشغيل تكمّل من غير ما تكرر.
- Suspended: القراءة/export مسموح غالبًا، الكتابة والـ AI ممنوعين، الـ jobs متوقفة — والـ UI بيقول ليه وإزاي يرجع.
- Deletion: نفس فكرة الـ erasure orchestrator + verifier في Governance، لكن على مستوى tenant: DB rows، vectors، blobs، caches، search indexes، traces، adapters، و backups بالـ expiry.
SSO pitfall: «أي حد إيميله ينتهي بـ @acme.com يدخل tenant Acme تلقائيًا» من غير domain verification (DNS TXT) = أي حد يسجل الدومين ده عند IdP ضعيف أو acme.com.evil يقدر يدخل. JIT provisioning مسموح بس بعد التحقق من ملكية الدومين ومن الـ IdP المربوط.
اختبار SaaS Isolation عمليًا
أنشئ Tenant A و Tenant B، وجرّب قراءة resource ID صحيح تابع للآخر، تحديثه، حذفه، البحث عنه في vector index، استرجاعه من cache، تشغيل background job له، وتنفيذ MCP tool عليه. اختبر أيضًا tenant switching داخل نفس user session، revoked membership، disabled tenant، و raw SQL/reporting endpoints.
اختبارات العزل يجب أن تكون integration/security tests على نفس roles/configuration المستخدمة فعليًا. أضف negative assertions: لا result، لا metadata leak، لا count leak، لا cache hit cross-tenant. أي cross-tenant leak هو release blocker.
# Example test matrix (automate with integration tests)
checks = [
'API_GET_cross_tenant_resource_denied',
'EF_Core_query_filter_applied',
'raw_SQL_RLS_policy_enforced',
'vector_search_acl_filter_applied',
'cache_key_includes_tenant',
'background_job_revalidates_tenant',
'MCP_tool_checks_resource_tenant',
]
print('Isolation checks:', len(checks))الـ matrix ده كـ xUnit test حقيقي
public sealed class IsolationMatrixTests(ApiFactory api) : IClassFixture<ApiFactory>
{
public static TheoryData<string, string> Endpoints => new()
{
{ "GET", "/api/invoices/{id}" },
{ "PUT", "/api/invoices/{id}" },
{ "DELETE", "/api/invoices/{id}" },
{ "GET", "/api/documents/{id}/download" },
{ "POST", "/api/chat?docId={id}" }, // AI path: retrieval must not see the other tenant
};
[Theory, MemberData(nameof(Endpoints))]
public async Task Tenant_B_cannot_touch_tenant_A_resources(string method, string template)
{
var aId = await api.SeedInvoiceAndDocAsync(tenant: "a");
var client = api.ClientFor(tenant: "b", role: "admin"); // even an ADMIN of B
var resp = await client.SendAsync(new HttpRequestMessage(new HttpMethod(method), template.Replace("{id}", aId.ToString())));
Assert.True(resp.StatusCode is HttpStatusCode.NotFound or HttpStatusCode.Forbidden, $"{method} {template} -> {resp.StatusCode}");
var body = await resp.Content.ReadAsStringAsync();
Assert.DoesNotContain("tenant-a-secret", body); // no data or metadata leak in errors either
}
}شغّله في CI على Postgres حقيقي (Testcontainers) بنفس الـ roles بتاعة الإنتاج. أي endpoint جديد لازم يتضاف للـ matrix — وتقدر تخلي test تاني يلف على كل الـ endpoints المسجلة (EndpointDataSource) ويفشل لو endpoint فيه {id} مش موجود في الـ matrix.
اختبر فهمك
هل X-Tenant-Id القادم من المتصفح دليل authorization؟
لماذا Global Query Filters ليست boundary أمنية وحيدة؟
لماذا نفصل usage ledger عن plan entitlements؟
تمارين محلولة
1: Redis cache key = invoice:{id}. فين المشكلة؟
الحل: لو الـ IDs مش globally unique (أو حتى لو unique)، أي bug في الـ authorization بعد الـ cache ممكن يرجّع بيانات tenant تاني، والمسح لكل tenant مستحيل. الـ key: t:{tenantId}:invoice:{id}، والـ cache layer نفسه بيرفض keys من غير prefix tenant.
2: عميل enterprise عايز «backup و restore للـ tenant بتاعنا بس» وانتوا shared schema. إيه الخيارات؟
الحل: (1) logical export/import per tenant (كل الجداول بـ tenant_id + blobs + vectors) كـ feature مختبرة. (2) نقله لـ silo DB (placement) لو العقد يبرر التكلفة. (3) PITR للـ DB كلها مش حل لأنه بيرجّع كل الـ tenants. القرار في ADR مع تكلفة الـ silo في الـ pricing.
3: Job بيبعت تقارير شهرية لكل tenants، وحد بلّغ إنه استلم تقرير شركة تانية. فين تدوّر؟
الحل: الـ job كان بيستخدم DbContext واحد (scoped للـ job) وبيلف على الـ tenants ← TenantContext اتضبط مرة واحدة أو الـ cache بتاع الـ filter. الإصلاح: scope جديد (DbContext جديد) لكل tenant، والـ email recipient يتجاب من نفس الـ scope، و test بيشغل الـ job على tenantين ويتأكد من الفصل.
Mini project: Tenant isolation kit
للـ CAPSTONE/: membership model، middleware الـ resolution، AppDb بالفلاتر التلقائية والـ TenantId immutable، RLS بـ FORCE و roles منفصلة، rate limiter per tenant، fair queue للـ ingestion، و IsolationMatrixTests على Testcontainers. معيار القبول: شيل الـ global filter عمدًا ← RLS لسه بيمنع التسريب والـ tests بتعدي؛ شيل RLS كمان ← الـ tests تفشل.
أسئلة إنترفيو: Junior → Senior → Staff
(Junior) ليه ما نثقش في X-Tenant-Id header؟
(Senior) Global query filters كفاية للعزل؟
(Senior) إزاي تتعامل مع noisy neighbor في AI ingestion؟
(Staff) صمم tenancy لـ SaaS هيبيع لـ SMBs و banks في 3 regions.
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خريطة التغطية: 18 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.