Docs: Aws3 - rollthecloudinc/quell GitHub Wiki

Documentation for AWS3 Angular Library

Table of Contents

  1. Introduction
  2. Installation
  3. Overview
  4. Key Concepts
    • AWS S3 Integration
    • CRUD Operations with Signed URL
    • Cognito Integration for Authentication
  5. Core Components
    • Aws3Module
  6. Key Factories
    • s3EntityCrudAdaptorPluginFactory
    • createS3SignedHttpRequest
  7. Usage
    • Registering the Plugin
    • Performing CRUD Operations
    • Querying Data in S3
  8. API Reference
  9. Examples
  10. Testing

1. Introduction

The AWS3 Angular library provides an efficient way to integrate AWS S3 into Angular applications. It leverages signed URLs for secure S3 object operations and integrates with AWS Cognito for identity management. The library works seamlessly with @rollthecloudinc/crud to provide CRUD operations on S3 objects and supports rule-based queries using json-rules-engine.

2. Installation

Install the library along with required dependencies:

npm install aws3 @aws-sdk/client-s3 @rollthecloudinc/crud @rollthecloudinc/awcog @rollthecloudinc/auth @rollthecloudinc/dparam

3. Overview

AWS3 is designed for secure interaction with AWS S3 buckets using signed URL requests. It integrates with AWS Cognito for authentication, enabling authorized operations on S3 objects, such as create, read, update, delete, and query.

Features:

  • Secure Object Operations: Uses pre-signed URLs with AWS Signature V4 for interacting with S3 objects.
  • AWS Cognito Authentication: Governs access to resources via identity pool credentials.
  • Dynamic CRUD Operations: Provides full CRUD functionality using S3 bucket storage for JSON objects.
  • Advanced Querying: Enables rule-based filtering and querying of S3 data using json-rules-engine.

4. Key Concepts

4.1 AWS S3 Integration

The library interacts with AWS S3 by generating signed HTTP requests using AWS Signature V4. These requests allow secure data exchanges without exposing AWS credentials.

4.2 CRUD Operations with Signed URL

CRUD operations (create, read, update, delete) are implemented using signed URLs, ensuring operations are performed securely and authenticated based on AWS credentials.

4.3 Cognito Integration for Authentication

AWS Cognito is used to fetch temporary credentials for the user. It integrates seamlessly into the signed URL workflow, enforcing identity-based access control on S3 objects.

5. Core Components

Aws3Module

The Aws3Module is the entry point of the library. It registers the CRUD adaptor plugin (aws_s3_entity) and handles initialization of dependencies such as AuthFacade and ParamEvaluatorService.

Core Features:

  • Automatic registration of S3 entity plugin for CRUD operations.
  • Dependency injection for Cognito settings via AWCOG.
  • Integration with @rollthecloudinc/crud for dynamic operations on S3 objects.

Example:

import { Aws3Module } from 'aws3';

@NgModule({
  imports: [Aws3Module],
  declarations: [],
  exports: [],
})
export class AppModule {}

6. Key Factories

s3EntityCrudAdaptorPluginFactory

This factory creates a CRUD adaptor plugin capable of interacting with AWS S3 objects using signed URLs. Its methods handle operations such as create, update, delete, and query.

Features:

  • Secure Requests: Uses AWS Signature V4 for signing HTTP requests.
  • Dynamic Options: Supports parameters like bucket and prefix for flexible bucket configurations.
  • Rule-based Queries: Queries objects in S3 using rules defined in json-rules-engine.

createS3SignedHttpRequest

Generates a signed HTTP request for secure interaction with AWS S3. This utility leverages AWS Signature V4 to compute request signatures.

Parameters:

  • body: Request payload.
  • headers: Custom headers for the HTTP request.
  • hostname: S3 bucket hostname.
  • method: HTTP method (GET, PUT, etc.).
  • path: S3 object path.
  • protocol: Request protocol (http, https).
  • service: AWS service (s3).
  • authFacade: Handles user authentication through Cognito.
  • cognitoSettings: AWS Cognito configuration.

7. Usage

7.1 Registering the Plugin

To enable the aws_s3_entity CRUD adaptor plugin, import the Aws3Module in your Angular application. Ensure that AWS Cognito settings are configured.

Example:

import { Aws3Module } from 'aws3';
import { CognitoSettings, COGNITO_SETTINGS } from '@rollthecloudinc/awcog';

