التحكّم الآمن في تزامن تكامل الملفّات - أفضل الممارسات لـ file lock والمطالبة الذرّيّة والمعالجة idempotent

يصبح التحكّم في التزامن مشكلةً حقيقيّة على الفور تقريباً في تدفّقات العمل القائمة على المجلّدات المشتركة، ودفعات اللّيل، وتكامل الملفّات بين العمليّات. الأسئلة المعتادة هي ما إذا كان file lock وحده كافياً، وكيف نمنع عدّة workers من التقاط الملفّ نفسه، وكيف نتجنّب قراءة ملفّ ما زال يُكتَب فيه.

يُنظِّم هذا المقال التحكّم في تزامن تكامل الملفّات حول file lock والمطالبة الذرّيّة و temp -> rename و idempotency.

المحتويات

1. النسخة المختصرة
2. أنماط التعارض التي تحدث في تكامل الملفّات
   • 2.1. قراءة ملفّ ما زال يُكتَب فيه
   • 2.2. التقاط workerين الملفّ نفسه في الوقت نفسه
   • 2.3. توقّف الجميع بسبب stale lock
3. الأنماط المضادّة
   • 3.1. الفحص ذو الخطوتين Exists -> Create
   • 3.2. الكتابة مباشرةً إلى اسم الملفّ النهائي
   • 3.3. اعتبار «توقّف حجم الملفّ عن التغيّر» اكتمالاً
   • 3.4. ترك الجميع يُحدِّثون ملفّاً مشتركاً
   • 3.5. الظنّ بأنّ lock API عالميّ
4. أفضل الممارسات
   • 4.1. النشر بأسلوب temp -> close -> rename / replace
   • 4.2. استخدام ملفّات done / manifest للإعلان عن الاكتمال
   • 4.3. اجعل المستلم يأخذ المطالبة ذرّيّاً
   • 4.4. إذا اعتمدت على lock files فاجعلها lease-based
   • 4.5. افترض idempotency
5. مقتطفات شيفرة افتراضيّة
6. دليل تقريبي للقاعدة العامّة
7. الخلاصة
8. المراجع

تكامل الملفّات مجال تكون فيه الشيفرة نفسها في الغالب أقلّ هشاشةً من اتّفاقيّة التسليم. تنجح الأمور في اختبارات الوحدة لكنّها تفشل أحياناً فقط في المجلّدات المشتركة الإنتاجيّة أو في تشغيلات الدفعات اللّيليّة. هذا أمر عادي جدّاً.

في كثير من الحالات، المشكلة الحقيقيّة ليست في واجهة برمجة file I/O نفسها، بل في أنّ هذه الأشياء الثلاثة غامضة:

• متى يكون من الآمن قراءة الملفّ
• مَن يملك الحقّ في معالجته
• كيف يعمل الاسترداد عند الفشل

لذلك يتعامل هذا المقال مع التحكّم في تزامن تكامل الملفّات لا باعتباره «مجرّد locking»، بل باعتباره بروتوكول تسليم.

1. النسخة المختصرة

• القاعدة الأهمّ هي التأكّد من أنّه حين يصبح اسم الملفّ النهائي مرئيّاً، يكون الملفّ آمناً للقراءة بالفعل
• عبِّر عن الحالات مثل قيد الكتابة و منشور و قيد المعالجة و تمّت معالجته عبر الأسماء أو الأدلّة
• إذا وُجد عدّة workers، خذ مطالبة ذرّيّة قبل المعالجة
• استخدم lock files و OS locks بوصفها أدوات مساعدة، لكن اعتبر idempotency شبكة الأمان النهائيّة

بعبارة أخرى، جوهر تكامل الملفّات ليس مجرّد «locking». إنّه في الحقيقة بروتوكول التسليم.

2. أنماط التعارض التي تحدث في تكامل الملفّات

2.1. قراءة ملفّ ما زال يُكتَب فيه

إذا كتب المرسل مباشرةً إلى اسم الملفّ النهائي، يظهر هذا الفشل على الفور. مع JSON قد يكون قوس الإغلاق مفقوداً. ومع CSV قد يكون عدد السطور غير مكتمل. ومع ZIP قد يكون الملفّ ببساطة مكسوراً.

sequenceDiagram
    participant Sender as Sender
    participant Share as Shared folder
    participant Receiver as Receiver

    Sender->>Share: Create orders.csv with its final name
    Sender->>Share: Still writing rows 1..5000
    Receiver->>Share: Detect orders.csv
    Receiver->>Share: Start reading it immediately
    Note over Receiver: The file is still incomplete
    Sender->>Share: Continue writing the rest
    Note over Receiver: Row shortage / parse failure / partial processing

