refresh-token
Quy tắc JWT refresh token service trong SASUCO InvoiceEasy. Dùng khi: implement TokenRefreshService, auto refresh access token trước khi hết hạn, JWT decode client-side, smart scheduling với setTimeou
SKILL.md.claude/skills/_archived-sasuco/refresh-token/SKILL.md
GitHubJWT Refresh Token Service — SASUCO InvoiceEasy
Tổng Quan
JWT-based Smart Refresh Service (v2.0) — Background service tự động làm mới access token trước khi hết hạn:
- ✅ Decode JWT client-side để lấy
exptimestamp - ✅ Schedule một lần
setTimeout(KHÔNG dùngsetInterval) - ✅ Gọi API refresh DUY NHẤT khi token còn 30 giây
- ✅ Retry tối đa 3 lần nếu thất bại, sau đó logout
File Structure
/shared/services/api/
├── TokenManager.ts ← Hiện có — lưu/đọc tokens
├── TokenRefreshService.ts ← NEW v2.0 — Smart scheduling
├── JwtUtils.ts ← NEW — JWT decode utility
├── ApiClient.ts ← Hiện có
└── index.ts ← Cập nhật export
Configuration
const CONFIG = {
REFRESH_THRESHOLD: 30 * 1000, // 30 giây trước khi hết hạn
RETRY_DELAY: 5 * 1000, // 5 giây giữa các retry
MAX_RETRIES: 3, // Tổng số lần thử
}
Service API
class TokenRefreshService {
static start(): void // Gọi SAU KHI login thành công
static stop(): void // Gọi KHI logout
static isRunning(): boolean
static refreshNow(): Promise<boolean> // Manual (debug)
static getNextRefreshTime(): number | null
}
Flow Chuẩn
LOGIN thành công
↓
Decode JWT → lấy exp
↓
delay = (exp - 30s) - now
↓
setTimeout(() => refreshToken(), delay)
↓
[Token còn 30 giây] setTimeout fires
↓
Gọi API /auth/refresh-token
↓
Thành công? → Lưu tokens mới → Schedule lại refresh
↓ Thất bại
Wait 5s → Retry (tối đa 3 lần)
↓ Hết retry
Logout user
State Management
interface ServiceState {
timeoutId: NodeJS.Timeout | null // setTimeout ID (KHÔNG phải interval)
isRunning: boolean
isRefreshing: boolean // Mutex flag — ngăn concurrent refresh
retryCount: number
nextRefreshTime: number | null
lastRefreshTime: number
}
Nguyên Tắc Quan Trọng
- ✅ Dùng
setTimeout— KHÔNG dùngsetInterval - ✅ Decode JWT client-side — KHÔNG gọi API kiểm tra token
- ✅
isRefreshingmutex — KHÔNG cho phép concurrent refresh - ✅
stop()phải gọiclearTimeout()ngay lập tức khi logout - ❌ KHÔNG check token bằng cách polling mỗi N giây
Retry Logic (Loop-based, KHÔNG dùng đệ quy)
// ✅ ĐúNG: Loop-based retry
let retried = 0
while (retried < CONFIG.MAX_RETRIES) {
retried++
await new Promise(resolve => setTimeout(resolve, CONFIG.RETRY_DELAY))
const retrySuccess = await callRefreshApi()
if (retrySuccess) {
// Lưu tokens mới, schedule lại, reset retry count
scheduleNextRefresh()
state.retryCount = 0
return
}
}
// Hết retry → Logout user
AuthService.logout()
// ❌ SAI: Recursive retry (gây stack overflow)
async function performRefresh() {
const success = await callRefreshApi()
if (!success) performRefresh() // ❌
}
Tích Hợp với AuthService
// Sau khi login thành công:
const tokens = await AuthService.login(credentials)
TokenManager.saveTokens(tokens)
TokenRefreshService.start() // Bắt đầu background service
// Khi logout:
TokenRefreshService.stop() // Dừng service TRƯỚC khi clear tokens
TokenManager.clearTokens()
redirectToLogin()