System.Net.HttpClient: Download mit Resume – Range-Requests, ETag-Prüfung und saubere Partial-File-Strategie

Scena este neplăcută, dar tipică: un job nocturn încarcă un arhiv mare, bara de progres este la 93 %. Apoi un scurt șoc VPN, timeout, anulare. Dimineața există un fișier în directorul țintă, dimensiunea „pare corectă“, dar la decomprimare apare doar „unexpected end of file“. Cine atunci reflexiv adaugă „Resume“, se lovește rapid de următorul caz limită: descărcarea se termină, dar este compusă din două versiuni.

Exact pentru asta este gândit un HttpClient Download mit Resume – dar numai dacă îl tratezi ca pe o mică conductă de date: cu reguli clare când poți atașa, cum verifici respectarea versiunii (ETag/If-Range) și cum gestionezi stările intermediare locale (fișiere parțiale) astfel încât operarea și depanarea să nu devină un joc de ghicit.

Conflictul de obiective este clar de formulat: economia de bandă și timp (continuare în loc de repornire) se află în opoziție cu integritatea și mentenabilitatea (fără mixuri de versiuni tăcute, decizii trasabile, comportament al erorilor reproductibil). Acest articol este construit ca o hartă de evaluare: beneficii, efort, riscuri, limite – și o linie pragmatică când să implementezi cu adevărat Resume și când un retry bine gândit e o soluție mai bună.

Hartă de evaluare: Două obiective, un compromis dur

Resume merită nu pentru că este „modern“, ci pentru că mediul tău îl impune: fișiere mari, conexiuni instabile, ferestre de timp în batch, utilizatori care întrerup descărcările sau servicii care trebuie să continue după repornire de unde au rămas. În același timp, Resume este punctul în care poți introduce neobservat corupție de date – iar aceasta se descoperă adesea mult mai târziu (import eșuează, semnătură invalidă, setup nu pornește).

De ce Resume este mai mult decât „setează Range”

HTTP recunoaște cererile byte-range prin headerul Range. Propoziția importantă, adesea trecută cu vederea: suportul pentru Range este opțional. Un server poate ignora Range și răspunde ca la un GET normal — adică cu 200 OK și corpul complet. Pentru clienți asta înseamnă: adevărul este în răspuns, nu în intenția din cerere.^[Quelle]

Un client Resume care confundă „Range trimis” cu „vine conținut parțial” comite exact eroarea pe care ai văzut‑o la începutul scenelor: un download complet este atașat unui fișier deja parțial descărcat. Rezultat: fișierul pare să aibă dimensiunea corectă, dar este corupt din punct de vedere logic.

Semnal de succes: 206 plus Content-Range plauzibil

Dacă Resume funcționează cu adevărat, vei vedea de obicei:

• Status 206 Partial Content în loc de 200 OK
• Content-Range cu Range-Unit bytes și offsetul de start așteptat
• validatoare consistente (de ex. ETag), dacă le folosești pentru integritatea versiunii

Verificările nu sunt „nice to have”. RFC 9110 afirmă explicit că destinatarii nu au voie să asambleze un răspuns 206 cu o unitate Range necunoscută împreună cu o reprezentare stocată. Consecință practică: fără un Content-Range înțeles corect, nu se face append.^[Quelle]

If-Range und ETag: Der saubere Weg gegen Versionsmix

Problema centrală la reluare nu este tehnica de a atașa, ci întrebarea: descarci încă aceeași resursă? HTTP oferă validatoare pentru aceasta. ETag (Entity Tag) este cel mai precis instrument: un identificator pe partea serverului pentru o reprezentare concretă. Last-Modified este o dată, adesea utilă, dar mai puțin precisă (rezoluție temporală, repackaging, stadii intermediare diferite prin CDN-uri).

Mecanismul pentru „Range doar dacă este într-adevăr aceeași versiune” se numește If-Range: trimiți Range plus condiție. Dacă validatorul corespunde, se livrează Range-ul; dacă nu, serverul ar trebui să trimită resursa completă. Pentru ETag-uri se aplică: condiția este îndeplinită doar la o potrivire puternică a ETag-ului (strong comparison). Asta nu este o chestiune de interpretare, ci este prevăzută în standard.^[Quelle]

Realitatea operațională rămâne: dacă serverul nu suportă Range, trebuie să ignore If-Range. Sună academic, dar este o cerință directă pentru clientul tău: trebuie să te aștepți și la 200 OK și să tragi o decizie fermă din asta (repornește de la zero, nu atașa).^[Quelle]

Strategia fișierelor parțiale: Das lokale Gegenstück zur HTTP-Semantik