2.2. التقاط workerين الملفّ نفسه في الوقت نفسه

إذا كان التدفّق هو «اسرد الملفّات، تحقّق ممّا إذا كان أحدها لم تتمّ معالجته، ثمّ افتحه»، فيمكن لـ workerين بسهولة أن يلتقطا المُدخل نفسه. هكذا يبدأ العدّ المزدوج والإرسال المكرّر.

sequenceDiagram
    participant W1 as Worker 1
    participant W2 as Worker 2
    participant Dir as incoming

    W1->>Dir: Find a.csv
    W2->>Dir: Find a.csv
    W1->>Dir: Start reading
    W2->>Dir: Start reading
    Note over W1,W2: The same input is processed twice

2.3. توقّف الجميع بسبب stale lock

التصميم الذي يقتصر على «إسقاط lock file» يَعلَق بسهولة شديدة بعد الإنهاء غير الطبيعي. إذا لم تستطع تحديد مَن يملك الـ lock، أو ما إذا كان لا يزال حيّاً، أو إلى متى يبقى صالحاً، فقد ينتظر الـ worker التالي إلى الأبد.

sequenceDiagram
    participant A as Worker A
    participant Lock as lock file
    participant B as Worker B

    A->>Lock: Create the lock
    Note over A: Abnormal termination happens here
    B->>Lock: See that the lock exists
    B->>Lock: Skip starting work
    B->>Lock: Wait even longer
    Note over B,Lock: Everyone stops because staleness cannot be judged

3. الأنماط المضادّة

3.1. الفحص ذو الخطوتين Exists -> Create

المشكلة هنا أنّ الفحص و المطالبة عمليّتان مختلفتان. يمكن لعمليّة أخرى أن تتسلّل بينهما، فلا يكون هذا إقصاءً حقيقيّاً.

sequenceDiagram
    participant A as Process A
    participant B as Process B
    participant FS as File system

    A->>FS: Check whether the lock exists
    B->>FS: Check whether the lock exists
    FS-->>A: It does not exist
    FS-->>B: It does not exist
    A->>FS: Create the lock
    B->>FS: Create the lock
    Note over A,B: Both sides move forward

if (!File.Exists(lockPath))
{
    File.WriteAllText(lockPath, Environment.ProcessId.ToString());
    ProcessFile();
}

ما تحتاجه فعلاً هو عمليّة ذرّيّة واحدة لـ «أنشئ فقط إن لم يكن موجوداً». في .NET يعني ذلك عادةً نهجاً بأسلوب FileMode.CreateNew. وفي POSIX، فإنّ O_CREAT | O_EXCL يحمل الفكرة نفسها.

3.2. الكتابة مباشرةً إلى اسم الملفّ النهائي

إذا فسّر المستلم «هذا الاسم مرئيّ» بأنّه «هذا الملفّ جاهز للقراءة»، فإنّ الكتابة مباشرةً إلى الاسم النهائي تكون خطأً بالفعل. لا تجعل مرئيّاً و آمناً للقراءة يحملان المعنى نفسه.

flowchart LR
    A["Final name becomes visible"] --> B["Receiver detects it"]
    B --> C["Sender is still writing"]
    C --> D["Receiver reads incomplete data"]

3.3. اعتبار «توقّف حجم الملفّ عن التغيّر» اكتمالاً

يبدو هذا مريحاً، لكنّه هشّ. النسخ عبر الشبكة، وتوقّفات المرسل، والـ buffering، والـ retries، تجعله كلّها غير موثوق.

if (currentLength == lastLength && stableSeconds >= 10)
{
    return Ready;
}

الاكتمال المُقرَّر بـ التخمين سيُؤذيك في المجلّدات المشتركة والملفّات الكبيرة. الإعلان الصريح عن الاكتمال عبر manifest أو done file أكثر استقراراً بكثير.

3.4. ترك الجميع يُحدِّثون ملفّاً مشتركاً

ملفّ status.csv أو counter.json مشترك يقرأه الجميع ويكتبون فيه ينتهي عادةً بـ «آخر كاتب يفوز». حين يبدأ تكامل الملفّات بالتصرّف كقاعدة بيانات صغيرة، يصبح هذا مؤلماً بسرعة.

3.5. الظنّ بأنّ lock API عالميّ

تهمّ lock APIs، لكنّها لا تعمل جيّداً إلّا حين يلتزم جميع المشاركين بالاتّفاقيّة نفسها. في تكامل الأنظمة غير المتجانسة، من الأكثر أماناً عدم المبالغة في تقدير شأنها.

