Playbook: Resilient Caller Standard

Mục đích

Tiêu chuẩn bắt buộc cho mọi cuộc gọi đến Cloud Run services và external APIs.

Cấu hình tiêu chuẩn

Tham số	Giá trị	Lý do
Max retries	3	Đủ cho cold start (~5-8s)
Backoff	1s, 2s, 4s (exponential)	Cho Cloud Run warm up
Client timeout	30s	Cold start có thể mất 10-15s
Startup timeout	60s	Init Qdrant connection lâu hơn
Retry conditions	timeout, 503, 504, ConnectionError	Chỉ transient errors

Kiến trúc 2 tầng

Tầng 1 — Server-side (trong Cloud Run)

• Module: agent_data/resilient_client.py
• ResilientCaller class: async httpx + tenacity
• sync_retry decorator: wrap Qdrant/OpenAI SDK calls
• Startup probes: verify connections trước khi nhận traffic
• /health endpoint: chi tiết per-service status

Tầng 2 — Client-side (phía gọi)

• Nuxt: ofetch built-in retry ($fetch('/api/data', { retry: 3 }))
• Python scripts: scripts/utils/resilient_fetch.py
• Directus Flows: cấu hình retry trong Request Node

Phonebook Pattern

• KHÔNG hardcode URLs — đọc từ env vars
• Convention: SERVICE_{NAME}_URL cho auto-discovery
• Backward compat: QDRANT_URL, OPENAI_API_URL vẫn hoạt động
• Thêm service mới = thêm 1 env var, không sửa code

Startup Probe (Cloud Run)

--startup-probe-path="/health"
--startup-probe-period=5
--startup-probe-failure-threshold=12

Container KHÔNG nhận traffic cho đến khi /health OK.

Áp dụng

• BẮT BUỘC cho mọi Cloud Run service (hiện tại và tương lai)
• BẮT BUỘC async-only (httpx, không requests)
• BẮT BUỘC dùng tenacity (không tự viết retry logic)

Ngày hiệu lực

2026-02-08, phê duyệt bởi User + Claude + Gemini