quantum_upload 📦 #

Upload large files over unreliable networks — reliably.
Splits. Persists. Resumes. Works with any HTTP server.

The Problem #

You're uploading a 2 GB video. The network drops at 99%.
You start again from zero. You cry.

The Solution #

quantum_upload splits the file into small pieces, confirms each one with the server, and saves progress locally. When the network drops, it picks up from the last confirmed piece — not from the beginning.

Features #

Installation #

dependencies:
  quantum_upload: ^1.0.0

dart pub get

Quick Start #

import 'package:quantum_upload/quantum_upload.dart';

final result = await Uploader.upload(
  filePath: '/path/to/video.mp4',
  url: 'https://api.example.com/upload',
  headers: {'Authorization': 'Bearer $token'},
  onProgress: (pct) => print('${pct.toStringAsFixed(1)} %'),
);

print('Done in ${result.duration.inSeconds}s @ ${result.speedMbps}');

Advanced Usage #

Full configuration #

final config = UploadConfig(
  filePath   : '/path/to/video.mp4',
  url        : Uri.parse('https://api.example.com/upload'),
  chunkSize  : 10 * 1024 * 1024,          // 10 MiB chunks
  maxRetries : 5,
  retryDelay : const Duration(seconds: 2), // 2 s → 4 s → 8 s → …
  headers    : {'Authorization': 'Bearer $token'},
  sessionId  : savedSessionId,             // null = fresh upload
  onProgress   : (pct)          => setState(() => _progress = pct),
  onChunkRetry : (chunk, attempt) => print('Retrying chunk $chunk ($attempt)'),
  onComplete   : (result)        => print('Done! ${result.speedMbps}'),
  onError      : (err)           => showErrorDialog(err.message),
);

final uploader = Uploader(config);
await uploader.start();

Pause and resume #

final uploader = Uploader(config);
unawaited(uploader.start());   // fire and forget in background

// From UI buttons:
uploader.pause();              // stops after current chunk finishes
uploader.resume();             // continues immediately
await uploader.cancel();       // permanent — cleans up session

Cross-session resume (app restart) #

// ── Run 1 — save the session ID ─────────────────────────────────
final uploader = Uploader(config);
await prefs.setString('uploadSession', uploader.sessionId);
await uploader.start();

// ── Run 2 — resume automatically ────────────────────────────────
await Uploader.upload(
  filePath  : '/path/to/video.mp4',
  url       : 'https://api.example.com/upload',
  sessionId : prefs.getString('uploadSession'),  // ← magic
);

Rich progress stream #

uploader.progressStream.listen((snap) {
  print(
    '[${snap.percent.toStringAsFixed(1).padLeft(5)}%]  '
    '${snap.uploadedFormatted} / ${snap.totalFormatted}  '
    '@ ${snap.speedMbps}  ETA ${snap.etaFormatted}',
  );
});

Sample output:

[ 12.5%]    12.50 MiB /  100.00 MiB  @  8.32 MB/s  ETA 10:38
[ 25.0%]    25.00 MiB /  100.00 MiB  @  9.01 MB/s  ETA 08:21

How It Works #

Uploader.start()
│
├─ ChunkManager.initialize()
│   └─ compute chunk boundaries: [(0, 5M), (5M, 10M), …]
│
├─ UploadSession.restore(sessionId) or create fresh
│   └─ persisted in SharedPreferences as JSON
│
└─ for each pending chunk:
    ├─ readChunk(i)           — RandomAccessFile.setPosition + read
    ├─ computeChecksum(data)  — MD5 hex
    ├─ RetryPolicy.executeChunk(() => UploadRequest.send(…))
    │   └─ on success: markChunkCompleted(i) + session.save()
    │   └─ on fail:    exponential back-off → retry
    └─ progressTracker.addBytes(chunkSize)

→ UploadResult  (session deleted from storage)

HTTP Wire Format #

Every chunk is a standard multipart/form-data POST:

POST /upload
Content-Type: multipart/form-data; boundary=…

X-Session-Id:     c3d4e5f6-…
X-Chunk-Index:    3
X-Total-Chunks:   40
X-Chunk-Checksum: a3f4b2c1d5e6…   (MD5 hex)
X-File-Size:      209715200
Content-Range:    bytes 15728640-20971519/209715200
Authorization:    Bearer <your-token>   (from config.headers)

--boundary
Content-Disposition: form-data; name="chunk"; filename="chunk_3"

<raw 5 MiB bytes>
--boundary--

See example/server_example/server.js for a Node.js reference implementation.

Package Architecture #

lib/
├── quantum_upload.dart       ← barrel (one import for everything)
└── src/
    ├── uploader.dart           ← main orchestrator — start/pause/resume/cancel
    ├── chunk_manager.dart      ← file splitting + chunk reading + MD5
    ├── upload_session.dart     ← persistent per-chunk state
    ├── upload_request.dart     ← HTTP multipart builder + sender
    ├── retry_policy.dart       ← exponential back-off executor
    ├── progress_tracker.dart   ← EMA speed, ETA, stream emitter
    ├── models/
    │   ├── upload_config.dart  ← immutable configuration value object
    │   ├── upload_state.dart   ← enum: idle|uploading|paused|…|completed
    │   ├── chunk_info.dart     ← byte-range + state + checksum per chunk
    │   └── upload_result.dart  ← final summary (speed, chunks, duration)
    ├── storage/
    │   ├── session_storage.dart        ← abstract interface
    │   └── shared_prefs_storage.dart   ← default implementation
    └── exceptions/
        ├── upload_exception.dart   ← base class
        ├── chunk_exception.dart    ← per-chunk failure (HTTP status, body)
        └── session_exception.dart  ← storage failure

Comparison #

Tests #

dart test
dart test --coverage=coverage
dart pub global run coverage:format_coverage --lcov \
    --in=coverage --out=lcov.info --report-on=lib

Test suite covers:

• chunk_manager_test.dart — boundary computation, byte reading, checksums
• upload_session_test.dart — persistence, restore, mutation
• retry_policy_test.dart — should-retry logic, delay formula, executors
• progress_tracker_test.dart — EMA speed, ETA, stream emissions
• uploader_test.dart — end-to-end with MockHttpClient

Contributing #

1. Fork the repo and create a feature branch.
2. Write tests for every new behaviour.
3. Run dart analyze && dart test — both must pass.
4. Submit a pull request with a clear description.

License #

MIT © 2026 — see LICENSE.