أمثلة:

• flock على Linux هو advisory lock، لذا يمكن للبرامج التي تتجاهل القاعدة أن تكتب رغم ذلك
• byte-range locks على Windows يتجاهلها الوصول إلى memory-mapped file
• بعبارة أخرى، لا تطلب من OS locks وحدها أن تحمل الإشارة بالاكتمال وتصميم الملكيّة

4. أفضل الممارسات

4.1. النشر بأسلوب temp -> close -> rename / replace

هذا هو المسار القياسي. أبقِ الملفّ مخفيّاً تحت اسم temp أثناء بنائه، أغلِقه، ثمّ ولا شيء قبل ذلك بدِّل الاسم إلى الاسم النهائي. المستلم يراقب الاسم النهائي فقط.

flowchart LR
    A["Create a unique temp name"] --> B["Write the full payload to temp"]
    B --> C["Flush / close it"]
    C --> D["Rename / replace to the final name inside the same directory"]
    D --> E["Receiver watches only the final name"]

نقاط مهمّة:

• ينبغي أن يكون temp والاسم النهائي في الدليل نفسه، أو على الأقلّ على الـ volume / file system نفسه
• على Windows / .NET، فإنّ File.Replace يستحقّ النظر فيه في الغالب
• اجعل «اسم الملفّ النهائي مرئيّ» يعني «المحتويات مكتملة بالفعل»

4.2. استخدام ملفّات done / manifest للإعلان عن الاكتمال

غالباً ما يكون الإعلان ليس عن الـ payload نفسه فحسب، بل أيضاً عن ما هو المكتمل بالضبط في ملفّ منفصل أكثر استقراراً بكثير. هذا مفيد بشكل خاصّ في تكامل الأنظمة غير المتجانسة.

تشمل حقول الـ manifest المفيدة في الغالب:

• اسم الملفّ المستهدف
• الحجم
• الـ hash
• عدد السجلّات
• معرّف التكامل / idempotency key
• طابع وقت الإنشاء

الترتيب يهمّ أيضاً. إذا نشرت ملفّ done قبل أن يكون الـ payload مكتملاً فعلاً، فهذه ليست إشارة اكتمال. هذه إعلان عن حادث.

4.3. اجعل المستلم يأخذ المطالبة ذرّيّاً

إذا كان عدّة workers يراقبون الدليل incoming نفسه، فإنّ النمط البسيط هو: rename الملفّ إلى منطقة المعالجة الخاصّة بك قبل القراءة. الـ worker الذي ينجح rename الخاصّ به وحده يملك الحقّ في معالجة الملفّ.

sequenceDiagram
    participant W1 as Worker 1
    participant W2 as Worker 2
    participant IN as incoming
    participant PR as processing

    W1->>IN: Find a.csv
    W2->>IN: Find a.csv
    W1->>PR: Rename a.csv
    W2->>PR: Rename a.csv
    Note over W1,W2: Only the first successful worker owns it

من الناحية التشغيليّة، يساعد أيضاً تقسيم الأدلّة بوضوح:

flowchart LR
    T[temp] -->|publish| I[incoming]
    I -->|claim| P[processing]
    P -->|success| A[archive]
    P -->|failure| E[error]

4.4. إذا اعتمدت على lock files فاجعلها lease-based

إذا استخدمت lock files، فلا تجعلها علامات فارغة. اجعلها تحوي معلومات الملكيّة وانتهاء الصلاحيّة.

flowchart TD
    L[lock.json] --> A[ownerId]
    L --> B[host]
    L --> C[pid]
    L --> D[acquiredAt]
    L --> E[expiresAt]
    L --> F[heartbeatAt]

نقاط مهمّة:

• أنشئها ذرّيّاً
• استخدم تحديثات الـ heartbeat المفقودة بوصفها أحد إشارات الـ staleness
• من حيث المبدأ، يجب على المنشئ وحده إزالة الـ lock
• افترض أنّ تسرّب الـ lock يمكن أن يحدث، وحدِّد مسار الاسترداد مسبقاً

4.5. افترض idempotency

الإقصاء يهمّ، لكن في التشغيل الفعلي نادراً ما تقضي تماماً على التسليم المزدوج أو الـ retries. في النهاية، يساعد كثيراً أن يُصمَّم النظام بحيث معالجة المُدخل نفسه مرّةً أخرى لا تكسر شيئاً.

