در رونویسی تکراری، idempotency جلوی ساخت دو کار برای یک فایل را می‌گیرد

اگر پاسخ درخواست رونویسی گم شود، ارسال دوباره نباید یک کار و هزینهٔ تازه بسازد. با یک کلید پایدار و SQLite، نتیجهٔ قبلی را برمی‌گردانیم و وضعیت‌های مبهم را هم پنهان نمی‌کنیم.

برای نرگس، توسعه‌دهندهٔ بک‌اند سامانهٔ پیاده‌سازی مصاحبه، idempotency باید جلوی این خطا را بگیرد: یک درخواست منطقی رونویسی، پس از قطع ارتباط و ارسال دوباره، به دو کار مستقل تبدیل شود. خروجی عملی این مقاله یک دروازهٔ کوچک است که درخواست تکراریِ تکمیل‌شده را با همان نتیجه پاسخ می‌دهد و درخواست در حال اجرا را دوباره به رونویس نمی‌فرستد. این سازوکار کیفیت متن را بهتر نمی‌کند و در تکرار ارسال HTTP هم مانع فیزیکی ایجاد نمی‌کند؛ اثر تکرار را کنترل می‌کند.

خطا از کجا می‌آید؟ پاسخ گم می‌شود، نه لزوماً درخواست

فرض کنید سرور فایل را دریافت کرده و کار رونویسی را ساخته است، اما اتصال پیش از رسیدن پاسخ به مرورگر قطع می‌شود. مرورگر فقط timeout می‌بیند؛ نمی‌داند کار ساخته شده یا نه. اگر ارسال مجدد هر بار یک کار تازه بسازد، ممکن است دو ردیف در فهرست کارها، دو اعلان و، بسته به مدل صورتحساب سرویس، دو هزینه ایجاد شود. timeout اثبات شکست عملیات نیست.

راه‌حل این است که کلاینت برای هر اقدام منطقی کاربر یک کلید بسازد و همان کلید را در تمام تلاش‌های مجدد نگه دارد. در HTTP می‌توان آن را با هدر Idempotency-Key منتقل کرد؛ ولی صرف وجود این هدر تضمینی ایجاد نمی‌کند و سرور باید قرارداد آن را اجرا کند. RFC 9110، idempotent بودن را بر پایهٔ اثر مورد انتظارِ درخواست‌های یکسان تعریف می‌کند؛ POST رونویسی صرفاً با انتخاب این متد چنین خاصیتی پیدا نمی‌کند.

قرارداد کوچک: کلید، اثرانگشت و وضعیت

برای هر کلید، اثرانگشت ورودی، وضعیت pending یا done و نتیجه را ذخیره می‌کنیم. اثرانگشت در مثال از بایت‌های فایل و زبان ساخته می‌شود؛ در محصول واقعی باید تمام گزینه‌های مؤثر، مانند مدل و تنظیمات تشخیص گوینده، هم وارد آن شوند. کلید یکسان با ورودی متفاوت خطاست، نه مجوز بازگرداندن متن قبلی. مستندات Stripe نیز الگویی از مقایسهٔ پارامترهای درخواست تکراری ارائه می‌کند؛ اینجا از همان اصل استفاده می‌کنیم، نه از تضمین‌های اختصاصی Stripe.

بررسی کلید و ثبت pending باید اتمی باشند؛ وگرنه دو درخواست هم‌زمان هر دو «وجود ندارد» می‌بینند و هر دو رونویسی را شروع می‌کنند. در نمونه، PRIMARY KEY جلوی ثبت تکراری را می‌گیرد و BEGIN IMMEDIATE نویسنده‌ها را هنگام بررسی و ثبت هماهنگ می‌کند. تراکنش را پیش از فراخوانی رونویس می‌بندیم تا قفل نوشتن در طول پردازش صوت نگه داشته نشود. در سرویس چندکاربره، کلید باید در محدودهٔ کاربر یا سازمان تعریف شود، نه در فضای مشترک همهٔ مشتریان.

آزمایش قابل اجرا با Python و SQLite

کد را در idempotent_transcribe.py ذخیره کنید. فقط کتابخانهٔ استاندارد Python لازم است. تابع fake_transcribe عمداً شبیه‌ساز است: یک پیام در stderr چاپ می‌کند تا ببینیم چند بار واقعاً فراخوانی شده است. ورودی آزمایش چند بایت ساختگی است، نه فایل صوتی معتبر. مقدار status نیز وضعیت پیشنهادی پاسخ API است؛ این اسکریپت سرور HTTP راه‌اندازی نمی‌کند.

