‫مهندسی تاب‌آوری در سیستم‌های تراکنشی توزیع‌شده: همزمانی و ایدامپوتنسی در دات‌نت

در سامانه‌های تراکنشی توزیع‌شده، مفهوم «دقیقاً یک‌بار» (Exactly-Once) وجود خارجی ندارد. تأخیر شبکه (Network Timeout)، قطع ناگهانی سوکت یا اجرای مجدد خودکار توسط کلاینت‌ها (Client Retries)، همگی سناریوهای معمول در محیط عملیاتی هستند. همان‌طور که در معماری Stripe و الگوی مرجع Rocket Rides (ارائه‌شده توسط Brandur Leach) تبیین شده، چالش اصلی زمانی رخ می‌دهد که تراکنش در میانه راه قطع شود؛ یعنی سرویس بیرونی (مانند درگاه پرداخت) کارت را شارژ کرده، اما پاسخ به سرور نرسیده یا قبل از ذخیره در دیتابیس داخلی، کانتینر یا پردازش سرور سقوط (Crash) کرده است. در این مقاله، به پیاده‌سازی گام‌به‌گام و علمی این الگو در اکوسیستم .NET 9/10 با اتکا به Entity Framework Core، پایگاه‌داده PostgreSQL و متدهای مدیریت تراکنش، همزمانی و قفل‌گذاری سطرها می‌پردازیم.

• قفل زمانی مشروط (Lease / Distributed Lock): جهت سریال‌سازی درخواست‌های همزمان و جلوگیری از Race Condition.
• نقاط بازیابی (Recovery Points): جهت تعیین اینکه در هر تلاش، فرایند دقیقاً تا کدام مرحله پیش رفته است.
• قیود سطح پایگاه‌داده (Database Invariants): شاخص‌های یکتا (Unique Constraints) که حتی در صورت انقضای پیش‌ازموعد قفل (Expired Lease)، مانع از درج رکوردهای تکراری شوند.

public enum RecoveryPoint
{
    Started = 0,
    RideCreated = 1,
    ChargeCompleted = 2,
    Finished = 3
}

public class IdempotencyKeyRecord
{
    public long Id { get; set; }
    
    // کلیدها همیشه باید مقید به شناسه کاربر/سازمان باشند
    public string UserId { get; set; } = string.Empty;
    public string Key { get; set; } = string.Empty;
    
    // هش بدنه و پارامترهای درخواست برای رد کردن درخواست‌های متناقض
    public string RequestHash { get; set; } = string.Empty;
    
    // زمان قفل برای مدیریت Lease
    public DateTimeOffset? LockedAt { get; set; }
    
    // مرحله بازیابی
    public RecoveryPoint RecoveryPoint { get; set; } = RecoveryPoint.Started;
    
    public int? ResponseStatusCode { get; set; }
    public string? ResponseBody { get; set; }
    
    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
}

public class Ride
{
    public long Id { get; set; }
    public string UserId { get; set; } = string.Empty;
    public long IdempotencyKeyId { get; set; }
    public int AmountCents { get; set; }
    public string? ChargeId { get; set; }
    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;

    public IdempotencyKeyRecord IdempotencyKey { get; set; } = null!;
}

public class AppDbContext : DbContext
{
    public DbSet<IdempotencyKeyRecord> IdempotencyKeys => Set<IdempotencyKeyRecord>();
    public DbSet<Ride> Rides => Set<Ride>();

    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);

        modelBuilder.Entity<IdempotencyKeyRecord>(b =>
        {
            b.ToTable("idempotency_keys");
            b.HasKey(x => x.Id);
            
            b.Property(x => x.Key).HasMaxLength(255).IsRequired();
            b.Property(x => x.UserId).HasMaxLength(128).IsRequired();
            b.Property(x => x.RequestHash).HasMaxLength(64).IsRequired();

            // قید یکتایی مرکب: کلید به ازای هر کاربر یکتاست
            b.HasIndex(x => new { x.UserId, x.Key }).IsUnique();
        });

        modelBuilder.Entity<Ride>(b =>
        {
            b.ToTable("rides");
            b.HasKey(x => x.Id);

            // قید حیاتی ایناریانت دیتابیس: هر کلید حداکثر یک رکورد سفر می‌سازد
            b.HasIndex(x => x.IdempotencyKeyId).IsUnique();

            b.HasOne(x => x.IdempotencyKey)
             .WithMany()
             .HasForeignKey(x => x.IdempotencyKeyId)
             .OnDelete(DeleteBehavior.Restrict);
        });
    }
}

