Skip to content

TLS_API_GUIDE.md

Latest commit

 

History

History
291 lines (225 loc) · 6.96 KB

TLS_API_GUIDE.md

File metadata and controls

291 lines (225 loc) · 6.96 KB

TLS/SSL API - Fixed for Vercel Timeouts

What Was Wrong

Before

  • SSL Labs analysis takes 60-120 seconds for a full scan
  • API was polling up to 6 times with 4-second delays = 24+ seconds
  • Vercel Hobby plan has a 10-second timeout
  • Result: 504 Gateway Timeout error
  • Error response was HTML, not JSON, causing parsing errors

The Error You Saw

"Unexpected token 'A', 'An error o'..."

This was Vercel's HTML error page starting with "An error occurred..."

How It Works Now

Smart Caching Strategy

The API now uses a cache-first approach:

1. Check SSL Labs Cache (fast, < 1 second)
   ├─ READY? → Return results immediately ✅
   ├─ IN_PROGRESS? → Tell user to wait and retry 🔄
   └─ NO_CACHE? → Start new scan, tell user to retry ⏱️

2. Never wait/poll (prevents timeout)
3. User retries after 1-2 minutes to get results

Response Types

✅ Success (Cached Results)

{
  "status": "READY",
  "endpoints": [...],
  "host": "example.com",
  // ... full SSL Labs data
}

🔄 Pending (Scan In Progress)

{
  "status": "PENDING",
  "message": "SSL Labs is analyzing this domain. Please try again in a moment.",
  "host": "example.com",
  "statusDetails": "Analysis in progress"
}

⏱️ First Time Scan

{
  "status": "PENDING",
  "message": "SSL Labs scan initiated. Please try again in 1-2 minutes.",
  "host": "example.com",
  "hint": "SSL Labs performs a comprehensive analysis which takes time."
}

❌ Error

{
  "error": "Failed to fetch TLS data",
  "message": "Specific error details",
  "host": "example.com",
  "suggestion": "Try again or check if domain is accessible"
}

User Experience

First Request

User runs: /tls example.com

If domain was never scanned or cache is old:

Response: "SSL Labs scan initiated. Please try again in 1-2 minutes."
Action: API triggers background scan (fire-and-forget)

Second Request (1-2 minutes later)

User runs: /tls example.com again

If scan is still running:

Response: "SSL Labs is analyzing this domain. Please try again in a moment."

If scan completed:

Response: Full SSL Labs analysis with grades, vulnerabilities, etc.

Subsequent Requests

SSL Labs caches results for 24 hours, so future requests are instant! ⚡

Technical Details

Timeout Handling

  • Request timeout: 8 seconds (under 10s limit)
  • No polling: Prevents cumulative timeout
  • AbortController: Properly cancels long requests
  • JSON responses: Always returns valid JSON, even for errors

SSL Labs API Parameters

  • fromCache=on: Check cache first
  • all=done: Only return completed scans
  • startNew=on: Trigger new scan (fire-and-forget)

Error Handling

try {
  // Try to fetch with timeout
} catch (AbortError) {
  // Return timeout message
} catch (Error) {
  // Return error message
}

Testing

Test Locally

# First request (should trigger scan)
curl "http://localhost:5173/api/tls?host=example.com"

# Response: PENDING

# Wait 1-2 minutes, then retry
curl "http://localhost:5173/api/tls?host=example.com"

# Response: Full results

Test on Vercel

# First request
curl "https://your-app.vercel.app/api/tls?host=example.com"

# Check logs
vercel logs --since 10m

Common Scenarios

Scenario 1: Popular Domain (Already Cached)

Request: /tls google.com
Response: Immediate results ✅
Why: Google is scanned frequently, cache is fresh

Scenario 2: Your Domain (First Scan)

Request 1: /tls mydomain.com
Response: "Please try again in 1-2 minutes" 🔄

[Wait 90 seconds]

Request 2: /tls mydomain.com
Response: Full results ✅

Scenario 3: Invalid Domain

Request: /tls invalid.domain.xyz
Response: SSL Labs error (domain doesn't exist) ❌

Scenario 4: SSL Labs Under Load

Request: /tls example.com
Response: "Please try again in a moment" 🔄
Why: SSL Labs API is slow/busy

Comparison with Other Tools

Tool Speed Depth Timeout Issues
SSL Labs Slow (60-120s) Deep analysis Fixed with cache-first
Qualys SSL Test Slow (60-90s) Very deep Would have same issue
SSL Checker Fast (5-10s) Basic Would work
testssl.sh Medium (20-40s) Deep Would timeout

Why we use SSL Labs:

  • Industry standard
  • Most comprehensive
  • Free API
  • Trusted by security professionals
  • Cache makes it fast for repeated checks

Troubleshooting

"Please try again in 1-2 minutes"

This is normal! SSL Labs needs time to:

  1. Connect to your server
  2. Test all SSL/TLS protocols
  3. Check for vulnerabilities
  4. Generate comprehensive report
  5. Cache results

Solution: Wait and retry. Second request will be instant.

Still Getting Timeout

Unlikely, but if it happens:

  1. Check SSL Labs Status

  2. Check Domain Accessibility

    curl -I https://yourdomain.com

  3. Check Vercel Logs

    vercel logs --since 10m

  4. Use Alternative

Error: "SSL Labs API returned 429"

Rate limited! SSL Labs limits:

  • Max 1 scan per domain per minute
  • Max 25 scans per hour from one IP

Solution: Wait 60 seconds and retry.

Improvements Made

✅ No More 504 Timeouts - Returns within 8 seconds
✅ Always Valid JSON - No more parsing errors
✅ Better Error Messages - Clear, actionable guidance
✅ Smart Caching - Uses SSL Labs 24-hour cache
✅ Fire-and-Forget Scans - Triggers scan without waiting
✅ User-Friendly Flow - Clear instructions to retry

Alternative: Get Results Faster

If you need instant results without waiting:

Option 1: Pre-scan Domains

Run scans manually before users test:

# Pre-scan your domains
curl "https://api.ssllabs.com/api/v3/analyze?host=yourdomain.com&startNew=on"

Option 2: Use Different Service

For instant results, consider:

  • Mozilla Observatory - Fast, good for headers
  • SecurityHeaders.com - Very fast, focused on headers
  • SSLMate - Faster but less detailed

Option 3: Run Your Own Scanner

  • testssl.sh - Command-line tool
  • sslyze - Python library
  • Requires your own infrastructure

Best Practices

  1. First Scan - Let users know it takes time
  2. Show Progress - Display "Analysis in progress" message
  3. Cache Results - Store in localStorage to avoid re-scanning
  4. Batch Scans - Scan multiple domains during off-peak hours
  5. Monitor - Track which domains are scanned most

Summary

The TLS API now works reliably within Vercel's timeout limits by:

  • Checking cache first (fast)
  • Never polling/waiting (prevents timeout)
  • Returning helpful PENDING status
  • Triggering background scans
  • Letting users retry for results

Result: No more 504 errors, always valid JSON responses! 🎉