Merge pull request #44 from transloadit/codex/tus-chunk-size-and-upload-docs

Expose TUS upload chunk size

Author: tim-kos

.github/workflows/transloaditkit-ci.yml

@@ -2,18 +2,11 @@ name: CI
 on: [push, workflow_dispatch]
 jobs:
   build:
-    name: Swift ${{ matrix.swift }} on ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: ["macos-latest"]
-        swift: ["6.0.2"]
-    runs-on: ${{ matrix.os }}
+    name: Swift on macos-latest
+    runs-on: macos-latest
     steps:
       - name: Extract Branch Name
         run: echo "BRANCH=$(echo ${GITHUB_REF##*/})" >> $GITHUB_ENV
-      - uses: swift-actions/setup-swift@v2
-        with:
-          swift-version: ${{ matrix.swift }}
       - name: Get swift version
         run: swift --version
       - uses: actions/checkout@v2

CHANGELOG.md

@@ -1,5 +1,10 @@
 # TransloaditKit Changelog
 
+## Next
+
+* Added `tusUploadChunkSize` to Transloadit initializers so apps can tune TUS chunking behavior, including single-request uploads with `0`.
+* Clarified that `createAssembly(... andUpload ..., completion:)` completes after upload scheduling, not after file upload or processing completion.
+
 ## 3.5.0
 
 * Allow clients to inject only an api key and provide a signature generator closure to calculate signatures for signing requests instead of injecting a key and secret. ([#42](https://github.com/transloadit/TransloaditKit/issues/42))
@@ -34,7 +39,7 @@
 ### Fixes
 
 ### Added
-* It's now possible to cancel a running Assembly 
+* It's now possible to cancel a running Assembly
 * Bumped TUSKit version
 * Allow passing of custom fields to assembly creating by passing them to `createAssembly` methods
 

README.md

@@ -45,10 +45,10 @@ To do this, use the `Transloadit` initializer that takes an api key and a `signa
 
 ```swift
 let transloadit = Transloadit(
-    apiKey: "YOUR-API-KEY", 
-    sessionConfiguration: .default, 
+    apiKey: "YOUR-API-KEY",
+    sessionConfiguration: .default,
     signatureGenerator: { stringToSign, onSignatureGenerated in
-        mySigningService.sign(stringToSign) { result in 
+        mySigningService.sign(stringToSign) { result in
           onSignatureGenerated(result)
         }
     })
@@ -63,7 +63,7 @@ public typealias SignatureGenerator = (String, SignatureCompletion) -> Void
 
 The generator itself is passed a string that needs to be signed (a JSON representation of the request parameters that you're generating a signature for) and a closure that you _must_ call to inform the SDK when you're done generating the signature (whether it's successful or failed).
 
-**Important** if you don't call the completion handler, your requests will never be sent. The SDK does not implement a fallback or timeout. 
+**Important** if you don't call the completion handler, your requests will never be sent. The SDK does not implement a fallback or timeout.
 
 The SDK will invoke the signature generator for every request that requires a signature. It will pass a parameter string for each request to your closure which you can then send to your service (local or external) for signature generation.
 
@@ -73,6 +73,18 @@ To learn more about signature generation see this page: https://transloadit.com/
 
 To create an `Assembly` you invoke `createAssembly(steps:andUpload:completion)` on `Transloadit`.
 It returns a `TransloaditPoller` that you can use to poll for the `AssemblyStatus` of your `Assembly`.
+The completion handler is called after the Assembly has been created and uploads have been scheduled. It does not mean the files have finished uploading.
+Use `TransloaditFileDelegate.didFinishUpload` to detect file upload completion, and use the returned poller to wait for processing completion.
+
+By default, TUS uploads are split into 500 KiB chunks. For iOS background uploads, this means the system needs to schedule a new upload task for every chunk.
+If that is too aggressive for your app, configure a larger `tusUploadChunkSize`, or pass `0` to let TUSKit upload each file in one request:
+
+```swift
+let transloadit = Transloadit(
+    credentials: credentials,
+    sessionConfiguration: .background(withIdentifier: "com.example.uploads"),
+    tusUploadChunkSize: 0)
+```
 
 ```swift
 let resizeStep = Step(
@@ -83,7 +95,7 @@ let resizeStep = Step(
         "height": 100,
         "resize_strategy": "fit",
         "result": true])
-        
+
 let filesToUpload: [URL] = ...
 transloadit.createAssembly(steps: [resizeStep], andUpload: filesToUpload) { result in
     switch result {