const cognitoSettings: CognitoSettings = {
  identityPoolId: 'us-east-1:xxxxxx',
  region: 'us-east-1',
  userPoolId: 'us-east-1_xxxxxx',
};

@NgModule({
  imports: [Aws3Module],
  providers: [{ provide: COGNITO_SETTINGS, useValue: cognitoSettings }],
})
export class AppModule {}

7.2 Performing CRUD Operations

Create

The create method writes objects to an S3 bucket using a signed URL.

Example:

const crudInput = {
  object: { id: '123', name: 'NewItem' },
  params: { bucket: 'myBucket', prefix: 'myApp_' },
  identity: () => of({ identity: 'uniqueKey' }),
};

s3EntityCrudAdaptorPluginFactory(...dependencies)
  .create(crudInput)
  .subscribe((response) => console.log('Create successful:', response.success));
Read

The read method retrieves an object from the S3 bucket (currently stubbed for development).

Example:

s3EntityCrudAdaptorPluginFactory(...dependencies)
  .read({})
  .subscribe((response) => console.log('Read successful:', response.success));
Update

The update method modifies an existing object in the S3 bucket.

Example:

const crudInput = {
  object: { id: '123', name: 'UpdatedItem' },
  params: { bucket: 'myBucket', prefix: 'myApp_' },
  identity: () => of({ identity: 'uniqueKey' }),
};

s3EntityCrudAdaptorPluginFactory(...dependencies)
  .update(crudInput)
  .subscribe((response) => console.log('Update successful:', response.success));
Delete

The delete method removes an object from the S3 bucket (currently stubbed for development).

Example:

s3EntityCrudAdaptorPluginFactory(...dependencies)
  .delete({})
  .subscribe((response) => console.log('Delete successful:', response.success));

7.3 Querying Data in S3

The query method retrieves objects from the S3 bucket based on rule conditions.

Example:

const queryInput = {
  params: { bucket: 'myBucket', prefix: 'myApp_' },
  rule: {
    conditions: {
      all: [
        { fact: 'identity', operator: 'startsWith', value: 'user' },
      ],
    },
    event: { type: 'visible' },
  },
};

s3EntityCrudAdaptorPluginFactory(...dependencies)
  .query(queryInput)
  .subscribe((response) =>
    console.log('Query successful, entities:', response.entities)
  );

8. API Reference

Factories

  1. s3EntityCrudAdaptorPluginFactory

    • create(input: CrudOperationInput): Observable<CrudOperationResponse>
    • read(input: CrudOperationInput): Observable<CrudOperationResponse>
    • update(input: CrudOperationInput): Observable<CrudOperationResponse>
    • delete(input: CrudOperationInput): Observable<CrudOperationResponse>
    • query(input: CrudCollectionOperationInput): Observable<CrudCollectionOperationResponse>

  2. createS3SignedHttpRequest(params: CreateSignHttpRequestParams): Observable<HttpRequest>

    • Generates signed HTTP requests for AWS S3 operations.

9. Examples

Example: Registering S3 Plugin

import { Aws3Module } from 'aws3';

@NgModule({
  imports: [Aws3Module],
  bootstrap: [AppComponent],
})
export class AppModule {}

Example: Querying Objects with Rules

const input = {
  params: { bucket: 'myBucket', prefix: 'myPrefix_' },
  rule: {
    conditions: {
      all: [{ fact: 'identity', operator: 'startsWith', value: 'admin' }],
    },
    event: { type: 'visible' },
  },
};

s3EntityCrudAdaptorPluginFactory(...dependencies)
  .query(input)
  .subscribe((response) => console.log('Queried entities:', response.entities));

10. Testing

Testing CRUD Operations

Example test for verifying create functionality:

describe('s3EntityCrudAdaptorPluginFactory', () => {
  it('should create an item in S3', () => {
    const input = {
      object: { id: 'item1', name: 'TestName' },
      params: { bucket: 'test-bucket', prefix: 'testPrefix_' },
      identity: () => of({ identity: 'itemKey1' }),
    };

    s3EntityCrudAdaptorPluginFactory(...dependencies)
      .create(input)
      .subscribe((response) => expect(response.success).toBeTruthy());
  });
});

Conclusion

The AWS3 Angular library provides secure integration with AWS S3 using signed URLs and Cognito-based authentication. It is ideal for applications requiring scalable, secure object storage with advanced querying capabilities.

For contributions, issues, or feature requests, feel free to contact us!