Prompt API

Hãy tạo một trang đích (landing page) hoàn chỉnh, được chăm chút tỉ mỉ và có thể sao chép-dán trực tiếp, được thiết kế để đóng vai trò như một trung tâm thanh toán tất cả trong một (all-in-one payment hub), tận dụng tối đa sự linh hoạt và tính năng phong phú của Notion. Trang được tuyển chọn tuyệt vời này cần tích hợp liền mạch hàng loạt tùy chọn thanh toán — hãy nghĩ đến PayPal, Stripe, PayEx, GRA, GrabPay Later, Shopee, Shopee PayLater, AhaPay và HitPay — quy tụ đa dạng các kênh tài chính vào trong một trải nghiệm gắn kết duy nhất.

Hãy tưởng tượng một khu chợ số sôi động, nơi các nhà sáng tạo có thể dễ dàng trưng bày sản phẩm/dịch vụ của mình, được thiết kế để thu hút và giữ chân người dùng. Khu vực được thiết kế chu đáo dành cho thành viên miễn phí sẽ trao quyền cho các nhà sáng tạo đồng nghiệp, mang lại cho họ khả năng độc đáo là chỉ cần dán đường liên kết của riêng mình vào, tạo ra sự kết nối tức thì tới những giá trị tinh hoa mà họ muốn chia sẻ.

Nhiệm vụ của bạn là khơi gợi một cảm giác mới mẻ đầy phấn khích, giống như sự hào hứng kỳ diệu khi bước ra khỏi những khuôn khổ quen thuộc nhàm chán thường ngày. Từng yếu tố trên trang đích này phải thổi luồng sinh khí mới vào những điều bình thường, biến các giao dịch hàng ngày thành những khoảnh khắc khơi dậy sự tò mò và tương tác. Với hàng loạt tùy chọn được bố trí dưới định dạng bắt mắt và thân thiện với người dùng, khách truy cập sẽ cảm nhận được sự háo hức mong chờ khi điều hướng qua bản giao hưởng của những lựa chọn sẵn có dành cho họ.

Hãy để trang web phản chiếu một bầu không khí cuốn hút nơi sự đơn điệu tan biến, mang đến một góc nhìn tươi mới cho quy trình thanh toán truyền thống. Đây không chỉ đơn thuần là một trang đích; đó là một lời mời gọi khám phá, kết nối và trải nghiệm tiềm năng năng động của thị trường kỹ thuật số qua từng cú nhấp chuột. Hãy đắm mình vào nghệ thuật thiết kế và công năng — suy cho cùng, trong bức tranh giao dịch trực tuyến không ngừng phát triển này, ai lại không muốn cảm nhận luồng sinh khí đầy hứng khởi đó?

---
name: api-contract-diff-reviewer
description: Rà soát các bản diff API/OpenAPI để phát hiện thay đổi gây lỗi tương thích và soạn thảo danh sách kiểm tra chuyển đổi cho các bên gọi API (consumers).
---

# Công cụ Rà soát Khác biệt Hợp đồng API (API Contract Diff Reviewer)

Khi người dùng dán vào một bản so sánh khác biệt (diff) của API, thay đổi trên OpenAPI, hoặc lược đồ (schema) trước/sau khi sửa, hãy tạo một bản báo cáo rà soát thay đổi gây lỗi tương thích có cấu trúc rõ ràng.

## Quy trình làm việc
1. Đọc tệp `references/breaking-change-rules.md` và áp dụng các quy tắc trong đó.
2. Phân loại từng thay đổi thành: **gây lỗi tương thích (breaking)** / **không gây lỗi tương thích (non-breaking)** / **chưa rõ ràng (unclear)**.
3. Đầu ra bao gồm:
   - Tóm tắt (3–6 gạch đầu dòng)
   - Bảng các thay đổi gây lỗi tương thích (đường dẫn path | nội dung thay đổi | lý do gây lỗi | cách giảm thiểu)
   - Đoạn nội dung gợi ý cho tệp `CHANGELOG`
   - Danh sách kiểm tra chuyển đổi dành cho bên sử dụng API (bản sao của `templates/migration-checklist.md` đã được điền thông tin)
4. Nếu bản diff chưa đầy đủ, hãy hỏi thêm về các đường dẫn còn thiếu trước khi phỏng đoán.

## Quy tắc
- Không bao giờ tự bịa ra các điểm cuối (endpoints) không có trong dữ liệu đầu vào.
- Ưu tiên trích dẫn chính xác đường dẫn JSON Pointer / path.
- Nêu bật một cách rõ ràng các thay đổi liên quan đến xác thực (auth), phân trang (pagination) và cấu trúc trả về lỗi (error-shape).
FILE:references/breaking-change-rules.md
# Nguyên tắc nhận diện thay đổi gây lỗi tương thích (Breaking change)

Hãy coi là **gây lỗi tương thích (breaking)** trừ khi có khoảng thời gian ngừng hỗ trợ (deprecation window) đã được ghi nhận trong tài liệu:
- Xóa hoặc đổi tên một trường dữ liệu (field), điểm cuối (endpoint), tham số truy vấn (query param) hoặc tiêu đề (header)
- Chuyển một trường tùy chọn (optional) thành bắt buộc (required)
- Thu hẹp kiểu dữ liệu (từ string sang enum, từ number sang integer, thêm giới hạn maxLength làm từ chối các giá trị hợp lệ trước đó)
- Thay đổi cơ chế xác thực hoặc các quyền truy cập (scopes) bắt buộc
- Thay đổi giá trị mặc định của phân trang theo cách làm cắt bớt kết quả trả về so với trước đây
- Thay đổi cấu trúc khung bọc thông báo lỗi (error envelope shape) mà các trình khách (clients) đang phân tích cú pháp

Thường là **không gây lỗi tương thích (non-breaking)**:
- Thêm các trường dữ liệu tùy chọn mới
- Thêm các điểm cuối (endpoints) mới
- Mở rộng kiểu dữ liệu một cách an toàn
- Thêm các giá trị enum mới chỉ khi phía trình khách được lập trình để bỏ qua các giá trị lạ chưa biết

**Chưa rõ ràng (Unclear)** (cần hỏi lại):
- Thay đổi ý nghĩa ngữ nghĩa nhưng vẫn giữ nguyên cấu trúc dữ liệu
- Thay đổi về hiệu năng hoặc giới hạn tần suất gọi (rate-limit) mà không có sự khác biệt nào trên lược đồ (schema diff)
FILE:templates/migration-checklist.md
# Danh sách kiểm tra chuyển đổi cho bên sử dụng API (Consumer migration checklist)

- [ ] Xác định toàn bộ các dịch vụ/trình khách đang gọi tới những đường dẫn bị thay đổi
- [ ] Cập nhật lại các kiểu dữ liệu của yêu cầu gửi đi và phản hồi trả về (request/response types)
- [ ] Bổ sung lớp đệm tương thích (compatibility shims) hoặc bộ chuyển đổi (adapters) nếu cần
- [ ] Mở rộng các bài kiểm thử hợp đồng (contract tests) cho các trường hợp lỗi mới
- [ ] Ghi rõ tài liệu về thứ tự triển khai (nâng cấp máy chủ trước hay nâng cấp trình khách trước)
- [ ] Thiết lập cảnh báo giám sát khi có sự gia tăng đột biến mã lỗi 4xx trên các tuyến đường (routes) bị thay đổi
- [ ] Thông báo ngày ngừng hỗ trợ chính thức (deprecation date) tới các đối tác bên ngoài

---
name: http-status-code-advisor
description: Chọn mã trạng thái HTTP chính xác cho một phản hồi API từ mô tả ngắn gọn về những gì đã xảy ra (đã tạo, xác thực thất bại, không tìm thấy, xung đột, giới hạn tần suất, dịch vụ thượng nguồn ngừng hoạt động) và giải thích lý do, kèm theo các lỗi phổ biến cần tránh. Sử dụng khi thiết kế các endpoint REST, đánh giá việc xử lý lỗi API, hoặc khi phân vân "trường hợp này nên trả về 400, 404, 409 hay 422?". Bao gồm một trình gợi ý sử dụng thư viện chuẩn Python.
---

# Cố vấn Mã trạng thái HTTP

Bạn giúp các nhà thiết kế và người đánh giá API chọn mã trạng thái HTTP phù hợp nhất với những gì thực sự đã xảy ra trong một yêu cầu (request). Bạn lập luận dựa trên phương thức yêu cầu (request method), kết quả đầu ra và bên nào có lỗi (máy khách, máy chủ hay dịch vụ thượng nguồn - upstream), đồng thời ưu tiên mã tiêu chuẩn cụ thể nhất mà máy khách có thể dựa vào đó để xử lý. Bạn tuân thủ ngữ nghĩa RFC 9110 và không tự bịa ra các mã phi tiêu chuẩn.

## Các tệp trong kỹ năng này

- `scripts/suggest_status.py` - ánh xạ một mô tả tình huống ngắn gọn (các từ khóa cộng với phương thức) sang một mã được đề xuất, các phương án thay thế và lý do dài một dòng (chỉ sử dụng thư viện chuẩn của Python 3)
- `references/status-cheatsheet.md` - các mã quan trọng đối với API, được nhóm theo phân lớp (class), kèm theo thời điểm sử dụng từng mã
- `references/common-mistakes.md` - các cách dùng sai phổ biến (trả về 200 kèm nội dung báo lỗi, nhầm lẫn 401 với 403, dùng 404 cho danh sách trống, dùng 500 cho lỗi xác thực dữ liệu)
- `templates/decision-tree.md` - luồng câu hỏi từng bước để đi đến mã phù hợp
- `examples/api-scenarios.md` - các tình huống thực tế đã được giải quyết kèm theo mã được chọn và cấu trúc phản hồi

## Quy trình làm việc

### 1. Thu thập thông tin thực tế
Yêu cầu cung cấp, hoặc suy luận từ mã nguồn hay mô tả:
- Phương thức HTTP và endpoint (ví dụ: `POST /orders`)
- Chuyện gì đã xảy ra: thành công, thành công một phần, đã chấp nhận xử lý bất đồng bộ, sự cố đầu vào, sự cố xác thực/phân quyền, thiếu tài nguyên, xung đột trạng thái, giới hạn tần suất (rate limit), lỗi máy chủ hoặc dịch vụ phụ thuộc
- Có trả về phần thân phản hồi (response body) hay không, và có tài nguyên mới nào được tạo ra hay không
- Bất kỳ quy ước API hiện có nào mà nhóm đang tuân theo

### 2. Duyệt qua cây quyết định
Sử dụng `templates/decision-tree.md`. Quyết định phân lớp trước (2xx, 3xx, 4xx, 5xx), sau đó mới đến mã cụ thể. Bên nào gây ra lỗi sẽ quyết định việc chọn 4xx hay 5xx.

### 3. Chạy công cụ hỗ trợ (tùy chọn)
```
python3 scripts/suggest_status.py --method POST "created new order"
python3 scripts/suggest_status.py --method GET "user not logged in"
python3 scripts/suggest_status.py --json "email already exists"
```
Hãy coi kết quả của script như một dự đoán ban đầu; cần xác nhận lại với bảng tra cứu nhanh (cheatsheet).

### 4. Kiểm tra các lỗi phổ biến
Đối chiếu lựa chọn với `references/common-mistakes.md`, đặc biệt là 401 so với 403, 400 so với 422, và 404 so với danh sách trống trả về mã 200.

### 5. Trả lời
Trả về:
1. **Mã được đề xuất** và cụm từ lý do (ví dụ: `409 Conflict`)
2. **Tại sao** trong một hoặc hai câu, gắn liền với các thông tin thực tế
3. **Các phương án thay thế** đã cân nhắc và lý do chúng không được chọn
4. **Các header cần bao gồm** khi có liên quan (`Location` cho 201, `Retry-After` cho 429/503, `WWW-Authenticate` cho 401, `Allow` cho 405)
5. **Phác thảo phần thân báo lỗi** sử dụng chuẩn RFC 9457 Problem Details (`type`, `title`, `status`, `detail`, `instance`) đối với các mã 4xx/5xx

## Quy tắc

- Không bao giờ trả về 2xx cho một thao tác thất bại.
- Chỉ sử dụng 5xx khi máy chủ hoặc dịch vụ thượng nguồn mà nó phụ thuộc vào gặp sự cố, không bao giờ dùng cho dữ liệu đầu vào sai từ phía máy khách.
- Giữ sự nhất quán với các quy ước hiện có của nhóm nếu chúng hợp lý; chỉ cần nhắc đến lựa chọn tiêu chuẩn một lần nếu có sự khác biệt.
- Nếu yêu cầu bảo mật đòi hỏi phải che giấu sự tồn tại của một tài nguyên, hãy nói rõ điều đó khi đề xuất dùng 404 thay vì 403.
FILE:references/common-mistakes.md
# Các lỗi Mã trạng thái phổ biến

1. **Trả về 200 kèm phần thân báo lỗi** (`{"success": false}`). Các máy khách, proxy, bộ nhớ đệm (caches) và hệ thống giám sát đều coi 200 là thành công. Hãy sử dụng đúng mã 4xx/5xx và đưa chi tiết lỗi vào phần thân (body).

2. **Nhầm lẫn giữa 401 và 403.** 401 có nghĩa là "bạn là ai?" (thiếu thông tin xác thực hoặc thông tin xác thực sai). 403 có nghĩa là "tôi biết bạn là ai, và câu trả lời là không được phép." Một người dùng đã đăng nhập nhưng không có quyền sẽ nhận được 403, không phải 401.

3. **Dùng 500 cho đầu vào không hợp lệ.** Lỗi xác thực dữ liệu (validation) là lỗi của phía máy khách: hãy dùng 400 hoặc 422. Dành riêng mã 500 cho các lỗi phần mềm (bugs) và sự cố máy chủ ngoài dự kiến. Sự gia tăng đột biến của mã 500 phải mang ý nghĩa là có thứ gì đó đang bị hỏng ở phía hệ thống của bạn.

4. **Dùng 404 cho một tập hợp trống.** `GET /users?role=admin` khi không có kết quả khớp phải là `200` kèm theo `[]`. Mã 404 chỉ dành cho một tài nguyên cụ thể bị thiếu, chẳng hạn như `/users/9999`.

5. **Dùng 400 cho mọi thứ.** Ưu tiên sử dụng mã cụ thể khi nó giúp máy khách biết cách xử lý: 409 cho dữ liệu trùng lặp, 413 cho dữ liệu vượt quá kích thước, 415 cho sai kiểu nội dung (content type), 429 cho giới hạn tần suất (rate limits).

6. **Dùng 201 mà không có `Location`.** Khi bạn tạo một tài nguyên có URL riêng, hãy gửi kèm `Location: /orders/123`.

7. **Dùng 204 kèm theo phần thân (body).** Mã 204 không được phép chứa nội dung trả về. Nếu bạn trả về tài nguyên, hãy sử dụng 200.

8. **Dùng 302 trong API.** Các máy khách có thể tự động đổi phương thức POST thành GET. Hãy sử dụng 307 hoặc 308 khi cần giữ nguyên phương thức gọi.

9. **503 so với 500.** 503 có nghĩa là sự cố tạm thời và có thể thử lại (đang bảo trì, quá tải), lý tưởng nhất là đi kèm `Retry-After`. 500 có nghĩa là một lỗi bất ngờ không lường trước.

10. **Làm lộ sự tồn tại của tài nguyên qua mã 403.** Đối với các tài nguyên riêng tư, việc trả về 404 cho người dùng không có quyền có thể ngăn chặn hành vi dò quét liệt kê (enumeration). Hãy quyết định một cách có chủ đích và ghi lại vào tài liệu.

11. **Sử dụng 422 và 400 thiếu nhất quán.** Hãy chọn một quy tắc (400 = không thể phân tích cú pháp, 422 = đã phân tích cú pháp nhưng giá trị không hợp lệ) và áp dụng nó trên mọi endpoint.

12. **Các mã phi tiêu chuẩn** (ví dụ: dùng 418 trên môi trường production, 499, các mã 6xx tự chế). Nhiều máy khách và proxy xử lý chúng rất kém. Hãy tuân thủ các mã đã được đăng ký chính thức.
FILE:references/status-cheatsheet.md
# Bảng tra cứu nhanh Mã trạng thái HTTP cho API

Dựa trên RFC 9110 (Ngữ nghĩa HTTP), RFC 6585 (429), và RFC 9457 (Chi tiết sự cố - Problem Details).

## 2xx Thành công (Success)
| Mã | Tên | Sử dụng khi |
|---|---|---|
| 200 | OK | Yêu cầu thành công và phần thân chứa kết quả (GET, hoặc PUT/PATCH trả về tài nguyên đã cập nhật). |
| 201 | Created | Một tài nguyên mới đã được tạo. Gửi kèm `Location` chứa URL của nó; phần thân thường chứa tài nguyên đó. |
| 202 | Accepted | Công việc đã được đưa vào hàng đợi và sẽ hoàn tất sau. Trả về một URL theo dõi trạng thái hoặc job id. |
| 204 | No Content | Thành công nhưng không có phần thân trả về (DELETE, hoặc PUT/PATCH khi bạn không trả về dữ liệu gì). |
| 206 | Partial Content | Phục vụ một dải byte (byte range) để phản hồi lại header `Range`. |

## 3xx Chuyển hướng (Redirection)
| Mã | Tên | Sử dụng khi |
|---|---|---|
| 301 | Moved Permanently | Tài nguyên có một URL cố định mới (phương thức có thể bị đổi thành GET trên các máy khách cũ). |
| 304 | Not Modified | Yêu cầu GET có điều kiện (`If-None-Match` / `If-Modified-Since`) và không có gì thay đổi. |
| 307 | Temporary Redirect | Di chuyển tạm thời; máy khách phải lặp lại yêu cầu với cùng phương thức và phần thân. |
| 308 | Permanent Redirect | Di chuyển vĩnh viễn; giữ nguyên cùng phương thức và phần thân. |

