اللي بيتكسر لما الـ tenants يبقوا 500
مع 5 عملاء، migration بتتعمل بإيدك، والـ support بيدخل الـ DB يشوف المشكلة، والـ cache key مش مهم. مع 500 (أو 50 DB منفصلة لعملاء enterprise)، كل عملية يدوية بتبقى حادثة مستنية تحصل. الدرس ده عن تحويل العمليات دي لأنظمة: قابلة للتكرار، للإيقاف، للمراجعة، ومحدودة الأثر.
Migrations عبر مئات الـ tenants
المشكلة: silos (DB لكل tenant enterprise) أو schemas لكل tenant يعني الـ migration بتتنفذ N مرة. لو اتعملت كـ loop في الـ deploy: بتطوّل الـ deploy، وفشل في النص بيسيب tenants على نسخ مختلفة، والكود الجديد بيقابل schema قديمة.
public sealed class TenantMigrationOrchestrator(IPlacementStore placements, IMigrationRunner runner,
ControlPlaneDb cp, ILogger<TenantMigrationOrchestrator> log)
{
public async Task RunWaveAsync(string targetVersion, IReadOnlyList<Guid> wave, int parallelism, CancellationToken ct)
{
await Parallel.ForEachAsync(wave, new ParallelOptions { MaxDegreeOfParallelism = parallelism, CancellationToken = ct },
async (tenantId, token) =>
{
var state = await cp.SchemaVersions.SingleAsync(s => s.TenantId == tenantId, token);
if (state.Version == targetVersion) return; // idempotent: resume skips finished tenants
if (await cp.IsPausedAsync(token)) return; // kill switch for the whole rollout
try
{
var p = await placements.GetAsync(tenantId, token);
await runner.MigrateAsync(p.ConnectionName, targetVersion, timeout: TimeSpan.FromMinutes(10), token);
state.Version = targetVersion; state.LastError = null;
}
catch (Exception ex)
{
state.LastError = ex.Message[..Math.Min(500, ex.Message.Length)];
log.LogError(ex, "Migration {Version} failed for {Tenant}", targetVersion, tenantId);
}
state.UpdatedAt = DateTimeOffset.UtcNow;
await cp.SaveChangesAsync(token);
});
var failed = await cp.SchemaVersions.CountAsync(s => wave.Contains(s.TenantId) && s.Version != targetVersion, ct);
if (failed > wave.Count * 0.02) await cp.PauseAsync($"wave failure rate {failed}/{wave.Count}", ct); // stop the line
}
}- Expand/contract شرط: الكود لازم يشتغل مع النسختين (القديمة والجديدة) طول فترة الـ rollout، لأن tenants هتبقى على الاتنين لأيام.
- Long-running DDL: على جداول كبيرة استخدم عمليات ما بتقفلش الجدول (
CREATE INDEX CONCURRENTLY، إضافة عمود nullable، backfill بـ batches)، وفي PostgreSQL حطlock_timeoutعشان migration ما تقفلش الإنتاج. - Shared schema: migration واحدة، لكن backfills ممكن تتعمل per tenant على موجات بنفس الـ orchestrator.
Migration بتضيف NOT NULL column بـ default على جدول 400M صف في نسخة PostgreSQL قديمة ← rewrite للجدول وقفل لساعة. (النسخ الحديثة بتتعامل مع الـ default الثابت من غير rewrite، لكن default متغير زي now() لأ.) الدرس: كل migration بتتراجع لـ «هل بتعمل lock/rewrite؟» وبتتجرب على نسخة بحجم الإنتاج.
Cache و queue و storage و observability واعية بالـ tenant
| الطبقة | القاعدة | ليه |
|---|---|---|
| Redis keys | t:{tenantId}:{area}:{id}، prefix إجباري من helper | عزل، مسح per tenant، تحليل الاستهلاك |
| Queues | tenant في الـ message envelope + fair scheduling + per-tenant concurrency | noisy neighbor، إعادة بناء الـ context في الـ worker |
| Blob storage | container أو prefix لكل tenant، SAS قصيرة المدة scoped للـ prefix | عزل الوصول، lifecycle وحذف |
| Logs/traces | tenant.id attribute على كل span/log | «العميل X بيشتكي» ← فلتر واحد |
| Metrics | tier/plan كـ label، مش tenant id (cardinality) | تكلفة وأداء الـ metrics backend |
| Dashboards | per-tenant views من الـ traces/logs للـ support | تشخيص سريع من غير دخول الـ DB |
public sealed class TenantCache(IConnectionMultiplexer redis, ITenantContext tenant)
{
private IDatabase Db => redis.GetDatabase();
private string Key(string area, string id) => $"t:{tenant.TenantId:N}:{area}:{id}"; // the only way to build a key
public async Task<T?> GetAsync<T>(string area, string id) =>
await Db.StringGetAsync(Key(area, id)) is { HasValue: true } v ? JsonSerializer.Deserialize<T>(v.ToString()) : default;
public Task SetAsync<T>(string area, string id, T value, TimeSpan ttl) =>
Db.StringSetAsync(Key(area, id), JsonSerializer.Serialize(value), ttl);
// Offboarding / incident response: remove everything of one tenant without touching others.
public async Task PurgeTenantAsync(IServer server, CancellationToken ct)
{
await foreach (var k in server.KeysAsync(pattern: $"t:{tenant.TenantId:N}:*", pageSize: 1000).WithCancellation(ct))
await Db.KeyDeleteAsync(k);
}
}Outgoing webhooks: موقّعة وبتتعاد ومتسجلة
لما المنتج بتاعك يبعت events للعملاء (مستند اتفهرس، agent خلص، فاتورة)، إنت بقيت الـ provider. نفس القواعد اللي بتطلبها من Stripe: توقيع (عشان العميل يتأكد إنه منك)، timestamp (ضد replay)، delivery id (عشان العميل يعمل idempotency)، retries بـ backoff، delivery log يشوفه العميل، وتعطيل الـ endpoint اللي بيفشل باستمرار مع إشعار. ومواصفة زي Standard Webhooks بتوحّد الشكل ده.
import hmac, hashlib, secrets, time, json
# ---------- 1) outgoing webhooks: sign, verify, reject tampering, old timestamps and replays ----------
SECRET = secrets.token_bytes(32) # per-subscriber secret, shown once to the customer
def sign(body: bytes, ts: int, secret: bytes) -> str:
return hmac.new(secret, f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
seen_ids = set()
def verify(headers: dict, body: bytes, secret: bytes, now: int, tolerance=300):
ts = int(headers["X-Timestamp"])
if abs(now - ts) > tolerance: return "reject: timestamp outside tolerance"
expected = sign(body, ts, secret)
if not hmac.compare_digest(expected, headers["X-Signature"]): return "reject: bad signature"
if headers["X-Delivery-Id"] in seen_ids: return "ignore: duplicate delivery (already processed)"
seen_ids.add(headers["X-Delivery-Id"]); return "accept"
now = int(time.time())
body = json.dumps({"type": "document.indexed", "tenant": "t-42", "doc": "d-9"}).encode()
good = {"X-Timestamp": str(now), "X-Signature": sign(body, now, SECRET), "X-Delivery-Id": "dlv_1"}
print("1) valid delivery ->", verify(good, body, SECRET, now))
print(" same delivery again ->", verify(good, body, SECRET, now + 5))
print(" tampered body ->", verify(dict(good, **{"X-Delivery-Id": "dlv_2"}), body.replace(b"d-9", b"d-1"), SECRET, now))
old = {"X-Timestamp": str(now - 3600), "X-Signature": sign(body, now - 3600, SECRET), "X-Delivery-Id": "dlv_3"}
print(" replayed old capture->", verify(old, body, SECRET, now))
# retry schedule with exponential backoff + jitter, capped, then dead-letter
import random; random.seed(1)
delays = [min(3600, 30 * 2 ** n * random.uniform(0.8, 1.2)) for n in range(8)]
print(" retry delays (s):", [round(d) for d in delays], "-> then mark endpoint unhealthy + notify tenant admin")
# ---------- 2) API keys: show once, store only a hash, look up by prefix ----------
def new_api_key():
prefix = "sk_live_" + secrets.token_hex(4) # identifiable, safe to log / display
secret_part = secrets.token_urlsafe(32)
full = f"{prefix}.{secret_part}"
stored = {"prefix": prefix, "hash": hashlib.sha256(full.encode()).hexdigest(), "scopes": ["documents:read", "chat:write"]}
return full, stored
full, stored = new_api_key()
DB = {stored["prefix"]: stored}
def authenticate(presented: str):
prefix = presented.split(".")[0]
row = DB.get(prefix)
if not row: return None
ok = hmac.compare_digest(row["hash"], hashlib.sha256(presented.encode()).hexdigest())
return row["scopes"] if ok else None
print("\n2) key shown once :", full[:20] + "...", "| stored:", {k: (v[:12] + "..." if k == "hash" else v) for k, v in stored.items()})
print(" correct key scopes :", authenticate(full))
print(" wrong secret :", authenticate(stored["prefix"] + ".guess"))
# (High-entropy random keys make a fast hash acceptable; passwords would need a slow KDF like Argon2/PBKDF2.)1) valid delivery -> accept
same delivery again -> ignore: duplicate delivery (already processed)
tampered body -> reject: bad signature
replayed old capture-> reject: timestamp outside tolerance
retry delays (s): [26, 68, 133, 216, 479, 941, 2036, 3600] -> then mark endpoint unhealthy + notify tenant admin
2) key shown once : sk_live_b4714a81.Gkd... | stored: {'prefix': 'sk_live_b4714a81', 'hash': 'fa790b9c890d...', 'scopes': ['documents:read', 'chat:write']}
correct key scopes : ['documents:read', 'chat:write']
wrong secret : Nonepublic sealed class WebhookSender(HttpClient http, IWebhookSecrets secrets, AppDb db)
{
public async Task<bool> DeliverAsync(WebhookDelivery d, CancellationToken ct)
{
var body = Encoding.UTF8.GetBytes(d.PayloadJson);
var ts = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
var secret = await secrets.GetAsync(d.SubscriptionId, ct);
var sig = Convert.ToHexString(HMACSHA256.HashData(secret, [.. Encoding.UTF8.GetBytes($"{ts}."), .. body])).ToLowerInvariant();
using var req = new HttpRequestMessage(HttpMethod.Post, d.Url) { Content = new ByteArrayContent(body) };
req.Content.Headers.ContentType = new("application/json");
req.Headers.Add("X-Delivery-Id", d.Id.ToString());
req.Headers.Add("X-Timestamp", ts.ToString());
req.Headers.Add("X-Signature", sig);
using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
cts.CancelAfter(TimeSpan.FromSeconds(10)); // never let a slow customer block our workers
HttpResponseMessage? resp = null;
try { resp = await http.SendAsync(req, cts.Token); } catch (Exception) { /* recorded below */ }
db.WebhookAttempts.Add(new(d.Id, d.Attempt, (int?)resp?.StatusCode, DateTimeOffset.UtcNow)); // customer-visible log
await db.SaveChangesAsync(ct);
return resp?.IsSuccessStatusCode == true;
}
}
// SSRF: validate customer URLs (https only, resolve and block private/link-local ranges) when saving AND when sending.API keys: تصميم آمن
- Show once: المفتاح الكامل بيظهر مرة واحدة وقت الإنشاء؛ بعد كده prefix وآخر 4 بس.
- Store a hash: المفاتيح عشوائية بإنتروبي عالي، فـ SHA-256 كفاية (مش زي الـ passwords اللي محتاجة KDF بطيء). تسريب الـ DB ما يكشفش مفاتيح صالحة.
- Prefix قابل للتعرف (
sk_live_): بيسهل الـ lookup، وبيخلي أدوات secret scanning (زي GitHub) تكتشف المفاتيح المتسربة في repos. - Scopes بأقل صلاحية، tenant مربوط بالمفتاح (مش بالـ request)، تاريخ انتهاء اختياري، و last-used للتنظيف.
- Rotation من غير downtime: مفتاحين صالحين في نفس الوقت لفترة انتقالية.
Audit logs و admin impersonation
الاحتياج: الـ support محتاج يشوف المشكلة زي ما العميل شايفها. الخطر: «login as user» = أقوى صلاحية في النظام. التصميم الآمن:
public sealed record ImpersonationGrant(Guid Id, Guid TenantId, Guid TargetUserId, string SupportAgentId,
string TicketId, bool ReadOnly, DateTimeOffset ExpiresAt, bool CustomerApproved);
app.MapPost("/internal/impersonation", async (StartImpersonation req, ClaimsPrincipal agent, AppDb db,
ITokenIssuer tokens, AuditWriter audit, CancellationToken ct) =>
{
var tenant = await db.Tenants.SingleAsync(t => t.Id == req.TenantId, ct);
if (tenant.RequiresCustomerApprovalForSupportAccess && !await db.SupportAccessApprovals.AnyAsync(
a => a.TenantId == tenant.Id && a.TicketId == req.TicketId && a.ExpiresAt > DateTimeOffset.UtcNow, ct))
return Results.Problem("Customer approval required for this tenant", statusCode: 403);
var grant = new ImpersonationGrant(Guid.NewGuid(), tenant.Id, req.UserId, agent.GetUserId(), req.TicketId,
ReadOnly: !req.WriteJustification.HasValue(), ExpiresAt: DateTimeOffset.UtcNow.AddMinutes(30),
CustomerApproved: tenant.RequiresCustomerApprovalForSupportAccess);
db.ImpersonationGrants.Add(grant);
await db.SaveChangesAsync(ct);
await audit.WriteAsync(new(tenant.Id, $"support:{agent.GetUserId()}", "support.impersonation.started",
$"user:{req.UserId}", new Dictionary<string, string> { ["ticket"] = req.TicketId, ["readOnly"] = grant.ReadOnly.ToString() },
DateTimeOffset.UtcNow), ct);
// The token carries BOTH identities: act=support agent, sub=user. Every write path checks "read_only".
return Results.Ok(new { token = tokens.IssueImpersonation(grant) });
}).RequireAuthorization("support-impersonation");- كل action وقت الـ impersonation بيتسجل باسم الـ agent «كـ» المستخدم (مش باسم المستخدم لوحده).
- الـ UI بيعرض banner واضح للـ agent، والعميل يقدر يشوف سجل وصول الـ support.
- الـ AI features وقت الـ impersonation: ما تتسجلش كاستخدام العميل في الـ billing، وما تتكتبش memory للمستخدم.
Cell-based architecture
الفكرة: بدل نظام واحد ضخم بيخدم كل العملاء، تقسم البنية لـ «cells» (أو deployment stamps): كل cell نسخة كاملة مستقلة (API، DB، cache، queues، AI gateway) بتخدم مجموعة tenants. Router رفيع بيوجّه كل tenant لـ cell بتاعته.
| مكسب | تمن |
|---|---|
| Blast radius: bad deploy/حادثة بتأثر على cell واحدة | تشغيل N نسخة (تكلفة، monitoring، migrations) |
| Residency طبيعي (cell لكل region) | features بين tenants في cells مختلفة (بحث عالمي، تقارير) أصعب |
| Scaling بإضافة cells بدل تكبير نظام واحد | نقل tenant بين cells = migration حقيقية |
| Canary طبيعي: deploy لـ cell واحدة الأول | محتاج أدوات control plane ناضجة |
إمتى؟ مش من أول يوم. لما حادثة واحدة بتوقع كل العملاء وده بقى مش مقبول، أو residency بقى مطلب، أو نظام واحد وصل لحدود scaling. ولما تقرر، ابدأ بـ «cell واحدة + router» عشان الكود يتعلم إنه مش وحيد.
Outgoing webhooks: الـ delivery pipeline كامل
public static class WebhookSigner
{
// header: X-Signature: t=1731900000,v1=hex(HMACSHA256(secret, $"{t}.{body}"))
public static string Sign(string secret, long unixTs, string body)
{
var mac = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"{unixTs}.{body}"));
return $"t={unixTs},v1={Convert.ToHexStringLower(mac)}";
}
public static bool Verify(string secret, string header, string body, DateTimeOffset now, TimeSpan tolerance)
{
var parts = header.Split(',').Select(p => p.Split('=', 2)).ToDictionary(p => p[0], p => p[1]);
if (!long.TryParse(parts.GetValueOrDefault("t"), out var ts)) return false;
if ((now - DateTimeOffset.FromUnixTimeSeconds(ts)).Duration() > tolerance) return false; // replay window
var expected = Sign(secret, ts, body).Split("v1=")[1];
return parts.TryGetValue("v1", out var got)
&& CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(got)); // constant time
}
}- SSRF: الـ URL بتاع العميل ممكن يشاور على
169.254.169.254أو شبكتك الداخلية. اعمل resolve للـ DNS، ارفض private/link-local ranges، ما تتبعش redirects، وابعت من egress معزول (نفس الحارس اللي في الـ Capstone لـ URL ingestion). - Secret لكل endpoint مع دعم secretين أثناء الـ rotation.
- Payload صغير + id: ابعت
event_idونوع الحدث وأقل بيانات لازمة، والعميل يعمل fetch للتفاصيل — بيقلل تسريب البيانات وحجم الـ retries. - Fairness: endpoint بطيء لعميل واحد ما يعطّلش الباقي: queue/concurrency limit لكل endpoint.
Tenant offboarding orchestrator: Saga للحذف
حذف tenant مش DELETE FROM Tenants. البيانات موجودة في: SQL، blob storage، vector index، cache، search، logs، backups، الـ billing provider، والـ LLM provider (لو فيه files أو fine-tunes). كل خطوة ممكن تفشل لوحدها. ده بالظبط استخدام الـ Saga: خطوات مستقلة، كل واحدة idempotent، مع حالة محفوظة وإعادة محاولة.
public sealed class OffboardingOrchestrator(AppDb db, IEnumerable<IOffboardingStep> steps, ILogger<OffboardingOrchestrator> log)
{
public async Task RunAsync(Guid tenantId, CancellationToken ct)
{
var run = await db.OffboardingRuns.SingleAsync(r => r.TenantId == tenantId, ct);
foreach (var step in steps.OrderBy(s => s.Order))
{
if (run.IsDone(step.Name)) continue; // resume: never redo finished steps
try
{
await step.ExecuteAsync(tenantId, ct); // each step must be idempotent (delete-if-exists)
var remaining = await step.VerifyAsync(tenantId, ct); // e.g. count of vectors with tenant_id
if (remaining > 0) throw new InvalidOperationException($"{step.Name}: {remaining} items left");
run.MarkDone(step.Name);
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
run.MarkFailed(step.Name, ex.Message);
await db.SaveChangesAsync(ct);
log.LogError(ex, "Offboarding step {Step} failed for {Tenant}", step.Name, tenantId);
throw; // the job scheduler retries with backoff
}
await db.SaveChangesAsync(ct);
}
run.Complete(DateTimeOffset.UtcNow); // produce a deletion certificate for the customer
await db.SaveChangesAsync(ct);
}
}Compensation؟ في الحذف مفيش «undo» بعد ما البيانات تتمسح، فالـ grace period (والـ export) هو الـ compensation. التصميم ده مربوط بالـ right to erasure في Governance والتنفيذ في CAPSTONE/backend.
Noisy neighbors: fairness بين الـ tenants
| المورد | العرض | الحماية |
|---|---|---|
| API | tenant بيعمل 5,000 req/s | rate limit partitioned بالـ tenant (token bucket) + limits أعلى للخطط الأعلى |
| Background jobs | import ضخم بيأخر emails الكل | queue لكل priority، و concurrency cap لكل tenant (fair queuing) |
| Database | تقرير تقيل بيعمل table scan | read replica للتقارير، query timeout، index على TenantId أول عمود |
| LLM quota | tenant واحد بيستهلك TPM الحساب كله | token budget لكل tenant + queue + routing لموديل أرخص عند الضغط |
| Storage | رفع TBs | quotas بالخطة + alerts |
القياس أولًا: لازم كل metric وكل trace يبقى عليه tenant_id (بحذر مع الـ cardinality: استخدمه في traces و logs، وفي metrics لأعلى N tenants أو tier بدل كل tenant). من غير ده هتعرف إن «النظام بطيء» ومش هتعرف مين السبب.
Backup و restore لـ tenant واحد
العميل مسح مشروع بالغلط امبارح ومحتاجه. في shared database مش هتعمل restore للـ DB كلها (هترجّع كل العملاء ليوم امبارح). الخطوات: restore لـ point-in-time في database منفصلة مؤقتة ← استخرج صفوف الـ tenant بالـ TenantId (وكل الجداول التابعة بترتيب الـ foreign keys) ← اعمل import لـ staging ← راجع ← دمج. اتدرب عليه قبل ما تحتاجه (restore drill كل ربع سنة)، واكتب runbook. لو ده صعب جدًا في تصميمك، ده سبب حقيقي للـ soft delete مع retention، أو للـ database-per-tenant للعملاء الكبار (Multi-Tenant Architecture).
Knowledge check
الـ offboarding job وقع بعد مسح الـ vectors وقبل مسح الـ SQL. إعادة التشغيل بتعمل إيه في التصميم الصح؟
عميل سجّل webhook URL = http://10.0.0.5/admin. إيه الصح؟
اختبر فهمك
Migration فشلت في 3% من الـ tenant DBs في الموجة التانية. السلوك الصح؟
ليه بنخزن hash للـ API key مش المفتاح؟
Customer webhook endpoint بقاله يومين بيرد 500. الصح؟
تمارين محلولة
1: صمّم rename لعمود مستخدم في كل الـ queries على 300 tenant DB
الحل: Expand: أضف العمود الجديد + trigger/dual-write في الكود. Backfill بموجات. الكود يقرأ من الجديد behind flag. بعد التأكد على كل الـ tenants: الكود يبطل يكتب القديم. Contract في release لاحق: drop القديم. كل مرحلة مستقلة وقابلة للرجوع.
2: عميل بيقول «webhooks بتاعتكم مش موثوقة، بتيجي مرتين». ردك الهندسي؟
الحل: ده at-least-once by design؛ وثّق إن الـ X-Delivery-Id للـ idempotency على جانبهم، ووفر delivery log و replay. ومن جانبك: ما تبعتش مرتين من غير سبب (سجّل النجاح بعد 2xx مباشرة، timeout معقول).
3: support agent محتاج يصلح إعداد عند عميل في نص الليل والعميل بيطلب موافقة مسبقة على أي وصول. إيه الحل؟
الحل: break-glass flow: موافقة من on-call lead + سبب + مدة قصيرة جدًا + audit عالي الأولوية + إشعار فوري للعميل بعدها. والأحسن: أداة admin مخصصة للإعداد ده من غير impersonation كامل.
Mini project: Ops toolkit للـ capstone
في الـ CAPSTONE/: TenantMigrationOrchestrator مع جدول versions و pause/resume (جرّبه على 20 tenant DB في Docker)، TenantCache و purge، outgoing webhooks موقّعة + delivery log في UI، API keys بالـ prefix/hash/scopes، و impersonation read-only بـ audit. معيار القبول: فشل مصطنع في tenant واحد يوقف الموجة ويتشاف في تقرير؛ والـ webhook verifier بتاع العميل (sample) بيرفض body معدّل.
أسئلة إنترفيو: Senior → Staff
(Senior) إزاي تعمل schema migration بدون downtime؟
(Senior) صمّم outgoing webhooks.
(Staff) إمتى تنقل لـ cell-based architecture؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.