Resume înseamnă: gestionezi starea locală. Iar această stare trebuie să rămână stabilă și după crash, restart, porniri paralele sau acțiuni ale utilizatorului („nochmal klicken“). O strategie curată pentru fișiere parțiale constă din trei artefacte:

• Fișier partial ca singurul loc de scriere în timpul descărcării (z. B. foo.zip.part)
• Metadate stocate separat (de ex. foo.zip.part.meta.json): URL, moment, ETag, Last-Modified, lungimea așteptată (dacă este cunoscută), eventual Content-Type, precum și lungimea locală la ultimul flush curat
• Încheiere atomică: doar după descărcarea completă și verificarea de plauzibilitate se redenumește/înlocuiește cu numele final

De ce metadate? Pentru că altfel la următoarea pornire cunoști doar lungimea fișierului – dar nu dacă aceasta corespunde exact acelei versiuni de pe server. Tocmai această informație decide dacă poți relua.

HttpClient Download cu reluare: logica decizională pe care o poți testa

System.Net.HttpClient îți oferă requests, responses și stream-uri. Robustețea provine din matricea ta de decizie. Dacă o formulezi clar, o poți testa la fel de clar (inclusiv „server ignoră Range“, „nepotrivire a validatorului“, „416″).

Flux minim în 6 pași

1. Determinați starea locală: Există .part? Citește lungimea ca offset. Încarcă metadatele.
2. Decide capacitatea de reluare: Încearcă reluarea doar dacă Offset > 0 și există în metadate cel puțin un validator util (preferabil ETag).
3. Construiește request-ul: Setează Range de la Offset. Setează suplimentar If-Range (ETag, altfel Last-Modified).
4. Clasifică response-ul:
   • 206: parsează Content-Range, verifică Range-Unit bytes, Start-Offset trebuie să se potrivească exact. Numai atunci se face append.
   • 200: niciodată append. Starea parțială se abandonează sau se plasează în carantină și se descarcă din nou.
   • 416 Range Not Satisfiable: Offset-ul nu mai corespunde (local sau pe server). Resetează starea și reîncepe.
   • altfel: cale de eroare cu diagnostic clar (loguează codul de stare + header-ele).
5. Scrierea stream-ului: în blocuri, flush regulat, actualizează metadatele (de ex. „ultimul flush la lungimea X“).
6. Finalizare: verificare dimensiune/plauzibilitate (dacă este posibil). Apoi redenumește/înlocuiește în mod atomic.

RangeHeaderValue: nu un detaliu, ci prevenire a erorilor

.NET oferă pentru header-ul Range clasa tipizată RangeHeaderValue. Nu este doar „cod mai frumos“: reduce erorile sintactice din header și face logurile mai ușor de interpretat, pentru că generezi valori consistente. Microsoft documentează și muchia relevantă pentru operare: serverele nu sunt obligate să accepte Range-Requests; Accept-Ranges este un indiciu, nu o garanție.^[Quelle]

Exemplu construit: când „200 OK“ îți strică reluarea

Capcane tipice și cum le recunoști în log

Accept-Ranges: un semnal util, dar fără garanție

Mulți membri ai echipelor folosesc Accept-Ranges ca indicator „serverul suportă resume”. MDN descrie header-ul exact așa ca indicator de suport („tot ce nu este none”). Este util pentru diagnostic și telemetrie. Totuși: nu te baza niciodată exclusiv pe el. Un proxy, un gateway de autentificare sau un CDN pot modifica comportamentul. Logica ta trebuie deci să se bazeze întotdeauna pe codul de stare (206 vs. 200) și pe Content-Range, nu pe speranța din Accept-Ranges.^[Quelle]

ETag-uri slabe (W/…) și transformări

ETag-urile slabe (W/"…") apar mai des decât ți-ai dori. Pentru If-Range însă este decisiv un match puternic al ETag-ului. În practică asta înseamnă: dacă primești doar un weak ETag, resume este mai puțin robust. Îl poți folosi în continuare, dar ar trebui să fii mai conservator (de ex. la primele neconcordanțe să repornești) și, pentru fișierele deosebit de critice, să aplici suplimentar o verificare de integritate out-of-band (hash din manifest/API), dacă este disponibilă.

Lungime totală necunoscută (chunked) și lipsă de plauzibilitate

Dacă nu apare Content-Length (de ex. transfer chunked), pierzi verificarea simplă „lungime locală == lungime așteptată”. Resume poate funcționa în continuare, dar ai nevoie de validatoare curate și de logging bun. Fără aceste suporturi, depanarea devine dificilă, pentru că nici măcar nu poți spune dacă îți lipsesc octeți sau ai în exces.

