Feather Storage S3

S3 compatible driver implementation for the abstract Feather Storage Swift API package.

Features

• S3 compatible driver for Feather Storage
• Designed for modern Swift concurrency
• DocC-based API Documentation
• Unit tests and code coverage

Requirements

• Swift 6.1+
• Platforms:
  • Linux
  • macOS 15+
  • iOS 18+
  • tvOS 18+
  • watchOS 11+
  • visionOS 2+

Installation

Add the dependency to your Package.swift:

.package(url: "https://github.com/feather-framework/feather-storage-s3", exact: "1.0.0-beta.4"),

Then add FeatherStorageS3 to your target dependencies:

.product(name: "FeatherStorageS3", package: "feather-storage-s3"),

Usage

API documentation is available at the link below:

Here is a brief example:

import Logging
import NIOCore
import FeatherStorage
import FeatherStorageS3
import SotoCore

try await withLogger(Logger(label: "example")) { _ in
    let awsClient = AWSClient(
        credentialProvider: .default,
        logger: Logger.current
    )
    let storage = StorageClientS3(
        awsClient: awsClient,
        region: "us-east-1",
        bucket: "example-bucket"
    )

    try await withThrowingTaskGroup(of: Void.self) { group in
        group.addTask {
            try await awsClient.run()
        }
        group.addTask {
            let text = "Hello, World"
            var buffer = ByteBufferAllocator()
                .buffer(capacity: text.utf8.count)
            buffer.writeString(text)

            try await storage.upload(
                key: "docs/hello.txt",
                sequence: StorageSequence(
                    asyncSequence: ByteBufferSequence(buffer: buffer),
                    length: UInt64(buffer.readableBytes)
                )
            )

            try await storage.exists(key: "docs/hello.txt")
            try await storage.size(key: "docs/hello.txt")

            let result = try await storage.download(
                key: "docs/hello.txt",
                range: nil
            )
            let buffer = try await result.collect(upTo: .max)
            let value = buffer.getString(
                at: 0,
                length: buffer.readableBytes
            )
            print(value)
        }

        try await group.next()
        group.cancelAll()
    }
}

The package uses Logger.current from swift-log for S3 request logging. Use withLogger to scope the logger for an operation; calls to Logger.current within that scope use the scoped logger.

Warning

This repository is a work in progress, things can break until it reaches v1.0.0.

Other storage drivers

The following storage client implementations are also available for use:

• FS
• Ephemeral

Development

• Build: swift build
• Test:
  • local with MinIO: make test
  • using Docker: make docker-test
• Bare swift test skips the MinIO integration test unless FEATHER_STORAGE_S3_TEST_ENDPOINT is set.
• Format: make format
• Check: make check

Contributing

Pull requests are welcome. Please keep changes focused and include tests for new logic.