## 4xx Lỗi phía máy khách (Client errors)
| Mã | Tên | Sử dụng khi |
|---|---|---|
| 400 | Bad Request | Cú pháp sai định dạng: JSON không hợp lệ, sai cấu trúc nội dung, thiếu tham số truy vấn (query param) bắt buộc. |
| 401 | Unauthorized | Không có thông tin xác thực hoặc thông tin xác thực không hợp lệ/đã hết hạn. Gửi kèm `WWW-Authenticate`. |
| 403 | Forbidden | Đã xác thực danh tính, nhưng không được phép thực hiện thao tác này. |
| 404 | Not Found | Tài nguyên không tồn tại (hoặc bạn muốn ẩn việc nó có tồn tại). |
| 405 | Method Not Allowed | URL có tồn tại nhưng không hỗ trợ phương thức này. Gửi kèm `Allow`. |
| 406 | Not Acceptable | Không thể tạo ra bất kỳ định dạng nào được liệt kê trong `Accept`. |
| 409 | Conflict | Yêu cầu xung đột với trạng thái hiện tại: trùng khóa duy nhất (unique key), xung đột phiên bản, chuyển đổi trạng thái không hợp lệ. |
| 410 | Gone | Tài nguyên từng tồn tại và đã bị xóa vĩnh viễn. |
| 412 | Precondition Failed | Điều kiện tiên quyết `If-Match` / `If-Unmodified-Since` thất bại (khóa lạc quan - optimistic locking). |
| 413 | Content Too Large | Phần thân vượt quá giới hạn kích thước. |
| 415 | Unsupported Media Type | `Content-Type` không được hỗ trợ. |
| 422 | Unprocessable Content | Cú pháp hoàn toàn ổn nhưng giá trị không vượt qua được bước kiểm tra hợp lệ (email sai, ngày kết thúc trước ngày bắt đầu). |
| 428 | Precondition Required | Máy chủ yêu cầu một truy vấn có điều kiện để ngăn chặn việc ghi đè làm mất dữ liệu cập nhật. |
| 429 | Too Many Requests | Vượt quá giới hạn tần suất gọi. Gửi kèm `Retry-After`. |

## 5xx Lỗi phía máy chủ (Server errors)
| Mã | Tên | Sử dụng khi |
|---|---|---|
| 500 | Internal Server Error | Sự cố bất ngờ trong mã nguồn của bạn. |
| 501 | Not Implemented | Máy chủ hoàn toàn không hỗ trợ chức năng này. |
| 502 | Bad Gateway | Một dịch vụ thượng nguồn trả về phản hồi không hợp lệ. |
| 503 | Service Unavailable | Tạm thời quá tải hoặc đang bảo trì. Gửi kèm `Retry-After` nếu biết thời gian. |
| 504 | Gateway Timeout | Một dịch vụ thượng nguồn không phản hồi kịp thời gian quy định. |
FILE:templates/decision-tree.md
# Cây quyết định Mã trạng thái

Trả lời theo thứ tự. Dừng lại ở kết quả khớp đầu tiên.

1. **Yêu cầu có thành công không?**
   - Có, công việc đã hoàn tất và một tài nguyên mới được tạo ra -> **201** (+ `Location`)
   - Có, công việc đã được chấp nhận nhưng sẽ hoàn tất sau -> **202** (+ URL trạng thái)
   - Có, không có gì để trả về -> **204**
   - Có, có trả về dữ liệu -> **200**
   - Không -> chuyển sang câu 2

2. **Máy khách có đang được chuyển hướng không?**
   - GET có điều kiện, dữ liệu không đổi -> **304**
   - Đã di chuyển, phải giữ nguyên phương thức -> **307** (tạm thời) / **308** (vĩnh viễn)
   - Không -> chuyển sang câu 3

3. **Đó có phải là vấn đề xác thực danh tính (authentication) không?**
   - Không có thông tin xác thực, hoặc token không hợp lệ / đã hết hạn -> **401** (+ `WWW-Authenticate`)
   - Không -> chuyển sang câu 4

4. **Người gọi đã xác thực có bị từ chối quyền thực hiện không?**
   - Có, và có thể tiết lộ sự tồn tại của tài nguyên -> **403**
   - Có, nhưng phải che giấu sự tồn tại của tài nguyên -> **404**
   - Không -> chuyển sang câu 5

5. **Đích đến có bị thiếu hoặc phương thức có bị sai không?**
   - Tài nguyên không tồn tại -> **404**
   - Tài nguyên đã bị xóa vĩnh viễn -> **410**
   - URL tồn tại, nhưng phương thức không được hỗ trợ -> **405** (+ `Allow`)
   - Không -> chuyển sang câu 6

6. **Bản thân yêu cầu có ở trạng thái không thể sử dụng được không?**
   - Không thể phân tích cú pháp (JSON lỗi, sai kiểu dữ liệu) -> **400**
   - Sai `Content-Type` -> **415**
   - Phần thân quá lớn -> **413**
   - Không thể đáp ứng `Accept` -> **406**
   - Không -> chuyển sang câu 7

7. **Đầu vào hợp lệ về cú pháp nhưng bị từ chối?**
   - Không vượt qua kiểm tra quy tắc nghiệp vụ -> **422**
   - Xung đột với trạng thái hiện tại (trùng lặp, sai phiên bản, máy trạng thái) -> **409**
   - Điều kiện tiên quyết `If-Match` thất bại -> **412**
   - Quá nhiều yêu cầu -> **429** (+ `Retry-After`)
   - Không -> chuyển sang câu 8

8. **Sự cố phía máy chủ**
   - Dịch vụ thượng nguồn trả về dữ liệu rác/lỗi -> **502**
   - Dịch vụ thượng nguồn bị hết thời gian chờ (timed out) -> **504**
   - Tạm thời không khả dụng / đang bảo trì -> **503** (+ `Retry-After`)
   - Tính năng hoàn toàn không được hỗ trợ -> **501**
   - Lỗi phần mềm (bug) bất ngờ -> **500**

## Mẫu câu trả lời

```
Recommended: <code> <reason phrase>
Why: <1-2 sentences>
Alternatives: <code> - <why not>; <code> - <why not>
Headers: <header: value>
Body (Problem Details):
{
  "type": "https://example.com/problems/<slug>",
  "title": "<short title>",
  "status": <code>,
  "detail": "<specific explanation>",
  "instance": "<request path or id>"
}
```
FILE:examples/api-scenarios.md
# Các tình huống API thực tế

## 1. Đăng ký bằng một email đã tồn tại
`POST /users` với `{"email": "ana@example.com"}` và email đó đã có người dùng.
- **Đề xuất:** 409 Conflict
- **Tại sao:** Đầu vào đúng định dạng và hợp lệ, nhưng nó xung đột với trạng thái hiện có (một khóa duy nhất).
- **Phương án thay thế:** 422 (dùng được nếu nhóm của bạn sử dụng 422 cho mọi lỗi vi phạm quy tắc, nhưng 409 cho máy khách biết vấn đề cụ thể nằm ở trạng thái dữ liệu); 400 (quá mơ hồ).
- **Phần thân (Body):**
```json
{"type": "https://example.com/problems/email-taken", "title": "Email already registered", "status": 409, "detail": "An account with this email already exists.", "instance": "/users"}
```

## 2. Đã tạo đơn hàng
`POST /orders` thành công và trả về đơn hàng đó.
- **Đề xuất:** 201 Created, `Location: /orders/8812`
- **Phương án thay thế:** 200 (làm mất tín hiệu "đã tạo mới"), 202 (chỉ dùng nếu quá trình xử lý là bất đồng bộ và đơn hàng chưa được lưu bền vững).

## 3. Xuất báo cáo được đưa vào hàng đợi
`POST /reports/exports` bắt đầu một tác vụ kéo dài 5 phút.
- **Đề xuất:** 202 Accepted kèm theo `{"jobId": "exp_41", "statusUrl": "/reports/exports/exp_41"}`

## 4. Người xem (Viewer) cố gắng xóa một dự án
Người dùng đã đăng nhập với vai trò chỉ đọc gọi `DELETE /projects/7`.
- **Đề xuất:** 403 Forbidden
- **Tại sao:** Danh tính đã được xác định; thứ bị thiếu là quyền hạn. Mã 401 sẽ gợi ý sai rằng họ nên đăng nhập lại.

## 5. Access token đã hết hạn
`GET /me` với một JWT đã hết hạn.
- **Đề xuất:** 401 Unauthorized, `WWW-Authenticate: Bearer error="invalid_token"`

## 6. Tìm kiếm không có kết quả khớp
`GET /products?q=zzzz`
- **Đề xuất:** 200 OK kèm theo `{"items": [], "total": 0}`
- **Tại sao:** Tập hợp tài nguyên có tồn tại; nó chỉ đang trống mà thôi. Mã 404 sẽ làm lỗi các máy khách vốn coi 404 là một lỗi thực sự.

## 7. Ngày bắt đầu sau ngày kết thúc
`POST /bookings` với `start=2026-10-20`, `end=2026-10-18`.
- **Đề xuất:** 422 Unprocessable Content
- **Phương án thay thế:** 400 (chấp nhận được nếu quy ước của bạn gộp chung lỗi phân tích cú pháp và lỗi kiểm tra tính hợp lệ).

## 8. Nhà cung cấp thanh toán hết thời gian chờ
`POST /checkout` và cổng thanh toán không trả lời trong vòng 10 giây.
- **Đề xuất:** 504 Gateway Timeout
- **Phương án thay thế:** 502 (nếu cổng thanh toán có trả lời nhưng bằng một phản hồi không hợp lệ), 503 (nếu bạn đang chủ động giảm tải).

## 9. Quá nhiều lần thử đăng nhập
- **Đề xuất:** 429 Too Many Requests, `Retry-After: 60`

## 10. Cập nhật dữ liệu cũ (Stale update)
`PUT /docs/3` với `If-Match: "v4"` nhưng phiên bản hiện tại là `"v5"`.
- **Đề xuất:** 412 Precondition Failed
FILE:scripts/suggest_status.py
#!/usr/bin/env python3
"""Suggest an HTTP status code from a short scenario description.

Usage:
    python3 suggest_status.py [--method METHOD] [--json] "scenario text"
    python3 suggest_status.py --self-test

Keyword-based and deliberately simple: it gives a first guess plus
alternatives. Always confirm against references/status-cheatsheet.md.
Python 3 standard library only.
"""
import argparse
import json
import re
import sys

# Ordered rules: first match wins. Each rule: (keywords, code, reason, alternatives, headers)
RULES = [
    (["rate limit", "too many", "throttl", "quota exceeded"], 429,
     "Client exceeded a rate limit or quota.", [503], ["Retry-After"]),
    (["not logged in", "no token", "missing token", "expired token", "invalid token",
      "unauthenticated", "no credentials", "bad credentials", "login required"], 401,
     "Credentials are missing or invalid.", [403], ["WWW-Authenticate"]),
    (["no permission", "not allowed", "forbidden", "insufficient role", "not authorized",
      "read-only user", "not the owner"], 403,
     "Caller is authenticated but lacks permission.", [404], []),
    (["already exists", "duplicate", "conflict", "version mismatch", "already taken",
      "invalid state", "state transition"], 409,
     "Request conflicts with the current state of the resource.", [422, 412], []),
    (["precondition", "if-match", "etag mismatch", "stale"], 412,
     "A conditional request header did not match.", [409], ["ETag"]),
    (["too large", "payload size", "file too big", "body too big"], 413,
     "Request body exceeds the allowed size.", [400], []),
    (["unsupported media", "content-type", "wrong content type"], 415,
     "Content-Type is not supported.", [400], ["Accept"]),
    (["malformed", "invalid json", "parse error", "cannot parse", "syntax error",
      "missing required"], 400,
     "Request cannot be parsed or is missing required parts.", [422], []),
    (["validation", "invalid email", "out of range", "must be", "before start",
      "invalid value", "fails rule"], 422,
     "Request is well-formed but values fail validation.", [400], []),
    (["method not allowed", "wrong method", "unsupported method"], 405,
     "The URL exists but does not support this method.", [404], ["Allow"]),
    (["gone", "permanently deleted", "removed permanently"], 410,
     "Resource existed and was permanently removed.", [404], []),
    (["not found", "does not exist", "no such", "unknown id"], 404,
     "Target resource does not exist.", [410], []),
    (["upstream timeout", "gateway timeout", "timed out", "timeout"], 504,
     "An upstream dependency did not respond in time.", [502, 503], []),
    (["bad gateway", "upstream error", "invalid upstream", "upstream returned"], 502,
     "An upstream dependency returned an invalid response.", [504], []),
    (["maintenance", "overloaded", "unavailable", "down for"], 503,
     "Service is temporarily unavailable.", [500], ["Retry-After"]),
    (["not implemented", "unsupported feature"], 501,
     "The server does not support this functionality.", [405], []),
    (["crash", "exception", "bug", "unexpected error", "internal error"], 500,
     "Unexpected server-side failure.", [503], []),
    (["queued", "async", "background job", "accepted for processing", "will process"], 202,
     "Work was accepted and will complete later.", [201], ["Location"]),
    (["created", "new resource", "signed up", "registered"], 201,
     "A new resource was created.", [200, 202], ["Location"]),
    (["deleted", "no content", "nothing to return"], 204,
     "Success with no response body.", [200], []),
    (["not modified", "unchanged", "cache hit"], 304,
     "Conditional request and resource is unchanged.", [200], ["ETag"]),
    (["empty list", "no results", "no matches", "empty collection"], 200,
     "Collection exists but is empty: return 200 with an empty list.", [404], []),
    (["success", "ok", "returned", "fetched", "updated"], 200,
     "Request succeeded and returns content.", [204], []),
]

REASONS = {
    200: "OK", 201: "Created", 202: "Accepted", 204: "No Content", 304: "Not Modified",
    400: "Bad Request", 401: "Unauthorized", 403: "Forbidden", 404: "Not Found",
    405: "Method Not Allowed", 409: "Conflict", 410: "Gone", 412: "Precondition Failed",
    413: "Content Too Large", 415: "Unsupported Media Type", 422: "Unprocessable Content",
    429: "Too Many Requests", 500: "Internal Server Error", 501: "Not Implemented",
    502: "Bad Gateway", 503: "Service Unavailable", 504: "Gateway Timeout",
}


def suggest(text, method=None):
    t = " " + re.sub(r"\s+", " ", text.lower()) + " "
    for keywords, code, reason, alts, headers in RULES:
        for kw in keywords:
            # word-boundary match for very short keywords like "ok"
            if len(kw) <= 3:
                if re.search(r"\b" + re.escape(kw) + r"\b", t):
                    break
            elif kw in t:
                break
        else:
            continue
        m = (method or "").upper()
        notes = []
        if code == 200 and m == "DELETE":
            code, reason, alts = 204, "DELETE succeeded; usually no body.", [200]
        if code == 201 and m and m not in ("POST", "PUT"):
            notes.append("201 is normally returned by POST or PUT.")
        if code == 204 and m == "GET":
            notes.append("GET rarely returns 204; prefer 200 with a body.")
        return {
            "code": code,
            "reason_phrase": REASONS.get(code, ""),
            "why": reason,
            "alternatives": [f"{a} {REASONS.get(a, '')}".strip() for a in alts],
            "headers": headers,
            "matched_keyword": kw,
            "notes": notes,
        }
    return {
        "code": None,
        "reason_phrase": "",
        "why": "No rule matched. Walk templates/decision-tree.md manually.",
        "alternatives": [],
        "headers": [],
        "matched_keyword": None,
        "notes": [],
    }


def self_test():
    cases = [
        ("created new order", "POST", 201),
        ("user not logged in", "GET", 401),
        ("read-only user tries to delete", "DELETE", 403),
        ("email already exists", "POST", 409),
        ("search returned no results", "GET", 200),
        ("end date before start date validation", "POST", 422),
        ("invalid json body", "POST", 400),
        ("payment gateway timed out", "POST", 504),
        ("too many login attempts", "POST", 429),
        ("order id does not exist", "GET", 404),
        ("report export queued as background job", "POST", 202),
        ("record deleted", "DELETE", 204),
        ("unexpected exception in handler", "GET", 500),
        ("something odd happened", "GET", None),
    ]
    failed = 0
    for text, method, expected in cases:
        got = suggest(text, method)["code"]
        ok = got == expected
        failed += not ok
        print(f"{'PASS' if ok else 'FAIL'}  {method:6} {text!r} -> {got} (expected {expected})")
    print(f"\n{len(cases) - failed}/{len(cases)} passed")
    return 1 if failed else 0


def main(argv=None):
    p = argparse.ArgumentParser(description="Suggest an HTTP status code for an API scenario.")
    p.add_argument("scenario", nargs="*", help="Short description of what happened")
    p.add_argument("--method", help="HTTP method, e.g. POST")
    p.add_argument("--json", action="store_true", help="Print JSON output")
    p.add_argument("--self-test", action="store_true", help="Run built-in tests")
    a = p.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.scenario:
        p.error("scenario text is required (or use --self-test)")
    r = suggest(" ".join(a.scenario), a.method)
    if a.json:
        print(json.dumps(r, indent=2))
        return 0
    if r["code"] is None:
        print(r["why"])
        return 2
    print(f"Recommended: {r['code']} {r['reason_phrase']}")
    print(f"Why: {r['why']}")
    if r["alternatives"]:
        print("Alternatives: " + ", ".join(r["alternatives"]))
    if r["headers"]:
        print("Headers: " + ", ".join(r["headers"]))
    for n in r["notes"]:
        print("Note: " + n)
    return 0


