Limits of k6’s HTTP module for automatic token refresh and expired credential handling

Answer

Short answer: k6 should not ship a built‑in token‑refresh feature. The current design keeps authentication fully under the test script’s control, which preserves flexibility, avoids hidden latency, and keeps the runtime lightweight.

Confirmed Facts

• The http module exposes only request primitives; there is no automatic retry or refresh logic in the core runtime.
• Virtual Users (VUs) run isolated JavaScript engines; a token refreshed in one VU is not automatically visible to others unless explicitly shared.
• Manual 401‑based retry patterns are common in k6 scripts, using shared variables or SharedArray to store a refreshed token.
• Introducing a global refresh mechanism would require stateful coordination across VUs, potentially causing a thundering herd against the identity provider during high‑load phases.
• Automatic refresh could mask real performance bottlenecks by hiding the latency of the renewal call.

Likely Explanation

Adding a built‑in token‑lifecycle API would:

• Increase the core’s dependency footprint (e.g., need an OAuth2 client library).
• Complicate the priority between user‑supplied headers, cookies, and the runtime‑managed token.
• Potentially break backward compatibility for scripts that rely on custom authentication flows.
• Reduce flexibility for non‑standard auth schemes (e.g., API keys, JWTs signed with custom claims).

Recommended Manual Approach

1. Detect expiration: After each request, check for a 401 or a custom header indicating token expiry.
2. Refresh token:
   • Call the token endpoint in a separate request.
   • Store the new token in a global variable or a SharedArray if it is immutable.
   • Use http.batch or http.get with a retry loop if the refresh itself fails.
3. Inject token:
   • Set Authorization header on subsequent requests using the refreshed token.
   • Prefer http.setDefaultOptions to avoid repeating header code, but remember that this is VU‑local.
4. Avoid thundering herd:
   • Introduce a short random back‑off before retrying the refresh.
   • Use a shared Mutex (via k6/x/crypto) if you need to serialize token updates across VUs.
5. Validate:

   import http from 'k6/http';
   export default function () {
     const res = http.get('https://api.example.com/data');
     if (res.status === 401) {
       const tokenRes = http.post('https://auth.example.com/token', {grant_type: 'client_credentials'});
       if (tokenRes.status === 200) {
         const token = JSON.parse(tokenRes.body).access_token;
         http.setDefaultOptions({headers: {Authorization: `Bearer ${token}`}});
       }
     }
   }
   

Diagnostic Detail Needed

Does the target API provide a predictable expiry header (e.g., expires_in or exp claim) that can be parsed ahead of time, or must the script rely solely on 401 responses?

Verification Checklist

• Run a minimal script that intentionally returns 401 and confirm that k6 does not auto‑retry.
• Check that a token stored in global is not visible across VUs unless explicitly shared.
• Confirm that adding http.setDefaultOptions after a token refresh applies only to the current VU.