Software Engineer Encyclopedia
0%
Domain 14 · SaaS & Product Engineering · Pillar

تشغيل SaaS على نطاق كبير: migrations لمئات الـ tenants، webhooks، API keys، impersonation، وcells

SaaS Operations at Scale

المشاكل اللي بتظهر لما المنتج يبقى فيه مئات أو آلاف الـ tenants: migrations على موجات، cache/queue/storage/observability واعية بالـ tenant، outgoing webhooks موقّعة، API keys آمنة، audit وadmin impersonation، وcell-based architecture — بمعمل متنفّذ.

  • Professional Engineering
  • ~12 min read
  • 16 sections
  • 6 code examples
  • 4 diagrams
  • 8 questions
  • Priority L2 · Essential
  • .NET 9 · PostgreSQL · Redis · Azure Blob Storage · OpenTelemetry · المعمل Python stdlib (executed)

بعد الدرس ده هتقدر

  • تنفذ schema migration على مئات الـ tenants/DBs بموجات قابلة للإيقاف والاستكمال وبـ expand/contract
  • تخلي الـ cache والـ queues والـ storage والـ observability واعية بالـ tenant
  • تبني outgoing webhooks موقّعة بـ retries وdelivery log وحماية من replay
  • تصمم API keys: prefix، hash، scopes، rotation، وrevocation
  • تبني admin impersonation آمن (موافقة، مدة، read-only افتراضيًا، audit)
  • تشرح cell-based architecture وإمتى تستاهل

المتطلبات قبل ما تبدأ

01

اللي بيتكسر لما الـ tenants يبقوا 500

Problems that only appear at scale
Basics

مع 5 عملاء، migration بتتعمل بإيدك، والـ support بيدخل الـ DB يشوف المشكلة، والـ cache key مش مهم. مع 500 (أو 50 DB منفصلة لعملاء enterprise)، كل عملية يدوية بتبقى حادثة مستنية تحصل. الدرس ده عن تحويل العمليات دي لأنظمة: قابلة للتكرار، للإيقاف، للمراجعة، ومحدودة الأثر.

02

Migrations عبر مئات الـ tenants

Waves, expand/contract and per-tenant schema versions
Deep dive

المشكلة: silos (DB لكل tenant enterprise) أو schemas لكل tenant يعني الـ migration بتتنفذ N مرة. لو اتعملت كـ loop في الـ deploy: بتطوّل الـ deploy، وفشل في النص بيسيب tenants على نسخ مختلفة، والكود الجديد بيقابل schema قديمة.

1 · Expandadditive, backward-compatibleWave 0internal + canaryWave 1..n10% → 50% → 100%Code uses newfeature flagContractdrop old, later releasetenant_schema_versions tablepause · resume · report · retry failed
Migrations as an orchestrated rollout: canary tenants first, waves after, compatible code throughout
C#TenantMigrationOrchestrator.cs
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.
Failure case

Migration بتضيف NOT NULL column بـ default على جدول 400M صف في نسخة PostgreSQL قديمة ← rewrite للجدول وقفل لساعة. (النسخ الحديثة بتتعامل مع الـ default الثابت من غير rewrite، لكن default متغير زي now() لأ.) الدرس: كل migration بتتراجع لـ «هل بتعمل lock/rewrite؟» وبتتجرب على نسخة بحجم الإنتاج.

03

Cache و queue و storage و observability واعية بالـ tenant

Tenant context in every infrastructure layer
Deep dive
الطبقةالقاعدةليه
Redis keyst:{tenantId}:{area}:{id}، prefix إجباري من helperعزل، مسح per tenant، تحليل الاستهلاك
Queuestenant في الـ message envelope + fair scheduling + per-tenant concurrencynoisy neighbor، إعادة بناء الـ context في الـ worker
Blob storagecontainer أو prefix لكل tenant، SAS قصيرة المدة scoped للـ prefixعزل الوصول، lifecycle وحذف
Logs/tracestenant.id attribute على كل span/log«العميل X بيشتكي» ← فلتر واحد
Metricstier/plan كـ label، مش tenant id (cardinality)تكلفة وأداء الـ metrics backend
Dashboardsper-tenant views من الـ traces/logs للـ supportتشخيص سريع من غير دخول الـ DB
C#TenantCache.cs
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);
    }
}
04

Outgoing webhooks: موقّعة وبتتعاد ومتسجلة

Sending webhooks customers can trust
Practical

لما المنتج بتاعك يبعت events للعملاء (مستند اتفهرس، agent خلص، فاتورة)، إنت بقيت الـ provider. نفس القواعد اللي بتطلبها من Stripe: توقيع (عشان العميل يتأكد إنه منك)، timestamp (ضد replay)، delivery id (عشان العميل يعمل idempotency)، retries بـ backoff، delivery log يشوفه العميل، وتعطيل الـ endpoint اللي بيفشل باستمرار مع إشعار. ومواصفة زي Standard Webhooks بتوحّد الشكل ده.

Pythonops_lab.pyExecuted ✓
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.)
ConsoleOutput — captured from a real run
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        : None
C#WebhookSender.cs
public 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.
05

API keys: تصميم آمن

Prefix, hash, scopes, rotation
Deep dive
  • 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: مفتاحين صالحين في نفس الوقت لفترة انتقالية.
06

Audit logs و admin impersonation

Letting support see what the customer sees, safely
Deep dive

الاحتياج: الـ support محتاج يشوف المشكلة زي ما العميل شايفها. الخطر: «login as user» = أقوى صلاحية في النظام. التصميم الآمن:

