Nanometer Process Machine

    @boostercloud/rocket-storage-aws-infrastructure
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.5-alpha • Public • Published

    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:

    {}

    Install

    npm i @boostercloud/rocket-storage-aws-infrastructure

    DownloadsWeekly Downloads

    2

    Version

    1.0.5-alpha

    License

    Apache-2.0

    Unpacked Size

    6.66 MB

    Total Files

    1876

    Last publish

    Collaborators

    • gjaubert
    • juanjoman
    • adrian.theam
    • nickseagull
    • alvaroloes
    • javiertoledo
    • charlietfe
    • laiaperez
    • otoumas
    • rdiaz_theam
    • rdoria
    • carlosper88
    • adrian.gonzalez
    • adayb
    • marcastr0