120 lines
3.3 KiB
Markdown
120 lines
3.3 KiB
Markdown
# Hash Algorithm Migration Strategy
|
|
|
|
## Overview
|
|
|
|
The NIP variant system is designed to support multiple hash algorithms simultaneously, enabling seamless migration from BLAKE2b to BLAKE3 (or future algorithms) without breaking existing installations.
|
|
|
|
## Current Implementation
|
|
|
|
### Supported Algorithms
|
|
|
|
- **BLAKE2b** (current): `blake2b-[hash]`
|
|
- **BLAKE3** (future): `blake3-[hash]`
|
|
|
|
### Path Format
|
|
|
|
Variant paths include the hash algorithm prefix:
|
|
```
|
|
/Programs/<PackageName>/<Version>-<Algorithm>-<Hash>/
|
|
```
|
|
|
|
Examples:
|
|
- `/Programs/nginx/1.28.0-blake2b-abc123def456/`
|
|
- `/Programs/nginx/1.29.0-blake3-xyz789abc123/`
|
|
|
|
## Forward Compatibility
|
|
|
|
### Algorithm Detection
|
|
|
|
The path manager automatically detects which hash algorithm is used:
|
|
|
|
```nim
|
|
let algo = detectHashAlgorithm(path)
|
|
# Returns: "blake2b", "blake3", or "" if unknown
|
|
```
|
|
|
|
### Coexistence
|
|
|
|
Multiple hash algorithms can coexist on the same system:
|
|
- Old packages with BLAKE2b hashes remain valid
|
|
- New packages with BLAKE3 hashes work alongside them
|
|
- All path operations work regardless of algorithm
|
|
|
|
## Migration Scenarios
|
|
|
|
### Scenario 1: Gradual Migration
|
|
|
|
Routers running for years with BLAKE2b packages:
|
|
1. System continues to work with existing BLAKE2b packages
|
|
2. New package installations use BLAKE3
|
|
3. Both algorithms coexist indefinitely
|
|
4. No forced migration required
|
|
|
|
### Scenario 2: Package Updates
|
|
|
|
When a package is updated:
|
|
- Old version: `/Programs/nginx/1.27.0-blake2b-old123/`
|
|
- New version: `/Programs/nginx/1.28.0-blake3-new456/`
|
|
- Both versions can coexist (different versions)
|
|
- Rollback to old version always possible
|
|
|
|
### Scenario 3: Same Version, Different Hash
|
|
|
|
If the same version is rebuilt with a different algorithm:
|
|
- `/Programs/nginx/1.28.0-blake2b-abc123/`
|
|
- `/Programs/nginx/1.28.0-blake3-xyz789/`
|
|
- These are treated as different variants
|
|
- Both can coexist (different fingerprints)
|
|
|
|
## Implementation Details
|
|
|
|
### Validation
|
|
|
|
The `validateVariantPath()` function checks for any supported algorithm:
|
|
```nim
|
|
const SUPPORTED_HASH_PREFIXES* = ["blake2b-", "blake3-"]
|
|
```
|
|
|
|
### Extraction
|
|
|
|
Version and fingerprint extraction work with any supported algorithm:
|
|
- `extractVersionFromPath()` - tries all supported prefixes
|
|
- `extractFingerprintFromPath()` - returns full hash with algorithm prefix
|
|
|
|
## Adding New Algorithms
|
|
|
|
To add support for a new hash algorithm:
|
|
|
|
1. Add prefix to `SUPPORTED_HASH_PREFIXES` in `variant_paths.nim`
|
|
2. Implement hash calculation in `variant_fingerprint.nim`
|
|
3. No changes needed to path validation or parsing
|
|
4. Existing packages continue to work
|
|
|
|
## Testing
|
|
|
|
Comprehensive tests ensure compatibility:
|
|
- 63 tests covering all path operations
|
|
- Specific tests for blake2b/blake3 coexistence
|
|
- Migration scenario tests
|
|
- Algorithm detection tests
|
|
|
|
## Recommendations
|
|
|
|
1. **Don't force migration**: Let old packages remain with BLAKE2b
|
|
2. **Use BLAKE3 for new packages**: When available in Nimble
|
|
3. **Document algorithm in metadata**: Store which algorithm was used
|
|
4. **Monitor both algorithms**: System should track usage of each
|
|
|
|
## Future Considerations
|
|
|
|
- Add algorithm preference configuration
|
|
- Implement automatic re-hashing tools (optional)
|
|
- Add metrics for algorithm usage
|
|
- Consider algorithm-specific optimizations
|
|
|
|
---
|
|
|
|
**Status**: Implemented and tested
|
|
**Compatibility**: Full backward and forward compatibility
|
|
**Risk**: Low - existing systems unaffected
|