Paralelizare: doar după ce baza este stabilă

Descărcarea mai multor range-uri în paralel este posibilă, dar multiplică problemele legate de stare: gestionare de segmente, scriere aleatorie, unire, jurnal de erori, retry per segment. Pentru multe soluții software orientate pe proces acesta este overkill. Câștigul stabil apare deseori deja prin: download serial + resume + matrice clară de decizie. Paralelizarea merită doar când ai demonstrat suport stabil pentru Range și când metricile concrete arată că ești limitat de rețea sau de server.

Debugging care aduce claritate în 5 minute

Bug-urile de reluare sunt rar „doar un if greșit”. De obicei e o combinație de infrastructură (Proxy/CDN), configurație de server, timeout-uri și stare locală. De aceea merită o înregistrare structurată pentru fiecare încercare. Nu ca o pădure de text, ci ca câmpuri consistente:

• Cerere: URL (fără secrete), metodă, Range (start/sfârșit), If-Range (ETag sau dată).
• Răspuns: Statuscode, Accept-Ranges, ETag, Last-Modified, Content-Length, Content-Range (brut și parsat).
• Stare locală: cale part, lungime part înainte de request, mod scriere (Append/Overwrite), lungime după scriere.
• Decizie: „Resume accepted“, „Resume rejected (200) – RESTart“, „416 – reset“, „Validator mismatch – RESTart“.

Cu exact aceste date poți testa ipoteze: „Ignoră serverul Range?“, „Se schimbă ETag între request-uri?“, „Este offsetul determinat greșit?“, „Scrie și un al doilea proces în același timp?“ – fără să trebuiască să scoți Wireshark din sertar.

Când să nu implementezi în mod deliberat reluarea

Decizia arhitecturală cea mai curată este uneori să renunți la reluare – nu din comoditate, ci pentru că în cazul tău creează mai multă suprafață de eroare decât beneficiu:

• URL fără legare de versiune: Dacă la aceeași URL apar regulat conținuturi noi, reluarea fără un validator solid este un risc pentru integritate.
• Fără validatoare utile: Dacă nici ETag, nici Last-Modified nu sunt consistente, „continuarea“ este o miză. La importuri critice e adesea mai bine un RESTart controlat.
• Descărcare mică și frecventă: Aici strategiile de retry (timeout, backoff, eventual Mirror-URL) sunt mai ușor de întreținut și mai simple de justificat în operare.

Măsuri pragmatice de siguranță care merită

Carantină în loc de ștergere

Dacă un încercare de reluare eșuează, nu șterge reflex .part. Redenumește (de ex. .part.bad + marcaj temporal). Asta face problemele de server/proxy vizibile, pentru că poți compara mai târziu header-ele de răspuns cu starea fișierului. Și previne ca o problemă rară să dispară din analiză din cauza „curățării”.

Blocare împotriva pornirilor multiple

Dacă două procese scriu simultan aceeași .part, toți validatorii HTTP devin inutili. Un lock exclusiv (Datei-Lock sau systemweiter Mutex) nu e un lux, ci protecție de bază. Metadatele pot include suplimentar o informație despre owner (Instanz-ID), astfel încât să poți identifica și curăța descărcările „orfane”.

Reguli esențiale de care ai cu adevărat nevoie

• Append doar pentru 206 – și doar cu Content-Range verificat (Unit bytes, Start-Offset se potrivește).
• 200 înseamnă: RESTart (overwrite), niciodată nu atașa la un fișier parțial.
• If-Range reduce mixul de versiuni, dar nu înlocuiește obligația de a evalua statusul/Content-Range.
• 416 este un semnal de reset: offsetul local nu mai corespunde, respinge/quarantenează starea.

Punct final: mai întâi integritatea, apoi optimizarea

Un download HttpClient cu resume este eficient atunci când este plictisitor: setează Range numai dacă starea locală este fiabilă, reia transferul doar dacă serverul răspunde cu 206 și Content-Range este verificat, și previne amestecul de versiuni prin If-Range și validatori. Tot ce rămâne este o funcționalitate „pare rapidă” care îți va mânca timp mai târziu, pentru că erorile sunt rare și atunci sunt dificil de reprodus.

Dacă pentru Updater, trasee de import sau servicii vrei să pui în funcțiune o pipeline robustă de download (Resume, Logging, strategie pentru fișiere parțiale, condiții de operare) într-un mod curat, asta se poate clarifica adesea într-un scurt check de arhitectură – inclusiv întrebarea dacă complexitatea merită în mediul tău. Ia legătura și discută proiectul cu Net-Base.

Discută un proiect sau o inițiativă de modernizare cu Net-Base.