Skip to content

Commit

Permalink
Update README for 2.0 (#45)
Browse files Browse the repository at this point in the history
Also remove some unnecessary code
  • Loading branch information
adam-fowler authored Aug 8, 2024
1 parent 262bb47 commit 02cb3ba
Show file tree
Hide file tree
Showing 3 changed files with 27 additions and 27 deletions.
21 changes: 15 additions & 6 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,20 @@ let package = Package(
.package(url: "https://github.com/apple/swift-log.git", from: "1.4.0")
],
targets: [
.target(name: "SotoS3FileTransfer", dependencies: [
.product(name: "SotoS3", package: "soto"),
.product(name: "Atomics", package: "swift-atomics"),
.product(name: "Logging", package: "swift-log"),
], swiftSettings: swiftSettings),
.testTarget(name: "SotoS3FileTransferTests", dependencies: ["SotoS3FileTransfer"]),
.target(
name: "SotoS3FileTransfer",
dependencies: [
.product(name: "SotoS3", package: "soto"),
.product(name: "Logging", package: "swift-log"),
],
swiftSettings: swiftSettings
),
.testTarget(
name: "SotoS3FileTransferTests",
dependencies: [
"SotoS3FileTransfer",
.product(name: "Atomics", package: "swift-atomics"),
]
),
]
)
30 changes: 12 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,27 +7,23 @@ Make uploading and downloading of files to AWS S3 easy.
Soto S3 Transfer uses the Soto Swift SDK for AWS. You need to create a Soto S3 service object before you can use the S3 transfer manager. See Soto [documentation](https://github.com/soto-project/soto) for more guidance. You also need to supply the `threadPoolProvider` parameter which indicates where Soto S3 Transfer will get threads from to run the file loading and saving.

```swift
let client = AWSClient(httpClientProvider: .createNew)
let client = AWSClient()
let s3 = S3(client: client, region: .euwest1)
let s3FileTransfer = S3FileTransferManager(s3: s3, threadPoolProvider: .singleton)
let s3FileTransfer = S3FileTransferManager(s3: s3)
```

## Shutdown

Because `S3FileTransferManager` can hold a thread pool that requires explicit shutdown, it also requires explicit shutdown. Before the manager is deleted you need to call `S3FileTransferManager.syncShutdown` to ensure the thread pool has been shutdown correctly.

## Upload to S3

Uploading files to S3 is done with one call. The call returns a [NIO](https://github.com/apple/swift-nio) EventLoopFuture which will be fulfilled with the response when the operation is finished.
Uploading files to S3 is done with one call.
```swift
let uploadFuture = s3FileTransfer.copy(
try await s3FileTransfer.copy(
from: "/Users/me/images/test.jpg",
to: S3File(url: "s3://my-bucket/test.jpg")!
)
```
You can also upload a folder as follows
```swift
let uploadFuture = s3FileTransfer.copy(
try await s3FileTransfer.copy(
from: "/Users/me/images/",
to: S3Folder(url: "s3://my-bucket/images/")!
)
Expand All @@ -36,19 +32,18 @@ If you are uploading a folder multiple files will be uploaded in parallel. The n
```swift
let s3Transfer = S3FileTransferManager(
s3: s3,
threadPoolProvider: .singleton,
configuration: .init(maxConcurrentTasks: 8)
)
```
## Download from S3

Download is as simple as upload just swap the parameters around
```swift
let downloadFuture = s3FileTransfer.copy(
try await s3FileTransfer.copy(
from: S3File(url: "s3://my-bucket/test.jpg")!,
to: "/Users/me/images/test.jpg"
)
let downloadFolderFuture = s3FileTransfer.copy(
try await s3FileTransfer.copy(
from: S3Folder(url: "s3://my-bucket/images/")!,
to: "/Users/me/downloads/images/"
)
Expand All @@ -58,27 +53,27 @@ let downloadFolderFuture = s3FileTransfer.copy(

You can also copy from one S3 bucket to another by supplying two `S3Files` or two `S3Folders`
```swift
let copyFuture = s3FileTransfer.copy(
try await s3FileTransfer.copy(
from: S3File(url: "s3://my-bucket/test2.jpg")!,
to: S3File(url: "s3://my-bucket/test.jpg")!
)
let copyFolderFuture = s3FileTransfer.copy(
try await s3FileTransfer.copy(
from: S3Folder(url: "s3://my-bucket/images/")!,
to: S3Folder(url: "s3://my-other-bucket/images/")!)
)
```

## Sync operations

There are `sync` versions of these operations as well. This will only copy files across if they are newer than the existing files. You can also have it delete files in the target folder if they don't exist in the source folder.
There are `sync` versions of these operations as well. This will only copy files across if they are newer than the existing files. You can also have it delete files in the target folder if they don't exist in the source folder.

```swift
let uploadSyncFuture = s3FileTransfer.sync(
try await s3FileTransfer.sync(
from: "/Users/me/images/",
to: S3Folder(url: "s3://my-bucket/images")!,
delete: true
)
let downloadFuture = s3FileTransfer.copy(
try await s3FileTransfer.sync(
from: S3Folder(url: "s3://my-bucket/images")!,
to: "/Users/me/downloads/images/",
delete: false
Expand All @@ -91,7 +86,6 @@ If uploads are above a certain size then the transfer manager will use multipart
```swift
let s3Transfer = S3FileTransferManager(
s3: s3,
threadPoolProvider: .singleton,
configuration: .init(multipartThreshold: 16*1024*1024, multipartPartSize: 16*1024*1024)
)
```
3 changes: 0 additions & 3 deletions Sources/SotoS3FileTransfer/S3FileTransferManager.swift
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@
//
//===----------------------------------------------------------------------===//

import Atomics
import Foundation
import Logging
import NIOConcurrencyHelpers
Expand Down Expand Up @@ -94,8 +93,6 @@ public final class S3FileTransferManager: Sendable {
public let configuration: Configuration
/// Logger
public let logger: Logger
/// Have we shutdown the Manager
let isShutdown = ManagedAtomic(false) // <Bool>.makeAtomic(value: false)

/// Initialize S3 Transfer manager.
/// - Parameters:
Expand Down

0 comments on commit 02cb3ba

Please sign in to comment.