C#Impersonation.cs
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 للمستخدم.
07

Cell-based architecture

Limiting blast radius by splitting the fleet
Deep dive

الفكرة: بدل نظام واحد ضخم بيخدم كل العملاء، تقسم البنية لـ «cells» (أو deployment stamps): كل cell نسخة كاملة مستقلة (API، DB، cache، queues، AI gateway) بتخدم مجموعة tenants. Router رفيع بيوجّه كل tenant لـ cell بتاعته.

Global routerCell EU-1API · DB · cache · AI gwtenants 1..800Cell EU-2API · DB · cache · AI gwtenants 801..1600Cell ME-1residency: Middle Eastenterprise + regional
Cells: a thin global router, independent full stacks, و tenants pinned to one 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» عشان الكود يتعلم إنه مش وحيد.

08

Outgoing webhooks: الـ delivery pipeline كامل

Delivering webhooks to customers
Deep dive
Domain change+ Outbox row (1 tx)Dispatcherfan-out per endpointDelivery attemptHMAC + timestampCustomer endpoint2xx within 10s = deliveredRetry schedule1m 5m 30m 2h 8h 24hDead letter + disable endpointemail admin, replay from UInon-2xx / timeoutEvery attempt is logged (status, latency, response snippet) and visible to the tenant
Outgoing webhooks: outbox in the same transaction, signed delivery, exponential retries, dead-letter and replay
C#WebhookSigner.cs: what customers verify
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.
09

Tenant offboarding orchestrator: Saga للحذف

Deleting a tenant across every system
Deep dive

حذف tenant مش DELETE FROM Tenants. البيانات موجودة في: SQL، blob storage، vector index، cache، search، logs، backups، الـ billing provider، والـ LLM provider (لو فيه files أو fine-tunes). كل خطوة ممكن تفشل لوحدها. ده بالظبط استخدام الـ Saga: خطوات مستقلة، كل واحدة idempotent، مع حالة محفوظة وإعادة محاولة.

Request + grace (30d)Freeze + exportCancel billingPurge vectors + blobs + searchPurge SQL rows (batched)Purge caches + provider filesVerify (counts = 0) + certificateState table: OffboardingRun(TenantId, Step, Status, Attempts, LastError) — resumable from the failed stepBackups: expire naturally per retention policy (documented), keys can be crypto-shredded
Offboarding saga: each step idempotent and recorded; failures retry without redoing finished steps
C#OffboardingOrchestrator.cs (shape)
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.

10

Noisy neighbors: fairness بين الـ tenants

Keeping one tenant from hurting all
Deep dive
الموردالعرضالحماية
APItenant بيعمل 5,000 req/srate limit partitioned بالـ tenant (token bucket) + limits أعلى للخطط الأعلى
Background jobsimport ضخم بيأخر emails الكلqueue لكل priority، و concurrency cap لكل tenant (fair queuing)
Databaseتقرير تقيل بيعمل table scanread replica للتقارير، query timeout، index على TenantId أول عمود
LLM quotatenant واحد بيستهلك TPM الحساب كلهtoken budget لكل tenant + queue + routing لموديل أرخص عند الضغط
Storageرفع TBsquotas بالخطة + alerts

القياس أولًا: لازم كل metric وكل trace يبقى عليه tenant_id (بحذر مع الـ cardinality: استخدمه في traces و logs، وفي metrics لأعلى N tenants أو tier بدل كل tenant). من غير ده هتعرف إن «النظام بطيء» ومش هتعرف مين السبب.

11

Backup و restore لـ tenant واحد

Point-in-time restore for one customer
Practical

العميل مسح مشروع بالغلط امبارح ومحتاجه. في 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).

12

Knowledge check

Check your understanding
Basics

الـ offboarding job وقع بعد مسح الـ vectors وقبل مسح الـ SQL. إعادة التشغيل بتعمل إيه في التصميم الصح؟

عميل سجّل webhook URL = http://10.0.0.5/admin. إيه الصح؟

13

اختبر فهمك

Knowledge check
Basics

Migration فشلت في 3% من الـ tenant DBs في الموجة التانية. السلوك الصح؟

ليه بنخزن hash للـ API key مش المفتاح؟

Customer webhook endpoint بقاله يومين بيرد 500. الصح؟

14

تمارين محلولة

Solved exercises
Practical
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 كامل.

15

Mini project: Ops toolkit للـ capstone

Mini project
Practical

في الـ 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 معدّل.

16

أسئلة إنترفيو: Senior → Staff

Interview ladder
Basics
(Senior) إزاي تعمل schema migration بدون downtime؟
Expand/contract، عمليات non-blocking، backfill بـ batches، الكود متوافق مع النسختين، flags للتحويل، ومراقبة الـ locks والـ lag.
(Senior) صمّم outgoing webhooks.
Event ← outbox ← delivery worker بـ HMAC signature و timestamp و delivery id، timeouts قصيرة، backoff بسقف، DLQ، تعطيل endpoints الفاشلة، delivery log و replay للعميل، SSRF protection.
(Staff) إمتى تنقل لـ cell-based architecture؟
لما blast radius الحوادث بقى غير مقبول، أو residency، أو حدود scaling لنظام واحد، والفريق عنده نضج في الأتمتة. أبدأ بـ router + cell واحدة، أتمتة الـ provisioning والـ migrations والـ observability عبر cells، وبعدين cell تانية لعملاء جدد قبل نقل القدام.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس