90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# 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. |