• اولین بار است که کلید دریافت می‌شود: رکورد ثبت شده و قفل دریافت می‌شود.
• کلید قبلاً پردازش شده و تمام شده: پاسخِ ذخیره‌شده بازپخش می‌شود (Replayed: true).
• درخواستی دیگر با همین کلید هم‌اکنون در جریان است: خطای 409 Conflict بازگردانده می‌شود (مگر اینکه زمان اجاره قفل یا Lease منقضی شده باشد که در آن صورت درخواست جدید کار را به دست می‌گیرد).

public static class RequestHasher
{
    public static string ComputeSha256(string method, string path, object body)
    {
        // نرمال‌سازی بدنه به فرم استاندارد
        var json = JsonSerializer.Serialize(body, new JsonSerializerOptions 
        { 
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            WriteIndented = false 
        });

        var raw = $"{method.ToUpperInvariant()}:{path.ToLowerInvariant()}:{json}";
        var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(raw));
        return Convert.ToHexString(bytes);
    }
}

public record ClaimResult(
    bool Success, 
    int StatusCode, 
    string? ResponseBody = null, 
    IdempotencyKeyRecord? Record = null);

public async Task<ClaimResult> ClaimKeyAsync(
    string userId, 
    string key, 
    string requestHash, 
    TimeSpan leaseTimeout, 
    CancellationToken ct)
{
    // ۱. درج کلید در صورت عدم وجود (Insert ... ON CONFLICT DO NOTHING)
    await _dbContext.Database.ExecuteSqlInterpolatedAsync($@"
        INSERT INTO idempotency_keys (user_id, key, request_hash, recovery_point, created_at)
        VALUES ({userId}, {key}, {requestHash}, {RecoveryPoint.Started}, clock_timestamp())
        ON CONFLICT (user_id, key) DO NOTHING;", ct);

    // ۲. خواندن و قفل سطر با استفاده از SELECT FOR UPDATE
    var record = await _dbContext.IdempotencyKeys
        .FromSqlInterpolated($@"
            SELECT * FROM idempotency_keys 
            WHERE user_id = {userId} AND key = {key} 
            FOR UPDATE")
        .AsTracking()
        .SingleOrDefaultAsync(ct);

    if (record == null)
    {
        return new ClaimResult(false, StatusCodes.Status500InternalServerError, "خطا در بازیابی رکورد کلید.");
    }

    // ۳. بررسی تغییر پارامترها با همان کلید قبلی
    if (!string.Equals(record.RequestHash, requestHash, StringComparison.OrdinalIgnoreCase))
    {
        return new ClaimResult(false, StatusCodes.Status409Conflict, 
            "از این Idempotency-Key قبلاً با پارامترهای متفاوتی استفاده شده است.");
    }

    // ۴. اگر فرایند قبلاً به پایان رسیده، بازپخش پاسخ ذخیره‌شده
    if (record.ResponseStatusCode.HasValue)
    {
        return new ClaimResult(true, record.ResponseStatusCode.Value, record.ResponseBody, record);
    }

    // ۵. بررسی Lease: اگر پردازش در جریان است و منقضی نشده، کلاینت باید بعداً Retry کند
    var now = DateTimeOffset.UtcNow;
    if (record.LockedAt.HasValue && (now - record.LockedAt.Value) < leaseTimeout)
    {
        return new ClaimResult(false, StatusCodes.Status409Conflict, 
            "درخواست دیگری با این کلید هم‌اکنون در حال اجراست.");
    }

    // ۶. تصاحب قفل (Acquire Lease)
    record.LockedAt = now;
    await _dbContext.SaveChangesAsync(ct);

    return new ClaimResult(true, StatusCodes.Status200OK, null, record);
}

[درخواست کلاینت]
      │
      ▼
[فاز ۱: تصاحب کلید و ارزیابی هش]
      │
      ▼
[فاز ۲: ثبت موجودیت محلی (Ride) درون تراکنش EF Core] ──► ذخیره RecoveryPoint = RideCreated
      │
      ▼
[فراخوانی درگاه پرداخت (Stripe) با کلید مشتق‌شده] ◄── مرز ایزولاسیون بیرونی
      │
      ▼
[فاز ۳: ثبت شناسه پرداخت و تکمیل] ──► ذخیره RecoveryPoint = Finished و آزادسازی LockedAt

public async Task<IResult> ProcessRidePaymentAsync(
    string userId, 
    string idempotencyKey, 
    RideRequest request, 
    CancellationToken ct)
{
    var hash = RequestHasher.ComputeSha256("POST", "/api/rides", request);
    var leaseTtl = TimeSpan.FromSeconds(15);

    // ۱. تصاحب قفل
    var claim = await ClaimKeyAsync(userId, idempotencyKey, hash, leaseTtl, ct);
    if (!claim.Success)
    {
        return Results.Json(new { error = claim.ResponseBody }, statusCode: claim.StatusCode);
    }

    // اگر نتیجه قبلاً ذخیره شده، بازپخش نتیجه همراه با Header اختصاصی
    if (claim.ResponseBody != null)
    {
        return Results.Content(
            claim.ResponseBody, 
            contentType: "application/json", 
            statusCode: claim.StatusCode);
    }

    var record = claim.Record!;

    // ۲. فاز دو: ثبت موجودیت در دیتابیس داخلی
    if (record.RecoveryPoint == RecoveryPoint.Started)
    {
        await using var tx = await _dbContext.Database.BeginTransactionAsync(ct);
        try
        {
            var ride = new Ride
            {
                UserId = userId,
                IdempotencyKeyId = record.Id,
                AmountCents = request.AmountCents
            };

            _dbContext.Rides.Add(ride);
            record.RecoveryPoint = RecoveryPoint.RideCreated;

            await _dbContext.SaveChangesAsync(ct);
            await tx.CommitAsync(ct);
        }
        catch (DbUpdateException)
        {
            await tx.RollbackAsync(ct);
            // در صورتی که قفل در اثر تأخیر منقضی شده و درخواست دیگری زودتر ثبت کرده باشد،
            // قید Unique Index فعال شده و از ثبت داده اشتباه جلوگیری می‌کند.
            throw;
        }
    }

    // ۳. فراخوانی سامانه خارجی (Third-party) با استفاده از Downstream Idempotency Key
    // کلید ارسالی به درگاه باید مشتق‌شده از کلید اصلی باشد
    string downstreamKey = $"{userId}:{idempotencyKey}:charge";
    string? chargeId = null;

    if (record.RecoveryPoint == RecoveryPoint.RideCreated)
    {
        // فراخوانی درگاه بانکی
        chargeId = await _paymentGateway.CreateChargeAsync(
            request.AmountCents, 
            downstreamKey, 
            ct);

        // شبیه‌سازی سقوط سرور: اگر در این نقطه سرور کرش کند،
        // در تلاش مجدد، برنامه از همین فاز کار را ادامه می‌دهد
        // و همان chargeId را از درگاه مجدداً دریافت می‌کند.
    }

    // ۴. فاز سه: تکمیل و ذخیره پاسخ نهایی
    await using (var tx = await _dbContext.Database.BeginTransactionAsync(ct))
    {
        var ride = await _dbContext.Rides
            .SingleAsync(r => r.IdempotencyKeyId == record.Id, ct);

        ride.ChargeId = chargeId;

        var responsePayload = JsonSerializer.Serialize(new
        {
            rideId = ride.Id,
            amount = ride.AmountCents,
            chargeId = ride.ChargeId
        });

        record.RecoveryPoint = RecoveryPoint.Finished;
        record.ResponseStatusCode = StatusCodes.Status201Created;
        record.ResponseBody = responsePayload;
        record.LockedAt = null; // آزادسازی قفل

        await _dbContext.SaveChangesAsync(ct);
        await tx.CommitAsync(ct);

        return Results.Created($"/api/rides/{ride.Id}", JsonSerializer.Deserialize<object>(responsePayload));
    }
}

• پردازش اول هنوز زنده است و در حال ذخیره‌سازی در دیتابیس است.
• کلید از دید پایگاه داده منقضی تلقی می‌شود.
• پردازش دوم قفل منقضی‌شده را تصاحب کرده و مجدداً فاز ساخت موجودیت را آغاز می‌کند.

• مدت‌زمان محافظه‌کارانه Lease: مدت‌زمان قفل باید فراتر از بیشینه زمان بدترین سناریوی پردازش (مثلاً ۱۰ الی ۳۰ ثانیه) باشد.
• پشتیبانی از ایناریانت دیتابیس: قید CREATE UNIQUE INDEX rides_one_per_key ON rides (idempotency_key_id) که در OnModelCreating نوشتیم ضامن نهایی است. حتی اگر Lease اشتباه کار کند، پایگاه‌داده جلوی ردیف دوم را با DbUpdateException می‌گیرد؛ یعنی شکست آشکار (500) رخ می‌دهد اما پول یا خدمات چندباره داده نمی‌شود.
• توکن‌های حصارکشی (Fencing Tokens): برای سناریوهای فوق‌العاده حساس، استفاده از یک مقدار افزایشی (مانند xmin در Postgres یا فیلد ورژن در SQL Server) باعث می‌شود رکوردی که Lease آن منقضی شده، در زمان Commit متوجه سلب مالکیت خود بشود.

public class IdempotencyReaperWorker : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly ILogger<IdempotencyReaperWorker> _logger;

    public IdempotencyReaperWorker(
        IServiceProvider serviceProvider, 
        ILogger<IdempotencyReaperWorker> logger)
    {
        _serviceProvider = serviceProvider;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                using var scope = _serviceProvider.CreateScope();
                var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();

                var retentionThreshold = DateTimeOffset.UtcNow.AddHours(-48);

                // استفاده از ExecuteDeleteAsync در EF Core 7/8/9 بدون بارگذاری در حافظه
                int deletedCount = await dbContext.IdempotencyKeys
                    .Where(k => k.CreatedAt < retentionThreshold && k.ResponseStatusCode != null)
                    .ExecuteDeleteAsync(stoppingToken);

                if (deletedCount > 0)
                {
                    _logger.LogInformation("تعداد {Count} کلید ایدامپوتنسی قدیمی پاک‌سازی شدند.", deletedCount);
                }
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "خطا حین اجرای پاک‌سازی دوره‌ای کلیدهای ایدامپوتنسی.");
            }

            // اجرای هر ۴ ساعت یک‌بار
            await Task.Delay(TimeSpan.FromHours(4), stoppingToken);
        }
    }
}

