rspade_system/app/RSpade/Ide/Services/SESSION_RECOVERY.md

IDE Services Session Recovery Mechanism

Overview

The VS Code extension now includes automatic session recovery for IDE services. Session files are treated as ephemeral and automatically recreated when needed.

How It Works

Server Side (handler.php)

• Sessions are stored in /storage/rsx-ide-bridge/auth-{session}.json files
• These files are transient and can be deleted anytime (e.g., during cache clear)
• When a session is not found, the server returns:

  {
    "error": "Session not found",
    "code": 401,
    "recoverable": true,
    "recovery": "Create new session via POST /_ide/service/auth/create"
  }
  

Client Side (VS Code Extension)

The extension automatically recovers from session loss:

1. Initial Request: Attempts to use existing session if available
2. Session Not Found: If server returns 401 with "Session not found"
3. Automatic Recovery:
   • Creates new session via /auth/create
   • Retries the original request with new session
4. Transparent to User: No user intervention required

Implementation

TypeScript/JavaScript (formatting_provider.ts)

async make_authenticated_request(endpoint: string, data: any, retry_count: number = 0) {
    // Try the request
    try {
        const response = await this.make_request(endpoint, data, 'POST', true, headers);
        return response;
    } catch (error: any) {
        // Check if recoverable
        if (retry_count === 0 && error.message.includes('Session not found')) {
            // Clear old session
            this.auth_data = null;
            // Retry with new session
            return this.make_authenticated_request(endpoint, data, retry_count + 1);
        }
        throw error;
    }
}

Benefits

1. Zero Configuration: Works automatically, no setup needed
2. Resilient: Survives cache clears, server restarts, file deletions
3. Transparent: Users never see authentication errors
4. Stateless: Session files are temporary and disposable

Testing

1. Normal Operation: Extension should work normally
2. Session Deletion: Delete /storage/rsx-ide-bridge/auth-*.json files
3. Cache Clear: Run php artisan rsx:clean
4. Expected Result: Extension automatically recovers and continues working

Troubleshooting

If recovery fails:

1. Check server logs: /storage/logs/laravel.log
2. Check VS Code Output panel: "RSpade Formatter" channel
3. Verify /_ide/service/auth/create endpoint is accessible
4. Ensure workspace has write permissions for /storage/rsx-ide-bridge/

Security Notes

• Sessions are workspace-specific (stored locally)
• Each session has unique client/server keys
• Signatures prevent replay attacks
• Sessions can be manually revoked by deleting files