if __name__ == "__main__":
    sys.exit(main())

---
name: openapi-spec-drift-checker
description: So sánh đặc tả OpenAPI YAML/JSON với danh sách các route đã được triển khai và gắn cờ cảnh báo sự lệch chuẩn (drift): thiếu thao tác (operation), thừa route, lệch phương thức (method), và khác biệt về cấu trúc tham số đường dẫn (path parameter). Sử dụng khi đánh giá PR của API, trước khi phát hành, hoặc khi hỏi "mã nguồn của chúng ta có còn khớp với OpenAPI không?". Bao gồm công cụ kiểm tra bằng thư viện chuẩn Python có hỗ trợ --self-test.
---

# Công cụ Kiểm tra Lệch chuẩn Đặc tả OpenAPI

Bạn giúp các đội ngũ phát triển API tìm ra sự lệch chuẩn (drift) giữa tài liệu OpenAPI 3.x và các route mà mã nguồn của họ thực sự phục vụ. Bạn so sánh các đường dẫn (path) và phương thức (method), gắn cờ các thao tác bị thiếu hoặc thừa, đồng thời chỉ ra những điểm không khớp về tham số hoặc phản hồi làm ảnh hưởng đến phía client. Bạn không tự bịa ra các endpoint; bạn chỉ báo cáo những gì dữ liệu đầu vào thể hiện.

## Các tệp trong kỹ năng này

- `scripts/check_drift.py` - so sánh một đoạn đặc tả OpenAPI nhỏ với danh sách route và in ra báo cáo lệch chuẩn (chỉ dùng thư viện chuẩn Python 3)
- `references/openapi-checklist.md` - những điều cần xác minh trong đặc tả trước khi so sánh
- `references/common-drift.md` - các nguyên nhân gây lệch chuẩn thường gặp và cách khắc phục
- `templates/drift-report.md` - cấu trúc báo cáo dùng cho các PR và ghi chú phát hành (release notes)
- `examples/openapi-snippet.yaml` - đoạn mẫu OpenAPI dùng cho bản chạy thử (demo)

## Quy trình làm việc

### 1. Thu thập dữ liệu đầu vào
Yêu cầu cung cấp, hoặc suy luận từ ngữ cảnh:
- Tệp OpenAPI (YAML hoặc JSON) hoặc phần paths được dán trực tiếp
- Các route đã triển khai: danh sách phương thức + đường dẫn từ bộ định tuyến (router) của framework, được trích xuất từ mã nguồn, hoặc từ cấu hình gateway
- Liệu tên tham số đường dẫn có bắt buộc phải khớp chính xác từng chữ hay không (`{id}` so với `{userId}`)

### 2. Chuẩn hóa dữ liệu
Chuyển các phương thức về chữ thường. Cắt bỏ dấu gạch chéo ở cuối đường dẫn (trailing slash). Coi `/users/{id}` và `/users/{userId}` có cùng hình thái đường dẫn trừ khi nhóm phát triển yêu cầu khớp chính xác tên tham số.

### 3. Chạy công cụ kiểm tra
```
python3 scripts/check_drift.py --spec examples/openapi-snippet.yaml --routes examples/routes.txt
python3 scripts/check_drift.py --self-test
```
Nếu danh sách các route chưa có sẵn trong tệp, hãy giúp người dùng trích xuất chúng từ mã nguồn trước.

### 4. Phân loại các phát hiện
- **missing_in_code**: có trong OpenAPI, nhưng chưa được triển khai trong mã nguồn
- **missing_in_spec**: đã triển khai trong mã nguồn, nhưng không có trong OpenAPI
- **method_mismatch**: đường dẫn có tồn tại nhưng khác phương thức HTTP (verb)
- **param_shape_diff**: cùng mẫu đường dẫn, nhưng khác tên tham số (chế độ nghiêm ngặt tùy chọn)

### 5. Trả lời
Trả về bảng tóm tắt số lượng ngắn gọn, sau đó liệt kê từng phát hiện kèm mức độ nghiêm trọng (high/medium/low) và gợi ý cách khắc phục. Sử dụng `templates/drift-report.md` để viết bình luận vào PR.

## Quy tắc

- Ưu tiên cập nhật lại tài liệu theo thực tế khi mã nguồn được viết có chủ đích và bản đặc tả đã lỗi thời; ưu tiên viết bổ sung mã nguồn khi bản đặc tả là hợp đồng giao tiếp đã được công bố cho các client.
- Không bao giờ tuyên bố rằng đã thực hiện đánh giá bảo mật; chỉ báo cáo sự lệch chuẩn về mặt cấu trúc.
- Nếu không thể phân tích cú pháp (parse) tệp OpenAPI, hãy dừng lại và hiển thị lỗi phân tích cú pháp đó.
FILE:references/openapi-checklist.md
# Danh sách kiểm tra OpenAPI trước khi đối chiếu

Trước khi chạy kiểm tra lệch chuẩn, hãy xác nhận bản đặc tả có tính nhất quán:

1. Trường **openapi** là `3.0.x` hoặc `3.1.x`.
2. Phần **paths** có tồn tại và bắt đầu bằng dấu `/`.
3. Mọi thao tác (operation) đều có phương thức HTTP (`get`, `post`, `put`, `patch`, `delete`, `head`, `options`).
4. Các tham số đường dẫn được khai báo trong đường dẫn (`{id}`) cũng xuất hiện dưới mục `parameters` với `in: path` và `required: true`.
5. Các đích tham chiếu `$ref` đều phân giải được (hoặc bạn đang so sánh một tài liệu đã được phân giải/đóng gói hoàn chỉnh).
6. Đã nắm rõ đường dẫn cơ sở (base path) trong URL của servers: nếu `servers[].url` bao gồm `/api/v1`, các route có thể được liệt kê kèm hoặc không kèm tiền tố đó—hãy chọn một quy ước thống nhất và giữ nguyên trong suốt quá trình so sánh.
7. Các thao tác không còn khuyên dùng (deprecated) vẫn phải được liệt kê cho đến khi bị xóa hoàn toàn khỏi mã nguồn; hãy đánh dấu chúng trong báo cáo thay vì bỏ qua.

## Cấu trúc paths tối thiểu

```yaml
paths:
  /pets:
    get:
      summary: List pets
    post:
      summary: Create pet
  /pets/{petId}:
    get:
      parameters:
        - name: petId
          in: path
          required: true
          schema: { type: string }
```
FILE:references/common-drift.md
# Các trường hợp lệch chuẩn OpenAPI thường gặp

| Triệu chứng | Nguyên nhân có thể | Cách khắc phục |
| --- | --- | --- |
| Đặc tả có `GET /users`, mã nguồn không có | Đặc tả được viết trước khi triển khai mã nguồn | Triển khai mã nguồn hoặc xóa khỏi bản đặc tả đã công bố |
| Mã nguồn có `POST /users/{id}/reset`, thiếu trong đặc tả | Bản vá nóng (hotfix) được đưa lên mà không cập nhật tài liệu | Thêm thao tác vào đặc tả; tăng phiên bản phụ (minor) nếu là API công khai |
| Đặc tả là `PUT`, mã nguồn là `PATCH` | Ngữ nghĩa cập nhật một phần đã thay đổi | Đồng bộ lại phương thức; lưu ý thay đổi gây lỗi tương thích (breaking change) nếu client đang gọi PUT |
| `{userId}` so với `{id}` | Framework tự động đặt tên so với đặc tả viết tay | Chuẩn hóa khi so sánh; ghi tài liệu quy tắc đặt tên |
| Chỉ có dấu gạch chéo cuối trong mã nguồn | Bộ định tuyến (router) chấp nhận linh hoạt dấu gạch chéo | Cắt bỏ khi so sánh; chọn dạng chuẩn tắc (canonical) trong đặc tả |
| Đường dẫn cơ sở `/api` chỉ có ở gateway | Mục servers trong đặc tả bỏ qua tiền tố của gateway | Cắt bỏ hoặc thêm cùng một tiền tố ở cả hai phía |
| Webhooks / callbacks chỉ có trong đặc tả | Không phải là các route HTTP thông thường | Loại trừ khỏi việc so sánh route |
| Route tải tệp lên chưa được ghi tài liệu | Bổ sung multipart vào giai đoạn muộn | Ghi tài liệu `multipart/form-data` vào requestBody |

## Hướng dẫn đánh giá mức độ nghiêm trọng

- **High**: các client công khai đã và đang gọi thao tác này; thiếu phương thức hoặc đường dẫn ở một trong hai phía.
- **Medium**: route chỉ dùng nội bộ bị thiếu trong đặc tả; đổi tên tham số nhưng có bí danh (alias).
- **Low**: dấu gạch chéo ở cuối, nhiễu từ các phương thức HEAD/OPTIONS tùy chọn, đã đánh dấu deprecated nhưng vẫn còn tồn tại.
FILE:templates/drift-report.md
# Báo cáo lệch chuẩn OpenAPI

- **Đặc tả (Spec)**: <path or URL>
- **Nguồn trích xuất route**: <router dump / gateway / manual>
- **Thời điểm so sánh**: <ISO timestamp>
- **Tóm tắt**: missing_in_code=<n>, missing_in_spec=<n>, method_mismatch=<n>, param_shape_diff=<n>

## Các phát hiện

| Mức độ nghiêm trọng | Loại | Đặc tả (Spec) | Mã nguồn (Code) | Ghi chú |
| --- | --- | --- | --- | --- |
| high | missing_in_code | `GET /pets/{petId}` | — | Triển khai hoặc gỡ khỏi tài liệu công bố |
| medium | missing_in_spec | — | `POST /pets/{petId}/adopt` | Bổ sung vào tài liệu trước khi phát hành |

## Quyết định

- [ ] Cập nhật OpenAPI
- [ ] Cập nhật mã nguồn
- [ ] Chấp nhận như một ngoại lệ đã biết (nêu rõ lý do)

## Các việc cần theo dõi tiếp

- [ ]
FILE:examples/openapi-snippet.yaml
openapi: 3.0.3
info:
  title: Pets demo
  version: 0.1.0
paths:
  /pets:
    get:
      summary: List pets
      operationId: listPets
    post:
      summary: Create pet
      operationId: createPet
  /pets/{petId}:
    get:
      summary: Get pet by id
      operationId: getPet
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: string
    delete:
      summary: Delete pet
      operationId: deletePet
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: string
  /health:
    get:
      summary: Health check
      operationId: health
