Leaf Extension & Documentation

ShouldBeS3File | Extension of Http Validator

ShouldBeS3File is a function decorator provided by the etherial/leafs/s3/extensions/http/validator module. It is designed to add file existence validation for S3 uploads within your Etherial Forms. This decorator ensures that the specified file exists in the designated S3 folder before processing the form data.

Usage:

To use ShouldBeS3File, apply it as a decorator to a property within an Etherial Form class. It can be used in any form that requires file validation.

Parameters:

• folder (string): The folder parameter specifies the S3 folder where the decorator should verify the existence of the file. This folder is directly derived from the attribute provided on the form.

Example:

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

@Form()
export class UserPictureUpdate {

    @ShouldExist()
    @ShouldBeNotEmpty()
    @ShouldBeS3File("users/pictures") // Verify if the file exists in the "users/pictures" S3 folder
    @Body()
    picture: string;

}

In this example, the ShouldBeS3File decorator is used to ensure that the file specified in the picture attribute exists in the "users/pictures" folder of your S3 bucket. This validation adds an additional layer of security to your forms by confirming the existence of the expected file in the designated folder.

By using ShouldBeS3File, you can enhance the security and reliability of your file upload forms by validating files against S3 folders.

FileRequestForm | Single Form Property

FileRequestForm is a form class, specifically designed for requesting a signed URL for file upload to an Amazon S3 bucket. The Create form includes the following properties, each of which serves a specific purpose in the file request process:

1. folder (string):

   • Validation: It must not be empty (@ShouldBeNotEmpty) and must exist (@ShouldExist).

   • Usage: This property specifies the target folder within the S3 bucket where the file will be uploaded.

2. content_type (string):

   • Validation: It must not be empty (@ShouldBeNotEmpty) and must exist (@ShouldExist).

   • Usage: This property specifies the content type or MIME type of the file being uploaded. It is used to determine the file's extension for naming.

3. private (boolean):

   • Validation: It must exist (@ShouldExist).

   • Usage: This property is optional and represents whether the uploaded file should have private access (e.g., "private") or public access (e.g., "public-read") in the S3 bucket. If not specified, it typically defaults to public access.

Example Usage:

@Form()
export class Create {
    @ShouldBeNotEmpty()
    @ShouldExist()
    @Body()
    folder: string;

    @ShouldBeNotEmpty()
    @ShouldExist()
    @Body()
    content_type: string;

    @ShouldExist()
    @Body()
    private: boolean;
}

This form is used when requesting a signed URL for file uploads, and it enforces validation rules to ensure the necessary data for the upload process is provided. Users can create an instance of this form and populate its properties when making requests to the FileRequestRoute.

FileRequestRoute | Single Route Property

FileRequestRoute is a route function that enables you to request a signed URL for file upload to an Amazon S3 bucket. This route is designed to be used with the ShouldUseRoute decorator and is typically invoked when your application needs to facilitate file uploads to S3.

Usage:

To use FileRequestRoute, you can invoke it as a route handler within your Etherial application. It can be used with the ShouldUseRoute decorator to define the route for requesting S3 upload URLs.

Example:

import { 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")
@ShouldUseRoute(FileRequestRoute())
@ShouldValidateForm(FileRequestForm.Create)
public userFileRequest() {}

In this example, the FileRequestRoute is associated with the route for requesting S3 upload URLs and is used to generate a signed URL for file uploads.

Returned Object:

The route handler returns a JSON object with the following structure:

{
    "status": 200,
    "data": {
        "url": "https://your-s3-bucket.s3.amazonaws.com/your-folder/unique-filename.ext?...",
        "filename": "unique-filename",
        "extension": "ext",
        "path": "your-folder/unique-filename.ext",
        "public_url": "https://your-public-url/your-folder/unique-filename.ext",
        "file": "unique-filename.ext"
    }
}

• status: The HTTP status code, indicating a successful response (e.g., 200).

• data: An object containing the following properties:

  • url: The signed URL for the S3 upload operation. This URL is time-limited and includes the S3 bucket, folder, filename, and other relevant parameters.

  • filename: The unique filename generated for the uploaded file.

  • extension: The file extension derived from the content_type in the form.

  • path: The complete path within the S3 bucket, including the folder and filename with extension.

  • public_url: The public URL where the uploaded file can be accessed. This URL is often based on your server configuration.

  • file: The filename with the file extension.

This structured response provides essential information about the uploaded file, making it clear and user-friendly for further processing in your application.