Migration zu v4

Version 4.0.0 ändert, wie das SDK Wiederholungen durchführt, sodass es nur wiederholt, was sich gefahrlos wiederholen lässt. Keine Methode, Option oder kein Export wurde umbenannt oder entfernt.

Voraussetzungen

Unverändert: Node.js 20 oder neuer, oder ein Browser; ESM und CommonJS.

Zusammenfassung der Breaking Changes

v3.x	v4.x
`429` wird wiederholt	Wird nie wiederholt (außer `TOO_MANY_CONCURRENT_CHUNKS` bei einem Multipart-Teil)
Schreibvorgänge werden bei Netzwerkfehlern und `5xx` wiederholt	Schreibvorgänge erhalten einen einzigen Versuch
Wiederholung nur bei `500` und `503`	Wiederholung bei jedem `5xx` (Lesevorgänge und Multipart-Teile)
`maxRetries` Standard `5`	Standard `2`
Backoff begrenzt auf 30 s	Begrenzt auf 8 s: `min(8 s, 500 ms · 2^n) · U(0.5, 1)`
`SavedRule.active_from: string`	`active_from?: string` (optional)
`delete([id])` mit einer ID wirft `PREFIX_NOT_ALLOWED`	Meldet es in `failed`
`RATE_LIMIT` in `BlobErrorCode`	Veraltet (weiterhin im Typ)

`429` wird nicht mehr wiederholt

RATE_LIMITED umfasst sowohl ein Zeitfenster pro Route als auch eine Konto- oder IP-Sperre, die etwa 30 Minuten dauern kann, daher wiederholt das SDK ihn nicht mehr. Das schließt das Limit für einfache Uploads und TOO_MANY_CONCURRENT_UPLOADS ein. Behandle ihn selbst und warte, bevor du es erneut versuchst:

import { SquareCloudBlobError } from "@squarecloud/blob";

try {
    await blob.put(file, { name: "report" });
} catch (error) {
    if (error instanceof SquareCloudBlobError && error.code === "RATE_LIMITED") {
        // back off: queue the job for later instead of retrying right away
    }
    throw error;
}

Die einzige Ausnahme ist TOO_MANY_CONCURRENT_CHUNKS bei einem Multipart-Teil: Der Server lehnt den Teil ab, bevor er ihn liest, daher sendet das SDK ihn innerhalb von maxRetries erneut.

Schreibvorgänge erhalten einen einzigen Versuch

Netzwerkfehler und 5xx werden jetzt nur noch bei GET-Aufrufen und bei Teilen von Multipart-Uploads wiederholt. Diese Aufrufe erhalten einen Versuch:

einfaches put() sowie Starten, Abschließen und Abbrechen eines Multipart-Uploads;
update(), copy(), move(), delete();
rules.set(), uploadTokens.create(), shares.create(), shares.revoke().

Wiederhole einen Schreibvorgang nur dann selbst, wenn das für dich gefahrlos ist, zum Beispiel ein put() auf denselben Namen mit overwrite: true. Siehe Schreibvorgänge selbst wiederholen.

Weniger Wiederholungen, kürzeres Backoff

maxRetries ist jetzt standardmäßig 2 (vorher 5), und das Backoff ist auf 8 Sekunden begrenzt (vorher 30). Um das alte Budget für Lesevorgänge und Multipart-Teile beizubehalten:

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY, { maxRetries: 5 });

Das bringt keine Wiederholungen bei 429 oder bei Schreibvorgängen zurück.

`SavedRule.active_from` ist optional

Die API sendet active_from nur bei Regeln mit delete_after_days. Berücksichtige in TypeScript undefined:

const rules = await blob.rules.get();

for (const rule of rules) {
    if (rule.active_from) {
        console.log(`${rule.prefix} starts deleting at ${rule.active_from}`);
    }
}

`delete([id])` mit einer einzelnen ID

Ein Batch mit einer ID meldet PREFIX_NOT_ALLOWED jetzt wie jeder andere Batch in failed, statt zu werfen:

// v3: threw SquareCloudBlobError (PREFIX_NOT_ALLOWED)
// v4:
const { failed } = await blob.delete([id]);
// failed: [{ id, code: "PREFIX_NOT_ALLOWED" }]

delete(id) mit einem einfachen String wirft weiterhin.

`RATE_LIMIT` ist veraltet

Der Dienst sendet RATE_LIMIT nicht mehr: Die Konto- oder IP-Sperre ist RATE_LIMITED. Der alte Code bleibt in BlobErrorCode, damit bestehende Vergleiche weiterhin kompilieren; stelle sie auf RATE_LIMITED um. DUPLICATE_RULE_PREFIX wurde hinzugefügt.

Korrekturen

Ein mitten im Lesen abgeschnittener Antwort-Body ist jetzt ein Netzwerkfehler: Er wird bei GET-Aufrufen und Multipart-Teilen wiederholt, ansonsten wird der ursprüngliche fetch-Fehler geworfen (früher war es UNKNOWN_ERROR).
Ein fehlgeschlagener Multipart-Upload wartet jetzt auf die noch laufenden Teile, bevor er abbricht, sodass kein Teil nach dem Abbruch ankommt und keine Anfrage put() überdauert.

Checkliste

429 selbst behandeln

Fange RATE_LIMITED ab und warte; das SDK wiederholt ihn nicht mehr.

Schreibvorgänge prüfen

Füge eigene Wiederholungen nur bei Schreibvorgängen hinzu, die sich gefahrlos wiederholen lassen.

Ein Wiederholungsbudget wählen

Übergib { maxRetries: 5 }, wenn du dich auf die alte Anzahl von Versuchen bei Lesevorgängen und Multipart-Teilen verlassen hast.

Typen aktualisieren

Berücksichtige, dass active_from undefined sein kann, und ersetze RATE_LIMIT durch RATE_LIMITED.

Dienste

Runtimes

Plattform

Fehlerbehebung

CLI

SDKs

Changelog

Voraussetzungen

Zusammenfassung der Breaking Changes

`429` wird nicht mehr wiederholt

Schreibvorgänge erhalten einen einzigen Versuch

Weniger Wiederholungen, kürzeres Backoff

`SavedRule.active_from` ist optional

`delete([id])` mit einer einzelnen ID

`RATE_LIMIT` ist veraltet

Korrekturen

Checkliste

​Voraussetzungen

​Zusammenfassung der Breaking Changes

​429 wird nicht mehr wiederholt

​Schreibvorgänge erhalten einen einzigen Versuch

​Weniger Wiederholungen, kürzeres Backoff

​SavedRule.active_from ist optional

​delete([id]) mit einer einzelnen ID

​RATE_LIMIT ist veraltet

​Korrekturen

​Checkliste

Voraussetzungen

Zusammenfassung der Breaking Changes

`429` wird nicht mehr wiederholt

Schreibvorgänge erhalten einen einzigen Versuch

Weniger Wiederholungen, kürzeres Backoff

`SavedRule.active_from` ist optional

`delete([id])` mit einer einzelnen ID

`RATE_LIMIT` ist veraltet

Korrekturen

Checkliste