@boostercloud/rocket-storage-aws-infrastructure

Storage Rocket for AWS

This package is a configurable rocket to add a storage API based on S3 to your Booster applications.

Overview

This rocket generates an Api Gateway API to access an AWS S3 bucket. It provides the following methods:

• presignedPost: Returns a presigned post url and the necessary form params. With this url files can be uploaded directly to S3.
• presignedGet: Returns a presigned get url to download a file. With this url files can be downloaded directly from S3.
• upload: Method to upload small files through the lambda function
• download: Method to download small files through the lambda function
• remove: Method to remove a file from S3 bucket

These endpoints may be secured via JWT Token.

Usage

Install this package as a devDependency in your project (It's a devDependency because it's only used during deployment, so we don't want this code to be uploaded to the project lambdas)

npm install --save-dev @boostercloud/rocket-storage-aws-infrastructure

In your Booster config file, pass a RocketDescriptor array to the AWS' Provider initializer configuring the storage rocket:

import { Booster } from '@boostercloud/framework-core'
import { BoosterConfig } from '@boostercloud/framework-types'
import * as AWS from '@boostercloud/framework-provider-aws'

Booster.configure('environment', (config: BoosterConfig): void => {
  config.appName = 'app-name'
  config.tokenVerifier = {
    issuer: string,
    jwksUri: string,
    rolesClaim: string
  }
  config.provider = Provider([{
    packageName: '@boostercloud/rocket-storage-aws-infrastructure',
    parameters: {
      bucketName: 'bucketName',
      fileAcl?: 'public-read',
      authParams?: {
        download?: []
        presignedGet?: []
        presignedPost?: ['Admin', 'CreatorRole'],
        upload?: [],
        remove?: [],
      },
    },
  },])
})

bucketName Specifies the bucket that will be created. It can't preexist. This is a limitation from AWS CDK.

fileAcl Optional parameter to change the ACL of the files uploaded, default value is public-read.

If a method is not added to the authParams then that method will be public.

If at least one method is authenticated, then a tokenVerifier object must exist in the config object.

authParams Parameter to set the different authorization roles for each of the endpoints. It is an optional parameter.

If a method is added to the authParams with an empty array in authorizedRoles then this method just needs an authenticated user.

If a method is added to the authParams with a non-empty array in authorizedRoles then this method is just available for the specified roles.

Every time a Put or Delete actions take place un the specified bucket a new event is generated in the event store.

PresignedPost Usage

The method presignedPost can be used with the following curl:

curl -X POST --location {httpUrl}/storage/presignedPost 
    -H Content-Type: application/json; charset=utf-8
    -H Authorization: Bearer {token}
    -d  {
          "key": "s3/file/key"
        }

This returns the following payload:

{
  "url": "https://s3.amazonaws.com/XXXXXXXXXXXXX",
  "fields": {
    "key": "${key}",
    "acl": "public-read",
    "bucket": "${bucket}",
    "X-Amz-Algorithm": "XXXXXXXXXXXXX",
    "X-Amz-Credential": "XXXXXXXXXXXXX",
    "X-Amz-Date": "XXXXXXXXXXXXX",
    "X-Amz-Security-Token": "XXXXXXXXXXXXX",
    "Policy": "XXXXXXXXXXXXX",
    "X-Amz-Signature": "XXXXXXXXXXXXX"
  },
  "fileUrl": "https://${bucket}.s3.amazonaws.com/${key}"
}

That can be used in a new post rest call:

curl --location --request POST "${url}" \
--form 'key="${key}"' \
--form 'acl="public-read"' \
--form 'bucketMethods="${bucketName}"' \
--form 'X-Amz-Algorithm="XXXXXXXXXXXXX"' \
--form 'X-Amz-Credential="XXXXXXXXXXXXX"' \
--form 'X-Amz-Date="XXXXXXXXXXXXX"' \
--form 'X-Amz-Security-Token="XXXXXXXXXXXXX"' \
--form 'Policy="XXXXXXXXXXXXX"' \
--form 'X-Amz-Signature="XXXXXXXXXXXXX"' \
--form "file=${selectFileToUpload}"

Node example:

const { createReadStream } = require("fs");
const FormData = require("form-data");

function uploadFile({url, fields, fileUrl}): string {
  const form = new FormData();
  Object.entries(fields).forEach(([field, value]) => {
    form.append(field, value);
  });
  form.append("file", createReadStream("path/to/a/file"));
  form.submit(url, (err, res) => {
    //handle the response pseudoCode
    // if (res.status === '204') {
    //   return fileUrl
    // }
    // return error
  });
  
}

PresignedGet Usage

The method presignedGet can be used with the following curl:

curl -X POST --location {httpUrl}/storage/presignedGet 
    -H Content-Type: application/json; charset=utf-8
    -H Authorization: Bearer {token}
    -d  {
          "key": "s3/file/key"
        }

This returns the following payload:

{
  "url": "https://${bucket}.s3.amazonaws.com/${key}?AWSAccessKeyId=XXXX&Expires=XXXXX&Signature=XXXX&x-amz-security-token=XXXXXXX"
}

With that Url the file can be downloaded

Upload usage

The method upload can be used with the following curl:

curl -X POST --location "{httpUrl}/storage/upload" \
    -H Content-Type: application/json; charset=utf-8 \
    -H Authorization: Bearer {token} \
    -d {
          "key": "s3/file/key",
          "fileContent": "this is the content of the file"
      }

This returns the following payload:

{
  "url": "https://${bucket}.s3.amazonaws.com/${key}"
}

Download usage

The method download can be used with the following curl:

curl -X POST --location "{httpUrl}/storage/download" \
    -H Content-Type: application/json; charset=utf-8 \
    -H Authorization: Bearer {token} \
    -d {
          "key": "s3/file/key",
      }

This returns the following payload:

{
  "file": {
    "type": "Buffer",
    "data": [116,101,32,102,105,108,101]
  }
}

Remove usage

The method remove can be used with the following curl:

curl -X POST --location "{httpUrl}/storage/remove" \
    -H Content-Type: application/json; charset=utf-8 \
    -H Authorization: Bearer {token} \
    -d {
          "key": "s3/file/key",
      }

This returns the following payload:

{}