Redflag/docs/3_BACKLOG/P2-001_Binary-URL-Architecture-Mismatch.md

Binary URL Architecture Mismatch Fix

Priority: P2 (New Feature - Critical Fix) Source Reference: From DEVELOPMENT_TODOS.md line 302 Status: Ready for Implementation

Problem Statement

The installation script template uses /downloads/{platform} URLs where platform = "linux", but the server only provides files at /downloads/linux-amd64 and /downloads/linux-arm64. This causes binary downloads to fail with 404 errors, resulting in empty or corrupted files that cannot be executed.

Feature Description

Fix the binary URL architecture mismatch by implementing server-side redirects that handle generic platform requests and redirect them to the appropriate architecture-specific binaries.

Acceptance Criteria

1. Server should respond to /downloads/linux requests with redirects to /downloads/linux-amd64
2. Server should maintain backward compatibility for existing installation scripts
3. Installation script should work correctly for x86_64 systems without modification
4. ARM systems should be properly handled with appropriate redirects
5. Error handling should return clear messages for unsupported architectures

Technical Approach

Option D: Server-Side Redirect Implementation (Recommended)

1. Modify Download Handler (aggregator-server/internal/api/handlers/downloads.go)

   • Add route handler for /downloads/{platform} where platform is generic ("linux", "windows")
   • Detect client architecture from User-Agent headers or default to x86_64
   • Return HTTP 301 redirect to architecture-specific URL
   • Example: /downloads/linux → /downloads/linux-amd64

2. Architecture Detection

   • Default x86_64 systems to /downloads/linux-amd64
   • Use User-Agent parsing for ARM detection when available
   • Fallback to x86_64 for unknown architectures

3. Error Handling

   • Return proper 404 for truly unsupported platforms
   • Log redirect attempts for monitoring

Definition of Done

• ✅ Installation scripts can successfully download binaries using generic platform URLs
• ✅ No 404 errors for x86_64 systems
• ✅ Proper redirect behavior implemented
• ✅ Backward compatibility maintained
• ✅ Error cases handled gracefully
• ✅ Integration testing shows successful agent installations

Test Plan

1. Unit Tests

   • Test redirect handler with various User-Agent strings
   • Test architecture detection logic
   • Test error handling for invalid platforms

2. Integration Tests

   • Test complete installation flow using generic URLs
   • Test Linux x86_64 installation (should redirect to amd64)
   • Test Windows x86_64 installation
   • Test error handling for unsupported platforms

3. Manual Tests

   • Run installation script on fresh Linux system
   • Verify binary download succeeds
   • Verify agent starts correctly after installation
   • Test with both generic and specific URLs

Files to Modify

• aggregator-server/internal/api/handlers/downloads.go - Add redirect handler
• aggregator-server/cmd/server/main.go - Add new route
• Test files for the download handler

Estimated Effort

• Development: 4-6 hours
• Testing: 2-3 hours
• Review: 1-2 hours

Dependencies

• None - this is a self-contained server-side fix
• Install script templates can remain unchanged
• Existing architecture-specific download endpoints remain functional

Risk Assessment

Low Risk - This is purely additive functionality that maintains backward compatibility while fixing a critical bug. The redirect pattern is a well-established HTTP pattern with minimal risk of side effects.