FILE:scripts/check_drift.py
#!/usr/bin/env python3
"""Compare OpenAPI paths to an implemented route list.

Usage:
    python3 check_drift.py --spec openapi.yaml --routes routes.txt
    python3 check_drift.py --spec openapi.yaml --route 'GET /pets' --route 'POST /pets'
    python3 check_drift.py --self-test

Route file format: one "METHOD /path" per line. Comments (#) and blank lines ignored.
Python 3 standard library only.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from typing import Dict, List, Set, Tuple

try:
    import yaml  # type: ignore
except ImportError:
    yaml = None

PathKey = str  # normalized path template
Method = str


def normalize_path(path: str) -> str:
    path = path.strip()
    if not path.startswith("/"):
        path = "/" + path
    if len(path) > 1 and path.endswith("/"):
        path = path.rstrip("/")
    # unify parameter names to {}
    return re.sub(r"\{[^}]+\}", "{}", path)


def normalize_method(m: str) -> str:
    return m.strip().upper()


def parse_routes(lines: List[str]) -> Dict[PathKey, Set[Method]]:
    out: Dict[PathKey, Set[Method]] = {}
    for raw in lines:
        line = raw.split("#", 1)[0].strip()
        if not line:
            continue
        parts = line.split()
        if len(parts) < 2:
            raise ValueError(f"Bad route line: {raw!r}")
        method, path = normalize_method(parts[0]), normalize_path(parts[1])
        out.setdefault(path, set()).add(method)
    return out


def _parse_openapi_json(text: str) -> dict:
    return json.loads(text)


def _parse_openapi_yaml_simple(text: str) -> dict:
    """Minimal YAML subset parser for simple OpenAPI path maps when PyYAML is absent.

    Supports the examples shipped with this skill (no anchors, no multiline).
    Prefer PyYAML when installed.
    """
    # Very small fallback: extract path keys and methods via regex for our demos.
    paths: Dict[str, dict] = {}
    current_path = None
    for raw in text.splitlines():
        if raw.startswith("  /") and raw.rstrip().endswith(":"):
            current_path = raw.strip()[:-1]
            paths[current_path] = {}
            continue
        if current_path and re.match(r"^    (get|post|put|patch|delete|head|options):", raw):
            method = raw.strip().split(":", 1)[0]
            paths[current_path][method] = {}
    if not paths:
        raise ValueError("Could not parse OpenAPI YAML without PyYAML; install pyyaml or pass JSON.")
    return {"paths": paths}


def load_spec(path: str) -> Dict[PathKey, Set[Method]]:
    text = open(path, encoding="utf-8").read()
    if path.endswith(".json"):
        data = _parse_openapi_json(text)
    else:
        if yaml is not None:
            data = yaml.safe_load(text)
        else:
            # try JSON first, then simple YAML
            try:
                data = _parse_openapi_json(text)
            except json.JSONDecodeError:
                data = _parse_openapi_yaml_simple(text)
    paths = data.get("paths") or {}
    out: Dict[PathKey, Set[Method]] = {}
    http = {"get", "post", "put", "patch", "delete", "head", "options", "trace"}
    for p, item in paths.items():
        if not isinstance(item, dict):
            continue
        methods = {normalize_method(m) for m in item if m.lower() in http}
        if methods:
            out[normalize_path(p)] = methods
    return out


def compare(spec: Dict[PathKey, Set[Method]], code: Dict[PathKey, Set[Method]]) -> List[dict]:
    findings = []
    all_paths = set(spec) | set(code)
    for p in sorted(all_paths):
        s = spec.get(p, set())
        c = code.get(p, set())
        if s and not c:
            for m in sorted(s):
                findings.append({"kind": "missing_in_code", "severity": "high", "method": m, "path": p})
        elif c and not s:
            for m in sorted(c):
                findings.append({"kind": "missing_in_spec", "severity": "medium", "method": m, "path": p})
        else:
            only_spec = s - c
            only_code = c - s
            for m in sorted(only_spec):
                findings.append({"kind": "method_mismatch", "severity": "high", "method": m, "path": p, "side": "spec_only"})
            for m in sorted(only_code):
                findings.append({"kind": "method_mismatch", "severity": "high", "method": m, "path": p, "side": "code_only"})
    return findings


def format_report(findings: List[dict]) -> str:
    counts: Dict[str, int] = {}
    for f in findings:
        counts[f["kind"]] = counts.get(f["kind"], 0) + 1
    lines = ["Drift summary: " + ", ".join(f"{k}={v}" for k, v in sorted(counts.items()))]
    if not findings:
        lines.append("No drift found.")
        return "\n".join(lines)
    for f in findings:
        side = f.get("side", "")
        extra = f" ({side})" if side else ""
        lines.append(f"- [{f['severity']}] {f['kind']}: {f['method']} {f['path']}{extra}")
    return "\n".join(lines)


def self_test() -> int:
    spec = {
        normalize_path("/pets"): {"GET", "POST"},
        normalize_path("/pets/{petId}"): {"GET", "DELETE"},
        normalize_path("/health"): {"GET"},
    }
    code = {
        normalize_path("/pets"): {"GET", "POST"},
        normalize_path("/pets/{id}"): {"GET"},  # same shape, missing DELETE
        normalize_path("/pets/{id}/adopt"): {"POST"},  # extra
    }
    findings = compare(spec, code)
    kinds = sorted(f["kind"] + ":" + f["method"] + ":" + f["path"] for f in findings)

    cases = [
        ("missing delete on pet", any(f["kind"] == "method_mismatch" and f["method"] == "DELETE" for f in findings), True),
        ("extra adopt route", any(f["kind"] == "missing_in_spec" and f["path"].endswith("/adopt") for f in findings), True),
        ("health missing in code", any(f["kind"] == "missing_in_code" and f["path"] == "/health" for f in findings), True),
        ("list pets matched", not any(f["path"] == "/pets" and f["kind"] == "missing_in_code" for f in findings), True),
        ("normalize params", normalize_path("/pets/{petId}") == normalize_path("/pets/{id}"), True),
        ("normalize slash", normalize_path("/pets/") == "/pets", True),
        ("parse routes", parse_routes(["GET /pets", "POST /pets # create"]) == {"/pets": {"GET", "POST"}}, True),
        ("empty compare", compare({"/x": {"GET"}}, {"/x": {"GET"}}) == [], True),
    ]

    # parse simple yaml fallback
    sample = """openapi: 3.0.3\npaths:\n  /pets:\n    get:\n      summary: x\n    post:\n      summary: y\n"""
    parsed = _parse_openapi_yaml_simple(sample)
    cases.append(("yaml fallback paths", "get" in parsed["paths"]["/pets"] and "post" in parsed["paths"]["/pets"], True))

    failed = 0
    for name, got, expected in cases:
        ok = got == expected
        failed += not ok
        print(f"{'PASS' if ok else 'FAIL'}  {name}: got={got!r} expected={expected!r}")
    # also assert finding count sanity
    ok = len(findings) >= 3
    failed += not ok
    print(f"{'PASS' if ok else 'FAIL'}  findings_count>={3}: got={len(findings)}")
    print(f"\n{len(cases)+1 - failed}/{len(cases)+1} passed")
    return 1 if failed else 0


def main(argv=None) -> int:
    p = argparse.ArgumentParser(description="Compare OpenAPI paths to implemented routes.")
    p.add_argument("--spec", help="OpenAPI YAML or JSON file")
    p.add_argument("--routes", help="File with METHOD /path lines")
    p.add_argument("--route", action="append", default=[], help="Single METHOD /path (repeatable)")
    p.add_argument("--json", action="store_true", help="Print findings as JSON")
    p.add_argument("--self-test", action="store_true")
    a = p.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.spec:
        p.error("--spec is required (or use --self-test)")
    route_lines: List[str] = list(a.route)
    if a.routes:
        route_lines.extend(open(a.routes, encoding="utf-8").read().splitlines())
    if not route_lines:
        p.error("provide --routes and/or --route")
    spec = load_spec(a.spec)
    code = parse_routes(route_lines)
    findings = compare(spec, code)
    if a.json:
        print(json.dumps(findings, indent=2))
    else:
        print(format_report(findings))
    return 0 if not findings else 2


if __name__ == "__main__":
    sys.exit(main())

---
name: jwt-token-inspector
description: Giải mã một chuỗi JWT mà không mặc định tin tưởng nó, đồng thời rà soát lỗi (lint) phần header và các thông tin xác nhận (claims): thuật toán alg none, khóa jku/x5u từ xa, thiếu hoặc hết hạn exp, lệch đồng hồ nbf/iat, dấu thời gian tính bằng mili-giây, thời hạn sống quá dài, sai lệch iss/aud, dữ liệu nhạy cảm nằm trong payload, và kiểm tra chữ ký HMAC bằng khóa bí mật lấy từ biến môi trường. Sử dụng khi thao tác đăng nhập hoặc lệnh gọi API thất bại với mã lỗi 401, hoặc khi rà soát cấu hình token. Bao gồm công cụ kiểm tra bằng thư viện chuẩn Python có hỗ trợ cờ --self-test.
---

# Công cụ Kiểm tra JWT Token

Bạn giúp các lập trình viên tìm hiểu và gỡ lỗi JSON Web Tokens (JWT) một cách an toàn. Bạn giải mã phần header và payload, chuyển đổi các dấu thời gian sang định dạng giờ UTC dễ đọc, giải thích ý nghĩa của từng claim, và gắn cờ cảnh báo những thiết lập khiến token trở nên mất an toàn, không thể sử dụng hoặc dễ gây lỗi trên môi trường thực tế (production). Bạn luôn coi mọi token là không đáng tin cậy: giải mã (decoding) không phải là xác minh chữ ký (verification), và bạn luôn nêu rõ điều đó.

## Các tệp trong kỹ năng này

- `scripts/jwt_inspect.py` - giải mã một JWS compact token, rà soát lỗi trong header và claims, tùy chọn xác minh chữ ký HS256/HS384/HS512 bằng khóa bí mật, xuất kết quả ra markdown hoặc JSON (chỉ sử dụng thư viện chuẩn Python 3)
- `references/claims-and-validation.md` - các claim đã đăng ký chuẩn, những gì bộ xác minh (verifier) bắt buộc phải kiểm tra và theo thứ tự nào
- `references/common-jwt-pitfalls.md` - những sai lầm đứng sau hầu hết các lỗi và sự cố bảo mật liên quan đến JWT, kèm theo cách khắc phục
- `templates/jwt-review.md` - mẫu báo cáo ngắn gọn cho phiếu báo lỗi (bug ticket), đánh giá PR hoặc rà soát bảo mật
- `examples/sample-tokens.md` - ba token mẫu minh họa (thời hạn quá dài, alg none, khóa jku từ xa kèm thời gian hết hạn exp tính bằng mili-giây) và các phát hiện kỳ vọng

## Quy trình thực hiện

### 1. Xử lý token an toàn
Yêu cầu người dùng cung cấp token từ môi trường thử nghiệm (test) hoặc tiền triển khai (staging). Nếu người dùng dán một token đang hoạt động trên môi trường thực tế (production), hãy cảnh báo họ rằng token đó vẫn cấp quyền truy cập cho đến khi hết hạn và đề nghị họ xoay vòng (rotate)/thu hồi nó sau phiên làm việc. Không bao giờ lặp lại toàn bộ chuỗi token hoặc phần chữ ký trong câu trả lời của bạn.

### 2. Chạy công cụ kiểm tra
```
python3 scripts/jwt_inspect.py "<token>"
python3 scripts/jwt_inspect.py "<token>" --now 2026-10-19T09:00:00Z --leeway 60
python3 scripts/jwt_inspect.py "<token>" --expect-iss https://auth.example.com --expect-aud api://orders
JWT_SECRET=... python3 scripts/jwt_inspect.py "<token>" --secret-env JWT_SECRET
python3 scripts/jwt_inspect.py --self-test
```
Tiền tố `Bearer ` sẽ tự động được lược bỏ. Sử dụng `-` để đọc token từ luồng đầu vào chuẩn (stdin). Mã thoát (exit code) bằng 1 có nghĩa là phát hiện ít nhất một vấn đề mức độ cao (`--strict`: bất kỳ phát hiện nào); mã thoát bằng 2 có nghĩa là không thể giải mã được token.

### 3. Giải thích kết quả
- Hiển thị phần header và các claim đã giải mã cùng thời gian exp/nbf/iat theo cả giờ UTC và múi giờ của người dùng.
- Nhóm các phát hiện theo mức độ nghiêm trọng: **cao (high)** (mất an toàn hoặc bị từ chối: alg none, chữ ký trống, đã hết hạn, chưa đến thời điểm có hiệu lực, sai lệch iss/aud, khóa nhúng trực tiếp hoặc tải từ xa, chữ ký sai, dấu thời gian tính bằng mili-giây), **trung bình (medium)** (không có exp, thời hạn vượt quá chính sách, chứa claim nhạy cảm, khóa bí mật HMAC yếu, iat nằm ở tương lai), **thấp (low)** (thiếu iss, aud, sub hoặc kid).
- Đối với lỗi 401, hãy đối chiếu phát hiện với triệu chứng thực tế bằng cách tham khảo `references/claims-and-validation.md`: lệch đồng hồ hệ thống, sai đối tượng thụ hưởng (audience), sai bên phát hành (issuer) hoặc sai khóa xác minh là những nguyên nhân phổ biến nhất.

### 4. Đề xuất biện pháp khắc phục
Sử dụng `references/common-jwt-pitfalls.md`: ghim cố định danh sách thuật toán cho phép trên bộ xác minh, giữ thời hạn của access token ngắn (5-15 phút) kết hợp với refresh token, chuyển dữ liệu cá nhân ra khỏi payload, cho phép khoảng dung sai thời gian (leeway) từ 30-60 giây, và chỉ tải khóa từ một URL JWKS đã được cấu hình cố định.

### 5. Báo cáo
Điền vào mẫu `templates/jwt-review.md` với dấu vân tay (fingerprint) của token (tuyệt đối không ghi nguyên chuỗi token), các phát hiện, nguyên nhân gốc rễ và biện pháp khắc phục đã thống nhất.

## Quy tắc

- Giải mã không phải là xác minh chữ ký. Không bao giờ khẳng định một token là hợp lệ trừ khi chữ ký của nó đã được kiểm tra bằng đúng khóa tương ứng.
- Không bao giờ in ra hoặc lưu trữ toàn bộ chuỗi token, chữ ký hoặc khóa bí mật. Hãy truyền khóa bí mật thông qua biến môi trường chứ không truyền trực tiếp trên dòng lệnh.
- Không hỗ trợ làm giả (forge), phát lại (replay) hoặc chỉnh sửa trái phép (tamper) các token cho những hệ thống mà người dùng không sở hữu.
- Các chữ ký RS/ES/PS/EdDSA cần có khóa công khai (public key) và thư viện JOSE chuyên dụng; kịch bản đi kèm chỉ xác minh các thuật toán họ HMAC.
FILE:references/claims-and-validation.md
# Các Claim và Thứ tự Xác thực

## Các claim chuẩn đã đăng ký (RFC 7519)
| Claim | Ý nghĩa | Kiểu dữ liệu | Ghi chú |
|---|---|---|---|
| iss | Bên phát hành (Issuer) | chuỗi/URL | Ghim cố định trên bộ xác minh; mỗi miền tin cậy một bên phát hành |
| sub | Chủ thể (ID người dùng hoặc dịch vụ) | chuỗi | ID ổn định, không dùng địa chỉ email vốn có thể thay đổi |
| aud | Đối tượng đích (Audience) | chuỗi hoặc mảng | Dịch vụ API phải tìm thấy ID của chính mình trong trường này |
| exp | Thời điểm hết hạn | NumericDate (giây) | Bắt buộc phải có đối với access token |
| nbf | Không có hiệu lực trước thời điểm | NumericDate | Token sẽ bị từ chối cho đến khi chạm mốc thời gian này |
| iat | Thời điểm phát hành | NumericDate | Dùng để kiểm tra vòng đời và độ mới của token |
| jti | Định danh token (Token ID) | chuỗi | Hỗ trợ danh sách thu hồi (revocation lists) và phát hiện tấn công phát lại (replay) |

NumericDate là số giây tính từ mốc 1970-01-01T00:00:00Z. Một giá trị gồm 13 chữ số là mili-giây và sẽ bị hiểu nhầm thành một ngày cách hiện tại hàng chục nghìn năm trong tương lai.

## Các tham số trong Header
- `alg` - thuật toán ký. Bộ xác minh mới là bên quyết định những giá trị nào được phép sử dụng; bản thân token không bao giờ được quyền quyết định.
- `kid` - định danh khóa (key ID), được dùng để chọn đúng khóa từ tập JWKS của bên phát hành trong quá trình xoay vòng khóa.
- `typ` - thường là `JWT` hoặc `at+jwt` (hồ sơ access token theo chuẩn RFC 9068).
- `jku`, `x5u`, `jwk` - trỏ tới hoặc nhúng trực tiếp các khóa. Hãy bỏ qua chúng trừ khi chúng khớp hoàn toàn với một nguồn đáng tin cậy đã được ghim cố định.

## Những gì bộ xác minh bắt buộc phải kiểm tra, theo đúng thứ tự
1. Token có đúng ba phân đoạn và giải mã ra các đối tượng JSON hợp lệ.
2. `alg` nằm trong danh sách cho phép (allow-list) của bộ xác minh (ví dụ: chỉ chấp nhận RS256). Từ chối thẳng `none`.
3. Chữ ký được xác minh thành công bằng khóa được chọn qua `kid` từ một nguồn JWKS đáng tin cậy, tuyệt đối không lấy khóa trực tiếp từ bên trong token.
4. `exp` nằm ở tương lai và `nbf` nằm ở quá khứ, cả hai đều được áp dụng một khoảng dung sai nhỏ (30-60 giây).
5. `iss` bằng đúng định danh của bên phát hành kỳ vọng.
6. `aud` có chứa ID của dịch vụ hiện tại.
7. Các quy tắc nghiệp vụ của ứng dụng: phạm vi quyền (scopes), vai trò (roles), định danh thuê bao (tenant), và `jti` chưa bị thu hồi.

## Đối chiếu triệu chứng lỗi 401 với nguyên nhân
| Triệu chứng | Nguyên nhân khả dĩ | Điểm cần kiểm tra |
|---|---|---|
| Chạy được ở máy cục bộ (local), lỗi trên prod | Lệch đồng hồ hệ thống hoặc URL của bên phát hành khác nhau | So sánh iat/nbf với giờ máy chủ, kiểm tra trường iss |
| Lỗi ngay lập tức sau khi vừa đăng nhập | nbf hoặc iat nằm ở tương lai | Đồng bộ thời gian trên các máy chủ (NTP) |
| Chỉ bị lỗi ở một API duy nhất | Sai đối tượng đích (audience) | Danh sách aud |
| Bị lỗi sau khi xoay vòng khóa (key rotation) | Không nhận diện được kid mới hoặc JWKS bị lưu đệm (cache) quá lâu | Đối chiếu kid với JWKS, kiểm tra thời gian sống (TTL) của bộ nhớ đệm |
| Không bao giờ hết hạn | Thiếu trường exp hoặc exp đang tính bằng mili-giây | Giá trị của trường exp |
FILE:references/common-jwt-pitfalls.md
# Những Sai lầm Phổ biến khi Sử dụng JWT

1. **Chấp nhận `alg: none`.** Các token không có chữ ký có thể bị làm giả dễ dàng. Cách khắc phục: truyền một danh sách thuật toán cho phép (allow-list) tường minh vào hàm xác minh.
2. **Nhầm lẫn thuật toán (RS256 so với HS256).** Nếu bộ xác minh chấp nhận cả hai, kẻ tấn công có thể ký bằng thuật toán HMAC với việc dùng chính khóa công khai (public key) làm khóa bí mật (secret). Cách khắc phục: mỗi khóa chỉ gắn với một họ thuật toán duy nhất.
3. **Tin tưởng khóa lấy từ bên trong token.** Các trường `jku`, `x5u` hoặc `jwk` nhúng sẵn cho phép người gửi tự ý chọn khóa xác minh. Cách khắc phục: chỉ tải khóa từ một URL JWKS đã được cấu hình cố định từ trước.
4. **Khóa bí mật HMAC yếu.** Các khóa bí mật ngắn hoặc nằm trong từ điển có thể bị dò quét vét cạn (brute-force) ngoại tuyến chỉ từ một token thu được. Cách khắc phục: dùng ít nhất 32 byte ngẫu nhiên cho HS256 (48 byte cho HS384, 64 byte cho HS512) và lưu trữ trong trình quản lý bí mật (secret manager).
5. **Access token có thời hạn quá dài.** Một token bị lộ sẽ tiếp tục có hiệu lực cho đến tận thời điểm exp. Cách khắc phục: đặt thời hạn access token từ 5-15 phút kết hợp với refresh token có xoay vòng; thu hồi theo `jti` nếu cần.
6. **Chứa dữ liệu cá nhân trong payload.** Base64url chỉ là mã hóa định dạng (encoding) chứ không phải mật mã hóa (encryption); bất kỳ ai cầm token đều đọc được nội dung. Cách khắc phục: chỉ lưu các ID và phạm vi quyền (scopes), hoặc sử dụng JWE.
7. **Dùng mili-giây thay vì giây.** Rất hay gặp khi dùng hàm `Date.now()` trong JavaScript. Cách khắc phục: sử dụng `Math.floor(Date.now() / 1000)`.
8. **Không cấu hình khoảng dung sai thời gian (leeway).** Sự chênh lệch nhỏ giữa đồng hồ các máy chủ sẽ gây ra lỗi 401 ngẫu nhiên. Cách khắc phục: cấu hình dung sai 30-60 giây và bật đồng bộ NTP trên tất cả các máy chủ.
9. **Bỏ qua bước kiểm tra aud/iss.** Token cấp cho dịch vụ này có thể bị đem phát lại (replay) để truy cập trái phép vào dịch vụ khác. Cách khắc phục: luôn xác thực cả hai trường này.
10. **Đặt token trên URL hoặc trong nhật ký (logs).** Chúng sẽ bị rò rỉ qua trường Referer, máy chủ proxy và hệ thống tìm kiếm nhật ký. Cách khắc phục: gửi token trong trường header Authorization và che (redact) token khi ghi nhật ký.
FILE:templates/jwt-review.md
# Báo cáo Rà soát JWT - <tên dịch vụ hoặc mã phiếu>

**Dấu vân tay token:** sha256 <12 ký tự hex đầu tiên>  **Môi trường:** <dev / staging / prod>  **Thời điểm kiểm tra:** <giờ UTC>
**Bên phát hành (Issuer):** <iss>  **Đối tượng đích (Audience):** <aud>  **Thuật toán:** <alg>  **Thời hạn sống:** <exp - iat>

## Các phát hiện
| Mức độ nghiêm trọng | Mã phát hiện | Chi tiết | Cách khắc phục |
|---|---|---|---|
| | | | |

## Nguyên nhân gốc rễ
<một hoặc hai câu liên kết phát hiện trên với triệu chứng lỗi được báo cáo>

## Các thay đổi đã thống nhất
- [ ] Bộ xác minh (Verifier): <danh sách cho phép allow-list, dung sai thời gian leeway, kiểm tra iss/aud>
- [ ] Bên phát hành (Issuer): <thời hạn sống, các claim, kích thước khóa, kid>
- [ ] Xoay vòng token hoặc khóa bí mật bị lộ: <có/không, người phụ trách>

## Ghi chú
Được giải mã bằng scripts/jwt_inspect.py. Bản thân chuỗi token không được lưu lại trong báo cáo này.
FILE:examples/sample-tokens.md
# Các Token Mẫu (chỉ dùng để minh họa, không thuộc hệ thống thực tế)

Chạy từng mẫu bằng lệnh:
```
python3 scripts/jwt_inspect.py "<token>" --now 2026-10-19T09:00:00Z --expect-aud api://orders
```

## 1. Token khách hàng có thời hạn sống dài (HS256, khóa bí mật minh họa "dev-secret")
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguc2hvcGZyb250LmV4YW1wbGUiLCJzdWIiOiJjdXN0Xzg4NDEiLCJhdWQiOlsiYXBpOi8vb3JkZXJzIiwiYXBpOi8vcHJvZmlsZSJdLCJpYXQiOjE3OTIzOTUwMDAsImV4cCI6MTc5Mjk5OTgwMCwiZW1haWwiOiJtaW5hQGV4YW1wbGUuY29tIiwicm9sZXMiOlsiY3VzdG9tZXIiXSwiY2FyZF9sYXN0NCI6IjQyNDIifQ.xupeoN2LYDYe-FKD_4qOh7KCw6G68Zi1pCms7dtUGh0
```
Kỳ vọng: mã thoát 0; mức trung bình `lifetime_long` (7.0 ngày vượt quá chính sách 1.0 ngày), mức trung bình `sensitive_claim` (card_last4). Khi đặt biến môi trường cho `--secret-env` là "dev-secret": xác minh chữ ký thành công, kèm theo cảnh báo mức trung bình `weak_secret` (10 byte).

## 2. Token quản trị viên không có chữ ký (alg none)
```
eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJpc3MiOiJodHRwczovL2F1dGguc2hvcGZyb250LmV4YW1wbGUiLCJzdWIiOiJhZG1pbiIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTc5MjM5NTAwMH0.
```
Kỳ vọng: mã thoát 1; mức cao `alg_none`, mức cao `aud_mismatch` (không có aud trong khi yêu cầu `api://orders`), mức trung bình `exp_missing`.

## 3. URL khóa từ xa và thời gian hết hạn tính bằng mili-giây (RS256)
```
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImprdSI6Imh0dHBzOi8va2V5cy5hdHRhY2tlci5leGFtcGxlL2p3a3MuanNvbiJ9.eyJpc3MiOiJodHRwczovL2F1dGguc2hvcGZyb250LmV4YW1wbGUiLCJzdWIiOiJzdmMtcmVwb3J0cyIsImF1ZCI6ImFwaTovL29yZGVycyIsImlhdCI6MTc5MjM5NTAwMCwiZXhwIjoxNzkyMzk4NjAwMDAwfQ.bm90LWEtcmVhbC1zaWduYXR1cmUtanVzdC1hLWRlbW8
```
Kỳ vọng: mã thoát 1; mức cao `exp_milliseconds`, mức cao `header_jku`, mức thấp `kid_missing`.
FILE:scripts/jwt_inspect.py
#!/usr/bin/env python3
"""JWT token inspector and claim linter (Python 3 standard library only).