```python
import hashlib
import json
import sqlite3
import sys
from pathlib import Path


def fake_transcribe(audio, language):
print('PROVIDER_CALLED', file=sys.stderr)
return {'text': 'این یک رونویسی آزمایشی است.', 'language': language}


def handle(key, audio, language):
canonical = json.dumps(
{'audio_sha256': hashlib.sha256(audio).hexdigest(),
'language': language},
sort_keys=True, separators=(',', ':')
).encode('utf-8')
fingerprint = hashlib.sha256(canonical).hexdigest()
db = sqlite3.connect('jobs.sqlite3', timeout=10, isolation_level=None)
try:
db.execute('''CREATE TABLE IF NOT EXISTS jobs (
key TEXT PRIMARY KEY,
fingerprint TEXT NOT NULL,
state TEXT NOT NULL CHECK(state IN ('pending', 'done')),
result TEXT
)''')
db.execute('BEGIN IMMEDIATE')
row = db.execute(
'SELECT fingerprint, state, result FROM jobs WHERE key = ?',
(key,)
).fetchone()
if row is not None:
db.execute('COMMIT')
if row[0] != fingerprint:
return {'status': 422, 'error': 'key_payload_mismatch'}
if row[1] == 'pending':
return {'status': 409, 'error': 'pending_or_unknown'}
return {'status': 200, 'result': json.loads(row[2])}

db.execute(
'INSERT INTO jobs(key, fingerprint, state) VALUES (?, ?, ?)',
(key, fingerprint, 'pending')
)
db.execute('COMMIT')

# A crash or exception here intentionally leaves the job pending.
result = fake_transcribe(audio, language)
db.execute(
'UPDATE jobs SET state = ?, result = ? WHERE key = ?',
('done', json.dumps(result, ensure_ascii=False), key)
)
return {'status': 200, 'result': result}
finally:
db.close()


if __name__ == '__main__':
if len(sys.argv) != 4:
raise SystemExit('Usage: python3 idempotent_transcribe.py KEY FILE LANGUAGE')
response = handle(sys.argv[1], Path(sys.argv[2]).read_bytes(), sys.argv[3])
print(json.dumps(response, ensure_ascii=False))
```

در یک پوشهٔ آزمایشی تازه، دستورهای زیر را اجرا کنید. دو فرمان اولِ رونویسی یک اقدام منطقی با کلید interview-42 هستند. فرمان سوم همان کلید را با زبان متفاوت می‌فرستد تا محافظت در برابر استفادهٔ نادرست از کلید را آزمایش کنیم. اجرای دوبارهٔ آزمایش در همان پوشه، نتایج ذخیره‌شدهٔ قبلی را می‌خواند.

```bash
printf 'mock-audio-bytes' > sample.bin
python3 idempotent_transcribe.py interview-42 sample.bin fa
python3 idempotent_transcribe.py interview-42 sample.bin fa
python3 idempotent_transcribe.py interview-42 sample.bin en
```

خروجی مورد انتظار در پوشهٔ تازه به شکل زیر است. PROVIDER_CALLED فقط در اجرای اول و در stderr دیده می‌شود؛ دو نتیجهٔ موفق یکسان‌اند و درخواست با زبان متفاوت رد می‌شود. پس آزمایش صرفاً برابری متن خروجی را نمی‌سنجد: نشان می‌دهد مسیر دارای اثر جانبی برای درخواست تکراری دوباره فراخوانی نشده است.

```other
PROVIDER_CALLED
{"status": 200, "result": {"text": "این یک رونویسی آزمایشی است.", "language": "fa"}}
{"status": 200, "result": {"text": "این یک رونویسی آزمایشی است.", "language": "fa"}}
{"status": 422, "error": "key_payload_mismatch"}
```

مرز تضمین: pending را کورکورانه دوباره اجرا نکنید

شکست مهم بین دو اتفاق رخ می‌دهد: سرویس بیرونی درخواست را پذیرفته، اما برنامه هنوز نتیجه را در SQLite ننوشته است. پس از خرابی، pending نمی‌گوید کار اصلاً ارسال نشده یا انجام شده و پاسخ گم شده است. نمونه در هر دو حالت 409 می‌دهد و دوباره اجرا نمی‌کند. این انتخاب احتمال اجرای تکراری را کاهش می‌دهد، اما ممکن است کاری را معلق نگه دارد که هرگز آغاز نشده است؛ بنابراین تضمین اجرای دقیقاً یک‌باره در سرویس بیرونی نیست.

اگر ارائه‌دهندهٔ رونویسی خودش کلید idempotency را پشتیبانی می‌کند، کلید پایدار متناظر را به آن هم بدهید و مدت اعتبار و رفتار خطاهایش را بررسی کنید. اگر امکان پیدا کردن کار با شناسهٔ همبستگی دارید، پیش از ارسال دوباره استعلام کنید. صرفاً حذف pending پس از چند دقیقه امن نیست: ممکن است کار بیرونی هنوز فعال باشد. در نبود این قابلیت‌ها، باید میان توقف برای بررسی و پذیرش ریسک تکرار تصمیم بگیرید.

غیرفعال کردن دکمهٔ ارسال فقط دوبارکلیک را کم می‌کند و در برابر تلاش مجدد شبکه کافی نیست. استفاده از هش فایل به‌عنوان تنها کلید هم وقتی غلط است که کاربر عمداً بخواهد همان فایل را دوباره پردازش کند؛ هش برای تشخیص ناسازگاری ورودی مناسب است، اما هویت اقدام کاربر را تعیین نمی‌کند. قرارداد درست این است: تلاش مجدد همان اقدام، همان کلید؛ اقدام تازه، کلید تازه. هزینهٔ این انتخاب، نگهداری وضعیت و نتیجه است؛ حذف رکورد نیز پایان بازهٔ محافظت آن کلید خواهد بود.

منابع

Stripe API — Idempotent requests
https://docs.stripe.com/api/idempotent_requests

SQLite — Transactions
https://www.sqlite.org/lang_transaction.html

Python — sqlite3: DB-API interface for SQLite databases
https://docs.python.org/3/library/sqlite3.html

RFC 9110 — Idempotent Methods
https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2

No comments yet