Better documentation

LICENSE

@@ -1,11 +1,11 @@
            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
                    Version 2, December 2004
 
-Copyright (C) 2018-2019 Binary Birds
+Copyright (C) 2018-2021 Tibor Bödecs
 
 Authors:
 
-    Tibor Bodecs <mail.tib@gmail.com>
+    Tibor Bödecs <mail.tib@gmail.com>
 
 Everyone is permitted to copy and distribute verbatim or modified
 copies of this license document, and changing it is allowed as long

Package.resolved

@@ -6,17 +6,17 @@
         "repositoryURL": "https://github.com/apple/swift-log.git",
         "state": {
           "branch": null,
-          "revision": "173f567a2dfec11d74588eea82cecea555bdc0bc",
-          "version": "1.4.0"
+          "revision": "12d3a8651d32295794a850307f77407f95b8c881",
+          "version": "1.4.1"
         }
       },
       {
         "package": "swift-nio",
         "repositoryURL": "https://github.com/apple/swift-nio.git",
         "state": {
           "branch": null,
-          "revision": "2bae395344d41710dffab456265d534d7dc34ab8",
-          "version": "2.25.0"
+          "revision": "6d3ca7e54e06a69d0f2612c2ce8bb8b7319085a4",
+          "version": "2.26.0"
         }
       }
     ]

Package.swift