Decodes a JSON Web Token (JWS compact form: header.payload.signature) WITHOUT trusting it,
prints the header and claims with human-readable times, and flags risky or broken settings.
Optionally verifies HS256/HS384/HS512 signatures when you pass the shared secret.

Usage:
  python3 jwt_inspect.py <token>                     # or "-" to read the token from stdin
  python3 jwt_inspect.py <token> --now 2026-10-19T09:00:00Z --leeway 60
  python3 jwt_inspect.py <token> --expect-iss https://auth.example.com --expect-aud api://orders
  python3 jwt_inspect.py <token> --secret-env JWT_SECRET   # verify HS* with a secret from an env var
  python3 jwt_inspect.py <token> --max-lifetime 3600 --json
  python3 jwt_inspect.py --self-test

Severity: high (token unsafe or unusable), medium (likely bug or weak policy), low (hygiene).
Exit code: 0 no high findings, 1 at least one high finding (or --strict and any finding), 2 bad input.
The signature itself is never printed; only its length and a short SHA-256 fingerprint of the token.
"""
import argparse
import base64
import datetime as dt
import hashlib
import hmac
import json
import os
import re
import sys

HS_ALGS = {"HS256": hashlib.sha256, "HS384": hashlib.sha384, "HS512": hashlib.sha512}
MIN_HS_SECRET = {"HS256": 32, "HS384": 48, "HS512": 64}
KNOWN_ALGS = set(HS_ALGS) | {"RS256", "RS384", "RS512", "PS256", "PS384", "PS512",
                             "ES256", "ES384", "ES512", "EdDSA"}
SENSITIVE = re.compile(r"(pass(word)?|pwd|secret|ssn|social|credit|card|cvv|iban|private|api_?key|refresh_?token)", re.I)
TIME_CLAIMS = ("exp", "nbf", "iat")


class TokenError(ValueError):
    pass


def b64url_decode(part, what):
    if not re.fullmatch(r"[A-Za-z0-9_-]*", part):
        raise TokenError(f"{what} is not base64url (found characters outside A-Z a-z 0-9 - _ or '=' padding)")
    try:
        return base64.urlsafe_b64decode(part + "=" * (-len(part) % 4))
    except (ValueError, TypeError) as e:
        raise TokenError(f"{what} could not be base64url-decoded: {e}")


def b64url_encode(raw):
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")


def decode(token):
    token = token.strip()
    if token.lower().startswith("bearer "):
        token = token[7:].strip()
    parts = token.split(".")
    if len(parts) == 5:
        raise TokenError("5 segments: this is an encrypted JWE, not a signed JWS; it cannot be inspected without the key")
    if len(parts) != 3:
        raise TokenError(f"expected 3 dot-separated segments, found {len(parts)}")
    out = {}
    for name, part in (("header", parts[0]), ("payload", parts[1])):
        raw = b64url_decode(part, name)
        try:
            obj = json.loads(raw.decode("utf-8"))
        except (UnicodeDecodeError, ValueError):
            raise TokenError(f"{name} is not valid UTF-8 JSON")
        if not isinstance(obj, dict):
            raise TokenError(f"{name} must be a JSON object")
        out[name] = obj
    out["signature"] = b64url_decode(parts[2], "signature")
    out["signing_input"] = (parts[0] + "." + parts[1]).encode("ascii")
    out["fingerprint"] = hashlib.sha256(token.encode("utf-8")).hexdigest()[:12]
    return out


def parse_now(value):
    if value is None:
        return int(dt.datetime.now(dt.timezone.utc).timestamp())
    if re.fullmatch(r"\d+", value):
        return int(value)
    t = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
    if t.tzinfo is None:
        t = t.replace(tzinfo=dt.timezone.utc)
    return int(t.timestamp())


def iso(ts):
    try:
        return dt.datetime.fromtimestamp(ts, dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    except (OverflowError, OSError, ValueError, TypeError):
        return "invalid"


def human_delta(seconds):
    s = abs(int(seconds))
    for unit, size in (("d", 86400), ("h", 3600), ("m", 60)):
        if s >= size:
            return f"{s / size:.1f}{unit}"
    return f"{s}s"


def verify_hs(tok, secret):
    alg = tok["header"].get("alg")
    fn = HS_ALGS.get(alg)
    if fn is None:
        return None
    mac = hmac.new(secret.encode("utf-8"), tok["signing_input"], fn).digest()
    return hmac.compare_digest(mac, tok["signature"])


def inspect(token, now=None, leeway=0, expect_iss=None, expect_aud=None, max_lifetime=86400, secret=None):
    tok = decode(token)
    h, p = tok["header"], tok["payload"]
    findings = []

    def add(sev, code, msg):
        findings.append({"severity": sev, "code": code, "message": msg})

    alg = h.get("alg")
    if alg is None:
        add("high", "alg_missing", "header has no 'alg'; libraries may reject it or guess")
    elif str(alg).lower() == "none":
        add("high", "alg_none", "alg is 'none': the token is unsigned and anyone can forge it")
        if tok["signature"]:
            add("medium", "none_with_signature", "alg 'none' but a signature segment is present")
    elif alg not in KNOWN_ALGS:
        add("medium", "alg_unknown", f"unusual alg '{alg}'")
    if alg and str(alg).lower() != "none" and not tok["signature"]:
        add("high", "signature_empty", "signature segment is empty although alg requires one")
    for key in ("jku", "x5u"):
        if key in h:
            add("high", f"header_{key}", f"header '{key}' points to a remote key URL ({h[key]}); never fetch keys from a URL inside the token")
    if "jwk" in h:
        add("high", "header_jwk", "header embeds its own 'jwk'; a verifier that trusts it accepts attacker keys")
    if "crit" in h:
        add("medium", "header_crit", f"'crit' lists extensions {h['crit']}; verifiers must understand them or reject the token")
    if alg in KNOWN_ALGS and alg not in HS_ALGS and "kid" not in h:
        add("low", "kid_missing", "asymmetric alg without 'kid'; key rotation will be painful")

    now = parse_now(now) if not isinstance(now, int) else now
    times = {}
    for c in TIME_CLAIMS:
        if c in p:
            v = p[c]
            if isinstance(v, bool) or not isinstance(v, (int, float)):
                add("high", f"{c}_not_numeric", f"'{c}' must be NumericDate seconds, got {v!r}")
            elif v > 10**11:
                add("high", f"{c}_milliseconds", f"'{c}'={v} looks like milliseconds; JWT uses seconds")
            else:
                times[c] = int(v)
    if "exp" not in p:
        add("medium", "exp_missing", "no 'exp': the token never expires")
    elif "exp" in times and times["exp"] + leeway < now:
        add("high", "expired", f"expired at {iso(times['exp'])} ({human_delta(now - times['exp'])} ago)")
    if "nbf" in times and times["nbf"] - leeway > now:
        add("high", "not_yet_valid", f"not valid before {iso(times['nbf'])} ({human_delta(times['nbf'] - now)} from now)")
    if "iat" in times and times["iat"] - leeway > now:
        add("medium", "iat_future", f"issued in the future ({iso(times['iat'])}); check clock skew")
    if "exp" in times and "iat" in times:
        life = times["exp"] - times["iat"]
        if life <= 0:
            add("high", "exp_before_iat", "exp is not after iat")
        elif max_lifetime and life > max_lifetime:
            add("medium", "lifetime_long", f"lifetime {human_delta(life)} exceeds policy {human_delta(max_lifetime)}")
    if "iss" not in p:
        add("low", "iss_missing", "no 'iss'; verifiers cannot pin the issuer")
    elif expect_iss and p["iss"] != expect_iss:
        add("high", "iss_mismatch", f"iss '{p['iss']}' != expected '{expect_iss}'")
    aud = p.get("aud")
    auds = aud if isinstance(aud, list) else ([aud] if aud is not None else [])
    if aud is None and expect_aud:
        add("high", "aud_mismatch", f"no 'aud' claim but '{expect_aud}' is required")
    elif aud is None:
        add("low", "aud_missing", "no 'aud'; the token could be replayed against another service")
    elif expect_aud and expect_aud not in auds:
        add("high", "aud_mismatch", f"aud {auds} does not contain expected '{expect_aud}'")
    if "sub" not in p:
        add("low", "sub_missing", "no 'sub'; who is this token about?")
    for k in p:
        if SENSITIVE.search(k):
            add("medium", "sensitive_claim", f"claim '{k}' looks sensitive; JWT payloads are only encoded, not encrypted")

    verified = None
    if secret is not None:
        if alg not in HS_ALGS:
            add("low", "verify_skipped", f"--secret only verifies HS256/384/512; alg is {alg}")
        else:
            verified = verify_hs(tok, secret)
            if not verified:
                add("high", "bad_signature", "HMAC signature does NOT match the given secret")
            if len(secret.encode("utf-8")) < MIN_HS_SECRET[alg]:
                add("medium", "weak_secret", f"{alg} secret is {len(secret.encode('utf-8'))} bytes; use at least {MIN_HS_SECRET[alg]} random bytes")

    order = {"high": 0, "medium": 1, "low": 2}
    findings.sort(key=lambda f: (order[f["severity"]], f["code"]))
    return {
        "fingerprint": tok["fingerprint"],
        "header": h,
        "payload": p,
        "times": {c: iso(v) for c, v in times.items()},
        "now": iso(now),
        "signature_bytes": len(tok["signature"]),
        "signature_verified": verified,
        "findings": findings,
    }


def to_markdown(r):
    lines = [f"# JWT inspection (sha256 {r['fingerprint']})", "",
             f"Checked at {r['now']}. Signature: {r['signature_bytes']} bytes"
             + ("" if r["signature_verified"] is None else (", verified OK" if r["signature_verified"] else ", NOT verified")), "",
             "## Header", "```json", json.dumps(r["header"], indent=2, ensure_ascii=False), "```", "",
             "## Claims", "```json", json.dumps(r["payload"], indent=2, ensure_ascii=False), "```", ""]
    if r["times"]:
        lines += ["| Claim | UTC |", "|---|---|"] + [f"| {k} | {v} |" for k, v in r["times"].items()] + [""]
    lines += ["## Findings"]
    if not r["findings"]:
        lines.append("No findings.")
    else:
        lines += ["| Severity | Code | Detail |", "|---|---|---|"]
        lines += [f"| {f['severity']} | {f['code']} | {f['message']} |" for f in r["findings"]]
    return "\n".join(lines)


def make_token(header, payload, secret=None, signature=b""):
    si = b64url_encode(json.dumps(header, separators=(",", ":")).encode()) + "." + \
         b64url_encode(json.dumps(payload, separators=(",", ":")).encode())
    if secret is not None:
        signature = hmac.new(secret.encode(), si.encode(), HS_ALGS[header["alg"]]).digest()
    return si + "." + b64url_encode(signature)


def self_test():
    now = 1760860800  # 2025-10-19T08:00:00Z
    strong = "k" * 40
    good_claims = {"iss": "https://auth.example.com", "sub": "user-42", "aud": "api://orders",
                   "iat": now - 60, "exp": now + 840}
    good = make_token({"alg": "HS256", "typ": "JWT"}, good_claims, strong)
    codes = lambda r: {f["code"] for f in r["findings"]}
    cases = []

    def check(name, cond):
        cases.append((name, bool(cond)))

    r = inspect(good, now=now, secret=strong, expect_iss="https://auth.example.com", expect_aud="api://orders")
    check("clean token has no findings", r["findings"] == [])
    check("clean token signature verified", r["signature_verified"] is True)
    check("bearer prefix accepted", inspect("Bearer " + good, now=now)["payload"]["sub"] == "user-42")
    check("wrong secret flagged", "bad_signature" in codes(inspect(good, now=now, secret="x" * 40)))
    check("weak secret flagged", "weak_secret" in codes(inspect(make_token({"alg": "HS256"}, good_claims, "short"), now=now, secret="short")))
    check("alg none flagged high", "alg_none" in codes(inspect(make_token({"alg": "none"}, good_claims), now=now)))
    check("expired flagged", "expired" in codes(inspect(good, now=now + 3600)))
    check("leeway tolerates small skew", "expired" not in codes(inspect(good, now=now + 850, leeway=30)))
    check("nbf in future flagged", "not_yet_valid" in codes(inspect(make_token({"alg": "HS256"}, dict(good_claims, nbf=now + 600), strong), now=now)))
    check("exp missing flagged", "exp_missing" in codes(inspect(make_token({"alg": "HS256"}, {"sub": "a", "iat": now}, strong), now=now)))
    check("milliseconds exp flagged", "exp_milliseconds" in codes(inspect(make_token({"alg": "HS256"}, dict(good_claims, exp=(now + 600) * 1000), strong), now=now)))
    check("long lifetime flagged", "lifetime_long" in codes(inspect(make_token({"alg": "HS256"}, dict(good_claims, exp=now + 30 * 86400), strong), now=now)))
    check("iss mismatch flagged", "iss_mismatch" in codes(inspect(good, now=now, expect_iss="https://evil.example")))
    check("aud list accepted", "aud_mismatch" not in codes(inspect(make_token({"alg": "HS256"}, dict(good_claims, aud=["a", "api://orders"]), strong), now=now, expect_aud="api://orders")))
    check("aud mismatch flagged", "aud_mismatch" in codes(inspect(good, now=now, expect_aud="api://billing")))
    check("missing aud with expected aud is high", "aud_mismatch" in codes(inspect(make_token({"alg": "HS256"}, {k: v for k, v in good_claims.items() if k != "aud"}, strong), now=now, expect_aud="api://orders")))
    check("jku header flagged", "header_jku" in codes(inspect(make_token({"alg": "RS256", "kid": "1", "jku": "https://x/keys"}, good_claims, signature=b"sig"), now=now)))
    check("rs256 without kid is low", "kid_missing" in codes(inspect(make_token({"alg": "RS256"}, good_claims, signature=b"sig"), now=now)))
    check("sensitive claim flagged", "sensitive_claim" in codes(inspect(make_token({"alg": "HS256"}, dict(good_claims, password="hunter2"), strong), now=now)))
    check("empty signature flagged", "signature_empty" in codes(inspect(make_token({"alg": "HS256"}, good_claims), now=now)))
    for bad, label in (("abc.def", "two segments rejected"), ("a.b.c.d.e", "JWE rejected"), ("!!.e30.", "bad base64 rejected")):
        try:
            inspect(bad, now=now)
            check(label, False)
        except TokenError:
            check(label, True)
    check("markdown never prints signature", make_token({"alg": "HS256"}, good_claims, strong).split(".")[2] not in to_markdown(r))
    passed = sum(ok for _, ok in cases)
    for name, ok in cases:
        print(("PASS " if ok else "FAIL ") + name)
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Decode and lint a JWT without trusting it.")
    ap.add_argument("token", nargs="?", help="JWT string, or '-' to read from stdin")
    ap.add_argument("--now", help="reference time: ISO 8601 (Z or offset) or epoch seconds; default: current UTC time")
    ap.add_argument("--leeway", type=int, default=0, help="allowed clock skew in seconds (default 0)")
    ap.add_argument("--expect-iss")
    ap.add_argument("--expect-aud")
    ap.add_argument("--max-lifetime", type=int, default=86400, help="max exp-iat seconds before warning (0 = off)")
    ap.add_argument("--secret-env", help="name of an environment variable holding the HS* secret (avoids shell history)")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--strict", action="store_true", help="exit 1 on any finding")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.token:
        ap.error("token required (or --self-test)")
    token = sys.stdin.read() if a.token == "-" else a.token
    secret = None
    if a.secret_env:
        secret = os.environ.get(a.secret_env)
        if secret is None:
            print(f"error: environment variable {a.secret_env} is not set", file=sys.stderr)
            return 2
    try:
        r = inspect(token, now=a.now, leeway=a.leeway, expect_iss=a.expect_iss, expect_aud=a.expect_aud,
                    max_lifetime=a.max_lifetime, secret=secret)
    except (TokenError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(r, indent=2, ensure_ascii=False) if a.json else to_markdown(r))
    if any(f["severity"] == "high" for f in r["findings"]) or (a.strict and r["findings"]):
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())

---
name: retry-backoff-policy-calculator
description: Kiểm tra các thiết lập retry, backoff và timeout trên toàn bộ chuỗi lệnh gọi để ngăn chặn bão retry (retry storm). Tính toán lịch trình độ trễ hàm mũ với jitter dạng full, equal hoặc decorrelated, độ trễ trường hợp xấu nhất cho mỗi tầng, số lần thử kỳ vọng và mức độ khuếch đại yêu cầu. Cảnh báo các timeout bên trong kéo dài vượt quá thời gian của bên gọi, việc retry các lệnh gọi không bất biến (non-idempotent), retry trên mã lỗi 4xx, bỏ qua Retry-After cũng như thiếu giới hạn trần (cap) hoặc hạn chót (deadline). Bao gồm một công cụ tính toán dùng thư viện chuẩn Python có hỗ trợ --self-test.
---

# Công cụ tính toán chính sách Retry và Backoff

Bạn giúp các kỹ sư thiết lập chính sách retry, backoff và timeout giúp các dịch vụ hoạt động đáng tin cậy hơn thay vì biến một sự cố nhỏ thành một sự cố sập hệ thống diện rộng. Bạn thu thập các thiết lập của từng chặng (hop) trong chuỗi lệnh gọi (trình duyệt, gateway, các dịch vụ, cơ sở dữ liệu, API bên thứ ba), tính toán những gì thực sự diễn ra khi gặp lỗi, và đề xuất một chính sách an toàn hơn kèm theo các con số cụ thể.

## Các tệp trong kỹ năng này

- `scripts/retry_policy.py` - đọc JSON chuỗi lệnh gọi và in ra lịch trình độ trễ, độ trễ trường hợp xấu nhất, số lần thử kỳ vọng, mức độ khuếch đại và các cờ cảnh báo (chỉ sử dụng thư viện chuẩn Python 3)
- `references/backoff-math.md` - các công thức tính backoff, jitter, thời gian trường hợp xấu nhất, số lần thử kỳ vọng, mức độ khuếch đại và việc lồng ghép timeout
- `references/retry-safety-guide.md` - những gì an toàn để retry, khóa bất biến (idempotency key), ngắt mạch (circuit breaker), ngân sách retry (retry budget), các thiết lập thư viện phổ biến
- `templates/retry-policy-review.md` - báo cáo đánh giá gồm chuỗi hiện tại, các phát hiện và chính sách đề xuất
- `examples/checkout-chain.json` - một chuỗi thanh toán ba tầng với những sai lầm điển hình

## Quy trình làm việc

### 1. Lập bản đồ chuỗi lệnh gọi
Hỏi thông tin cho từng chặng, bắt đầu từ tầng ngoài cùng trước: số lần thử (attempts - tổng số lần thực hiện), độ trễ cơ sở (base delay), hệ số nhân (multiplier), độ trễ tối đa (max delay), loại jitter, timeout cho mỗi lần thử (per-try timeout), hạn chót tổng thể (overall deadline), điều kiện kích hoạt retry (mã trạng thái, "timeout", "network"), liệu lệnh gọi có tính bất biến (idempotent) hay không, có gửi kèm khóa bất biến (idempotency key) hay không, và có tuân thủ Retry-After hay không. Đọc các thông số này từ mã nguồn hoặc tệp cấu hình (SDK client, bộ chuyển đổi retry của HTTP client, các route Envoy/Istio, cấu hình dịch vụ gRPC, hàng đợi công việc). Với các giá trị chưa biết: sử dụng giá trị mặc định của thư viện và đánh dấu chúng là giả định.

### 2. Chạy công cụ tính toán
```
python3 scripts/retry_policy.py examples/checkout-chain.json
python3 scripts/retry_policy.py chain.json --failure-rate 0.5 --max-amplification 8
python3 scripts/retry_policy.py chain.json --json > retry-report.json
python3 scripts/retry_policy.py --self-test
```
Mã thoát (exit code) 1 có nghĩa là có các phát hiện mức độ nghiêm trọng cao, 2 có nghĩa là dữ liệu đầu vào không hợp lệ.

### 3. Giải thích các phát hiện
Thứ tự ưu tiên: RETRY_UNSAFE và AMPLIFICATION trước tiên (chúng gây ra các tác dụng phụ trùng lặp và làm sập hệ thống), tiếp theo là INNER_OUTLIVES_CALLER, HOT_LOOP, NO_PER_TRY_TIMEOUT, sau đó đến mức trung bình (medium) và thấp (low). Giải thích từng vấn đề bằng các con số trích từ báo cáo, ví dụ: "một lần thanh toán có thể biến thành 36 lệnh gọi tới nhà cung cấp dịch vụ thanh toán".

### 4. Đề xuất chính sách đã khắc phục
Sử dụng `references/backoff-math.md` và `references/retry-safety-guide.md`: chỉ retry tại một tầng duy nhất, dùng full jitter có giới hạn trần (cap), thời gian trường hợp xấu nhất của tầng bên trong phải nhỏ hơn per-try timeout của bên gọi, truyền hạn chót (deadline) xuống các tầng dưới, dùng khóa bất biến cho các thao tác ghi, không retry trên các lỗi 4xx ngoại trừ 408/429, tuân thủ Retry-After, áp dụng ngân sách retry hoặc bộ ngắt mạch. Chạy lại kịch bản trên tệp JSON đề xuất và hiển thị kết quả so sánh trước và sau khi sửa.

### 5. Viết báo cáo tổng hợp
Điền vào biểu mẫu `templates/retry-policy-review.md` và cung cấp các đoạn mã cấu hình (config snippets) cho thư viện mà người dùng đang sử dụng.

## Ví dụ kết quả
Đối với `examples/checkout-chain.json` ở tỷ lệ lỗi 30%: mức độ khuếch đại trường hợp xấu nhất là 36 lệnh gọi cho mỗi lần thanh toán (kỳ vọng là 2.74); thời gian trường hợp xấu nhất 9.3 giây của tầng gateway kéo dài vượt quá per-try timeout 8 giây của ứng dụng web; tầng thanh toán retry một lệnh trừ tiền không bất biến 4 lần mà không có khóa bất biến và retry cả lỗi 409; không có jitter tại tầng gateway; bỏ qua Retry-After trên lỗi 429/503.

## Quy tắc

- Không bao giờ khuyến nghị retry một lệnh gọi không bất biến mà không có khóa bất biến (idempotency key).
- Giữ tính trung thực của các con số: gắn nhãn rõ ràng các giá trị mặc định của thư viện và các phỏng đoán là giả định.
- Ưu tiên số lần retry ít hơn kèm theo thiết lập timeout hợp lý hơn là retry quá nhiều lần.
- Khuyến nghị kiểm thử tải (load test) hoặc tiêm lỗi (fault injection) để xác nhận chính sách trong thực tế, chứ không chỉ dựa vào tính toán lý thuyết.
FILE:references/backoff-math.md
# Toán học về Backoff và Timeout

## Thuật ngữ
- **attempts**: tổng số lần thử bao gồm cả lần đầu tiên. attempts 3 = 1 lần thử ban đầu + 2 lần retry.
- **base**: độ trễ của lần retry đầu tiên. **multiplier**: hệ số tăng trưởng (thường là 2). **cap**: độ trễ tối đa cho một lần chờ.
- **per-try timeout**: khoảng thời gian tối đa mà một lần thử được phép diễn ra trước khi bị hủy bỏ.
- **deadline**: tổng ngân sách thời gian cho toàn bộ lệnh gọi bao gồm tất cả các lần thử và thời gian chờ.

## Độ trễ trước lần retry thứ k (k = 1 .. attempts-1)
d(k) = min(cap, base x multiplier^(k-1))

| Jitter | Độ trễ | Phạm vi | Giá trị trung bình |
|---|---|---|---|
| none | d | d | d |
| full | random(0, d) | 0 .. d | d/2 |
| equal | d/2 + random(0, d/2) | d/2 .. d | 0.75 d |
| decorrelated | min(cap, random(base, 3 x previous)) | base .. min(cap, base x 3^k) | mô phỏng |

Full jitter phân tán tải tốt nhất và là khuyến nghị mặc định. Equal jitter giữ lại một khoảng thời gian chờ tối thiểu. Decorrelated jitter thích ứng với độ trễ liền trước đó và hoạt động tốt cho các client chạy dài hạn.

## Thời lượng trường hợp xấu nhất của một lệnh gọi
worst = attempts x per_try_timeout + tổng các độ trễ tối đa, sau đó cắt tại ngưỡng deadline nếu có thiết lập deadline.
Ví dụ: 3 lần thử x 1 s + 100 ms + 200 ms = 3.3 s.

## Số lần thử kỳ vọng
Với xác suất lỗi độc lập p cho mỗi lần thử và tổng số n lần thử (attempts):
E[tries] = 1 + p + p^2 + ... + p^(n-1)
p = 0.3, n = 3 -> 1.39. Trong trường hợp sập toàn bộ hệ thống, p = 1 và E = n.

## Sự khuếch đại qua các tầng
Nếu tầng A retry 3 lần và gọi B, B lại retry 3 lần và gọi C, C lại retry 4 lần, thì một yêu cầu từ người dùng có thể biến thành 3 x 3 x 4 = 36 lệnh gọi tới C khi xảy ra sự cố. Đây chính là bão retry (retry storm): các lệnh retry giữ cho dịch vụ đang gặp sự cố luôn trong tình trạng quá tải, khiến nó không thể phục hồi.

Quy tắc kinh nghiệm:
- Chỉ retry tại một tầng duy nhất, thường là tầng gần người dùng nhất hoặc tầng sở hữu khóa bất biến (idempotency key).
- Các tầng bên trong: đặt attempts là 1 hoặc 2 với hạn chót (deadline) ngắn.
- Giữ mức độ khuếch đại trong trường hợp xấu nhất ở mức bằng hoặc dưới khoảng 10.
- Thêm **ngân sách retry (retry budget)**: số lượng retry chỉ được chiếm tối đa 10-20% tổng số yêu cầu trong một cửa sổ trượt (sliding window); vượt quá ngưỡng đó, hãy báo lỗi ngay lập tức (fail fast).

## Lồng ghép Timeout (Timeout nesting)
Trường hợp xấu nhất của mỗi tầng phải nằm gọn bên trong per-try timeout của bên gọi nó, trừ đi một khoảng dự phòng (margin) cho độ trễ mạng và xử lý:
inner_worst <= outer_per_try_timeout - margin
Nếu không, bên gọi sẽ hủy bỏ lần thử đó và thực hiện retry trong khi tầng bên trong vẫn đang tiếp tục xử lý, làm tăng gấp đôi tải hệ thống. Hãy truyền một hạn chót (deadline) xuống dọc theo chuỗi lệnh gọi (ví dụ qua header `grpc-timeout` hoặc `X-Request-Deadline`) và dừng xử lý ngay khi thời gian này cạn kiệt.

## Retry-After
Đối với mã lỗi 429 và 503, máy chủ có thể gửi kèm `Retry-After: <seconds>` hoặc một ngày giờ theo chuẩn HTTP. Hãy chờ ít nhất bằng khoảng thời gian đó (sử dụng max(Retry-After, backoff tính toán được)), và từ bỏ ngay nếu khoảng thời gian chờ này dài hơn thời hạn (deadline) còn lại.
FILE:references/retry-safety-guide.md
# Hướng dẫn an toàn khi Retry

## Những trường hợp nên retry
| Kết quả | Có Retry không? | Ghi chú |
|---|---|---|
| Từ chối kết nối (Connection refused) / ngắt kết nối (reset) trước khi yêu cầu được gửi đi | Có | An toàn cho bất kỳ phương thức nào |
| Hết thời gian chờ (Timeout) sau khi yêu cầu đã được gửi đi | Chỉ khi có tính bất biến hoặc có khóa bất biến (idempotency key) | Máy chủ có thể đã thực hiện xong công việc đó |
| 408 Request Timeout | Có, kèm theo backoff | |
| 429 Too Many Requests | Có, sau khoảng thời gian Retry-After | Không bao giờ gọi lại nhanh hơn thời gian máy chủ yêu cầu |
| 500 Internal Server Error | Đôi khi | Chỉ khi biết chắc lỗi đó là lỗi tạm thời (transient) |
| 502 / 503 / 504 | Có, kèm theo backoff và jitter | Tuân thủ Retry-After trên lỗi 503 |
| 400 / 401 / 403 / 404 / 405 / 410 / 422 | Không | Cùng một yêu cầu sẽ thất bại theo cùng một cách; hãy sửa lại yêu cầu, hoặc làm mới xác thực (auth) tối đa một lần |
| 409 Conflict | Thường là không | Ngoại lệ: một khóa bất biến vẫn đang trong quá trình xử lý, hãy retry sau một khoảng chờ ngắn |

## Tính bất biến (Idempotency)
- GET, HEAD, OPTIONS, PUT và DELETE có tính bất biến theo ngữ nghĩa HTTP, nếu máy chủ triển khai chúng đúng chuẩn.
- POST và PATCH không có tính bất biến. Để retry chúng, hãy gửi kèm một **khóa bất biến (idempotency key)** (một mã UUID cho mỗi thao tác logic, ví dụ qua header `Idempotency-Key`) mà máy chủ sẽ lưu trữ cùng với kết quả trong vòng 24 giờ hoặc lâu hơn. Khởi tạo khóa này một lần duy nhất trước lần thử đầu tiên, và tái sử dụng lại nó cho mọi lần retry.
- Các tác vụ thanh toán, gửi email, SMS, tạo đơn hàng và giữ chỗ tồn kho tuyệt đối không bao giờ được retry nếu không có khóa bất biến.

## Danh sách kiểm tra cho Client (Client checklist)
1. Đã thiết lập per-try timeout và ngắn hơn timeout của bên gọi.
2. Đã thiết lập hạn chót tổng thể (overall deadline) và truyền xuống dọc theo chuỗi lệnh gọi.
3. Sử dụng exponential backoff có giới hạn trần (cap) và full jitter.
4. Số lần thử (attempts) <= 3 ở tầng biên (edge), 1-2 ở các tầng bên trong.
5. Chỉ retry trên các hàng có giá trị "Có" trong bảng hướng dẫn.
6. Đính kèm khóa bất biến (idempotency key) trên mọi lệnh gọi không bất biến có thực hiện retry.
7. Có ngân sách retry (retry budget) hoặc bộ ngắt mạch (circuit breaker) để dừng retry khi xảy ra sự cố diện rộng.
8. Các chỉ số đo lường (metrics): số lần thử trên mỗi yêu cầu, tỷ lệ retry, số lần từ bỏ (give-up count), phân loại theo từng dịch vụ phụ thuộc (dependency).
9. Chỉ ghi log lỗi cuối cùng kèm theo tổng số lần đã thử, không ghi log ở mức error cho từng lần thử thất bại riêng lẻ.

## Kiến thức cơ bản về Bộ ngắt mạch (Circuit breaker)
- Đóng (Closed): các lệnh gọi diễn ra bình thường; đếm số lỗi trong một cửa sổ trượt (rolling window).
- Mở (Open): sau khi vượt ngưỡng ví dụ như 50% lỗi trên ít nhất 20 lệnh gọi, báo lỗi ngay lập tức (fail fast) trong vòng 30 giây.
- Nửa mở (Half-open): cho phép một vài lệnh gọi thăm dò đi qua; chuyển về trạng thái Đóng nếu chúng thành công.
Sự kết hợp giữa bộ ngắt mạch và ngân sách retry sẽ ngăn chặn bão retry làm trầm trọng thêm sự cố sập hệ thống.

## Thiết lập của các thư viện phổ biến
- AWS SDKs: chế độ tiêu chuẩn (standard mode) = 3 lần thử (attempts), full jitter, độ trễ cơ sở (base) 1 giây khi bị giới hạn tốc độ (throttling); chế độ thích ứng (adaptive mode) bổ sung thêm tính năng giới hạn tốc độ phía client.
- Chính sách retry của gRPC: maxAttempts, initialBackoff, maxBackoff, backoffMultiplier, retryableStatusCodes (UNAVAILABLE là mã phổ biến nhất); việc retry cần tuân thủ các quy tắc hedging/transparent retry đối với các phương thức không bất biến.
- Envoy / Istio: retry_on: 5xx,reset,connect-failure; num_retries; per_try_timeout; thiết lập route timeout >= per_try_timeout x (num_retries + 1).
- Python `urllib3.Retry(total=3, backoff_factor=0.5, status_forcelist=[502,503,504], respect_retry_after_header=True, allowed_methods=[...])`.
Hãy kiểm tra tài liệu của thư viện tương ứng với phiên bản bạn đang sử dụng; các giá trị mặc định có thể thay đổi theo phiên bản.
FILE:templates/retry-policy-review.md
# Đánh giá Chính sách Retry - <dịch vụ / chuỗi lệnh gọi> - <ngày>

**Người đánh giá:** <tên>  **Đầu vào:** <JSON chuỗi / các tệp cấu hình>  **Tỷ lệ lỗi giả định:** <30%>

## Chuỗi lệnh gọi
| # | Bên gọi -> Bên được gọi | Số lần thử (Attempts) | Backoff (base / x / cap) | Jitter | Per-try timeout | Deadline | Trường hợp xấu nhất |
|---|---|---|---|---|---|---|---|
| 1 | | | | | | | |

**Mức độ khuếch đại trường hợp xấu nhất:** <36> lệnh gọi trên mỗi yêu cầu (mục tiêu <= 10)
**Mức độ khuếch đại kỳ vọng tại <p>:** <2.7>

## Các phát hiện
| Mức độ nghiêm trọng | Tầng | Mã lỗi | Vấn đề | Cách khắc phục |
|---|---|---|---|---|
| high | | | | |

## Chính sách đề xuất
| # | Bên gọi -> Bên được gọi | Số lần thử (Attempts) | Backoff | Jitter | Per-try timeout | Deadline | Retry khi gặp |
|---|---|---|---|---|---|---|---|
| 1 | | | | full | | | |

**Mức độ khuếch đại trường hợp xấu nhất mới:** <n>  **Độ trễ trường hợp xấu nhất mới:** <s>

## Công việc tiếp theo
- [ ] Bổ sung khóa bất biến (idempotency keys) cho: <các lệnh gọi>
- [ ] Thiết lập ngân sách retry / bộ ngắt mạch cho: <dịch vụ phụ thuộc>
- [ ] Bảng điều khiển (Dashboards): số lần thử trên mỗi yêu cầu, tỷ lệ retry, số lần từ bỏ
FILE:examples/checkout-chain.json
{
  "name": "checkout: browser -> api gateway -> orders service -> payments provider",
  "failure_rate": 0.3,
  "max_amplification": 10,
  "layers": [
    {
      "name": "web app -> api gateway",
      "attempts": 3,
      "base_delay_ms": 200,
      "multiplier": 2,
      "max_delay_ms": 2000,
      "jitter": "full",
      "per_try_timeout_ms": 8000,
      "deadline_ms": 20000,
      "retry_on": ["network", 502, 503, 504],
      "idempotent": true,
      "respect_retry_after": true
    },
    {
      "name": "api gateway -> orders service",
      "attempts": 3,
      "base_delay_ms": 100,
      "multiplier": 2,
      "max_delay_ms": 1000,
      "jitter": "none",
      "per_try_timeout_ms": 3000,
      "retry_on": [500, 502, 503, 504, "timeout"],
      "idempotent": true
    },
    {
      "name": "orders service -> payments provider (create charge)",
      "attempts": 4,
      "base_delay_ms": 250,
      "multiplier": 2,
      "jitter": "equal",
      "per_try_timeout_ms": 2500,
      "deadline_ms": 9000,
      "retry_on": [409, 429, 500, 503, "timeout"],
      "idempotent": false,
      "idempotency_key": false,
      "respect_retry_after": false
    }
  ]
}
FILE:scripts/retry_policy.py
#!/usr/bin/env python3
"""Retry and backoff policy calculator (Python 3 standard library only).

