Swiftpack.co - Package - adam-fowler/s3-filesystem-kit

S3 File System Kit

Swift 5.1 CI

File manager for Amazon Web Service S3.


S3 File System uses the S3 library from Soto. You need to initialise S3FileSystem with a S3 client object from this library. S3 File System will require AWS credentials before you can continue. The S3 client object will provide these.

let s3 = S3(region: .euwest1)
let s3fs = S3FileSystem(s3Client: s3)

Path descriptors

S3 File System uses an S3File to describe the location of a file in S3 and an S3Folder to describe the location of a folder. These are initialized with a url of the form s3://<bucketname>/<path>. For example

let folder = S3Folder(url: "s3://bucket/folder")
let file = S3File(url: "s3://bucket2/folder/file")

Most functions in S3FileSystem have two forms, one that takes an S3File and one that takes a filename String relative to the currentPath set in S3FileSystem.

s3fs.writeFile(S3File("s3://bucket/folder/file")!, data: data)


s3fs.setCurrentFolder(S3Folder(url: "s3://bucket/folder")!)
    .flatMap { _ in
        return s3fs.writeFile(name: "file", data: data)

will both do the same thing. Except in the second case setCurrentFolder will check the S3 bucket exists before running writeFile. The advantage of the second version is you can now push and pop folders (using pushFolder and popFolder) and traverse the S3 bucket as if it is a hierarchical file system.


Most of the functions in S3FileSystem return an EventLoopFuture from the swift-nio library. This is not the result of the function. This is populated with the result when it is available. In this manner the library will not block the main thread. It is recommended you familiarize yourself with swift-nio documention to get the most out of S3 File System.

The recommended way to interact with EventLoopFutures is chaining. The following creates an S3 bucket, uploads an object and then downloads it.

import S3FileSystemKit

let result: EventLoopFuture<Data> = s3fs.setCurrentFolder(S3Folder(url: "s3://bucket/")!, createBucket: true)
  .flatMap { _ in
      return self.s3fs.writeFile(name: filename, data: data)
  .flatMap { _ in
      return self.s3fs.readFile(name: filename)


You can find API reference documentation here. It is also useful to read the Amazon S3 documentation which you can find here.


Stars: 4


Used By

Total: 0


v0.3.0 - 2020-09-26 11:16:26

Replace swift-aws/aws-sdk-swift in Package.swift with soto-project/soto

v0.2.0 - 2020-03-24 17:12:15

  • Added readFileURL and writeFileURL to created signed URLs that can be used to read and write a file

v0.1.1 - 2020-03-12 14:09:01

  • Conform S3Path to Equatable
  • Conform S3Path to CustomStringConvertible
  • Add file tag editing functions
  • Add file ACL(Access control) editing functions
  • Add listBuckets
  • Add iOS/tvOS/watchOS platforms

v0.1.0 - 2020-03-10 12:30:21

  • Fix up S3Path so path is correct. Remove leading forward slash
  • Add support for copying files
  • Add support for reading/writing file attributes

v0.0.1 - 2020-03-09 19:33:01

Initial version