• [ ] اسکوپ سه‌گانه کلید: کلید را با ترکیبی از (UserId, Path, Key) یکتا کنید.
• [ ] هش اعتبارسنجی بدنه: بدنه درخواست را در کنار کلید هش کنید تا کلاینت نتواند با همان کلید، مقادیر مالی دیگری را ارسال کند.
• [ ] ارسال کلیدهای مشتق‌شده: به ازای هر تماس خروجی با وب‌سرویس‌های خارجی، یک کلید مشتق‌شده (مثلاً key:charge) بفرستید.
• [ ] قید یکتایی در جداول بیزینسی: هرگز صرفاً به کد سی‌شارپ اعتماد نکنید؛ جدول نهایی سفارش یا تراکنش باید به شناسه کلید مقید باشد (Unique Constraint).
• [ ] انجام فازهای اتمیک: از BeginTransactionAsync تفکیک‌شده به ازای هر گام استفاده کنید و وضعیت RecoveryPoint را پیش از خروج از تراکنش ثبت کنید.
• [ ] تنظیم هدرهای شفاف: در پاسخ‌های Replay شده، هدر Idempotent-Replayed: true را در خط لوله Middleware برگردانید تا تیم فرانت‌اند یا سیستم‌های مصرف‌کننده متوجه کشف مجدد پاسخ شوند.