Usage & Example

Backend:

1. Request an S3 URL for file upload:

To request an S3 URL for file upload, you should create a route. Here's how to do it using Etherial:

import {
    Get,
    ShouldUseRoute,
} from "etherial/components/http/provider";

import * as FileRequestForm from "etherial/leafs/s3/forms/file_request_form";
import { FileRequestRoute } from "etherial/leafs/s3/routes/files";

@Post("/users/me/files/requests")
@ShouldUseRoute(FileRequestRoute())
@ShouldValidateForm(FileRequestForm.Create)
@ShouldBeAuthentificate()
public userFileRequest() {}

This code creates a route for requesting an S3 URL for file upload.

2. Create a route to receive the uploaded document:

Before creating a route to receive the uploaded document, you need to define a form for it. Here's an example of how to create a form for a user picture upload:

import {
    Form,
    Body,
    ShouldExist,
    ShouldBeNotEmpty
} from "etherial/components/http/validator";

import { ShouldBeS3File } from 'etherial/leafs/s3/extensions/http/validator'

@Form()
export class Create {

    @ShouldExist()
    @ShouldBeNotEmpty()
    @ShouldBeS3File("users/pictures") // This has to be the users/pictures folder from S3 !
    @Body()
    picture: string;
    
}

This form enforces validation rules on the uploaded picture.

3. Create a route to handle the picture upload:

Now, you can create a route to handle the picture upload:

@Put('/users/me/picture')
@ShouldValidateForm(UserPictureForm.Create)
@ShouldBeAuthentificate()
public async userPicture(
    req: Request & { form: UserPictureForm.Create },
    res: Response
): Promise<any> {
    return req.user.update({
        picture: req.form.picture
    })
}

This route handles the picture upload, and it should be protected with authentication (@ShouldBeAuthentificate()).

Frontend:

1. Request an S3 URL for file upload:

Once you have a file to upload, you can request an S3 URL by making a POST request to /users/me/files/requests (Can be fetch with RTKQ). You can use the fetch API to do this:

let umfr = await fetch("/users/me/files/requests", {
    method: "POST",
    headers: {...token...},
    body: JSON.stringify({
        "content-type": "image/png",
        "private": false,
        "folder": "users/pictures" // this has to be the same of your form
    })
}).then((res) => res.json())

This code sends a POST request to request an S3 URL for uploading the file.

2. Upload the file to S3:

After obtaining the S3 URL, you can upload the file to S3 using a PUT request:

let s3res = await fetch(data.url, {
    method: "PUT",
    headers: {
        "x-amz-acl": "public-read",
    },
    body: ImageObj.blobData, // ImageObj can be a base64 or a blob
}).then((res) => res.json())

This code sends a PUT request to upload the file to S3 with the specified headers and the file data in the body.

Then you can do a PUT to your backend for notify that you've uploaded your picture / document

fetch("/users/me/picture", {
    method: "PUT",
    headers: {...token...},
    body: JSON.stringify({
        picture: umfr.file
    })
})

These instructions provide a high-level overview of how to use your S3 component module in the Etherial Framework for both the backend and frontend. Be sure to integrate these steps into your application as needed.

Security Consideration

Important Note: By configuring S3 access according to the provided guidelines, your application obtains authorization for uploading files to Amazon S3. This authorization is scoped to the defined S3 bucket and access keys.

In the current implementation, we ensure that only valid documents are uploaded, providing an initial layer of security. However, as a security best practice, it's important to restrict the types of documents that can be uploaded to specific S3 folders.

Future Enhancement: In future releases of the Etherial Framework, we plan to introduce a feature that allows you to specify permitted MIME types for each folder within your S3 bucket. This feature will provide additional security by ensuring that only files with approved MIME types are accepted for upload, further enhancing the security of your application.

It's essential to regularly review and update your security policies, including MIME type restrictions, to maintain a secure and compliant file upload system. Stay tuned for updates on this feature in upcoming releases of Etherial Framework.