flowchart LR
    A["Input + idempotency key"] --> B{"Already processed?"}
    B -- yes --> C["Treat as success without re-executing"]
    B -- no --> D["Execute processing"]
    D --> E["Record in processed ledger"]

5. مقتطفات شيفرة افتراضيّة

5.1. نمط مكسور نموذجي

var lockPath = finalPath + ".lock";

if (!File.Exists(lockPath))
{
    File.WriteAllText(lockPath, "");
    using var writer = OpenForWrite(finalPath); // writes directly to final name
    WritePayload(writer);

    File.Delete(lockPath);
}

المشكلات:

• Exists و WriteAllText عمليّتان منفصلتان
• finalPath يصبح مرئيّاً بينما الكتابة لا تزال جارية
• يبقى الـ lock بعد الإنهاء غير الطبيعي

5.2. اتّجاه أسلم

var tempPath = MakeTempPathSameDirectory(finalPath);
WritePayload(tempPath);
FlushAndClose(tempPath);

PublishByRenameOrReplace(tempPath, finalPath); // same FS / same volume
PublishDoneFile(finalPath + ".done", new
{
    FileName = Path.GetFileName(finalPath),
    Size = GetFileSize(finalPath),
    Hash = ComputeHash(finalPath),
    IdempotencyKey = integrationId
});

if (!TryClaimBundleByRename(baseName, incomingDir, processingDir))
{
    return; // another worker already took it
}

var manifest = ReadDoneFile(Path.Combine(processingDir, baseName + ".done"));
VerifyPayload(Path.Combine(processingDir, baseName), manifest);

if (AlreadyProcessed(manifest.IdempotencyKey))
{
    MoveBundle(processingDir, archiveDir, baseName);
    return;
}

Process(Path.Combine(processingDir, baseName));
RecordProcessed(manifest.IdempotencyKey);
MoveBundle(processingDir, archiveDir, baseName);

تفاصيل التنفيذ تهمّ، لكن الترتيب يهمّ أكثر. لا تخلط «الكتابة» و «النشر» و «أخذ الملكيّة» و «تسجيل الاكتمال».

6. دليل تقريبي للقاعدة العامّة

• writer واحد / reader واحد / المضيف نفسه -> temp -> rename وحده يأخذك بعيداً بالفعل
• عدّة consumers -> أضف claim rename من incoming إلى processing
• الأنظمة غير المتجانسة، NAS، المجلّدات المشتركة -> أضف manifest / done و idempotency أيضاً
• عدّة writers يُحدِّثون الحالة المنطقيّة نفسها -> لا تدفع المشكلة إلى الملفّات؛ فكِّر في قاعدة بيانات أو طابور
• تكون OS locks مفيدة داخل عائلة تطبيقات واحدة مُتحكَّم بها، لكنّها لا تحلّ محلّ بروتوكول التسليم نفسه

النقطة الأخيرة هي أيضاً معيار انسحاب. بعض المشكلات تكون ببساطة غير مريحة عند فرضها على التكامل القائم على الملفّات.

7. الخلاصة

جوهر الإقصاء الحقيقي هنا:

• التحكّم في تزامن تكامل الملفّات لا يدور أساساً حول استدعاء دالّة lock؛ بل يدور حول تعريف انتقالات الحالة
• تمثيل قيد الكتابة و منشور و قيد المعالجة و تمّت معالجته عبر الأسماء والأدلّة يقلّل الحوادث كثيراً

تصاميم يجب تجنّبها:

• Exists -> Create
• الكتابة مباشرةً إلى اسم الملفّ النهائي
• تخمين الاكتمال من ثبات حجم الملفّ
• تحديث الجميع للملفّ المشترك نفسه
• مطالبة lock APIs وحدها بحمل البروتوكول كلّه

تدابير عمليّة تنجح:

• temp -> close -> rename / replace
• اكتمال صريح عبر ملفّات done / manifest
• الملكيّة عبر claim rename
• قواعد lease و idempotency للاسترداد

الخدعة الجوهريّة هي ألّا تجعل «قابلاً للقراءة» و «آمناً للقراءة» يحملان المعنى نفسه. هذا الفصل وحده يُلغي عدداً مدهشاً من المشكلات التي لولا ذلك لظهرت في منتصف اللّيل فقط.

8. المراجع

• LockFileEx function (Win32)
• Locking and Unlocking Byte Ranges in Files (Win32)
• Moving and Replacing Files (Win32)
• File.Replace Method (.NET)
• rename - POSIX
• open - POSIX (O_CREAT | O_EXCL)
• flock(2) - Linux manual page
• open(2) - Linux manual page