docs: add guides for errors/retries, keys and sessions, and large uploads

Aperta
  • Qualcosa non va?
#313 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@ffumero2003 ci sta già lavorando.

Dal 8/11/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

documentation

Context

The README covers errors, retries, keys/sessions and large/resumable uploads in roughly one line each; backblaze.com/docs has no error/retry guide for the SDKs. Two extension points are also undocumented: blazer accepts a custom transport (b2.Transport(http.RoundTripper), b2/b2.go:158) but the README never mentions it, and blazer's debug logging has no "how to turn it on" doc. (Both gaps surfaced by comparing against the Vercel SDK's docs, which document Retries, Error Handling, Custom HTTP Client and Debugging as standard sections.)

Acceptance criteria

  • R1. Every code sample compiles; wording matches behavior.
  • R2. The transport section shows a working b2.Transport(...) example; the debugging section shows how to enable request logging.

In scope

Add repo guides, linked from the README:

  • Errors and retries: how to check for not-found (and the unwrappable-error helpers), what blazer retries, how Retry-After is applied, and that a retry can create a duplicate version; one example. List the error types/helpers (the "error classes" idea).
  • Keys and sessions: minimal keys and session persistence via WithAccountInfo.
  • Large and resumable uploads: part splitting, resume, and Compose.
  • Custom HTTP client / transport: how to supply your own http.RoundTripper via b2.Transport(...) for timeouts, a proxy, or tracing/instrumentation, and how it composes with blazer's retries.
  • Debugging / request logging: how to see requests and responses (the debug logging / caller logger, see #173), and what is redacted.

Use the Vercel SDK section layout as a template (Retries → Error Handling → Custom HTTP Client → Debugging). Keep every section consistent with shipped behavior (the error-wrapping, Retry-After and upload-retry work). Offer the errors-and-retries text to the docs team afterward.

Out of scope

  • Unrelated work outside the components and behavior described in In scope.

Verification

git diff --check
  • Compile the documented examples, including the custom-transport and logging examples, and record their exact build/test commands.
  • Cross-check error/retry, key/session, upload/resume, and logging statements against shipped behavior. Keep external docs-team coordination explicit rather than claiming it happened.
  • Expected result: the checks above succeed and the observable outcomes in Acceptance criteria are demonstrated. If a check cannot run, report Could not run because: ...; if it starts but fails, report Could not complete because: .... A skipped check is not a pass.

Links

Lingua principale
Go
Stelle
66
Fork
18
Merge medio
1g 10h
PR unite (30g)
132

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Backblaze/blazer

Tutte le issue di Backblaze/blazer

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.