@@ -10,7 +10,7 @@ let package = Package(
         .library(name: "LiquidKit", targets: ["LiquidKit"]),
     ],
     dependencies: [
-        .package(url: "https://github.com/apple/swift-nio.git", from: "2.23.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.26.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.4.0"),
     ],
     targets: [

README.md

@@ -1,75 +1,131 @@
 # LiquidKit
 
-Common interfaces for the Liquid file storage.
+An abstract FileStorage solution, based on the SwiftNIO framework.
 
+### Drivers and Vapor 4 support
 
-## Usage example
+Currently available drivers:
 
-Add dependencies:
+- [local](https://github.com/BinaryBirds/liquid-local-driver)
+- [AWS S3](https://github.com/BinaryBirds/liquid-aws-s3-driver)
+
+LiquidKit is also compatible with Vapor 4 through the [Liquid](https://github.com/BinaryBirds/liquid) repository, that contains Vapor specific extensions.
+
+
+## Usage with SwiftNIO
+
+You can use the Liquid FileStorage driver directly with SwiftNIO, here's a possible usage example:   
+
+```
+/// setup thread pool
+let elg = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+let pool = NIOThreadPool(numberOfThreads: 1)
+pool.start()
+
+/// create fs  
+let fileio = NonBlockingFileIO(threadPool: pool)
+let storages = FileStorages(fileio: fileio)
+storages.use(.custom(exampleConfigVariable: "assets"), as: .custom)
+let fs = storages.fileStorage(.custom, logger: .init(label: "[test-logger]"), on: elg.next())!
+
+/// test file upload
+let key = "test.txt"
+let data = Data("file storage test".utf8)
+let res = try fs.upload(key: key, data: data).wait()
 
-```swift
-// swift-tools-version:5.3
-import PackageDescription
-
-let package = Package(
-    name: "myProject",
-    platforms: [
-       .macOS(.v10_15)
-    ],
-    dependencies: [
-        // 💧 A server-side Swift web framework.
-        .package(url: "https://github.com/vapor/vapor.git", from: "4.30.0"),
-        .package(url: "https://github.com/binarybirds/liquid.git", from: "1.1.0"),
-        .package(url: "https://github.com/binarybirds/liquid-local-driver.git", from: "1.1.0"),
-    ],
-    targets: [
-        .target(name: "App", dependencies: [
-            .product(name: "Vapor", package: "vapor"),
-            .product(name: "Liquid", package: "liquid"),
-            .product(name: "LiquidLocalDriver", package: "liquid-local-driver"),
-        ]),
-    ]
-)
 ```
 
-Driver configuration
+
+## How to implement a custom driver?
+
+Drivers should implement the following protocols:
+
+### FileStorageID
+
+Used to uniquely identify the file storage driver.
 
 ```swift
-import Liquid
-import LiquidLocalDriver
+public extension FileStorageID {
+    static var customDriver: FileStorageID { .init(string: "custom-driver-identifier") }
+}
+```
+
+### FileStorageConfiguration
 
-public func configure(_ app: Application) throws {
+A custom set of configuration variables required to initialize or setup the driver. 
 
-    app.middleware.use(FileMiddleware(publicDirectory: app.directory.publicDirectory))
+```swift
+struct LiquidCustomStorageConfiguration: FileStorageConfiguration {
+    let exampleConfigVariable: String
 
-    // using the local driver
-    app.fileStorages.use(.local(publicUrl: "http://localhost:8080/",
-                                publicPath: app.directory.publicDirectory,
-                                workDirectory: "assets"), as: .local)
+    func makeDriver(for storages: FileStorages) -> FileStorageDriver {
+        return LiquidCustomStorageDriver(fileio: storages.fileio, configuration: self)
+    }
 }
 ```
 
-File upload example:
+### FileStorageDriver
+
+The file storage driver used to create the underlying storage object (that implements the API methods) using the configuration and context.
 
 ```swift
+struct LiquidCustomStorageDriver: FileStorageDriver {
+
+    let fileio: NonBlockingFileIO
+    let configuration: LiquidCustomStorageConfiguration
+
+    func makeStorage(with context: FileStorageContext) -> FileStorage {
+        LiquidCustomStorage(fileio: fileio, configuration: configuration, context: context)
+    }
+
+    func shutdown() {
 
-func testUpload(req: Request) -> EventLoopFuture<String> {
-    let data: Data! = //...
-    let key = "path/to/my/file.txt"
-    return req.fs.upload(key: key, data: data)
-    // returns the full public url of the uploaded image
+    }
 }
+```
+
+### FileStorage
+
+Actual storage implementation that handles the necessary API methods.
 
-// resolve public url based on a key
-// func resolve(key: String) -> String
-req.fs.resolve(key: myImageKey)
+```swift
 
-// delete file based on a key
-// func delete(key: String) -> EventLoopFuture<Void>
-req.fs.delete(key: myImageKey)
+struct LiquidCustomStorage: FileStorage {
+
+    let fileio: NonBlockingFileIO
+    let configuration: LiquidCustomStorageConfiguration
+    let context: FileStorageContext
+
+
+    init(fileio: NonBlockingFileIO, configuration: LiquidCustomStorageConfiguration, context: FileStorageContext) {
+        self.fileio = fileio
+        self.configuration = configuration
+        self.context = context
+    }
+
+    // MARK: - api
+
+    func resolve(key: String) -> String { /* ... */ }
+    func upload(key: String, data: Data) -> EventLoopFuture<String> { /* ... */ }
+    func createDirectory(key: String) -> EventLoopFuture<Void> { /* ... */ }
+    func list(key: String?) -> EventLoopFuture<[String]> { /* ... */ }
+    func copy(key source: String, to destination: String) -> EventLoopFuture<String> { /* ... */ }
+    func move(key source: String, to destination: String) -> EventLoopFuture<String> { /* ... */ }
+    func delete(key: String) -> EventLoopFuture<Void> { /* ... */ }
+    func exists(key: String) -> EventLoopFuture<Bool> { /* ... */ }
+}
 ```
 
+### FileStorageConfigurationFactory
 
-## License
+An extension on the FileStorageConfigurationFactory object that helps you to create the custom driver with the necessary config values.
+
+```swift
+public extension FileStorageConfigurationFactory {
+
+    static func custom(exampleConfigVariable: String) -> FileStorageConfigurationFactory {
+        .init { LiquidCustomStorageConfiguration(exampleConfigVariable) }
+    }
+}
+```
 
-[WTFPL](LICENSE) - Do what the fuck you want to.

Sources/LiquidKit/FileStorage.swift

@@ -7,11 +7,16 @@
 
 import struct Foundation.Data
 
+/// Liquid errors
 public enum LiquidError: Swift.Error {
+    /// key not exists error
     case keyNotExists
 }
 
+/// file storage protocol, must be implemented by the drivers
 public protocol FileStorage {
+
+    /// fs context
     var context: FileStorageContext { get }
 
     /// returns a key as a full url

Sources/LiquidKit/FileStorageConfiguration.swift

@@ -5,7 +5,9 @@
 //  Created by Tibor Bodecs on 2020. 04. 28..
 //
 
+/// fs configuration protocol
 public protocol FileStorageConfiguration {
 
+    /// creates a new driver using the FileStorages object, driver will be stored in that storage
     func makeDriver(for: FileStorages) -> FileStorageDriver
 }

Sources/LiquidKit/FileStorageConfigurationFactory.swift

@@ -5,10 +5,13 @@
 //  Created by Tibor Bodecs on 2020. 04. 28..
 //
 
+/// file storage configuration factory
 public struct FileStorageConfigurationFactory {
 
+    /// creates a new fs configuration object
     public let make: () -> FileStorageConfiguration
 
+    /// init the fs factory with a make block
     public init(make: @escaping () -> FileStorageConfiguration) {
         self.make = make
     }

Sources/LiquidKit/FileStorageContext.swift

@@ -5,11 +5,19 @@
 //  Created by Tibor Bodecs on 2020. 04. 28..
 //
 
+/// file storage context object
 public struct FileStorageContext {
+
+    /// file storage configuration
     public let configuration: FileStorageConfiguration
+
+    /// logger
     public let logger: Logger
+
+    /// event loop
     public let eventLoop: EventLoop
 
+    /// public init method
     public init(configuration: FileStorageConfiguration,
                 logger: Logger,
                 eventLoop: EventLoop) {

Sources/LiquidKit/FileStorageDriver.swift

@@ -5,7 +5,12 @@
 //  Created by Tibor Bodecs on 2020. 04. 28..
 //
 
+/// FileStorageDriver protocol to create a FileStorage with a given context
 public protocol FileStorageDriver {
+
+    /// creates a FileStorage object with a given context
     func makeStorage(with context: FileStorageContext) -> FileStorage
+
+    /// shuts down the driver
     func shutdown()
 }

Sources/LiquidKit/FileStorageID.swift

@@ -5,8 +5,13 @@
 //  Created by Tibor Bodecs on 2020. 04. 28..
 //
 
+/// a hashable, and codable file storage identifier object
 public struct FileStorageID: Hashable, Codable {
+
+    /// string representation of the identifier
     public let string: String
+
+    /// init a fs identifier using a string 
     public init(string: String) {
         self.string = string
     }