Bios.Storage.S3

Nesne deposu için küçük bir sözleşme ve S3 uyumlu gerçeklemesi. Sözleşme üç işten ibaret: koy, al, sil. İçinde bucket, imza, HTTP geçmez; depoyu değiştirmek üst katmanlara dokunmaz.

Okurken bir tavan verilebilir: deponun bildirdiği boyut tavanı aşıyorsa içerik belleğe hiç çekilmeden null döner. Düşmanca büyüklükte bir dosya, servisi şişirerek düşüremez.

Gerçekleme standart AWS SDK ile her S3 uyumlu sunucuya konuşur. SeaweedFS ile çalışan ayarlar hazırdır: path-style adresleme açık, SDK'nın AWS dışı sunucuların reddettiği checksum davranışı WHEN_REQUIRED seviyesine çekilmiş, zaman aşımı yerel ağa göre kısaltılmıştır.

Bağlama

using Bios.Storage;   // paket adi degil -- asagidaki Dikkat bolumune bak

services.AddBiosStorage(configuration);   // Storage bolumunu okur, acilista dogrular

Kullanımı:

public sealed class LogoService
{
    private readonly IObjectStore _store;

    public LogoService(IObjectStore store) => _store = store;

    public Task SaveAsync(Stream file, long length, CancellationToken ct)
        => _store.PutAsync("office/1/logo.png", file, "image/png", length, ct);

    public async Task<byte[]?> ReadAsync(CancellationToken ct)
    {
        // Anahtar yoksa null doner; tavani asan nesne de null doner.
        await using var found = await _store.GetAsync(
            "office/1/logo.png", maxBytes: 2 * 1024 * 1024, ct);

        if (found is null)
            return null;

        using var buffer = new MemoryStream();
        await found.Content.CopyToAsync(buffer, ct);
        return buffer.ToArray();
    }

    public Task RemoveAsync(CancellationToken ct)
        => _store.DeleteAsync("office/1/logo.png", ct);
}

Yapılandırma

Bölüm adı: Storage.

{
  "Storage": {
    "Endpoint": "http://objectstore:8333",
    "AccessKey": "...",
    "SecretKey": "...",
    "Bucket": "urun-dosyalari",
    "Region": "us-east-1"
  }
}

Aynı ayarlar ortam değişkeni olarak Storage__Endpoint, Storage__Bucket biçiminde de verilebilir.

Eksik ya da bozuk ayar host'u ilk yüklemede değil, açılışta durdurur; hata metni hangi anahtarların eksik olduğunu tek tek sayar.

Dikkat

Paketin adı Bios.Storage.S3, ad alanı ise Bios.Storage. Paket adına bakıp using Bios.Storage.S3; yazmak derleme hatası verir; öyle bir ad alanı yoktur. Ad alanı kasıtlı olarak .S3 taşımaz: IObjectStore sözleşmesi S3'e ait değildir, S3 yalnız bugünkü gerçeklemesidir. İkinci bir gerçekleme geldiğinde çağıran tarafın using satırı değişmesin diye böyle.

GetAsync bulunamayan anahtarda null döner, hata fırlatmaz. İki ayrı durum aynı sonucu verir: anahtarın altında hiçbir şey yoktur, ya da nesne verilen maxBytes tavanını aşmaktadır. İkisini ayırman gerekiyorsa aynı anahtar bir kez de tavansız okunur.

StoredObject atılmalıdır. Sözleşme, dönen nesnenin bir akışa sahip olduğunu ve onu kapatmanın çağıranın işi olduğunu söyler; await using ile kullan. Bugünkü S3 gerçeklemesi içeriği belleğe alıp sunucuyla olan bağlantıyı kendisi bıraktığı için atmayı unutmak şu an bir bağlantı sızdırmaz — ama buna güvenme; kural sözleşmenin kuralıdır ve akışı gerçekten canlı tutan bir gerçekleme sözleşmeye uygun olur.

Belleğe alma, büyük dosya yolu değildir. GetAsync içeriği baştan sona bir bellek tamponuna kopyalar. maxBytes tavanı bunu sınırlamak için vardır ve nesnenin bildirilen boyutuna, tek bayt okunmadan önce bakılır. Büyük dosyalar için maxBytes vermeden okumak süreci şişirir.

PutAsync'e verilen akışı çağıran kapatır. Paket akışı sonuna kadar okur ama sahiplenmez; SDK'nın akışı elinden alıp kapatması bilerek engellenmiştir.

Kova ilk yazmada kendiliğinden oluşturulur, açılışta değil. İlk PutAsync kovanın varlığına bakar, yoksa yaratır ve bunu bir kez yapar. Böylece nesne deposu henüz ayakta değilken de host açılabilir; hata, düzeltilebilir olduğu yerde — ilk yükleme denemesinde — çıkar. Okuma ve silme bu adımı çalıştırmaz.