Disk API

A Disk (a storage.NewDisk eredménye) az a típus, amitől a service-kód függ; a main.go-n kívül senkinek nem kell tudnia, milyen Driver áll mögötte. Minden metódus egy context.Context-et és egy per-jellel tagolt path-ot kap, és minden hívás egy tracelt OTel span, így egy lassú feltöltés ott jelenik meg a trace waterfallban, közvetlenül a hozzá közeli DB-lekérdezések mellett.

Írások

err := disk.Put(ctx, "avatars/42.png", r, storage.PutOptions{ContentType: "image/png"})
err := disk.PutBytes(ctx, "reports/2026-07.csv", data, storage.PutOptions{})

A Put egy io.Reader-ből streamel, így egy nagy feltöltés sosem ül teljesen a memóriában. A PutBytes a kényelmi forma olyan adathoz, ami már []byte-ként a kezedben van (egy generált riport, egy kis memóriabeli buffer): egy bytes.Reader-t csomagol be, és a Put-ot hívja. A PutOptions hordozza azt a metaadatot, amire egy driver reagálhat (content type, és bármi más, amit egy konkrét driver opciói támogatnak); egy driver, ami ennek egy részét nem őrzi meg, attól még érvényes, csak kevésbé képes implementáció, és a storagetest segít eldönteni, hogy megőrzi-e.

Olvasások

b, err := disk.Get(ctx, "avatars/42.png")               // a teljes objektum, memóriába
rc, err := disk.Reader(ctx, "avatars/42.png")           // streamelt; a hívónak kell Close()-olnia
rc, err := disk.RangeReader(ctx, "video.mp4", 0, 1<<20) // csak az első MiB

info, err := disk.Stat(ctx, "avatars/42.png")
ok := disk.Exists(ctx, "avatars/42.png")
missing := disk.Missing(ctx, "avatars/42.png")

A Get a kényelmi forma kis objektumokhoz: az egészet memóriába olvassa, és helyetted zárja a readert. Bármi nagyobbhoz a Reader streamel, és a hívó felelőssége a lezárás. A RangeReader egy [offset, offset+length) bájttartományt nyit meg, folytatható letöltésekhez vagy HTTP Range-kérések kiszolgálásához az egész objektum beolvasása nélkül. A Stat egy FileInfo-t ad vissza (méret, content type, utolsó módosítás ideje és társai) a törzs átvitele nélkül: egy HEAD-jellegű ellenőrzés. Az Exists/Missing boolean kényelmi metódusok ugyanarra a hívásra, arra a gyakori esetre, amikor csak az érdekel, ott van-e az objektum, nem a metaadata; egy valódi backend-hiba az alatta lévő Stat-ból "nem megerősítetten létezőként" kezelődik, nem panicol és nem terjed csendben tovább, úgyhogy ha meg kell különböztetned a "hiányzik"-ot a "storage elérhetetlen"-től, hívd közvetlenül a Stat-ot.

Listázás

page, err := disk.List(ctx, storage.ListOptions{Prefix: "avatars/", After: cursor})

A List a ListOptions.Prefix alatti FileInfo-k egy lapját adja vissza, a ListOptions.After/ListPage.ContinuationToken viszi a következő lapra: reconciliation- és GC-sweepekhez való, nem kiszolgáló code path-okhoz, objektumonként egyesével.

Ha egy teljes prefixet be akarsz járni a lapozási ciklus kézi megírása nélkül, a Files egy Go 1.23+ range-over-func iterátor:

for info, err := range disk.Files(ctx, "avatars/") {
    if err != nil {
        return err
    }
    fmt.Println(info.Path, info.Size)
}

A Files belül a List-en lapoz végig, és egyesével adja a FileInfo-kat; a ciklusból való korai kilépés (break, return) egyszerűen leállítja a további lapok lekérését.

Copy, Delete, Move

err := disk.Copy(ctx, "uploads/staging/x.png", "avatars/42.png")
err := disk.Delete(ctx, "uploads/staging/x.png")
err := disk.Move(ctx, "uploads/staging/x.png", "avatars/42.png")

A Copy szerver-oldali másolás ott, ahol a driver támogatja, anélkül hogy a bájtok átfolynának a processzeden. A Delete idempotens: egy nem létező path törlése nem hiba. A Move a driver natív mozgatását használja, ha az implementálja az opcionális Mover interfészt (lásd Áttekintés); egyébként a Disk maga csinál Copy-t majd Delete-et, így a hívónak sosem kell tudnia, melyik esetben van.

URL-ek

url, err := disk.URL(ctx, "avatars/42.png")
signed, err := disk.TemporaryURL(ctx, "exports/orders.csv", storage.TemporaryURLOptions{TTL: 15 * time.Minute})
upload, err := disk.TemporaryUploadURL(ctx, "uploads/42.png", storage.TemporaryUploadURLOptions{TTL: 5 * time.Minute})

if disk.ProvidesTemporaryURLs() {
    // biztonságos közvetlen storage-hoz-download/upload linkeket kínálni
}

Az URL publikus tartalomhoz való: egy stabil link, jellemzően egy publikus bucket vagy egy CDN base URL mögött. A TemporaryURL időkorlátos, aláírt linket ad privát tartalomhoz, így a kliens közvetlenül a storage-tól tölt le, a service-eden való átfolyás helyett. A TemporaryUploadURL ugyanez közvetlen kliens-oldali feltöltéshez, egy UploadURL-t adva vissza (az URL-t, plusz bármilyen headert vagy mezőt, amit a hívónak a kéréshez csatolnia kell, mert ez driverenként változik). Nem minden driver tud URL-t aláírni; a ProvidesTemporaryURLs egy capability-ellenőrzés, amivel elágazhatsz ahelyett, hogy meghívnád a metódust, és utólag kezelnéd az ErrUnsupported-ot.

Kapcsolódó oldalak

• Áttekintés: a Driver/Disk/Manager modell, a dekorátorok.
• Memória és helyi lemez: driverek, amikre egy Disk-et rá lehet építeni, teszthez vagy egy-node-os telepítéshez.
• S3: az S3-kompatibilis driver, és a saját presigned URL-támogatása.
• Tesztelés: a konformancia-suite, ami ellenőrzi, hogy egy Driver konzisztensen viselkedik-e.