Idempotency-Key: thử lại an toàn cho tác vụ PDF
Gửi Idempotency-Key cho POST dưới /api/v1/. PDF123 cache 24h phản hồi thành công trong bộ nhớ tiến trình; gửi lại trả Idempotency-Replayed: true, không chạy lại.

Timeout mạng và việc client thử lại là chuyện bình thường với những lần tải PDF multipart. Không có idempotency key, một POST thứ hai sẽ chạy lại đúng thao tác merge, OCR hay compress từ đầu, khiến phần tải lên và thời gian xử lý bị lặp lại vô ích. Có Idempotency-Key, PDF123 có thể phát lại phản hồi thành công đầu tiên.
Middleware làm gì
Middleware trong pdfx-server chỉ áp dụng cho những lời gọi làm thay đổi dữ liệu: POST tới các đường dẫn dưới /api/v1/ (kể cả /api/v1/pipeline). GET và những phương thức khác đi qua nguyên vẹn. Nếu request không có tiêu đề Idempotency-Key (hoặc để trống sau khi trim), thao tác chạy bình thường và không tra cache.
Khi có tiêu đề:
- Store khóa entry theo principal + key. Principal lấy từ
X-API-KEY(dạngkey:…), nếu không có thì từAuthorization(dạngauth:…), cuối cùng là literalanon. Hai giá trị đó được hash (SHA-256) thành khóa của map; thân request không tham gia vào khóa. - Nếu trúng cache trong 24 giờ, middleware trả về status, content type, content disposition và body đã lưu, đồng thời đặt
Idempotency-Replayed: true. - Nếu trượt, request tiếp tục. Chỉ những phản hồi thành công mới được đệm và lưu (phản hồi không thành công không được cache để phát lại).
- Thân phản hồi được đệm tối đa 100 MiB để lần phát lại gửi được nguyên byte của tệp. Thân nào không đệm được thì không âm thầm bỏ qua cache: yêu cầu đó trả HTTP 500, nên phản hồi vượt giới hạn sẽ thất bại thay vì đi tiếp mà không được cache.
Tác vụ thất bại vẫn an toàn để thử lại với cùng key: vì thất bại không được lưu, lần thử sau có thể thành công rồi trở thành kết quả được cache. Đừng dùng lại một key cho tệp hay tham số khác; cache không hash body, chỉ hash principal và key. Hai caller không chia sẻ API key lẫn Authorization thì không thể va chạm tình cờ; còn caller ẩn danh dùng chung principal anon, nên họ phải chọn key khác nhau.
Cách gửi
Chọn một chuỗi opaque ổn định cho mỗi tác vụ logic (UUID là đủ):
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
Caller ẩn danh lẫn caller dùng API key đều dùng được. Pipeline nối watermark rồi compress vẫn nên gửi một key cho mỗi request HTTP bạn muốn chống trùng, kể cả từng bước nếu bạn POST riêng lẻ, hoặc một key cho một lần gọi /api/v1/pipeline.
Những lần dùng lẻ trên trang công cụ (Compress, OCR, …) không bắt bạn tự nghĩ ra key; tiêu đề này quan trọng với client có thử lại. Skill đã phát hành tại /skills/pdf123.md cũng hiển thị Idempotency-Key trong ví dụ pipeline vì lý do đó.
Những mẫu client hiệu quả
- Sinh key trước lần POST đầu; dùng lại chính key đó cho các lần thử lại do timeout của cùng tác vụ.
- Khi thành công, kiểm tra
Idempotency-Replayed: truenếu cần biết phản hồi này đến từ cache hay vừa chạy lại thao tác. - Đổi key khi tệp, thao tác hoặc tham số thay đổi, dù principal vẫn giữ nguyên.
- Với
/api/v1/pipeline, một key phủ toàn bộ POST pipeline, không phải từng bước bên trong.
Phát lại không phải là gì
Phát lại không phải một hàng đợi tác vụ bền vững. Store nằm trong tiến trình (HashMap sau mutex) với TTL 24 giờ. Sau khi hết hạn, hoặc sau khi tiến trình khởi động lại làm mất map trong bộ nhớ, cùng key đó sẽ chạy lại thao tác. Triển khai nhiều instance không chia sẻ map đó, trừ khi bạn đặt một store dùng chung phía trước; middleware hiện nay là theo từng tiến trình.
Hãy coi Idempotency-Replayed: true là bằng chứng phản hồi này đến từ cache, không phải một sổ cái vĩnh viễn. Nó không có nghĩa PDF đã được xử lý lại, và cũng không gia hạn TTL.
Thêm chi tiết về bề mặt API: Nhà phát triển và Xây cho AI agent. Những trang công cụ như Compress vẫn sẵn cho các tác vụ dùng lẻ trên trình duyệt mà không cần nghĩ ra key.