Feat blossom stream file from disk

[1-leo]

fixes: #211
dependent on: #332 (merge before)

This PR introduces file streaming so large files are not loaded entirely into memory.
Its non-breaking, old method signatures have not been altered.
Both the files usecase and blossom usecase have the new streaming methods.

• file streaming
• progress report (stream of progress values)
• mirrorToServers()

[codecov]

Codecov Report

❌ Patch coverage is 84.59215% with 51 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.90%. Comparing base (9c82ef7) to head (3ed54c3).
⚠️ Report is 24 commits behind head on master.

Files with missing lines	Patch %	Lines
.../data_layer/repositories/blossom/blossom_impl.dart	85.93%	18 Missing ⚠️
.../ndk/lib/data_layer/data_sources/http_request.dart	72.50%	11 Missing ⚠️
packages/ndk/lib/data_layer/io/file_io_native.dart	76.74%	10 Missing ⚠️
...s/ndk/lib/domain_layer/usecases/files/blossom.dart	87.30%	8 Missing ⚠️
...ib/domain_layer/entities/blob_upload_progress.dart	82.35%	3 Missing ⚠️
.../lib/domain_layer/entities/file_hash_progress.dart	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #341      +/-   ##
==========================================
+ Coverage   75.37%   75.90%   +0.53%     
==========================================
  Files         148      152       +4     
  Lines        5908     6201     +293     
==========================================
+ Hits         4453     4707     +254     
- Misses       1455     1494      +39     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nogringo]

Is it possible to cancel an upload ?

[1-leo]

Is it possible to cancel an upload ?

for uploadFromFile yes, you can just cancel the returned stream .cancel()
for the in memory no

[1-leo]

• add to demo app

[frnandu]

nice!

[nogringo]

Currently, the file is read twice. We can optimize it to read it once if the server does not require auth.

UploadFromFile flow

verifyHash = false

1. Send bytes to the server
   • If server requires auth:
     1. Calculate hash locally
     2. Create the auth event
     3. Resend bytes
2. Server sends the blob descriptor

verifyHash = true

1. Start reading file (bytes are used for both hash + upload in parallel)
   • If server asks for auth:
     1. Continue calculating hash, stop uploading
     2. Once hash is calculated, create the auth event
     3. Resend bytes to the server
2. Both hash and blob descriptor are done
3. Verify blob descriptor hash matches local hash

[nogringo]

I got this Idea for optimizing the flow in some cases but IMO it add too much complexity so the idea is here but we don't need to implement it.

[nogringo]

The implementation that we need is BUD-06

[nogringo]

Currently, the progress only reflects the upload phase. Hash calculation and mirroring phases have no progress reporting.

Report progress for each phase separately:

class BlobUploadProgress {                                                   
  final UploadPhase phase;         // hashing | uploading | mirroring        
  final double progress;           // 0.0 - 1.0 for current phase           
                                                                             
  // For mirroring phase                                                     
  final int mirrorsTotal;                                                    
  final int mirrorsCompleted;                                                
} 

Example flow

Phase: hashing    → progress: 0% ... 50% ... 100%                            
Phase: uploading  → progress: 0% ... 50% ... 100%                            
Phase: mirroring  → progress: 0/3 ... 2/3 ... 3/3                            

This lets developers show accurate progress for each phase instead of the current behavior where progress stays at 0% during hashing.

[1-leo]

Start reading file (bytes are used for both hash + upload in parallel)

Currently, the file is read twice. We can optimize it to read it once if the server does not require auth.

UploadFromFile flow

verifyHash = false

1. Send bytes to the server
   
   * If server requires auth:
     
     1. Calculate hash locally
     2. Create the auth event
     3. Resend bytes

2. Server sends the blob descriptor

verifyHash = true

1. Start reading file (bytes are used for both hash + upload in parallel)
   
   * If server asks for auth:
     
     1. Continue calculating hash, stop uploading
     2. Once hash is calculated, create the auth event
     3. Resend bytes to the server

2. Both hash and blob descriptor are done

3. Verify blob descriptor hash matches local hash

The described verifyHash = true flow won't work in parallel because we need the hash before uploading, and reading the file once would require storing it in memory.
It could work if the developer provides the hash, but when is this the case?

[nogringo]

BlobUploadProgress and UploadPhase are not exported from the public API.