Feature/support version 0.28.2 of the storage api (#26)

* add javadoc to main interfaces/classes

* bump compiled code to java 17

* add transform options
add more tests
add info to changelog
bump version

* update GHA secret name

* update GHA secret name

* update pom.xml reference

* usa java 17 on GHA

* Update tests

Co-authored-by: MagnusHJensen <magnus.holm.jensen@lego.dk>

Author: MagnusHJensen

.github/workflows/main.yml

@@ -14,15 +14,15 @@ jobs:
       - name: Clone Repository
         uses: actions/checkout@v3
 
-      - name: Setup JDK 8
+      - name: Setup JDK 17
         uses: actions/setup-java@v3
         with:
-          java-version: '8'
+          java-version: '17'
           distribution: 'adopt'
           cache: maven
           server-id: 'github'
           server-username: 'supabase-community'
-          server-password: ${{ secrets.GITHUB_TOKEN }}
+          server-password: ${{ secrets.PACKAGES_PAT }}
 
       - name: Run docker compose
         run: cd infra && docker compose up -d
@@ -38,5 +38,5 @@ jobs:
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           javadoc-branch: javadoc
-          java-version: 8
+          java-version: 17
           project: maven

.github/workflows/pull_request.yml

@@ -17,10 +17,10 @@ jobs:
     steps:
       - name: Clone Repository
         uses: actions/checkout@v3
-      - name: Setup JDK 8
+      - name: Setup JDK 17
         uses: actions/setup-java@v3
         with:
-          java-version: '8'
+          java-version: '17'
           distribution: 'adopt'
           cache: maven
       - name: Run docker compose

CHANGELOG.md

@@ -1 +1,6 @@
 # Changelog
+
+## v1.0.0 - [Supports v0.28.2](https://github.com/supabase/storage-api/releases/tag/v0.28.2)
+- Added new `FileTransformOptions`.
+- Updated [javadocs](https://supabase-community.github.io/storage-java)
+- Cleaned up code a bit.

README.md

@@ -5,13 +5,15 @@
 # storage-java
 An async Java client library for the [Supabase Storage API](https://github.com/supabase/storage-api)
 
+The version being used supports different version of the storage API, you can find which version supports up to what version in the [CHANGELOG](./CHANGELOG.md)
+
 ## Example
+
 ```java
 import io.supabase.StorageClient;
 import io.supabase.api.IStorageFileAPI;
 import io.supabase.data.bucket.CreateBucketResponse;
-import io.supabase.data.file.FileDownloadOption;
-import io.supabase.data.file.FilePathResponse;
+import io.supabase.data.file.*;
 
 import java.io.File;
 import java.util.concurrent.CompletableFuture;
@@ -36,13 +38,13 @@ public class Main {
                 FilePathResponse response = fileAPI.upload("my-secret-image/image.png", new File("file-path-to-image.png")).get();
 
                 // Generate a public url (The link is only valid if the bucket is public).
-                fileAPI.getPublicUrl("my-secret-image/image.png", new FileDownloadOption(false));
+                fileAPI.getPublicUrl("my-secret-image/image.png", new FileDownloadOption(false), new FileTransformOptions(500, 500, ResizeOption.COVER, 50, FormatOption.NONE));
 
                 // Create a signed url to download an object in a private bucket that expires in 60 seconds, and will be downloaded instantly on link as "my-image.png"
-                fileAPI.getSignedUrl("my-secret-image/image.png", 60, new FileDownloadOption("my-image.png"));
+                fileAPI.getSignedUrl("my-secret-image/image.png", 60, new FileDownloadOption("my-image.png"), null);
 
                 // Download the file
-                fileAPI.download("my-secret-image/image.png");
+                fileAPI.download("my-secret-image/image.png", null);
 
             } catch (InterruptedException | ExecutionException e) {
                 throw new RuntimeException(e);

infra/docker-compose.yml

@@ -17,20 +17,22 @@ services:
     ports:
       - '3000:3000'
     depends_on:
-      - db
+      storage:
+        condition: service_healthy
     restart: always
     environment:
       PGRST_DB_URI: postgres://postgres:postgres@db:5432/postgres
       PGRST_DB_SCHEMA: public, storage
       PGRST_DB_ANON_ROLE: postgres
       PGRST_JWT_SECRET: super-secret-jwt-token-with-at-least-32-characters-long
   storage:
-    image: supabase/storage-api:v0.20.2
+    build:
+      context: ./storage
     ports:
       - '5000:5000'
     depends_on:
-      - db
-      - rest
+      db:
+        condition: service_healthy
     restart: always
     environment:
       ANON_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlhdCI6MTYxMzUzMTk4NSwiZXhwIjoxOTI5MTA3OTg1fQ.ReNhHIoXIOa-8tL1DO3e26mJmOTnYuvdgobwIYGzrLQ
@@ -47,6 +49,12 @@ services:
       FILE_SIZE_LIMIT: 52428800
       STORAGE_BACKEND: file
       FILE_STORAGE_BACKEND_PATH: /tmp/storage
+      ENABLE_IMAGE_TRANSFORMATION: "true"
+      IMGPROXY_URL: http://imgproxy:8080
+    volumes:
+      - assets-volume:/tmp/storage
+    healthcheck:
+      test: [ 'CMD-SHELL', 'curl -f -LI http://localhost:5000/status' ]
 
   db:
     build:
@@ -61,4 +69,22 @@ services:
       POSTGRES_DB: postgres
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
-      POSTGRES_PORT: 5432
+      POSTGRES_PORT: 5432
+    healthcheck:
+      test: [ "CMD-SHELL", "pg_isready" ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  imgproxy:
+    image: darthsim/imgproxy
+    ports:
+      - "50020:8080"
+    volumes:
+      - assets-volume:/tmp/storage
+    environment:
+      - IMGPROXY_LOCAL_FILESYSTEM_ROOT=/
+      - IMGPROXY_USE_ETAG=true
+      - IMGPROXY_ENABLE_WEBP_DETECTION=true
+volumes:
+  assets-volume:

infra/storage/Dockerfile

@@ -0,0 +1,3 @@
+FROM supabase/storage-api:v0.28.0
+
+RUN apk add curl --no-cache

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.supabase</groupId>
     <artifactId>storage-java</artifactId>
-    <version>0.1.0</version>
+    <version>1.0.0</version>
 
     <name>Storage Java</name>
     <description>An async client library for the Supabase Storage API in Java</description>
@@ -83,11 +83,6 @@
                 <artifactId>maven-surefire-plugin</artifactId>
                 <version>2.22.2</version>
                 <dependencies>
-                    <dependency>
-                        <groupId>org.junit.platform</groupId>
-                        <artifactId>junit-platform-surefire-provider</artifactId>
-                        <version>1.3.2</version>
-                    </dependency>
                     <dependency>
                         <groupId>org.junit.jupiter</groupId>
                         <artifactId>junit-jupiter-engine</artifactId>
@@ -121,12 +116,20 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>${maven.compiler.source}</source>
+                    <target>${maven.compiler.target}</target>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 
     <properties>
-        <maven.compiler.source>8</maven.compiler.source>
-        <maven.compiler.target>8</maven.compiler.target>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     </properties>
 

src/main/java/io/supabase/StorageClient.java

@@ -12,7 +12,7 @@ public class StorageClient extends StorageBucketAPI implements IStorageClient {
     private final Map<String, String> headers;
 
     public StorageClient(String apiKey, String url) {
-        this(url, new HashMap<String, String>() {{
+        this(url, new HashMap<>() {{
             put("Authorization", "Bearer " + apiKey);
         }});
         // Validate URL and throw if not a valid url.

src/main/java/io/supabase/api/IStorageBucketAPI.java

@@ -11,21 +11,62 @@
 
 public interface IStorageBucketAPI {
 
+    /**
+     * <p>POST /bucket/</p>
+     *
+     * @param bucketId The name/id of the bucket you want to create.
+     * @return a {@link CreateBucketResponse} object.
+     */
     CompletableFuture<CreateBucketResponse> createBucket(String bucketId);
+
+    /**
+     * <p>POST /bucket/</p>
+     *
+     * @param bucketId The name/id of the bucket you want to create.
+     * @param options  The options you want to pass for the bucket creation.
+     * @return a {@link CreateBucketResponse} object.
+     */
     CompletableFuture<CreateBucketResponse> createBucket(String bucketId, BucketCreateOptions options);
 
     /**
+     * <p>GET /bucket/</p>
      * Lists all buckets in the project.
+     *
      * @return A list of all buckets.
      */
     CompletableFuture<List<Bucket>> listBuckets();
 
+    /**
+     * <p>POST /bucket/{bucketId}/empty</p>
+     *
+     * @param bucketId The bucket you want to empty.
+     * @return a status message
+     */
     CompletableFuture<MessageResponse> emptyBucket(String bucketId);
 
+    /**
+     * <p>GET /bucket/{bucketId}/</p>
+     *
+     * @param bucketId The bucket of which you want to retrieve.
+     * @return the asked for bucket
+     */
     CompletableFuture<Bucket> getBucket(String bucketId);
 
+    /**
+     * <p>PUT /bucket/{bucketId}/</p>
+     *
+     * @param bucketId The bucket you want to update
+     * @param options  The options to update the bucket to.
+     * @return a status message
+     */
     CompletableFuture<MessageResponse> updateBucket(String bucketId, BucketUpdateOptions options);
 
+    /**
+     * <p>DELETE /bucket/{bucketId}</p>
+     *
+     * @param bucketId The bucket of which you want to delete.
+     * @return a status message
+     */
     CompletableFuture<MessageResponse> deleteBucket(String bucketId);
 
 }

src/main/java/io/supabase/api/IStorageFileAPI.java

@@ -9,16 +9,107 @@
 
 public interface IStorageFileAPI {
 
+    /**
+     * <p>POST /object/{bucketName}/{wildcard}</p>
+     *
+     * @param path The path to the file within the bucket of where it should be uploaded.
+     * @param file The file that needs to be uploaded.
+     * @return a {@link FilePathResponse}
+     */
     CompletableFuture<FilePathResponse> upload(String path, File file);
+
+    /**
+     * <p>PUT /object/{bucketName}/{wildcard}</p>
+     *
+     * @param path The path to the file within the bucket that should get updated.
+     * @param file The new file that should be placed.
+     * @return a {@link FilePathResponse}
+     */
     CompletableFuture<FilePathResponse> update(String path, File file);
+
+    /**
+     * <p>POST /object/move/</p>
+     *
+     * @param fromPath The path to the object that needs to be moved.
+     * @param toPath   The new path where the object should be moved to.
+     * @return a {@link MessageResponse}
+     */
     CompletableFuture<MessageResponse> move(String fromPath, String toPath);
+
+    /**
+     * <p>POST /object/copy/</p>
+     *
+     * @param fromPath The path to the object that needs to be copied.
+     * @param toPath   The new path where the object should be copied to.
+     * @return a {@link FilePathResponse}
+     */
     CompletableFuture<FilePathResponse> copy(String fromPath, String toPath);
-    CompletableFuture<FileSignedUrlResponse> getSignedUrl(String path, int expiresIn, FileDownloadOption options);
-    CompletableFuture<List<FileSignedUrlResponse>> getSignedUrls(List<String> paths, int expiresIn, FileDownloadOption options);
-    CompletableFuture<FileDownload> download(String path);
-    FilePublicUrlResponse getPublicUrl(String path, FileDownloadOption options);
 
+    /**
+     * <p>POST /object/sign/{bucketName}</p>
+     * <p>This method just wraps {@link #getSignedUrls(List, int, FileDownloadOption, FileTransformOptions)}</p>
+     *
+     * @param path      The singular file path that should be signed.
+     * @param expiresIn how many seconds until the signed url expires.
+     * @param downloadOptions   any additional download options.
+     * @param transformOptions The transform options if any
+     * @return a {@link FileSignedUrlResponse}
+     */
+    CompletableFuture<FileSignedUrlResponse> getSignedUrl(String path, int expiresIn, FileDownloadOption downloadOptions, FileTransformOptions transformOptions);
+
+    /**
+     * <p>POST /object/sign/{bucketName}</p>
+     *
+     * @param paths     a list of file paths that should be signed.
+     * @param expiresIn how many seconds until the signed urls expires.
+     * @param downloadOptions   any additional download options.
+     * @param transformOptions The transform options if any
+     * @return a list of {@link FileSignedUrlResponse}
+     */
+    CompletableFuture<List<FileSignedUrlResponse>> getSignedUrls(List<String> paths, int expiresIn, FileDownloadOption downloadOptions, FileTransformOptions transformOptions);
+
+    /**
+     * <p>Downloads a file from a private bucket. To download something from a public bucket, make a request to the url from {@link #getPublicUrl(String, FileDownloadOption, FileTransformOptions)}</p>
+     * <p>GET /object/authenticated/{bucketName}/{wildcard}</p>
+     *
+     * @param path The path of the file to download
+     * @param transformOptions The transform options if any
+     * @return a {@link FileDownload}
+     */
+    CompletableFuture<FileDownload> download(String path, FileTransformOptions transformOptions);
+
+    /**
+     * Creates the url for an object in a public bucket
+     *
+     * @param path    The path of the file the link should point to.
+     * @param downloadOptions The download options if any.
+     * @param transformOptions The transform options if any
+     * @return a {@link FilePublicUrlResponse}
+     */
+    FilePublicUrlResponse getPublicUrl(String path, FileDownloadOption downloadOptions, FileTransformOptions transformOptions);
+
+    /**
+     * <p>POST /object/list/{bucketName}</p>
+     *
+     * @param options Options for the file search
+     * @return a list of {@link io.supabase.data.file.File}
+     */
     CompletableFuture<List<io.supabase.data.file.File>> list(FileSearchOptions options);
+
+    /**
+     * <p>POST /object/list/{bucketName}</p>
+     *
+     * @param path    The prefix to list objects by
+     * @param options Options for the file search
+     * @return a list of {@link io.supabase.data.file.File}
+     */
     CompletableFuture<List<io.supabase.data.file.File>> list(String path, FileSearchOptions options);
+
+    /**
+     * <p>DELETE /object/{bucketName}</p>
+     *
+     * @param paths a list of paths to files that should be deleted. BE WARY! PROVIDING NULL OR AN EMPTY LIST WILL DELETE THE ENTIRE BUCKET!
+     * @return a list of the deleted files
+     */
     CompletableFuture<List<io.supabase.data.file.File>> delete(List<String> paths);
 }