{"id":17295198,"url":"https://github.com/adam-fowler/s3-filesystem-kit","last_synced_at":"2025-04-14T11:55:47.382Z","repository":{"id":55636447,"uuid":"246075206","full_name":"adam-fowler/s3-filesystem-kit","owner":"adam-fowler","description":"Swift File Manager for AWS S3","archived":false,"fork":false,"pushed_at":"2020-12-16T10:53:02.000Z","size":882,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-14T11:55:39.645Z","etag":null,"topics":["aws","s3","server-side-swift","swift","swift-nio"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adam-fowler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"adam-fowler"}},"created_at":"2020-03-09T15:40:11.000Z","updated_at":"2021-09-06T15:42:12.000Z","dependencies_parsed_at":"2022-08-15T05:10:14.110Z","dependency_job_id":null,"html_url":"https://github.com/adam-fowler/s3-filesystem-kit","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adam-fowler%2Fs3-filesystem-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adam-fowler%2Fs3-filesystem-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adam-fowler%2Fs3-filesystem-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adam-fowler%2Fs3-filesystem-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adam-fowler","download_url":"https://codeload.github.com/adam-fowler/s3-filesystem-kit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248878020,"owners_count":21176242,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","s3","server-side-swift","swift","swift-nio"],"created_at":"2024-10-15T11:09:42.023Z","updated_at":"2025-04-14T11:55:47.355Z","avatar_url":"https://github.com/adam-fowler.png","language":"Swift","funding_links":["https://github.com/sponsors/adam-fowler"],"categories":[],"sub_categories":[],"readme":"# S3 File System Kit\n\n[\u003cimg src=\"http://img.shields.io/badge/swift-5.1-brightgreen.svg\" alt=\"Swift 5.1\" /\u003e](https://swift.org)\n[\u003cimg src=\"https://github.com/adam-fowler/s3-filesystem-kit/workflows/CI/badge.svg\" alt=\"CI\" /\u003e](https://github.com/adam-fowler/s3-filesystem-kit/actions?query=workflow%3ACI)\n\nFile manager for Amazon Web Service S3.\n\n# Setup\n\nS3 File System uses the S3 library from [Soto](https://github.com/soto-project/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. \n\n```swift\nlet awsClient = AWSClient(httpClientProvider: .createNew)\nlet s3 = S3(client: awsClient, region: .euwest1)\nlet s3fs = S3FileSystem(s3Client: s3)\n```\n\n# Path descriptors\n\nS3 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://\u003cbucketname\u003e/\u003cpath\u003e`. For example\n```swift\nlet folder = S3Folder(url: \"s3://bucket/folder\")\nlet file = S3File(url: \"s3://bucket2/folder/file\")\n```\nMost 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`.\n```swift\ns3fs.writeFile(S3File(\"s3://bucket/folder/file\")!, data: data)\n```\nand\n```swift\ns3fs.setCurrentFolder(S3Folder(url: \"s3://bucket/folder\")!)\n    .flatMap { _ in\n        return s3fs.writeFile(name: \"file\", data: data)\n}\n```\nwill 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. \n\n# Asynchronous\n\nMost 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](https://apple.github.io/swift-nio/docs/current/NIO/index.html) to get the most out of S3 File System. \n\nThe recommended way to interact with `EventLoopFutures` is chaining. The following creates an S3 bucket, uploads an object and then downloads it.\n```swift\nimport S3FileSystemKit\n\nlet result: EventLoopFuture\u003cData\u003e = s3fs.setCurrentFolder(S3Folder(url: \"s3://bucket/\")!, createBucket: true)\n  .flatMap { _ in\n      return self.s3fs.writeFile(name: filename, data: data)\n  }\n  .flatMap { _ in\n      return self.s3fs.readFile(name: filename)\n  }\n```\n\n# Documentation\n\nYou can find API reference documentation [here](https://adam-fowler.github.io/s3-filesystem-kit/index.html). It is also useful to read the Amazon S3 documentation which you can find [here](https://docs.aws.amazon.com/AmazonS3/latest/dev/Welcome.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadam-fowler%2Fs3-filesystem-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadam-fowler%2Fs3-filesystem-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadam-fowler%2Fs3-filesystem-kit/lists"}