Input: a JSON file describing a call chain, outermost caller first:
  {"name": "checkout", "failure_rate": 0.3, "max_amplification": 10,
   "layers": [
     {"name": "web -> api", "attempts": 3, "base_delay_ms": 100, "multiplier": 2,
      "max_delay_ms": 2000, "jitter": "full", "per_try_timeout_ms": 5000,
      "deadline_ms": 12000, "retry_on": [502, 503, 504, "timeout"],
      "idempotent": true, "respect_retry_after": true}, ...]}
attempts = total tries including the first one (attempts 1 = no retries).
jitter: none | full | equal | decorrelated.  Delay before retry k (k = 1..attempts-1):
  none  d = min(cap, base * multiplier^(k-1))
  full  U(0, d)              equal  d/2 + U(0, d/2)
  decorrelated  min(cap, U(base, 3 * previous))  (AWS style; expected value simulated, seed 7)

Reports per layer: delay schedule (min / expected / max), worst-case time for one call
(attempts x per-try timeout + max delays, cut at deadline), expected tries at the given
failure rate, and for the chain: worst-case and expected request amplification at the
innermost dependency. Flags:
  NO_JITTER, NO_CAP, HOT_LOOP (base 0), TOO_MANY_ATTEMPTS (> 5), NO_PER_TRY_TIMEOUT,
  NO_DEADLINE, DEADLINE_TOO_SHORT (deadline < one per-try timeout), INNER_OUTLIVES_CALLER
  (worst case > the outer layer's per-try timeout), RETRY_UNSAFE (non-idempotent with
  retries and no idempotency key), RETRY_ON_4XX (retrying 400/401/403/404/409/422),
  IGNORES_RETRY_AFTER (retries 429/503 without honoring Retry-After), AMPLIFICATION.
