aminet-mirror

Purpose

Manages selective mirroring of Aminet packages to the local filesystem. Handles single-package fetching with ordered mirror fallback, SHA-256 integrity verification, persistent mirror state tracking with 7-state status enum, concurrent bulk downloads with rate limiting, and sync detection comparing local state against the INDEX.

Capabilities

• Single-package fetch with ordered mirror fallback
• Directory hierarchy preservation matching Aminet structure
• Non-fatal .readme download (best-effort alongside archive)
• User-Agent header on all HTTP requests
• SHA-256 integrity verification via node:crypto
• Size verification with +/-1 KB tolerance for Aminet metadata rounding
• Combined integrity result (hash + size) in single check
• 7-state PackageStatus enum tracking full lifecycle
• Atomic write-then-rename for mirror state persistence
• Immutable updateEntry pattern for safe concurrent access
• Bulk download with async semaphore concurrency control
• Global rate limiting gate between requests
• Resume from interruption (skips already-mirrored packages)
• Serialized state writes via Promise chain mutex
• Sync detection comparing mirror state vs INDEX by sizeKb
• O(1) Map lookup for efficient change detection
• Only change-eligible statuses compared (mirrored+)

Key Modules

| Module | Purpose | |--------|---------| | src/aminet/package-fetcher.ts | Single-package fetch with ordered mirror fallback and .readme | | src/aminet/mirror-state.ts | 7-state status enum, atomic persistence, immutable updateEntry | | src/aminet/integrity.ts | SHA-256 hash and size verification with combined IntegrityResult | | src/aminet/bulk-downloader.ts | Concurrent downloads with semaphore, rate limiting, resume support | | src/aminet/sync-detector.ts | Detects INDEX changes against local mirror state via Map lookup |

Usage Examples

Fetch a single package:

import { fetchPackage } from './package-fetcher.js';

const result = await fetchPackage({
  entry: indexEntry,
  mirrors: ['https://aminet.net', 'https://de.aminet.net'],
  outputDir: './mirror',
});
// Downloads archive + .readme, preserves directory structure

Verify integrity:

import { verifyIntegrity } from './integrity.js';

const result = await verifyIntegrity(filePath, { expectedSha256: hash, expectedSizeKb: 42 });
// result.valid, result.hashMatch, result.sizeMatch

Bulk download with concurrency:

import { bulkDownload } from './bulk-downloader.js';

await bulkDownload({
  entries: selectedPackages,
  mirrors,
  outputDir: './mirror',
  concurrency: 4,
  rateLimit: 500, // ms between requests
  onProgress: (completed, total) => console.log(`${completed}/${total}`),
});

Detect sync changes:

import { detectChanges } from './sync-detector.js';

const changes = detectChanges(mirrorState, currentIndex);
// changes: { added: [], updated: [], removed: [] }

Dependencies

• Node.js node:crypto for SHA-256 hashing
• Node.js node:fs for mirror state persistence and file I/O
• HTTP client for mirror downloads
• Aminet mirror network (ordered fallback list)

Token Budget Rationale

1.0% budget reflects the 5 modules covering fetch, state, integrity, bulk download, and sync detection. The concurrency control, rate limiting, and atomic state persistence patterns require moderate context for safe operation.