Usage:
  python3 retry_policy.py chain.json
  python3 retry_policy.py chain.json --failure-rate 0.5 --json
  python3 retry_policy.py --self-test
Exit code: 0 OK, 1 high-severity flags found, 2 bad input.
"""
import argparse
import json
import random
import sys

JITTERS = ("none", "full", "equal", "decorrelated")
BAD_4XX = {400, 401, 403, 404, 405, 409, 410, 422}
SEVERITY = {"INNER_OUTLIVES_CALLER": "high", "RETRY_UNSAFE": "high", "AMPLIFICATION": "high",
            "HOT_LOOP": "high", "NO_PER_TRY_TIMEOUT": "high", "RETRY_ON_4XX": "medium",
            "NO_JITTER": "medium", "NO_CAP": "medium", "IGNORES_RETRY_AFTER": "medium",
            "NO_DEADLINE": "medium", "DEADLINE_TOO_SHORT": "medium", "TOO_MANY_ATTEMPTS": "low"}


class PolicyError(ValueError):
    pass


def num(layer, key, default=None, minimum=0):
    v = layer.get(key, default)
    if v is None:
        return None
    if isinstance(v, bool) or not isinstance(v, (int, float)):
        raise PolicyError(f"layer {layer.get('name', '?')!r}: {key} must be a number")
    if v < minimum:
        raise PolicyError(f"layer {layer.get('name', '?')!r}: {key} must be >= {minimum}")
    return v


def delays(layer):
    """Return [(min, expected, max)] in ms for each retry."""
    n = int(layer["attempts"])
    base, mult, cap = layer["base_delay_ms"], layer["multiplier"], layer["max_delay_ms"]
    capf = (lambda x: x) if cap is None else (lambda x: min(cap, x))
    j = layer["jitter"]
    out = []
    if j == "decorrelated":
        rng = random.Random(7)
        runs = 20000
        sums = [0.0] * (n - 1)
        for _ in range(runs):
            prev = base
            for k in range(n - 1):
                prev = capf(rng.uniform(base, prev * 3)) if base > 0 else 0.0
                sums[k] += prev
        hi = base
        for k in range(n - 1):
            hi = capf(hi * 3)
            out.append((capf(base), sums[k] / runs, hi))
        return out
    for k in range(n - 1):
        d = capf(base * mult ** k)
        if j == "none":
            out.append((d, d, d))
        elif j == "full":
            out.append((0.0, d / 2, d))
        else:
            out.append((d / 2, d * 0.75, d))
    return out


def normalize(raw):
    layers = raw.get("layers") if isinstance(raw, dict) else None
    if not layers or not isinstance(layers, list):
        raise PolicyError("JSON must have a non-empty 'layers' list (outermost caller first)")
    out = []
    for i, l in enumerate(layers):
        if not isinstance(l, dict):
            raise PolicyError(f"layer {i} must be an object")
        l = dict(l)
        l.setdefault("name", f"layer {i + 1}")
        a = num(l, "attempts", 1, 1)
        if int(a) != a:
            raise PolicyError(f"layer {l['name']!r}: attempts must be a whole number")
        l["attempts"] = int(a)
        l["base_delay_ms"] = num(l, "base_delay_ms", 0)
        l["multiplier"] = num(l, "multiplier", 2, 1)
        l["max_delay_ms"] = num(l, "max_delay_ms", None)
        l["per_try_timeout_ms"] = num(l, "per_try_timeout_ms", None, 1)
        l["deadline_ms"] = num(l, "deadline_ms", None, 1)
        j = str(l.get("jitter", "none")).lower()
        if j not in JITTERS:
            raise PolicyError(f"layer {l['name']!r}: jitter must be one of {', '.join(JITTERS)}")
        l["jitter"] = j
        l["retry_on"] = list(l.get("retry_on", []))
        l["idempotent"] = bool(l.get("idempotent", True))
        l["idempotency_key"] = bool(l.get("idempotency_key", False))
        l["respect_retry_after"] = bool(l.get("respect_retry_after", False))
        out.append(l)
    return out


def expected_tries(n, p):
    if p >= 1:
        return float(n)
    return sum(p ** k for k in range(n))


def analyze(raw, failure_rate=None, max_amp=None):
    layers = normalize(raw)
    p = failure_rate if failure_rate is not None else raw.get("failure_rate", 0.2)
    if not 0 <= p <= 1:
        raise PolicyError("failure rate must be between 0 and 1")
    max_amp = max_amp if max_amp is not None else raw.get("max_amplification", 10)
    res = {"name": raw.get("name", "retry policy"), "failure_rate": p, "max_amplification": max_amp, "layers": []}
    worst_amp, exp_amp = 1, 1.0
    for i, l in enumerate(layers):
        n = l["attempts"]
        ds = delays(l)
        flags = []
        retries = n > 1
        if retries and l["jitter"] == "none":
            flags.append(("NO_JITTER", "all clients retry at the same moments; use full or decorrelated jitter"))
        if retries and l["max_delay_ms"] is None and n > 3:
            flags.append(("NO_CAP", "no max_delay_ms; exponential delays grow without bound"))
        if retries and l["base_delay_ms"] == 0:
            flags.append(("HOT_LOOP", "base_delay_ms is 0; retries fire immediately and hammer the dependency"))
        if n > 5:
            flags.append(("TOO_MANY_ATTEMPTS", f"{n} attempts; 3 (2 retries) is usually enough"))
        if l["per_try_timeout_ms"] is None:
            flags.append(("NO_PER_TRY_TIMEOUT", "no per-try timeout; one hung call can block every retry"))
        if l["deadline_ms"] is None and retries:
            flags.append(("NO_DEADLINE", "no overall deadline across attempts"))
        if l["deadline_ms"] is not None and l["per_try_timeout_ms"] and l["deadline_ms"] < l["per_try_timeout_ms"]:
            flags.append(("DEADLINE_TOO_SHORT", "deadline is shorter than a single try"))
        if retries and not l["idempotent"] and not l["idempotency_key"]:
            flags.append(("RETRY_UNSAFE", "retries a non-idempotent call without an idempotency key (double charge / duplicate write risk)"))
        bad = sorted(c for c in l["retry_on"] if isinstance(c, int) and c in BAD_4XX)
        if retries and bad:
            flags.append(("RETRY_ON_4XX", f"retries client errors {bad}; they will fail the same way again"))
        if retries and any(c in (429, 503) for c in l["retry_on"]) and not l["respect_retry_after"]:
            flags.append(("IGNORES_RETRY_AFTER", "retries 429/503 but ignores the Retry-After header"))
        max_delay_total = sum(d[2] for d in ds)
        exp_delay_total = sum(d[1] for d in ds)
        worst = None
        if l["per_try_timeout_ms"] is not None:
            worst = n * l["per_try_timeout_ms"] + max_delay_total
            if l["deadline_ms"] is not None:
                worst = min(worst, l["deadline_ms"])
        elif l["deadline_ms"] is not None:
            worst = l["deadline_ms"]
        if i > 0:
            parent = layers[i - 1]
            pt = parent["per_try_timeout_ms"]
            if pt is not None and (worst is None or worst > pt):
                flags.append(("INNER_OUTLIVES_CALLER", f"worst case {fmt_ms(worst)} > caller per-try timeout {fmt_ms(pt)}; the caller gives up and retries while this layer is still working"))
        et = expected_tries(n, p)
        worst_amp *= n
        exp_amp *= et
        res["layers"].append({
            "name": l["name"], "attempts": n, "jitter": l["jitter"],
            "delays_ms": [[round(a, 1), round(b, 1), round(c, 1)] for a, b, c in ds],
            "max_delay_total_ms": round(max_delay_total, 1), "expected_delay_total_ms": round(exp_delay_total, 1),
            "per_try_timeout_ms": l["per_try_timeout_ms"], "deadline_ms": l["deadline_ms"],
            "worst_case_ms": None if worst is None else round(worst, 1),
            "expected_tries": round(et, 3), "cumulative_worst_amplification": worst_amp,
            "cumulative_expected_amplification": round(exp_amp, 3),
            "flags": [{"code": c, "severity": SEVERITY[c], "detail": d} for c, d in flags]})
    if worst_amp > max_amp:
        res["layers"][-1]["flags"].append({"code": "AMPLIFICATION", "severity": "high",
            "detail": f"one top-level request can become {worst_amp} calls to the innermost dependency during an outage (limit {max_amp}); retry at one layer only or add a retry budget"})
    res["worst_amplification"] = worst_amp
    res["expected_amplification"] = round(exp_amp, 3)
    res["high_flags"] = sum(1 for l in res["layers"] for f in l["flags"] if f["severity"] == "high")
    return res


def fmt_ms(v):
    if v is None:
        return "unbounded"
    if v >= 1000:
        s = f"{v / 1000:.2f}".rstrip("0").rstrip(".")
        return s + " s"
    return f"{v:g} ms"


def to_markdown(r):
    out = [f"# Retry policy report: {r['name']}", "",
           f"Failure rate used for expected values: {r['failure_rate']:.0%}", "",
           "| Layer | Attempts | Jitter | Max total delay | Per-try timeout | Deadline | Worst case | Expected tries |",
           "|---|---|---|---|---|---|---|---|"]
    for l in r["layers"]:
        out.append(f"| {l['name']} | {l['attempts']} | {l['jitter']} | {fmt_ms(l['max_delay_total_ms'])} | "
                   f"{fmt_ms(l['per_try_timeout_ms'])} | {fmt_ms(l['deadline_ms'])} | {fmt_ms(l['worst_case_ms'])} | {l['expected_tries']:g} |")
    out += ["", "## Delay schedule (min / expected / max)"]
    for l in r["layers"]:
        if not l["delays_ms"]:
            out.append(f"- {l['name']}: no retries")
            continue
        parts = [f"retry {k + 1}: {fmt_ms(a)} / {fmt_ms(b)} / {fmt_ms(c)}" for k, (a, b, c) in enumerate(l["delays_ms"])]
        out.append(f"- {l['name']}: " + "; ".join(parts))
    out += ["", "## Amplification at the innermost dependency",
            f"- Worst case (every try fails): {r['worst_amplification']} calls per top-level request",
            f"- Expected at {r['failure_rate']:.0%} failure rate: {r['expected_amplification']:g} calls per top-level request", "",
            "## Findings"]
    n = 0
    for sev in ("high", "medium", "low"):
        for l in r["layers"]:
            for f in l["flags"]:
                if f["severity"] == sev:
                    n += 1
                    out.append(f"- **{sev.upper()} {f['code']}** ({l['name']}): {f['detail']}")
    if not n:
        out.append("- No findings.")
    return "\n".join(out)


def self_test():
    cases = []

    def ok(name, cond):
        cases.append((name, bool(cond)))

    def one(**kw):
        base = {"name": "x", "attempts": 3, "base_delay_ms": 100, "multiplier": 2, "max_delay_ms": 1000,
                "jitter": "full", "per_try_timeout_ms": 1000, "deadline_ms": 5000, "retry_on": [503],
                "respect_retry_after": True}
        base.update(kw)
        return base

    def codes(r, i=0):
        return {f["code"] for f in r["layers"][i]["flags"]}

    d = delays(normalize({"layers": [one(jitter="none", attempts=5)]})[0])
    ok("exponential no jitter 100,200,400,800", [x[2] for x in d] == [100, 200, 400, 800])
    d = delays(normalize({"layers": [one(jitter="none", attempts=6)]})[0])
    ok("cap applied at 1000", d[-1][2] == 1000 and d[-2][2] == 800)
    d = delays(normalize({"layers": [one(jitter="full")]})[0])
    ok("full jitter mean half", d[0] == (0.0, 50.0, 100))
    d = delays(normalize({"layers": [one(jitter="equal")]})[0])
    ok("equal jitter 50..100 mean 75", d[0] == (50.0, 75.0, 100))
    d = delays(normalize({"layers": [one(jitter="decorrelated", attempts=4)]})[0])
    ok("decorrelated within bounds", all(a <= b <= c for a, b, c in d) and d[0][2] == 300 and d[2][2] == 1000)
    r = analyze({"layers": [one()]})
    ok("clean policy has no flags", not codes(r))
    ok("worst case = 3x1000 + 100 + 200", r["layers"][0]["worst_case_ms"] == 3300)
    r = analyze({"layers": [one(deadline_ms=2000)]})
    ok("deadline caps worst case", r["layers"][0]["worst_case_ms"] == 2000)
    ok("expected tries p=0.5 n=3 is 1.75", expected_tries(3, 0.5) == 1.75 and expected_tries(3, 1) == 3)
    ok("no jitter flagged", "NO_JITTER" in codes(analyze({"layers": [one(jitter="none")]})))
    ok("hot loop flagged", "HOT_LOOP" in codes(analyze({"layers": [one(base_delay_ms=0)]})))
    ok("no cap flagged with 4+ attempts", "NO_CAP" in codes(analyze({"layers": [one(max_delay_ms=None, attempts=4)]})))
    ok("unsafe retry flagged", "RETRY_UNSAFE" in codes(analyze({"layers": [one(idempotent=False)]})))
    ok("idempotency key makes it safe", "RETRY_UNSAFE" not in codes(analyze({"layers": [one(idempotent=False, idempotency_key=True)]})))
    ok("4xx retry flagged", "RETRY_ON_4XX" in codes(analyze({"layers": [one(retry_on=[400, 503])]})))
    ok("Retry-After ignored flagged", "IGNORES_RETRY_AFTER" in codes(analyze({"layers": [one(retry_on=[429], respect_retry_after=False)]})))
    ok("single attempt is not a retry policy", not codes(analyze({"layers": [one(attempts=1, jitter="none", deadline_ms=None)]})))
    r = analyze({"layers": [one(per_try_timeout_ms=2000, deadline_ms=None), one(per_try_timeout_ms=1000, deadline_ms=None)]})
    ok("inner outlives caller flagged", "INNER_OUTLIVES_CALLER" in codes(r, 1))
    r = analyze({"layers": [one(per_try_timeout_ms=4000), one(per_try_timeout_ms=1000, deadline_ms=3500)]})
    ok("inner within caller timeout ok", "INNER_OUTLIVES_CALLER" not in codes(r, 1))
    r = analyze({"layers": [one(), one(), one()], "max_amplification": 10})
    ok("3x3x3 amplification 27 flagged", r["worst_amplification"] == 27 and "AMPLIFICATION" in codes(r, 2))
    r = analyze({"layers": [one(), one()]}, failure_rate=0.5)
    ok("expected amplification 1.75^2", r["expected_amplification"] == 3.062)
    for bad, label in ((({"layers": []}), "empty layers rejected"), (({"layers": [one(jitter="random")]}), "bad jitter rejected"),
                       (({"layers": [one(attempts=0)]}), "zero attempts rejected"), (({"layers": [one(attempts=2.5)]}), "fractional attempts rejected")):
        try:
            analyze(bad)
            ok(label, False)
        except PolicyError:
            ok(label, True)
    ok("fmt_ms", fmt_ms(1500) == "1.5 s" and fmt_ms(250) == "250 ms" and fmt_ms(None) == "unbounded")
    passed = sum(c for _, c in cases)
    for name, c in cases:
        print(("PASS " if c else "FAIL ") + name)
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Check retry/backoff/timeout policies across a call chain.")
    ap.add_argument("file", nargs="?", help="chain JSON ('-' for stdin)")
    ap.add_argument("--failure-rate", type=float, help="probability that one try fails (default from file or 0.2)")
    ap.add_argument("--max-amplification", type=float, help="flag chains above this worst-case amplification (default 10)")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        ap.error("chain JSON required (or --self-test)")
    try:
        raw = json.load(sys.stdin if a.file == "-" else open(a.file, encoding="utf-8"))
        r = analyze(raw, a.failure_rate, a.max_amplification)
    except (OSError, PolicyError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(r, indent=2) if a.json else to_markdown(r))
    return 1 if r["high_flags"] else 0


if __name__ == "__main__":
    sys.exit(main())

# Gu thiết kế API GraphQL của một kỹ sư nền tảng (platform engineer)
- Thiết kế lược đồ (schema) xoay quanh các ca sử dụng (use cases) của phía client và ngôn ngữ nghiệp vụ (domain language), chứ không xoay quanh các bảng cơ sở dữ liệu. Độ tin cậy: 0.90
- Tự động sinh kiểu dữ liệu (types) cho cả phía server và client từ schema (sử dụng GraphQL Code Generator hoặc công cụ tương đương); không bao giờ tự viết tay các kiểu dữ liệu phản hồi. Độ tin cậy: 0.90
- Chỉ đặt các trường (fields) là non-null theo mặc định khi server luôn có thể phân giải (resolve) được chúng; giữ cho các trường phụ thuộc vào dịch vụ khác ở trạng thái có thể null (nullable) để một lỗi đơn lẻ không làm mất trắng toàn bộ phản hồi. Độ tin cậy: 0.80
- Sử dụng một đối tượng đầu vào duy nhất cho mỗi thao tác biến đổi dữ liệu (mutation) (ví dụ: createOrder(input: CreateOrderInput!)) và trả về một kiểu payload chuyên biệt, không trả về trực tiếp thực thể gốc (bare entity). Độ tin cậy: 0.85
- Trả về các lỗi nghiệp vụ dự kiến dưới dạng các thành phần kiểu hợp (typed union members) trong payload (ví dụ: OrderCreated | InsufficientStock); dành riêng mảng errors ở cấp cao nhất cho các lỗi hệ thống bất ngờ. Độ tin cậy: 0.75
- Phân trang danh sách bằng kết nối con trỏ theo phong cách Relay (edges, node, pageInfo) và giới hạn tham số first/last ở một mức tối đa hợp lý. Độ tin cậy: 0.80
- Gom nhóm (batch) và lưu đệm việc tải dữ liệu theo từng yêu cầu bằng DataLoader để triệt tiêu hoàn toàn vấn đề truy vấn N+1. Độ tin cậy: 0.95
- Áp dụng giới hạn độ sâu (depth) và độ phức tạp (complexity) của truy vấn ngay tại cổng giao tiếp (gateway). Độ tin cậy: 0.90
- Sử dụng truy vấn cố định (persisted queries - danh sách cho phép các mã băm thao tác) cho các ứng dụng client nội bộ (first-party) trên môi trường production. Độ tin cậy: 0.80
- Tắt tính năng tự tra cứu lược đồ (introspection) trên các điểm cuối (endpoints) production công khai trừ khi API đó thực sự được thiết kế để công khai cho bên thứ ba. Độ tin cậy: 0.70
- Phát triển mở rộng schema theo hướng bổ sung thêm (additively) và đánh dấu các trường cũ bằng chỉ thị @deprecated(reason: ...); không bao giờ phân tách phiên bản endpoint bằng đường dẫn như /v2. Độ tin cậy: 0.90
- Chỉ xóa bỏ một trường đã đánh dấu @deprecated sau khi số liệu đo lường mức sử dụng trường đó cho thấy không còn lưu lượng truy cập nào trong suốt một chu kỳ phát hành đầy đủ. Độ tin cậy: 0.85
- Chạy kiểm tra so sánh sự khác biệt của schema (schema diff) trong quy trình CI và cho dừng quá trình build nếu phát hiện các thay đổi gây phá vỡ tương thích (breaking changes). Độ tin cậy: 0.90
- Sử dụng các định danh ẩn (opaque IDs) duy nhất trên toàn cục và triển khai giao diện Node để hỗ trợ truy xuất lại dữ liệu (refetching). Độ tin cậy: 0.70
- Giữ cho các hàm phân giải (resolvers) thật mỏng gọn: chúng chỉ gọi các dịch vụ miền nghiệp vụ (domain services), và việc phân quyền (authorization) phải nằm ở tầng dịch vụ đó chứ không nằm trong các câu lệnh if của resolver. Độ tin cậy: 0.85
- Đặt tên rõ ràng cho mọi thao tác (operations) trong từng truy vấn của client để dữ liệu truy vết (traces), nhật ký (logs) và số liệu đo lường (metrics) dễ đọc hiểu. Độ tin cậy: 0.90
- Đặt các mảnh truy vấn (fragments) nằm cùng chỗ với chính các thành phần giao diện (UI components) sử dụng chúng. Độ tin cậy: 0.80
- Ưu tiên các kiểu vô hướng tùy chỉnh (custom scalars như DateTime, URL, Email) có kiểm tra tính hợp lệ hơn là dùng kiểu String thuần túy. Độ tin cậy: 0.75
- Chỉ sử dụng cơ chế đăng ký nhận dữ liệu (subscriptions) cho dữ liệu thời gian thực thực sự; cơ chế hỏi vòng định kỳ (polling) là hoàn toàn ổn đối với bất kỳ dữ liệu nào chỉ thay đổi sau mỗi vài phút. Độ tin cậy: 0.70
- Chỉ sử dụng kiến trúc liên hợp (federation) khi có nhiều nhóm khác nhau cùng sở hữu các đồ thị con (subgraphs) riêng biệt; một nhóm duy nhất thì chỉ nên dùng một schema duy nhất. Độ tin cậy: 0.75
- Truy vết mọi resolver bằng OpenTelemetry và thiết lập cảnh báo cho các trường xử lý chậm, chứ không chỉ cảnh báo các yêu cầu (requests) chậm nói chung. Độ tin cậy: 0.80
- Viết tài liệu cho mọi kiểu dữ liệu và mọi trường bằng phần mô tả trực tiếp trong schema; bản thân schema chính là tài liệu tham chiếu API. Độ tin cậy: 0.85

# Dịch Vụ FastAPI taste của một kỹ sư API Python
- Định nghĩa phần thân của yêu cầu (request) và phản hồi (response) bằng các mô hình Pydantic v2 và luôn thiết lập response_model để không vô tình làm rò rỉ dữ liệu ngoài ý muốn. Độ tin cậy: 0.95
- Tách riêng các lược đồ (schemas) cho các thao tác tạo mới (create), cập nhật (update) và đọc (read) thay vì tái sử dụng mô hình ORM làm cấu trúc dữ liệu trả về của API. Độ tin cậy: 0.90
- Chỉ sử dụng các endpoint khai báo với async def khi mọi lệnh gọi bên trong đều thực sự là bất đồng bộ (async); nếu không, hãy viết bằng def thông thường và để threadpool tự xử lý. Độ tin cậy: 0.85
- Tiêm (inject) các phiên kết nối cơ sở dữ liệu (database sessions), cài đặt cấu hình và người dùng hiện tại thông qua Depends, tuyệt đối không dùng các biến toàn cục ở cấp độ module. Độ tin cậy: 0.90
- Tải cấu hình bằng pydantic-settings từ các biến môi trường và cho dừng ứng dụng báo lỗi ngay lúc khởi động (fail fast) nếu thiếu bất kỳ thông tin cấu hình nào. Độ tin cậy: 0.90
- Chia nhỏ các tuyến đường (routes) thành các module APIRouter theo từng miền nghiệp vụ (domain) và giữ cho tệp main.py chỉ giới hạn ở việc khởi tạo ứng dụng và kết nối các thành phần lại với nhau. Độ tin cậy: 0.85
- Đặt logic nghiệp vụ vào trong các hàm dịch vụ (service functions) hoàn toàn tách biệt và không biết gì về giao thức HTTP, để có thể tái sử dụng chúng từ các tiến trình chạy ngầm (workers) và trong kiểm thử (tests). Độ tin cậy: 0.85
- Sử dụng cú pháp SQLAlchemy 2.0 với các phiên bất đồng bộ (async sessions) và quản lý lược đồ cơ sở dữ liệu bằng các bản di chuyển (migrations) của Alembic. Độ tin cậy: 0.80
- Sử dụng trình quản lý ngữ cảnh lifespan cho quá trình khởi động (startup) và tắt ứng dụng (shutdown) thay vì các hook on_event đã lỗi thời. Độ tin cậy: 0.85
- Chỉ phát sinh ngoại lệ HTTPException ở tầng giao tiếp ngoài cùng và ánh xạ các lỗi nghiệp vụ (domain errors) sang mã trạng thái HTTP bằng các trình xử lý ngoại lệ (exception handlers) đã đăng ký. Độ tin cậy: 0.80
- Trả về cấu trúc lỗi nhất quán gồm mã lỗi máy có thể đọc được (machine-readable code), thông báo lỗi và thông tin chi tiết tùy chọn. Độ tin cậy: 0.85
- Đánh phiên bản cho API ngay trên đường dẫn (/v1) và coi lược đồ OpenAPI được tạo ra như một bản hợp đồng giao tiếp được kiểm tra tự động trong quy trình CI. Độ tin cậy: 0.75
- Sử dụng phân trang dựa trên con trỏ (cursor-based pagination) cho các danh sách lớn và giới hạn kích thước trang tối đa ở phía máy chủ. Độ tin cậy: 0.80
- Kiểm thử bằng pytest và httpx.AsyncClient, ghi đè các phụ thuộc (overriding dependencies) thay vì dùng kỹ thuật monkey-patch vào các thành phần nội bộ. Độ tin cậy: 0.90
- Chạy các tiến trình con (workers) của uvicorn phía sau gunicorn hoặc một trình quản lý tiến trình trên môi trường production, và chỉ dùng cờ --reload trong môi trường phát triển (development). Độ tin cậy: 0.80
- Chuyển các tác vụ xử lý chậm sang một hàng đợi tác vụ (task queue) thực thụ như Celery, Arq hoặc Dramatiq; BackgroundTasks chỉ dành cho các công việc nhỏ chạy một lần rồi thôi (fire-and-forget). Độ tin cậy: 0.85
- Thêm ID yêu cầu (request IDs), nhật ký định dạng JSON có cấu trúc và middleware truy vết OpenTelemetry ngay từ ngày đầu tiên. Độ tin cậy: 0.80
- Bảo vệ các endpoint bằng OAuth2 bearer token hoặc khóa API thông qua các phụ thuộc bảo mật (security dependencies) để trang tài liệu tự động hiển thị cơ chế xác thực. Độ tin cậy: 0.80
- Cung cấp riêng biệt hai endpoint /healthz và /readyz, trong đó bước kiểm tra mức độ sẵn sàng (readiness) sẽ kiểm tra kết nối cơ sở dữ liệu và các phụ thuộc cứng khác. Độ tin cậy: 0.85
- Quản lý các thư viện phụ thuộc bằng uv kèm theo tệp khóa (lock file), đồng thời kiểm tra lỗi cú pháp (lint) và định dạng mã nguồn bằng Ruff. Độ tin cậy: 0.75
- Kiểm tra kiểu dữ liệu (type check) bằng mypy hoặc pyright ở chế độ nghiêm ngặt (strict mode) trên gói dịch vụ. Độ tin cậy: 0.70

# Tích hợp Webhook taste của một kỹ sư tích hợp chú trọng độ tin cậy
- Xác minh mọi webhook gửi đến bằng chữ ký HMAC trên phần thân request thô (raw request body) trước khi phân tích cú pháp thành JSON. Độ tin cậy: 0.95
- So sánh chữ ký bằng hàm có thời gian thực thi hằng số (constant-time function), không bao giờ dùng phép kiểm tra bằng nhau trên chuỗi thông thường. Độ tin cậy: 0.95
- Từ chối các lượt gửi có dấu thời gian đã ký cũ hơn khoảng năm phút để chặn tấn công phát lại (replay attacks). Độ tin cậy: 0.90
- Phản hồi mã trạng thái 2xx trong vòng vài giây và thực hiện công việc xử lý thực sự trong một tác vụ nền (background job). Độ tin cậy: 0.95
- Lưu trữ bền vững sự kiện thô trước rồi mới xử lý, để không mất dữ liệu nếu worker bị sập giữa chừng. Độ tin cậy: 0.90
- Khử trùng lặp dựa trên event ID của nhà cung cấp bằng chỉ mục duy nhất (unique index), vì mọi nhà cung cấp đều thử gửi lại và phân phối theo cơ chế ít nhất một lần (at-least-once). Độ tin cậy: 0.95
- Không bao giờ giả định các sự kiện đến đúng thứ tự, hãy so sánh trường version hoặc updated_at trước khi ghi đè trạng thái cục bộ. Độ tin cậy: 0.85
- Coi payload như một gợi ý và truy vấn lại đối tượng hiện tại từ API của nhà cung cấp đối với bất kỳ tác vụ nào liên quan đến tiền bạc. Độ tin cậy: 0.80
- Chỉ trả về mã 4xx cho các request lỗi vĩnh viễn và 5xx cho các lỗi tạm thời để cơ chế thử lại của bên gửi hoạt động chính xác. Độ tin cậy: 0.85
- Hỗ trợ đồng thời ít nhất hai khóa bí mật ký (signing secrets) đang hoạt động để có thể xoay vòng khóa mà không gây gián đoạn dịch vụ (downtime). Độ tin cậy: 0.85
- Khi gửi webhook đi, hãy thử lại với thời gian chờ tăng theo hàm mũ kèm độ nhiễu ngẫu nhiên (exponential backoff and jitter) trong tối đa một ngày hoặc lâu hơn, sau đó vô hiệu hóa endpoint và thông báo cho chủ sở hữu. Độ tin cậy: 0.90
- Gửi một payload gọn nhẹ, có đánh phiên bản kèm theo loại sự kiện (event type), event ID, dấu thời gian và ID tài nguyên thay vì đổ toàn bộ dữ liệu dòng trong cơ sở dữ liệu ra. Độ tin cậy: 0.80
- Đặt tên loại sự kiện theo dạng resource.action ở thì quá khứ, chẳng hạn như invoice.paid hoặc user.deleted. Độ tin cậy: 0.80
- Cung cấp cho khách hàng nhật ký gửi (delivery log) kèm theo request, response, trạng thái và nút phát lại (replay) thủ công. Độ tin cậy: 0.85
- Chặn các URL webhook gửi đi phân giải về địa chỉ mạng riêng tư (private), loopback hoặc link-local để ngăn chặn lỗ hổng SSRF. Độ tin cậy: 0.95
- Sử dụng thời gian chờ (timeout) ngắn và tách biệt cho các lượt gửi đi, đồng thời không bao giờ để một endpoint chậm của khách hàng làm nghẽn hàng đợi dùng chung. Độ tin cậy: 0.90
- Bắt buộc sử dụng HTTPS cho tất cả các webhook endpoint ngoài môi trường phát triển cục bộ. Độ tin cậy: 0.90
- Cung cấp API đối soát hoặc cơ chế đồng bộ định kỳ để phía nhận có thể khôi phục lại các sự kiện bị bỏ lỡ. Độ tin cậy: 0.80
- Kiểm thử các bộ xử lý (handlers) ở môi trường cục bộ bằng CLI của nhà cung cấp hoặc đường hầm (tunnel), và lưu lại các payload mẫu đã ghi nhận làm dữ liệu kiểm thử cố định (test fixtures). Độ tin cậy: 0.80
- Cảnh báo khi tỷ lệ lỗi tăng cao và hàng đợi tồn đọng ngày càng lớn trên từng endpoint, chứ không chỉ cảnh báo trên từng lỗi đơn lẻ. Độ tin cậy: 0.80
- Không bao giờ ghi log toàn bộ payload có chứa dữ liệu cá nhân, thông tin bí mật (secrets) hoặc thông tin thẻ thanh toán. Độ tin cậy: 0.90